ODM: Improve error message when files lack GPS EXIF data

[JesJehle]

Problem

When users upload pre-processed orthomosaics or tiles (instead of raw drone images) to the ODM pipeline, the error message is confusing:

ODM processing failed with exit code 1
Images directory contains 0 image files: []

This is misleading because:

• Files DO exist in the directory (45+ TIFF files)
• They ARE valid image files (TIFF format)
• But they're NOT valid drone images (missing GPS EXIF data required by ODM)

Impact

• Users are confused about why processing failed
• Wastes support time investigating "missing files"
• Users retry the same invalid upload multiple times
• Recent example: 4 datasets from same user (6226, 6227, 6228, 6258)

Root Cause

ODM's error "0 image files" means "0 images with valid GPS EXIF data", not "0 files found". Our error logging doesn't clarify this distinction.

Proposed Solution

File: processor/src/process_odm.py

After ODM fails, detect the specific failure reason and provide actionable error messages:

# After ODM container exits with error
if odm_exit_code == 1:
    # Check if files exist but lack EXIF GPS
    image_files = list(images_dir.glob('*.{jpg,jpeg,tif,tiff}'))
    
    if len(image_files) > 0:
        # Files exist but ODM rejected them
        has_gps_exif = check_gps_exif_in_images(image_files)
        
        if not has_gps_exif:
            raise ValueError(
                f"ODM rejected {len(image_files)} image files due to missing GPS EXIF metadata. "
                f"ODM requires raw drone images with GPS coordinates embedded in EXIF data. "
                f"Your files appear to be pre-processed tiles or orthomosaics. "
                f"\n\nTo upload pre-processed data: Use 'Upload GeoTIFF' instead of 'Upload Raw Images'."
                f"\nTo use ODM: Upload original drone photos from your flight (typically .JPG files with GPS)."
            )

Acceptance Criteria

• Error message clearly states files were rejected due to missing GPS EXIF
• Error message explains the difference between raw drone images and processed tiles
• Error message guides users to correct upload method (GeoTIFF vs Raw Images)
• Test with pre-processed tiles (should show clear error)
• Test with raw drone images (should succeed as normal)

Related

• See also: Frontend validation issue (to prevent this at upload time)
• Affected datasets: 6226, 6227, 6228, 6258
• User: [user email redacted]

Priority

Medium - improves UX but workaround exists (user support can explain)

[linear]

DT-140

[JesJehle]

Updated Analysis: ODM Exit Code 1 Pattern (60% of Recent Failures)

Analyzed 10 failing datasets from the past 30 days - 6 datasets (60%) failed with ODM Exit Code 1 due to users uploading processed orthomosaics instead of raw drone images.

Error Pattern Breakdown

• ODM Exit Code 1: 6 datasets (60%)
• ODM Exit Code 134 (crash): 2 datasets (20%) - see ODM Processing Failure: Exit Code 134 During Image Undistortion (Dataset 6266) #226
• COG GDAL Error: 1 dataset (10%)
• Other errors: 1 dataset (10%)

Common Indicators

All ODM Exit Code 1 failures share these characteristics:

• ❌ No EXIF data (camera_metadata: {})
• ❌ Filenames contain: tiles, Ortomosaico, mosaic, tfw
• ❌ File count matches tiles (e.g., 45 "images")
• ✅ Files exist and upload succeeds
• ✅ Processing starts normally
• ❌ ODM fails in <5 seconds with "Images directory contains 0 image files"

Real-World Example (Dataset 6306)

Timeline:

• 18:18 - Upload completed (8.2GB)
• 18:53 - Analysis: "2 images, 0 RTK, NO EXIF" ⚠️
• 18:54 - ODM failed in 2 seconds (exit code 1)
• 18:54 - Error: "Images directory contains 0 image files"

User self-resolution:

• Failed: Barbeau_20250826.zip (processed tiles)
• 2 hours later uploaded: Barbeau_20250825.tif (direct TIF) ✅ succeeded

User realized the ZIP was wrong and uploaded the ortho directly instead.

Impact

• Users confused by "0 image files" error despite files existing
• Multiple retry attempts with same invalid data
• One user uploaded 3 different variations before getting support
• Wasted processing time (SSH transfer, extraction, volume creation)

Validation Point Location

The issue is the validation happens too late - after:

1. ✅ Upload accepted (8GB transferred)
2. ✅ Files stored on disk
3. ✅ ZIP extracted successfully
4. ✅ Files counted (shows "2 images")
5. ✅ Copied to Docker volume
6. ❌ ODM rejects files ← First validation

Should fail at step 2 (during upload) with clear message.

Recommendation Priority

P0 - Critical UX Issue

Backend validation (proposed in this issue) would prevent 60% of current ODM failures. Frontend validation (#224) would catch it even earlier.