forked from jsnbuchanan/crowd-funder-for-time-pwa
309 lines
6.8 KiB
Markdown
309 lines
6.8 KiB
Markdown
# 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
|