# Feature: User Interaction

## Description
REST endpoints for user-triggered operations: submitting GPS fixes for blocked flights and converting detected object pixel coordinates to GPS. These endpoints support the human-in-the-loop workflow when automated localization fails.

## Component APIs Implemented
- `submit_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResponse`
- `convert_object_to_gps(flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> ObjectGPSResponse`

## REST Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/flights/{flightId}/user-fix` | Submit user-provided GPS anchor |
| POST | `/flights/{flightId}/frames/{frameId}/object-to-gps` | Convert pixel to GPS |

## External Tools and Services
- **FastAPI**: Web framework for REST endpoints
- **Pydantic**: Request/response validation

## Internal Methods
| Method | Purpose |
|--------|---------|
| `_validate_user_fix_request(fix_data)` | Validate pixel and GPS coordinates |
| `_validate_flight_blocked(flight_id)` | Verify flight is in blocked state |
| `_validate_frame_processed(flight_id, frame_id)` | Verify frame has pose in Factor Graph |
| `_validate_pixel_coordinates(pixel, resolution)` | Validate pixel within image bounds |
| `_build_user_fix_response(result)` | Build response with processing status |
| `_build_object_gps_response(result)` | Build GPS response with accuracy |

## Unit Tests
1. **submit_user_fix validation**
   - Valid request for blocked flight → returns 200, processing_resumed=true
   - Flight not blocked → returns 409
   - Invalid GPS coordinates → returns 400
   - Non-existent flight_id → returns 404

2. **submit_user_fix pixel validation**
   - Pixel within image bounds → accepted
   - Negative pixel coordinates → returns 400
   - Pixel outside image bounds → returns 400

3. **convert_object_to_gps validation**
   - Valid processed frame → returns GPS with accuracy
   - Frame not yet processed → returns 409
   - Non-existent frame_id → returns 404
   - Invalid pixel coordinates → returns 400

4. **convert_object_to_gps accuracy**
   - High confidence frame → low accuracy_meters
   - Low confidence frame → high accuracy_meters

## Integration Tests
1. **User fix unblocks processing**
   - Process until blocked → Submit user fix → Verify processing resumes
   - Verify SSE `processing_resumed` event sent

2. **Object-to-GPS workflow**
   - Process flight → Call object-to-gps for multiple pixels
   - Verify GPS coordinates are spatially consistent

3. **User fix with invalid anchor**
   - Submit fix with GPS far outside geofence
   - Verify appropriate error handling

4. **Concurrent object-to-gps calls**
   - Multiple clients request conversion simultaneously
   - All receive correct responses

