# Flight Processing Engine

## Interface Definition

**Interface Name**: `IFlightProcessingEngine`

### Interface Methods

```python
class IFlightProcessingEngine(ABC):
    @abstractmethod
    def start_processing(self, flight_id: str) -> None:
        """Starts the main processing loop in a background thread/task."""
        pass
    
    @abstractmethod
    def stop_processing(self, flight_id: str) -> None:
        pass
    
    @abstractmethod
    def process_frame(self, flight_id: str, frame_id: int) -> FrameResult:
        pass
    
    @abstractmethod
    def apply_user_fix(self, flight_id: str, fix_data: UserFixRequest) -> UserFixResult:
        pass
    
    @abstractmethod
    def handle_tracking_loss(self, flight_id: str, frame_id: int) -> RecoveryStatus:
        pass
    
    # Chunk Lifecycle (Delegates to F12 but orchestrated here)
    @abstractmethod
    def get_active_chunk(self, flight_id: str) -> Optional[ChunkHandle]:
        pass
    
    @abstractmethod
    def create_new_chunk(self, flight_id: str, frame_id: int) -> ChunkHandle:
        pass
```

## Component Description

### Responsibilities
- **Component ID**: F02.2
- **Processing Orchestration**: Runs the main loop: Image -> VO -> Graph -> Result.
- **State Machine**: Manages flight status (Processing, Blocked, Recovering, Completed).
- **Recovery Coordination**: Calls F11 methods and acts on return values.
- **Chunk Management**: Calls F12 to manage chunk lifecycle based on tracking status.
- **Background Tasks**: Manages background chunk matching tasks.

### Scope
- Per-flight processing logic.
- Interaction with Visual Pipeline (F06, F07, F09).
- Interaction with State Estimation (F10).
- Interaction with Recovery (F11).
- Result Publishing (F14, F15).

## Processing Flow

### `run_processing_loop(flight_id: str)`
1.  **Loop**: While `F05.get_next_image()` returns image:
2.  **Chunk Check**:
    *   `active_chunk = F12.get_active_chunk()`
    *   If `detect_chunk_boundary()`: `active_chunk = F12.create_chunk()`.
3.  **Visual Odometry**:
    *   Call `F06.requires_rotation_sweep()`.
    *   Call `F07.compute_relative_pose()`.
4.  **Tracking Check**:
    *   If tracking good:
        *   `F12.add_frame_to_chunk()`.
        *   `F09.align_to_satellite()` (optional drift correction).
        *   `F10.add_relative_factor()`.
        *   `F10.optimize_chunk()`.
        *   `F14.update_frame_result()`.
    *   If tracking lost:
        *   **Proactive Chunking**: `F11.create_chunk_on_tracking_loss()`.
        *   **Recovery**: Call `handle_tracking_loss()`.

### `handle_tracking_loss(flight_id, frame_id)`
1.  Call `F11.start_search()`.
2.  Loop progressive search (1..25 tiles):
    *   `result = F11.try_current_grid()`.
    *   If found: `F11.mark_found()`, break.
    *   If not found: `F11.expand_search_radius()`.
3.  If still not found:
    *   `req = F11.create_user_input_request()`.
    *   `F15.send_user_input_request(req)`.
    *   Set status to **BLOCKED**.
    *   Wait for `apply_user_fix`.

### `apply_user_fix(fix_data)`
1.  Call `F11.apply_user_anchor(fix_data)`.
2.  If success:
    *   Set status to **PROCESSING**.
    *   Resume loop.

## Dependencies
- **F05 Image Input Pipeline**: Image source.
- **F06 Image Rotation Manager**: Pre-processing.
- **F07 Sequential Visual Odometry**: Motion estimation.
- **F09 Metric Refinement**: Satellite alignment.
- **F10 Factor Graph Optimizer**: State estimation.
- **F11 Failure Recovery Coordinator**: Recovery logic.
- **F12 Route Chunk Manager**: Chunk state.
- **F14 Result Manager**: Saving results.
- **F15 SSE Event Streamer**: Real-time updates.

