AI Photo Trainer PhotoRater

Cloud Connectivity

The Cloud Connectivity page lets you manage AI model downloads, Rails API authentication, and monitor connectivity status. The desktop application integrates with the Rails API for centralized photographer management while operating fully offline when needed.

What Is Cloud Connectivity?

The Cloud Connectivity system provides:

  • Rails API Integration: Secure PIN authentication and session data sync with the central platform
  • ML Detection Models: Required models for glasses, glare, eyes, and pose detection (~1.4 GB total)
  • AI Review Model (PhotoRater AI): Vision-language model for generating human-readable feedback (~520 MB)

From this page you can:

  • View download status for all model files
  • Test Google Drive URLs before downloading
  • Download missing models with progress tracking
  • Monitor validation status (e.g., "10/10 URLs validated")

Accessing Cloud Connectivity

  1. Click the gear icon (⚙) in the sidebar to open Settings
  2. Navigate to the "Cloud Connectivity" tab
  3. The page displays status of all model files

[IMAGE: Cloud Connectivity Page]

Overview showing ML models and AI Review model sections

Cloud Connectivity page with model status overview

Rails API Integration

Available in v0.11.4+ — The desktop application integrates with the Rails API (training.schoolpicturedays.com) for centralized photographer management, PIN authentication, and session data synchronization.

PIN Authentication

When you log in with your 6-digit PIN, the desktop application:

  1. Validates your PIN against the Rails API using secure HMAC-SHA256 authentication
  2. Downloads photographer data (name, email, skill level, company settings)
  3. Caches credentials locally for offline use
  4. Syncs company settings (thresholds, pose profiles) if configured

Security: PIN validation uses HMAC-SHA256 signatures to ensure request integrity and prevent tampering. All communication with the Rails API uses HTTPS encryption in production.

Authentication Flow

Step Action Timeout
1. PIN Cache Refresh Download all active PINs on app startup 30 seconds (cold start)
2. PIN Validation Validate entered PIN and retrieve photographer data 30 seconds
3. Settings Sync Download company threshold settings 30 seconds

Cold Start Performance: The first API request after server restart may take up to 30 seconds (typical: ~16 seconds in development). Subsequent requests complete in less than 1 second due to server warm-up.

Online vs. Offline Mode

The desktop application operates seamlessly in both online and offline modes with automatic failover.

Mode PIN Validation Session Data Settings Sync
Online Validated against Rails API Synced immediately on session end Downloaded on login
Offline Validated against local cache Queued for sync when online Uses last cached settings

Offline Mode User Experience:

  1. Photographer enters PIN (validated against local cache)
  2. Warning displayed: "Working offline - session will sync when online"
  3. Full functionality available (rating, badges, statistics)
  4. Session data queued for sync when connection restored

Transparent Failover: No user action required. The application automatically detects network availability and gracefully degrades to offline mode. Smart caching prevents repeated API calls for better performance.

Session Data Sync

When you complete a photography session, the application syncs your work to the Rails API for centralized reporting and analytics.

Data Synced:

  • Session metadata (start time, end time, duration, mode)
  • Photo ratings and quality scores
  • Badges earned during session
  • Quality statistics and distributions
  • Photographer skill level and feedback preferences

API Endpoint: POST /api/v1/sessions

Privacy: Photo files are NEVER uploaded to the Rails API. Only metadata and quality scores are synced. All photos remain local on your machine.

ML Detection Models

These machine learning models are required for core photo analysis functionality. Without them, the application cannot analyze photos.

Required Models

Model File Purpose Size
ml_eyes_closed_detection_model.joblib Eye state detection (open/closed) ~1 MB
ml_eyes_closed_detection_scaler.joblib Feature scaling for eyes ~1 KB
ml_glare_detection_model.joblib Glasses glare detection ~1 MB
ml_glare_detection_scaler.joblib Feature scaling for glare ~1 KB
ml_glare_detection_features.json Feature configuration ~1 KB
phase2_feature_scaler.joblib Phase 2 feature scaling ~1 KB
phase2_glasses_model.joblib Glasses detection ~1 MB

Total ML Models Size: ~5 MB

Efficient Design: The ML ensemble approach provides accurate detection with significantly smaller model sizes than CNN alternatives, enabling faster downloads and reduced disk space usage.

Testing Model URLs

Before downloading, you can validate that all Google Drive URLs are accessible:

  1. Each model row has a "Test" button
  2. Click Test to validate the specific model's URL
  3. A green checkmark (✓) indicates the URL is valid and accessible
  4. A red X indicates a problem with the URL

The validation count at the top shows your overall status:

