crowd-funder-for-time-pwa/docs/camera-implementation.md

Camera Implementation Documentation

Overview

This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for several purposes:

1. QR Code scanning for contact sharing and verification
2. Photo capture for gift records
3. Profile photo management
4. Shared photo handling
5. Image upload and processing

Components

QRScannerDialog.vue

Primary component for QR code scanning in web browsers.

Key Features:

• Uses qrcode-stream for web-based QR scanning
• Supports both front and back cameras
• Provides real-time camera status feedback
• Implements error handling with user-friendly messages
• Includes camera switching functionality

Camera Access Flow:

1. Checks for camera API availability
2. Enumerates available video devices
3. Requests camera permissions
4. Initializes camera stream with preferred settings
5. Handles various error conditions with specific messages

PhotoDialog.vue

Component for photo capture and selection.

Key Features:

• Cross-platform photo capture interface
• Image cropping capabilities
• File selection fallback
• Unified interface for different platforms

ImageMethodDialog.vue

Component for selecting image input method.

Key Features:

• Multiple input methods (camera, file upload, URL)
• Unified interface for image selection
• Integration with PhotoDialog for processing
• Support for image cropping
• URL-based image handling

SharedPhotoView.vue

Component for handling shared photos.

Key Features:

• Processes incoming shared photos
• Options to use photo for gifts or profile
• Image preview and confirmation
• Server upload integration
• Temporary storage management

Services

QRScanner Services

WebDialogQRScanner

Web-based implementation of QR scanning.

Key Methods:

• checkPermissions(): Verifies camera permission status
• requestPermissions(): Requests camera access
• isSupported(): Checks for camera API support
• Handles various error conditions with specific messages

CapacitorQRScanner

Native implementation using Capacitor's MLKit.

Key Features:

• Uses @capacitor-mlkit/barcode-scanning
• Supports both front and back cameras
• Implements permission management
• Provides continuous scanning capability

Platform Services

WebPlatformService

Web-specific implementation of platform features.

Camera Capabilities:

• Uses HTML5 file input with capture attribute
• Falls back to file selection if camera unavailable
• Processes captured images for consistent format

CapacitorPlatformService

Native implementation using Capacitor.

Camera Features:

• Uses Camera.getPhoto() for native camera access
• Supports image editing
• Configures high-quality image capture
• Handles base64 image processing

ElectronPlatformService

Desktop implementation (currently unimplemented).

Status:

• Camera functionality not yet implemented
• Planned to use Electron's media APIs

Camera Usage Scenarios

Gift Photo Capture

Implementation:

• Uses PhotoDialog for capture/selection
• Supports multiple input methods
• Optional image cropping
• Server upload with authentication
• Integration with gift records

Flow:

1. User initiates photo capture from gift details
2. ImageMethodDialog presents input options
3. PhotoDialog handles capture/selection
4. Image is processed and uploaded
5. URL is attached to gift record

Profile Photo Management

Implementation:

• Uses same PhotoDialog component
• Enforces square aspect ratio
• Requires image cropping
• Updates user profile settings
• Handles profile image updates

Flow:

1. User initiates profile photo update
2. PhotoDialog opens with cropping enabled
3. Image is captured/selected
4. User crops to square aspect ratio
5. Image is uploaded and profile updated

Shared Photo Processing

Implementation:

• Handles incoming shared photos
• Temporary storage in IndexedDB
• Options for photo usage
• Server upload integration
• Cleanup after processing

Flow:

1. Photo is shared to application
2. Stored temporarily in IndexedDB
3. SharedPhotoView presents options
4. User chooses usage (gift/profile)
5. Image is processed accordingly

Image Upload and Processing

Implementation:

• Secure server upload
• Authentication handling
• Image format standardization
• Error handling and retry
• Progress feedback

Flow:

1. Image is prepared for upload
2. Authentication token is obtained
3. Multipart form data is created
4. Upload progress is monitored
5. Server URL is returned

Platform-Specific Considerations

iOS

• Requires NSCameraUsageDescription in Info.plist
• Supports both front and back cameras
• Implements proper permission handling

Android

• Requires camera permissions in manifest
• Supports both front and back cameras
• Handles permission requests through Capacitor

Web

• Requires HTTPS for camera access
• Implements fallback mechanisms
• Handles browser compatibility issues

Error Handling

Common Error Scenarios

1. No camera found
2. Permission denied
3. Camera in use by another application
4. HTTPS required
5. Browser compatibility issues

Error Response

• User-friendly error messages
• Troubleshooting tips
• Clear instructions for resolution
• Platform-specific guidance

Security Considerations

Permission Management

• Explicit permission requests
• Permission state tracking
• Graceful handling of denied permissions

Data Handling

• Secure image processing
• Proper cleanup of camera resources
• No persistent storage of camera data

Best Practices

Camera Access

1. Always check for camera availability
2. Request permissions explicitly
3. Handle all error conditions
4. Provide clear user feedback
5. Implement proper cleanup

Performance

1. Optimize camera resolution
2. Implement proper resource cleanup
3. Handle camera switching efficiently
4. Manage memory usage

User Experience

1. Clear status indicators
2. Intuitive camera controls
3. Helpful error messages
4. Smooth camera switching
5. Responsive UI feedback

Future Improvements

Planned Enhancements

1. Implement Electron camera support
2. Add advanced camera features
3. Improve error handling
4. Enhance user feedback
5. Optimize performance

Known Issues

1. Electron camera implementation pending
2. Some browser compatibility limitations
3. Platform-specific quirks to address

Dependencies

Key Packages

• @capacitor-mlkit/barcode-scanning
• qrcode-stream
• vue-picture-cropper
• Platform-specific camera APIs

Testing

Test Scenarios

1. Permission handling
2. Camera switching
3. Error conditions
4. Platform compatibility
5. Performance metrics

Test Environment

• Multiple browsers
• iOS and Android devices
• Desktop platforms
• Various network conditions