gps-denied-desktop/docs/03_tests/07_image_input_pipeline_integration_spec.md

Integration Test: Image Input Pipeline

Summary

Validate the Image Input Pipeline component for loading, preprocessing, and preparing UAV images for processing by vision algorithms.

Component Under Test

Component: Image Input Pipeline Location: gps_denied_05_image_input_pipeline Dependencies:

• Image loading libraries (PIL/OpenCV)
• Image Rotation Manager (for orientation correction)
• File system access
• Configuration Manager

Detailed Description

This test validates that the Image Input Pipeline can:

1. Load UAV images from disk in various formats (JPG, PNG)
2. Read and validate image metadata (resolution, EXIF if available)
3. Resize images appropriately for different processing layers
4. Normalize pixel values for neural network input
5. Handle high-resolution images (6252x4168) efficiently
6. Detect and handle corrupted images gracefully
7. Maintain consistent image quality during preprocessing
8. Support batch loading for multiple images

The component is the entry point for all UAV imagery into the ASTRAL-Next system.

Input Data

Test Case 1: Standard Resolution Image

• Image: AD000001.jpg
• Expected Resolution: 6252x4168 (26MP)
• Format: JPEG
• Expected: Load successfully, extract metadata

Test Case 2: Batch Loading

• Images: AD000001-AD000010 (10 images)
• Expected: All load successfully, maintain order

Test Case 3: Image Resizing for Vision Layers

• Image: AD000015.jpg
• Target Resolutions:
  • L1 (Sequential VO): 1024x683 (for SuperPoint)
  • L2 (Global PR): 512x341 (for AnyLoc)
  • L3 (Metric Ref): 640x427 (for LiteSAM)
• Expected: Maintain aspect ratio, preserve image quality

Test Case 4: Pixel Normalization

• Image: AD000020.jpg
• Target Format: Float32, range [0, 1] or [-1, 1]
• Expected: Correct normalization for neural network input

Test Case 5: EXIF Data Extraction

• Image: AD000001.jpg
• Expected EXIF: Camera model, focal length, ISO, capture time
• Note: May not be present in all images

Test Case 6: Image Sequence Loading

• Images: AD000001-AD000060 (all 60 images)
• Expected: Load in order, track sequence number

Test Case 7: Corrupted Image Handling

• Image: Create test file with corrupted data
• Expected: Detect corruption, fail gracefully with clear error

Test Case 8: Rotation Detection

• Image: AD000025.jpg (may have orientation metadata)
• Expected: Detect if rotation needed, coordinate with Image Rotation Manager

Expected Output

For each test case:

{
  "success": true/false,
  "image_path": "path/to/image.jpg",
  "image_id": "AD000001",
  "original_resolution": {"width": 6252, "height": 4168},
  "loaded_resolution": {"width": <int>, "height": <int>},
  "format": "JPEG",
  "file_size_kb": <float>,
  "exif_data": {
    "camera_model": "string",
    "focal_length_mm": <float>,
    "iso": <int>,
    "capture_time": "timestamp"
  },
  "preprocessing_applied": ["resize", "normalize"],
  "output_dtype": "float32",
  "pixel_value_range": {"min": <float>, "max": <float>},
  "loading_time_ms": <float>,
  "preprocessing_time_ms": <float>,
  "memory_mb": <float>
}

Success Criteria

Test Case 1 (Standard Loading):

• success = true
• original_resolution matches expected (6252x4168)
• format detected correctly
• loading_time_ms < 500
• memory_mb < 200 (for single 26MP image)

Test Case 2 (Batch Loading):

• All 10 images load successfully
• Images maintain sequential order
• Total loading_time < 5 seconds
• Memory usage scales linearly

Test Case 3 (Resizing):

• All target resolutions achieved
• Aspect ratio preserved (within 1%)
• No significant quality degradation (PSNR > 30dB)
• Resizing time < 200ms per image

Test Case 4 (Normalization):

• Pixel values in expected range
• No clipping (min ≥ 0, max ≤ 1 for [0,1] normalization)
• Mean and std dev reasonable for natural images
• Normalization time < 100ms

Test Case 5 (EXIF):

• EXIF data extracted if present
• Missing EXIF handled gracefully (not error)
• Camera model matches known: "ADTi Surveyor Lite 26S v2"
• Focal length matches known: 25mm

Test Case 6 (Sequence):

• All 60 images load successfully
• Sequential order maintained
• Total loading time < 30 seconds
• Memory usage stays bounded (< 2GB)

Test Case 7 (Corruption):

