gps-denied-onboard/docs/03_tests/55_chunk_rotation_recovery_spec.md

Acceptance Test: Chunk Rotation Recovery

Summary

Validate chunk LiteSAM matching with rotation sweeps for chunks with unknown orientation (sharp turns).

Linked Acceptance Criteria

AC-4: Robust to sharp turns (<5% overlap) AC-5: Connect route chunks

Preconditions

1. F02.2 Flight Processing Engine running
2. F11 Failure Recovery Coordinator (chunk orchestration, returns status objects)
3. F12 Route Chunk Manager functional (chunk lifecycle via create_chunk(), mark_chunk_anchored())
4. F06 Image Rotation Manager with chunk rotation support (try_chunk_rotation_steps())
5. F08 Global Place Recognition (chunk semantic matching via retrieve_candidate_tiles_for_chunk())
6. F09 Metric Refinement with chunk LiteSAM matching (align_chunk_to_satellite())
7. F10 Factor Graph Optimizer with chunk operations (add_chunk_anchor(), merge_chunk_subgraphs())
8. Test dataset: Chunk with unknown orientation (simulated sharp turn)

Test Description

Test system's ability to match chunks with unknown orientation using rotation sweeps. When a chunk is created after a sharp turn, its orientation relative to the satellite map is unknown. The system must rotate the entire chunk to all possible angles and attempt LiteSAM matching.

Test Steps

Step 1: Create Chunk with Unknown Orientation

• Action: Simulate sharp turn scenario
  • Process frames 1-10 (normal flight, heading 0°)
  • Sharp turn at frame 11 (heading changes to 120°)
  • Tracking lost, chunk_2 created proactively
  • Process frames 11-20 in chunk_2
• Expected Result:
  • Chunk_2 created with frames 11-20
  • Chunk orientation unknown (previous heading not relevant)
  • Chunk ready for matching (10 frames)

Step 2: Chunk Semantic Matching

• Action: Attempt chunk semantic matching
• Expected Result:
  • F08.compute_chunk_descriptor() → aggregate DINOv2 descriptor
  • F08.retrieve_candidate_tiles_for_chunk() → returns top-5 candidate tiles
  • Correct tile in top-5 candidates

Step 3: Chunk Rotation Sweeps

• Action: Attempt chunk LiteSAM matching with rotation sweeps
• Expected Result:
  • F06.try_chunk_rotation_steps() called
  • For each rotation angle (0°, 30°, 60°, ..., 330°):
    • F06.rotate_chunk_360() rotates all 10 images
    • F09.align_chunk_to_satellite() attempts matching
  • Match found at 120° rotation (correct orientation)
  • Returns ChunkAlignmentResult with:
    • rotation_angle: 120°
    • chunk_center_gps: correct GPS
    • confidence > 0.7
    • Sim(3) transform computed

Step 4: Chunk Merging

• Action: Merge chunk_2 to main trajectory
• Expected Result:
  • F12.mark_chunk_anchored() updates chunk state (calls F10.add_chunk_anchor())
  • F12.merge_chunks() merges chunk_2 into chunk_1 (calls F10.merge_chunk_subgraphs())
  • Sim(3) transform applied correctly
  • Global trajectory consistent

Step 5: Verify Final Trajectory

• Action: Verify all frames have GPS coordinates
• Expected Result:
  • All 20 frames have GPS coordinates
  • Frames 1-10: Original trajectory
  • Frames 11-20: Merged chunk trajectory
  • Global consistency maintained
  • Accuracy: 18/20 < 50m (90%)

Success Criteria

Primary Criterion:

• Chunk rotation sweeps find correct orientation (120°)
• Chunk LiteSAM matching succeeds with rotation
• Chunk merged correctly to main trajectory

Supporting Criteria:

• All 12 rotation angles tried
• Match found at correct angle
• Sim(3) transform computed correctly
• Final trajectory globally consistent

Expected Results

Chunk Rotation Recovery:
- Chunk_2 created: frames 11-20
- Unknown orientation: previous heading (0°) not relevant
- Chunk semantic matching: correct tile in top-5
- Rotation sweeps: 12 rotations tried (0°, 30°, ..., 330°)
- Match found: 120° rotation
- Chunk center GPS: Accurate (within 20m)
- Chunk merged: Sim(3) transform applied
- Final trajectory: Globally consistent
- Accuracy: 18/20 < 50m (90%)

Pass/Fail Criteria

TEST PASSES IF:

• Chunk rotation sweeps find match at correct angle (120°)
• Chunk LiteSAM matching succeeds
• Chunk merged correctly
• Final trajectory globally consistent
• Accuracy acceptable (≥ 80% < 50m)

TEST FAILS IF:

• Rotation sweeps don't find correct angle
• Chunk LiteSAM matching fails
• Chunk merging produces inconsistent trajectory
• Final accuracy below threshold

Architecture Elements

Chunk Rotation:

• F06 rotates all images in chunk by same angle
• 12 rotation steps: 0°, 30°, 60°, ..., 330°
• F09 attempts LiteSAM matching for each rotation

Chunk LiteSAM Matching:

• Aggregate correspondences from multiple images
• More robust than single-image matching
• Handles featureless terrain better

Chunk Merging:

• Sim(3) transform (translation, rotation, scale)
• Critical for monocular VO scale ambiguity
• Preserves internal consistency

Notes

• Rotation sweeps are critical for chunks from sharp turns
• Previous heading may not be relevant after sharp turn
• Chunk matching more robust than single-image matching
• Sim(3) transform accounts for scale differences