✓ 10/10 URLs validated

All model download links are working correctly

Downloading ML Models

  1. Click the "Download All" button in the ML Models section
  2. Sign in with Google when prompted (one-time authentication)
  3. Progress bar shows download status for each file
  4. Models install to %LOCALAPPDATA%\AI Photo Training\models\
  5. Once complete, models are available immediately

AI Review Model (PhotoRater AI)

Available in v0.11.1+ — The AI Review model section allows you to download the PhotoRater AI vision-language model for generating human-readable photo feedback.

What Is PhotoRater AI?

PhotoRater AI is a vision-language model that can "see" photos and generate natural language feedback about them. Unlike the ML detection models that provide numerical scores, PhotoRater AI provides written suggestions like:

"The subject's head is tilted slightly too far to the left. For a traditional portrait, guide them to straighten their head position by about 5 degrees."

The model consists of two files:

Component Purpose Size
PhotoRater AI Main Model Core language model for generating feedback text ~417 MB
PhotoRater AI Vision Encoder Image analysis and feature extraction ~104 MB

Total PhotoRater AI Model Size: ~520 MB (70% smaller than previous version)

Hardware Requirements

No GPU required - PhotoRater AI works on all systems. The model runs entirely offline on your CPU, with automatic GPU acceleration if available.

Component Minimum (CPU-Only) Recommended (GPU)
CPU Intel i5-6500 / AMD Ryzen 5 1600 (4 cores) Intel i7-8700K / AMD Ryzen 7 3700X (8 cores)
System RAM 8 GB 16 GB
GPU None required (CPU inference) NVIDIA GTX 1660 or better (2+ GB VRAM)
Disk Space 520 MB 520 MB
Performance 10-30 seconds per image 2-3 seconds per image (4-12× faster)

Supported GPUs (Automatic Detection)

GPU VRAM Est. Performance Notes
GTX 1050 Ti 4 GB ~5-6s/image Entry-level, still 3× faster than CPU
GTX 1660 Ti 6 GB ~3-4s/image Good performance, budget-friendly
RTX 3060 12 GB ~2-3s/image Great performance, common GPU
RTX 4070 12 GB ~2s/image Excellent performance
RTX 4090 24 GB ~1-2s/image Fastest (overkill for this app)

Legacy GPUs: GTX 900 series (Maxwell) and newer supported (CUDA 8.0+)

Automatic GPU Detection: The application automatically detects and uses your NVIDIA GPU if available. No configuration needed - it works seamlessly with both CPU-only and GPU-accelerated systems. All other features (pose detection, glasses detection, glare detection, eye detection) always run on CPU and are instant (< 100ms).

Downloading PhotoRater AI

  1. Navigate to Settings → Cloud Connectivity
  2. Scroll to the "AI Review Model (PhotoRater AI)" section
  3. View the status of both model files (main model and vision encoder)
  4. Optionally click "Test" buttons to validate URLs first
  5. Click "Download AI Model" to begin
  6. Progress bar shows combined download progress for both files
  7. Download takes 5-15 minutes depending on connection speed

[IMAGE: PhotoRater AI Download Section]

AI Review Model section with download progress

PhotoRater AI download progress in Cloud Connectivity

Restart After Download

After downloading the PhotoRater AI model, a restart dialog appears:

✓ Download Complete!

The AI model has been downloaded successfully. To use the AI Image Review feature, please restart the application. The model will be loaded automatically on startup.

Later Restart Now

Why restart is required: The PhotoRater AI model is loaded into GPU memory at startup. A restart ensures the model is properly initialized and ready for use.

Performance Note: PhotoRater AI runs in the background (2 worker threads) and doesn't block your workflow. You can continue rating photos while AI feedback generates. CPU-only: 10-30s per image. GPU: 2-3s per image.

URL Validation

The validation count includes all model URLs:

  • 8 ML Detection Model URLs (required models)
  • 2 AI Review Model URLs (PhotoRater AI main + vision encoder)

When all URLs are validated, you'll see:

✓ 10/10 URLs validated

If any URL fails validation:

  • Check your internet connection
  • Ensure firewall isn't blocking Google Drive
  • Try again in a few minutes
  • Contact support if the issue persists

Offline Operation

Once models are downloaded, the application operates fully offline:

  • No internet required for photo analysis
  • Models persist across application restarts
  • Updates optional — existing models continue working

Internet is only needed for:

  • Initial model downloads
  • Syncing sessions to the cloud (if enabled)
  • Company Settings Sync (on PIN login)

Field-Ready: After initial setup, the desktop app works perfectly in locations without internet access — ideal for on-location photography sessions.

Next Steps