gps-denied-desktop/docs/03_tests/44_async_refinement_spec.md

Acceptance Test: Asynchronous Trajectory Refinement

Summary

Validate AC-8 requirement that the system refines previously computed results asynchronously in the background without blocking real-time result delivery.

Linked Acceptance Criteria

AC-8: Results of image processing should appear immediately to user, so that user shouldn't wait for the whole route to complete in order to analyze first results. Also, system could refine existing calculated results and send refined results again to user.

Preconditions

• ASTRAL-Next system operational
• Multi-threaded/process architecture active
• SSE event streaming enabled
• Factor graph configured for both incremental and batch optimization
• Test client subscribed to result stream

Test Data

• Dataset: AD000001-AD000060 (60 images)
• Focus: Timing of initial results vs refined results
• Expected Behavior: Initial results immediate, refinements sent later

Result Types

1. Initial Result: L1 sequential tracking estimate (fast, may drift)
2. Intermediate Result: L1 + periodic L2/L3 anchors (improved)
3. Refined Result: Full factor graph optimization (best accuracy)

Test Steps

Step 1: Start Flight Processing and Monitor Initial Results

Action: Begin processing, subscribe to SSE result stream Expected Result:

Frame 1 processed: Initial result delivered <500ms
Frame 2 processed: Initial result delivered <500ms
Frame 3 processed: Initial result delivered <500ms
...
Observation: User receives results immediately
Refinement: None yet (not enough data for global optimization)
Status: INITIAL_RESULTS_STREAMING

Step 2: Detect First Refinement Event

Action: Continue processing, monitor for refinement of early frames Expected Result:

Frame 10 processed: Initial result delivered <500ms
Background: Factor graph optimization triggered (10 frames accumulated)
Refinement Event: Frames 1-10 refined results published
Timing: Refinement ~2-3 seconds after Frame 10 initial result
Change: Frames 1-10 positions adjusted by 5-20m (drift correction)
Status: FIRST_REFINEMENT_SENT

Step 3: Verify Real-Time Processing Not Blocked

Action: Measure frame processing timing during background refinement Expected Result:

Frame 11 processing: <500ms (not blocked by refinement)
Frame 12 processing: <500ms (not blocked by refinement)
Frame 13 processing: <500ms (not blocked by refinement)
Background refinement: Running in parallel
CPU usage: Main thread 40%, background thread 30%
GPU usage: Shared between inference and optimization
Status: PARALLEL_PROCESSING_VERIFIED

Step 4: Monitor Multiple Refinement Cycles

Action: Process full flight, count refinement events Expected Result:

Total frames: 60
Initial results: 60 (all delivered immediately)
Refinement cycles: 6 (every ~10 frames)
Refinement triggers:
  - Cycle 1: Frame 10 (refines 1-10)
  - Cycle 2: Frame 20 (refines 1-20)
  - Cycle 3: Frame 30 (refines 1-30)
  - Cycle 4: Frame 40 (refines 1-40)
  - Cycle 5: Frame 50 (refines 1-50)
  - Cycle 6: Frame 60 (refines 1-60, final)
Status: MULTIPLE_REFINEMENTS_OBSERVED

Step 5: Analyze Refinement Impact

Action: Compare initial vs refined results for accuracy improvement Expected Result:

Frame 10 (example):
  Initial result: 48.27532, 37.38522 (estimate)
  Refined result: 48.27529, 37.38520 (improved)
  Ground truth:   48.27529, 37.38522
  Initial error: 12m
  Refined error: 3m
  Improvement: 75% error reduction

Mean improvement across all frames: 40-60% error reduction
Status: REFINEMENT_BENEFICIAL

Step 6: Test User Experience Flow

Action: Simulate user viewing results in real-time Expected Result:

T=0s: User starts flight processing
T=0.5s: Frame 1 result appears (can start analysis immediately)
T=1s: Frame 2 result appears
T=2s: Frame 4 result appears
T=5s: Frame 10 result appears
T=7s: Frames 1-10 refined (map updates with improved positions)
T=10s: Frame 20 result appears
T=12s: Frames 1-20 refined
...
User experience: Immediate feedback, incremental improvement
Blocked waiting: 0 seconds (AC-8 requirement met)
Status: UX_OPTIMAL

Step 7: Validate Refinement Message Format

Action: Inspect SSE messages for initial vs refined results Expected Result:

// Initial result
{
  "type": "initial_result",
  "frame_id": "AD000010.jpg",
  "timestamp": 1234567890.5,
  "gps": [48.27532, 37.38522],
  "confidence": 0.85,
  "status": "TRACKED"
}

// Refined result (same frame, later)
{
  "type": "refined_result",
  "frame_id": "AD000010.jpg",
  "timestamp": 1234567893.2,
  "gps": [48.27529, 37.38520],
  "confidence": 0.95,
  "refinement_cycle": 1,
  "improvement_m": 9.2,
  "status": "REFINED"
}

Pass/Fail Criteria

PASS if:

• ALL initial results delivered in <500ms (real-time requirement)
• Refinement occurs in background without blocking new frame processing
• ≥3 refinement cycles observed in 60-frame flight
• Refinement improves accuracy by ≥30% on average
• User receives both initial and refined results via SSE
• No race conditions or result ordering issues

FAIL if:

• Initial results delayed >1000ms waiting for refinement
• Refinement blocks real-time processing (frames queue up)
• No refinement occurs (system only outputs initial results)
• Refinement degrades accuracy (worse than initial)
• SSE messages dropped or out-of-order
• System crashes during concurrent processing

Architecture Requirements

Threading Model

• Main Thread: Image ingest, L1/L2/L3 inference, initial results
• Background Thread: Factor graph batch optimization, refinement
• Communication: Thread-safe queue for initial results, SSE for output

Refinement Triggers

• Time-based: Every 5 seconds
• Frame-based: Every 10 frames
• Anchor-based: When new L3 global anchor added
• Final: When flight completes

Optimization Strategy

• Initial: L1 only (sequential VO, fast but drifts)
• Incremental: iSAM2 updates every frame (moderate accuracy)
• Batch: Full graph optimization during refinement (best accuracy)

Performance Considerations

• Refinement CPU-bound (factor graph optimization)
• Inference GPU-bound (neural networks)
• Parallel execution achieves near-zero blocking
• Refinement overhead <20% of real-time processing budget

User Interface Integration

// Client receives two types of events
eventSource.addEventListener('initial_result', (e) => {
  const result = JSON.parse(e.data);
  map.addMarker(result.frame_id, result.gps, 'initial');
});

eventSource.addEventListener('refined_result', (e) => {
  const result = JSON.parse(e.data);
  map.updateMarker(result.frame_id, result.gps, 'refined');
  showImprovement(result.improvement_m);
});

Notes

• AC-8 enables real-time mission monitoring while maintaining high accuracy
• Decoupled architecture critical for concurrent processing
• Refinement is optional enhancement, not required for basic operation
• Users benefit from both immediate feedback and eventual accuracy improvement
• Similar to Google Maps "blue dot" moving immediately, then snapping to road