initial structure implemented

docs -> _docs

_docs/03_tests/55_chunk_rotation_recovery_spec.md

@@ -0,0 +1,139 @@
+# 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
+