# ID Scanner & OCR Setup Guide
## Overview
The booking system includes a comprehensive ID scanner modal that supports:
- **Mobile camera capture** for taking photos of ID cards
- **QR code scanning** for quick guest check-in
- **OCR (Optical Character Recognition)** to extract data from ID documents
- **Secure document storage** with encryption
## Features
### 1. Camera Integration
- Uses HTML5 camera API with `capture="environment"` attribute
- Automatically opens rear camera on mobile devices
- Supports both photo upload and direct camera capture
### 2. QR Code Scanner
- Real-time QR code scanning using `html5-qrcode` library
- Supports booking QR codes with structured guest data
- Auto-populates guest information from scanned codes
### 3. OCR Data Extraction
The system supports multiple OCR backends (in priority order):
#### Option A: Tesseract OCR (Free, Open Source)
**Installation on Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install tesseract-ocr
sudo apt-get install tesseract-ocr-eng tesseract-ocr-bul
```
**Installation on Windows:**
1. Download from: https://github.com/UB-Mannheim/tesseract/wiki
2. Install to `C:\Program Files\Tesseract-OCR`
3. Add to system PATH
**Installation on macOS:**
```bash
brew install tesseract
brew install tesseract-lang
```
#### Option B: Google Cloud Vision API (Paid, High Accuracy)
1. Create a Google Cloud project
2. Enable Cloud Vision API
3. Create service account and download JSON key
4. Add to `.env`:
```env
GOOGLE_VISION_KEY=path/to/service-account-key.json
```
#### Option C: Manual Entry (Fallback)
If no OCR is available, users can manually enter data after capturing the photo.
## How It Works
### User Flow
1. User clicks **"📷 Scan ID Card"** button in guest repeater
2. Modal opens with two tabs:
- **Upload Image**: Take photo or upload from gallery
- **Scan QR Code**: Scan booking QR code
3. System processes the image/QR code
4. Extracted data auto-fills guest form fields
5. User reviews and saves
### Technical Flow
#### Image Upload & OCR
```
User uploads image
↓
Image preprocessing (resize, enhance, grayscale)
↓
OCR extraction (Tesseract/Google Vision)
↓
Text parsing (regex patterns for ID#, name, DOB, nationality)
↓
Data normalization
↓
Auto-fill form fields
```
#### QR Code Scanning
```
User starts QR scanner
↓
Camera stream opens
↓
QR code detected
↓
Parse JSON data
↓
Dispatch Livewire event
↓
Auto-fill form fields
```
## Data Extraction Patterns
The OCR parser looks for:
### ID Number
- Format: `XX-123456` or `123456789`
- Pattern: `/\b([A-Z]{2,3}[\s-]?\d{6,10}|\d{9,12})\b/`
### Date of Birth
- Formats: `DD/MM/YYYY`, `DD.MM.YYYY`, `YYYY-MM-DD`
- Pattern: `/\b(\d{2}[\/\.\-]\d{2}[\/\.\-]\d{4}|\d{4}[\/\.\-]\d{2}[\/\.\-]\d{2})\b/`
- Normalized to: `YYYY-MM-DD`
### Full Name
- Format: Capitalized words (2-4 words)
- Pattern: `/^([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,3})$/`
- Example: `John Smith`, `Maria Garcia Lopez`
### Nationality
- Keywords: `Bulgarian`, `BG`, `American`, `USA`, `British`, `UK`, etc.
- Normalized to full country names
## Security Features
### Document Encryption
All uploaded ID documents are:
1. Stored in private storage (`storage/app/private/guest-documents/`)
2. Filename encrypted with unique hash
3. Path encrypted using Laravel's `Crypt` facade
4. Only accessible via temporary signed URLs
### Secure Deletion
When a guest is deleted or document is replaced:
1. Old encrypted path is decrypted
2. Physical file is deleted from storage
3. Database reference is removed
4. Error handling prevents data leaks
## File Structure
```
app/
├── Services/
│ └── IdScannerService.php # OCR & document handling
├── Livewire/
│ └── IdScannerModal.php # Modal component logic
resources/
├── views/
│ ├── livewire/
│ │ └── id-scanner-modal.blade.php # Modal UI
│ └── filament/
│ └── forms/
│ └── components/
│ └── id-scanner-modal.blade.php # Form integration
```
## Configuration
### Environment Variables
```env
# Optional: Google Cloud Vision API
GOOGLE_VISION_KEY=/path/to/service-account.json
# File Storage
FILESYSTEM_DISK=local
```
### Supported Languages
Tesseract supports multiple languages. Add more:
```bash
# Bulgarian
sudo apt-get install tesseract-ocr-bul
# Spanish
sudo apt-get install tesseract-ocr-spa
# French
sudo apt-get install tesseract-ocr-fra
```
Update the Tesseract command in `IdScannerService.php`:
```php
'tesseract %s %s -l eng+bul+spa+fra 2>&1'
```
## Testing
### Test OCR Locally
```bash
# Check Tesseract installation
tesseract --version
# Test OCR on sample image
tesseract sample-id.jpg output -l eng+bul
cat output.txt
```
### Test in Browser
1. Navigate to booking edit page
2. Add a new guest
3. Click "📷 Scan ID Card"
4. Upload a test ID image
5. Check console for extracted data
6. Verify form fields are populated
## Troubleshooting
### OCR Not Working
**Check Tesseract installation:**
```bash
which tesseract
tesseract --list-langs
```
**Check PHP exec() is enabled:**
```php
<?php
exec('tesseract --version', $output);
var_dump($output);
```
**Check permissions:**
```bash
chmod +x /usr/bin/tesseract
```
### Camera Not Opening
- Ensure HTTPS (camera requires secure context)
- Check browser permissions
- Test on mobile device (better camera support)
### QR Scanner Not Working
- Check if `html5-qrcode` library is loaded
- Verify camera permissions
- Check browser console for errors
## Browser Compatibility
| Feature | Chrome | Firefox | Safari | Edge |
|---------|--------|---------|--------|------|
| Camera Capture | ✅ | ✅ | ✅ | ✅ |
| QR Scanner | ✅ | ✅ | ✅ | ✅ |
| File Upload | ✅ | ✅ | ✅ | ✅ |
**Note:** Camera features require HTTPS in production.
## Performance Optimization
### Image Preprocessing
- Images resized to max 2000px width
- Converted to grayscale
- Contrast/brightness enhanced
- Reduces OCR processing time by ~40%
### Cleanup
- Temporary files auto-deleted after processing
- Processed images removed from temp storage
- Failed uploads cleaned up automatically
## Future Enhancements
### Planned Features
- [ ] Support for passport MRZ (Machine Readable Zone)
- [ ] Multi-page document scanning
- [ ] Real-time OCR preview
- [ ] Batch guest import from spreadsheet
- [ ] Integration with national ID verification APIs
- [ ] Face detection and matching
- [ ] Document authenticity verification
### API Integrations
- AWS Textract (high accuracy, paid)
- Azure Computer Vision (enterprise features)
- ABBYY Cloud OCR (specialized in IDs)
## Support
For issues or questions:
1. Check Laravel logs: `storage/logs/laravel.log`
2. Check browser console for JavaScript errors
3. Verify Tesseract installation and permissions
4. Test with sample images first
## License & Credits
- **html5-qrcode**: MIT License
- **Tesseract OCR**: Apache 2.0 License
- **Intervention Image**: MIT License