• Corruption detected
• Clear error message provided
• No crash or hang
• Other images in batch can still load

Test Case 8 (Rotation):

• Rotation metadata detected if present
• Coordinates with Image Rotation Manager
• Correct orientation applied

Maximum Expected Time

• Single image load: < 500ms (6252x4168)
• Single image resize: < 200ms
• Single image normalize: < 100ms
• Batch 60 images: < 30 seconds
• Total test suite: < 60 seconds

Test Execution Steps

1. Setup Phase: a. Initialize Image Input Pipeline b. Configure preprocessing parameters c. Verify test images exist d. Create corrupted test image

2. Test Case 1 - Standard Loading: a. Load AD000001.jpg b. Verify resolution and format c. Check metadata extraction d. Measure timing and memory

3. Test Case 2 - Batch Loading: a. Load AD000001-AD000010 b. Verify all load successfully c. Check sequential order d. Measure batch timing

4. Test Case 3 - Resizing: a. Load AD000015.jpg b. Resize to multiple target resolutions c. Verify aspect ratio preservation d. Check image quality (visual or PSNR)

5. Test Case 4 - Normalization: a. Load and normalize AD000020.jpg b. Check pixel value range c. Verify data type conversion d. Validate statistics (mean/std)

6. Test Case 5 - EXIF: a. Load AD000001.jpg b. Attempt EXIF extraction c. Verify known camera parameters d. Handle missing EXIF gracefully

7. Test Case 6 - Sequence: a. Load all 60 images b. Verify complete and ordered c. Monitor memory usage d. Check for memory leaks

8. Test Case 7 - Corruption: a. Attempt to load corrupted test file b. Verify error detection c. Check error message quality d. Ensure no crash

9. Test Case 8 - Rotation: a. Check for orientation metadata b. Apply rotation if needed c. Verify correct orientation d. Measure rotation timing

Pass/Fail Criteria

Overall Test Passes If:

• At least 7 out of 8 test cases pass (Test Case 5 may fail if EXIF missing)
• All valid images load successfully
• No crashes or hangs
• Memory usage bounded
• Timing constraints met

Test Fails If:

• Any valid image fails to load
• Resolution or format detection fails
• Memory leak detected (>500MB growth)
• Any timing exceeds 2x maximum expected
• Corrupted images cause crash
• Batch loading loses or reorders images

Additional Validation

Image Quality Tests:

1. Lossy Preprocessing: Verify resizing doesn't introduce artifacts
2. Color Space: Verify RGB ordering (not BGR)
3. Bit Depth: Handle 8-bit and 16-bit images
4. Compression: Test various JPEG quality levels

Memory Management:

1. Cleanup: Verify images released from memory after processing
2. Large Batch: Test with 100+ images (memory should not explode)
3. Repeated Loading: Load same image 1000 times (no memory growth)

Format Support:

1. JPEG: Primary format (required)
2. PNG: Should support (for satellite tiles)
3. TIFF: Optional (may be used for high-quality)
4. RAW: Not required but document limitations

Edge Cases:

1. Non-Existent File: Should fail with clear file-not-found error
2. Empty File: Should detect as corrupted
3. Non-Image File: Should reject with clear error
4. Symbolic Links: Should follow or reject appropriately
5. Permissions: Should handle read permission errors

Performance Benchmarks:

• Load 1000 FullHD images in < 60 seconds
• Resize 100 images to 640x480 in < 10 seconds
• Normalize 100 images in < 5 seconds
• Memory footprint per loaded image < 200MB

Configuration Testing

Test various configuration options:

• Resize Method: bilinear, bicubic, lanczos
• Normalization: [0,1], [-1,1], ImageNet statistics
• Color Mode: RGB, grayscale
• Cache Behavior: cache vs load-on-demand

Camera Parameters Validation

For the known camera (ADTi Surveyor Lite 26S v2):

• Resolution: 6252x4168 (26MP) ✓
• Focal Length: 25mm ✓
• Sensor Width: 23.5mm ✓
• Expected Ground Sampling Distance (GSD) at 400m altitude: ~37.6 cm/pixel

Calculate and validate GSD: GSD = (altitude * sensor_width) / (focal_length * image_width)

• GSD = (400m * 23.5mm) / (25mm * 6252) = 0.0602m = 6.02cm/pixel per sensor pixel
• Effective GSD in final image ≈ 6cm/pixel

Error Handling Tests

Verify appropriate errors for:

• File path with invalid characters
• Image with unsupported format
• Image with invalid header
• Truncated image file
• Image with mismatched metadata
• Empty directory
• Directory instead of file path