# Feature: User Input Handling

## Description

Handles human-in-the-loop recovery when all automated strategies are exhausted. Creates user input requests with candidate tiles and applies user-provided GPS anchors to the factor graph.

## Component APIs Implemented

- `create_user_input_request(flight_id: str, frame_id: int, candidate_tiles: List[TileCandidate]) -> UserInputRequest`
- `apply_user_anchor(flight_id: str, frame_id: int, anchor: UserAnchor) -> bool`

## External Tools and Services

| Component | Usage |
|-----------|-------|
| F10 Factor Graph Optimizer | `add_absolute_factor()`, `optimize()` for anchor application |
| F08 Global Place Recognition | Candidate tiles (passed in, not called directly) |

## Internal Methods

| Method | Purpose |
|--------|---------|
| `_generate_request_id()` | Creates unique request ID |
| `_get_uav_image_for_frame(flight_id, frame_id)` | Retrieves UAV image for user display |
| `_validate_anchor(anchor)` | Validates anchor data (GPS bounds, pixel within image) |
| `_convert_anchor_to_factor(anchor, frame_id)` | Transforms UserAnchor to factor graph format |

## Request/Response Flow

1. **Request Creation**: F11 creates UserInputRequest → F02.2 sends via F15 → Client receives
2. **Anchor Application**: Client sends anchor → F01 API → F02.2 calls F11.apply_user_anchor()

## Unit Tests

1. **create_user_input_request** → Returns UserInputRequest with correct flight_id, frame_id, candidates
2. **create_user_input_request generates unique ID** → Multiple calls produce unique request_ids
3. **apply_user_anchor valid** → Returns true, calls F10.add_absolute_factor with is_user_anchor=true
4. **apply_user_anchor invalid GPS** → Returns false, no factor added
5. **apply_user_anchor invalid pixel coords** → Returns false, rejected
6. **apply_user_anchor triggers optimization** → F10.optimize() called after factor addition

## Integration Tests

1. **Full user input flow** → Search exhausted → create_user_input_request → user provides anchor → apply_user_anchor → processing resumes
2. **User anchor improves trajectory** → Before/after anchor application, trajectory accuracy improves
3. **Multiple user anchors** → Can apply anchors to different frames in sequence

