gps-denied-onboard/docs/02_components/14_result_manager/result_manager_spec.md

Result Manager

Interface Definition

Interface Name: IResultManager

Interface Methods

class IResultManager(ABC):
    @abstractmethod
    def update_frame_result(self, flight_id: str, frame_id: int, result: FrameResult) -> bool:
        """
        Atomic update:
        1. Saves result to frame_results table.
        2. Updates waypoint in waypoints table.
        3. All within a single transaction via F03.
        """
        pass
    
    @abstractmethod
    def publish_waypoint_update(self, flight_id: str, frame_id: int) -> bool:
        pass
    
    @abstractmethod
    def get_flight_results(self, flight_id: str) -> FlightResults:
        pass
    
    @abstractmethod
    def mark_refined(self, flight_id: str, frame_ids: List[int]) -> bool:
        pass
    
    @abstractmethod
    def get_changed_frames(self, flight_id: str, since: datetime) -> List[int]:
        pass
    
    @abstractmethod
    def update_results_after_chunk_merge(self, flight_id: str, merged_frames: List[int]) -> bool:
        pass

Component Description

Responsibilities

• Result consistency and publishing.
• Atomic Updates: Ensures consistency between normalized waypoints and denormalized frame_results via transaction requests to F03.

Scope

• Result state management
• Flight Database integration (waypoint storage)
• SSE event triggering
• Incremental update detection
• Result persistence

API Methods

update_frame_result(flight_id: str, frame_id: int, result: FrameResult) -> bool

Description: Persists and publishes the result of a processed frame.

Called By:

• Main processing loop (after each frame)
• F10 Factor Graph (after refinement)

Input:

flight_id: str
frame_id: int
result: FrameResult:
    gps_center: GPSPoint
    altitude: float
    heading: float
    confidence: float
    timestamp: datetime
    refined: bool
    objects: List[ObjectLocation]  # From external detector

Output: bool - True if updated

Processing Flow:

1. Construct DB transaction:
   • Insert/Update frame_results.
   • Update waypoints (latest position).
2. Call F03.execute_transaction().
3. If success: call F15.send_frame_result().
4. Update flight statistics.

Test Cases:

1. New frame result → stored and published
2. Refined result → updates existing, marks refined=True

---

publish_waypoint_update(flight_id: str, frame_id: int) -> bool

Description: Specifically triggers an update for the waypoint visualization.

Called By:

• Internal (after update_frame_result)

Input:

flight_id: str
frame_id: int

Output: bool - True if updated successfully

Processing Flow:

1. Fetch latest data.
2. Call F15.send_frame_result() (or a specific lightweight event).
3. Handle errors (retry if transient)

Test Cases:

1. Successful update → Waypoint stored in database
2. Database unavailable → logs error, continues

---

get_flight_results(flight_id: str) -> FlightResults

Description: Retrieves all results for a flight.

Called By:

• F01 REST API (results endpoint)
• Testing/validation

Input: flight_id: str

Output:

FlightResults:
    flight_id: str
    frames: List[FrameResult]
    statistics: FlightStatistics

Test Cases:

1. Get all results → returns complete trajectory

---

mark_refined(flight_id: str, frame_ids: List[int]) -> bool

Description: Updates results for frames that have been retrospectively improved (e.g., after loop closure or chunk merge).

Called By:

• F10 Factor Graph (after asynchronous refinement)

Input:

flight_id: str
frame_ids: List[int]  # Frames with updated poses

Output: bool

Note: F14 does NOT call F10 or F13. The caller (F02.2) performs the following steps before calling mark_refined():

1. F02.2 gets refined poses from F10.get_trajectory(flight_id)
2. F02.2 converts ENU to GPS via F13.enu_to_gps(flight_id, enu_tuple)
3. F02.2 calls F14.mark_refined() with the GPS-converted results

Processing Flow:

1. For each frame_id in frame_ids:
   • Receive GPS coordinates from caller (already converted)
   • Update result with refined=True via F03 Flight Database (part of transaction)
   • Update waypoint via F03 Flight Database (part of transaction)
   • Call F15 SSE Event Streamer.send_refinement()

Test Cases:

1. Batch refinement → all frames updated and published

---

get_changed_frames(flight_id: str, since: datetime) -> List[int]

Description: Gets frames changed since timestamp (for incremental updates).

Called By:

• F15 SSE Event Streamer (for reconnection replay)

Input:

flight_id: str
since: datetime

Output: List[int] - Frame IDs changed since timestamp

Test Cases:

1. Get changes → returns only modified frames
2. No changes → returns empty list

---

update_results_after_chunk_merge(flight_id: str, merged_frames: List[int]) -> bool

Description: Handling specific to chunk merging events.

Triggered By:

• ChunkMerged event from F11 (F14 subscribes to this event)
• Alternative: F02.2 Flight Processing Engine can coordinate this call after receiving ChunkMerged event

Input:

flight_id: str
merged_frames: List[int]  # Frames whose poses changed due to chunk merge

Output: bool - True if updated successfully

Processing Flow:

1. Similar to mark_refined but triggered by ChunkMerged event context.
2. Ensures all frames in the merged chunk are updated to the global coordinate system.

Test Cases:

1. Chunk merge updates: All merged frames updated and published
2. GPS accuracy: Updated GPS matches optimized poses

Integration Tests

Test 1: Per-Frame Processing

1. Process frame 237
2. update_frame_result() → stores result
3. Verify publish_waypoint_update() called (F03.update_waypoint())
4. Verify F15 SSE event sent

Test 2: Batch Refinement

1. Process 100 frames
2. Factor graph refines frames 10-50
3. mark_refined([10-50]) → updates all
4. Verify Flight Database updated (F03.batch_update_waypoints())
5. Verify SSE refinement events sent

Test 3: Incremental Updates

1. Process frames 1-100
2. Client disconnects at frame 50
3. Client reconnects
4. get_changed_frames(since=frame_50_time)
5. Client receives frames 51-100

Non-Functional Requirements

Performance

• update_frame_result: < 50ms
• publish_waypoint_update: < 100ms (non-blocking)
• get_flight_results: < 200ms for 2000 frames

Reliability

• Result persistence survives crashes
• Guaranteed at-least-once delivery to Flight Database
• Idempotent updates

Dependencies

Internal Components

• F03 Flight Database: Must support transactional updates.
• F15 SSE Event Streamer: For real-time result streaming.

Note: F14 does NOT depend on F10, F13, or F11. The caller (F02.2) coordinates with those components and provides GPS-converted results to F14. This ensures unidirectional data flow and eliminates circular dependencies.

External Dependencies

• None

Data Models

FrameResult

class ObjectLocation(BaseModel):
    object_id: str
    pixel: Tuple[float, float]
    gps: GPSPoint
    class_name: str
    confidence: float

class FrameResult(BaseModel):
    frame_id: int
    gps_center: GPSPoint
    altitude: float
    heading: float
    confidence: float
    timestamp: datetime
    refined: bool
    objects: List[ObjectLocation]
    updated_at: datetime

FlightResults

class FlightStatistics(BaseModel):
    total_frames: int
    processed_frames: int
    refined_frames: int
    mean_confidence: float
    processing_time: float

class FlightResults(BaseModel):
    flight_id: str
    frames: List[FrameResult]
    statistics: FlightStatistics