mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-22 19:56:37 +00:00
add features
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,67 @@
|
||||
# Feature: Flight & Waypoint Management
|
||||
|
||||
## Description
|
||||
Core CRUD operations for flights and waypoints. Handles flight creation with satellite prefetching trigger, flight state management, waypoint updates, and data validation. This is the primary data management feature of the Flight Lifecycle Manager.
|
||||
|
||||
## Component APIs Implemented
|
||||
|
||||
### Flight Lifecycle
|
||||
- `create_flight(flight_data: FlightData) -> str` - Creates flight, validates data, sets ENU origin, triggers satellite prefetching
|
||||
- `get_flight(flight_id: str) -> Optional[Flight]` - Retrieves flight by ID
|
||||
- `get_flight_state(flight_id: str) -> Optional[FlightState]` - Retrieves current flight state
|
||||
- `delete_flight(flight_id: str) -> bool` - Deletes flight and associated resources
|
||||
- `update_flight_status(flight_id: str, status: FlightStatusUpdate) -> bool` - Updates flight status
|
||||
|
||||
### Waypoint Management
|
||||
- `update_waypoint(flight_id: str, waypoint_id: str, waypoint: Waypoint) -> bool` - Updates single waypoint
|
||||
- `batch_update_waypoints(flight_id: str, waypoints: List[Waypoint]) -> BatchUpdateResult` - Batch waypoint update
|
||||
- `get_flight_metadata(flight_id: str) -> Optional[FlightMetadata]` - Retrieves flight metadata
|
||||
|
||||
### Validation
|
||||
- `validate_waypoint(waypoint: Waypoint) -> ValidationResult` - Validates single waypoint
|
||||
- `validate_geofence(geofence: Geofences) -> ValidationResult` - Validates geofence boundaries
|
||||
- `validate_flight_continuity(waypoints: List[Waypoint]) -> ValidationResult` - Validates waypoint sequence continuity
|
||||
|
||||
## External Dependencies
|
||||
- **F03 Flight Database** - Persistence layer for flights and waypoints
|
||||
- **F04 Satellite Data Manager** - Triggered for prefetch_route_corridor on flight creation
|
||||
- **F13 Coordinate Transformer** - Called for set_enu_origin on flight creation
|
||||
|
||||
## Internal Methods
|
||||
|
||||
### Flight Operations
|
||||
- `_generate_flight_id()` - Generates unique flight identifier
|
||||
- `_persist_flight(flight: Flight)` - Saves flight to F03
|
||||
- `_load_flight(flight_id: str)` - Loads flight from F03
|
||||
- `_delete_flight_resources(flight_id: str)` - Cleans up flight-related resources
|
||||
|
||||
### Validation Helpers
|
||||
- `_validate_gps_bounds(lat: float, lon: float)` - Validates GPS coordinates within valid range
|
||||
- `_validate_waypoint_sequence(waypoints: List[Waypoint])` - Checks waypoint ordering and gaps
|
||||
- `_validate_geofence_polygon(geofence: Geofences)` - Validates geofence geometry
|
||||
|
||||
### Coordinate Setup
|
||||
- `_setup_enu_origin(flight_id: str, start_gps: GPSPoint)` - Delegates to F13 for ENU origin setup
|
||||
|
||||
## Unit Tests
|
||||
- Test flight creation with valid data returns flight_id
|
||||
- Test flight creation with invalid geofence returns validation error
|
||||
- Test flight creation triggers F04.prefetch_route_corridor
|
||||
- Test flight creation calls F13.set_enu_origin
|
||||
- Test get_flight returns None for non-existent flight
|
||||
- Test delete_flight removes flight from database
|
||||
- Test update_flight_status transitions state correctly
|
||||
- Test validate_waypoint rejects out-of-bounds GPS
|
||||
- Test validate_geofence rejects invalid polygon
|
||||
- Test validate_flight_continuity detects excessive gaps
|
||||
- Test batch_update_waypoints handles partial failures
|
||||
- Test waypoint update validates before persisting
|
||||
|
||||
## Integration Tests
|
||||
- Test flight creation end-to-end with F03 persistence
|
||||
- Test flight creation triggers F04 satellite prefetching
|
||||
- Test flight creation sets ENU origin via F13
|
||||
- Test flight deletion cleans up all related data in F03
|
||||
- Test concurrent flight creation handles ID generation correctly
|
||||
- Test waypoint batch update maintains data consistency
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# Feature: Processing Delegation
|
||||
|
||||
## Description
|
||||
Delegation methods that route API calls from F01 Flight API to appropriate subsystems. Manages F02.2 Processing Engine instances, coordinates image queuing, handles user fixes, and provides access to SSE streaming and coordinate transformation services.
|
||||
|
||||
## Component APIs Implemented
|
||||
- `queue_images(flight_id: str, batch: ImageBatch) -> BatchQueueResult` - Queues images via F05, ensures F02.2 engine is active
|
||||
- `handle_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResult` - Forwards user fix to active F02.2 engine
|
||||
- `create_client_stream(flight_id: str, client_id: str) -> StreamConnection` - Creates SSE stream via F15
|
||||
- `convert_object_to_gps(flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> GPSPoint` - Converts pixel to GPS via F13
|
||||
|
||||
## External Dependencies
|
||||
- **F02.2 Flight Processing Engine** - Managed child component, created/retrieved per flight
|
||||
- **F05 Image Input Pipeline** - Image batch queuing
|
||||
- **F13 Coordinate Transformer** - Pixel-to-GPS conversion
|
||||
- **F15 SSE Event Streamer** - Client stream creation
|
||||
|
||||
## Internal Methods
|
||||
|
||||
### Engine Management
|
||||
- `_get_or_create_engine(flight_id: str) -> FlightProcessingEngine` - Retrieves existing or creates new F02.2 instance
|
||||
- `_get_active_engine(flight_id: str) -> Optional[FlightProcessingEngine]` - Gets active engine or None
|
||||
- `_engine_registry: Dict[str, FlightProcessingEngine]` - Registry of active engines per flight
|
||||
|
||||
### Image Queuing
|
||||
- `_delegate_queue_batch(flight_id: str, batch: ImageBatch)` - Delegates to F05.queue_batch
|
||||
- `_trigger_processing(engine: FlightProcessingEngine)` - Triggers async engine.start_processing
|
||||
|
||||
### User Fix Handling
|
||||
- `_validate_fix_request(fix_data: UserFixRequest)` - Validates fix data before delegation
|
||||
- `_apply_fix_to_engine(engine: FlightProcessingEngine, fix_data: UserFixRequest)` - Calls engine.apply_user_fix
|
||||
|
||||
### Stream Management
|
||||
- `_delegate_stream_creation(flight_id: str, client_id: str)` - Delegates to F15
|
||||
|
||||
### Coordinate Conversion
|
||||
- `_delegate_coordinate_transform(flight_id: str, frame_id: int, pixel: Tuple)` - Delegates to F13
|
||||
|
||||
## Unit Tests
|
||||
- Test queue_images delegates to F05.queue_batch
|
||||
- Test queue_images creates new engine if none exists
|
||||
- Test queue_images retrieves existing engine for active flight
|
||||
- Test queue_images triggers engine.start_processing
|
||||
- Test handle_user_fix returns error for non-existent flight
|
||||
- Test handle_user_fix delegates to correct engine
|
||||
- Test create_client_stream delegates to F15
|
||||
- Test convert_object_to_gps delegates to F13
|
||||
- Test engine registry tracks active engines correctly
|
||||
- Test multiple queue_images calls reuse same engine instance
|
||||
|
||||
## Integration Tests
|
||||
- Test queue_images end-to-end with F05 and F02.2
|
||||
- Test image batch flows through F05 to F02.2 processing
|
||||
- Test user fix applied correctly through F02.2
|
||||
- Test SSE stream creation and connection via F15
|
||||
- Test coordinate conversion accuracy via F13
|
||||
- Test engine cleanup on flight completion
|
||||
- Test concurrent requests to same flight share engine
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# Feature: System Initialization
|
||||
|
||||
## Description
|
||||
System startup routine that initializes all dependent components in correct order. Loads configuration, initializes ML models, prepares database connections, sets up satellite cache, and loads place recognition indexes. This is called once at service startup.
|
||||
|
||||
## Component APIs Implemented
|
||||
- `initialize_system() -> bool` - Executes full system initialization sequence
|
||||
|
||||
## External Dependencies
|
||||
- **F17 Configuration Manager** - Configuration loading
|
||||
- **F16 Model Manager** - ML model initialization (SuperPoint, LightGlue, LiteSAM, DINOv2)
|
||||
- **F03 Flight Database** - Database connection initialization
|
||||
- **F04 Satellite Data Manager** - Satellite cache initialization
|
||||
- **F08 Global Place Recognition** - Faiss index loading
|
||||
|
||||
## Internal Methods
|
||||
|
||||
### Initialization Sequence
|
||||
- `_load_configuration()` - Loads config via F17, validates required settings
|
||||
- `_initialize_models()` - Initializes ML models via F16 with TensorRT optimization
|
||||
- `_initialize_database()` - Sets up F03 database connections and schema
|
||||
- `_initialize_satellite_cache()` - Prepares F04 cache with operational region data
|
||||
- `_load_place_recognition_indexes()` - Loads F08 Faiss indexes into memory
|
||||
|
||||
### Health Checks
|
||||
- `_verify_gpu_availability()` - Checks CUDA/TensorRT availability
|
||||
- `_verify_model_loading()` - Validates all models loaded correctly
|
||||
- `_verify_database_connection()` - Tests database connectivity
|
||||
- `_verify_index_integrity()` - Validates Faiss indexes are loadable
|
||||
|
||||
### Error Handling
|
||||
- `_handle_initialization_failure(component: str, error: Exception)` - Logs and handles component init failures
|
||||
- `_rollback_partial_initialization()` - Cleans up on partial initialization failure
|
||||
|
||||
## Unit Tests
|
||||
- Test initialize_system calls F17 config loading
|
||||
- Test initialize_system calls F16 model initialization
|
||||
- Test initialize_system calls F03 database initialization
|
||||
- Test initialize_system calls F04 cache initialization
|
||||
- Test initialize_system calls F08 index loading
|
||||
- Test initialize_system returns False on config load failure
|
||||
- Test initialize_system returns False on model init failure
|
||||
- Test initialize_system returns False on database init failure
|
||||
- Test initialization order is correct (config first, then models, etc.)
|
||||
- Test partial initialization failure triggers rollback
|
||||
|
||||
## Integration Tests
|
||||
- Test full system initialization with all real components
|
||||
- Test system startup on cold start (no cached data)
|
||||
- Test system startup with existing database
|
||||
- Test initialization with GPU unavailable falls back gracefully
|
||||
- Test initialization timeout handling
|
||||
- Test system ready state after successful initialization
|
||||
- Test re-initialization after failure recovery
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# Feature: Frame Processing Loop
|
||||
|
||||
## Description
|
||||
Core frame-by-frame processing orchestration that runs the main visual odometry pipeline. Manages the continuous loop of fetching images, computing poses, updating the factor graph, and publishing results. Includes flight state machine management (Processing, Blocked, Recovering, Completed).
|
||||
|
||||
## Component APIs Implemented
|
||||
- `start_processing(flight_id: str) -> None` - Starts the main processing loop in a background thread/task
|
||||
- `stop_processing(flight_id: str) -> None` - Stops the processing loop gracefully
|
||||
- `process_frame(flight_id: str, frame_id: int) -> FrameResult` - Processes a single frame through the pipeline
|
||||
|
||||
## External Dependencies
|
||||
- **F05 Image Input Pipeline**: `get_next_image()` - Image source
|
||||
- **F06 Image Rotation Manager**: `requires_rotation_sweep()` - Pre-processing checks
|
||||
- **F07 Sequential Visual Odometry**: `compute_relative_pose()` - Motion estimation
|
||||
- **F09 Metric Refinement**: `align_to_satellite()` - Drift correction
|
||||
- **F10 Factor Graph Optimizer**: `add_relative_factor()`, `optimize_chunk()` - State estimation
|
||||
- **F14 Result Manager**: `update_frame_result()` - Saving results
|
||||
|
||||
## Internal Methods
|
||||
- `run_processing_loop(flight_id: str)` - Main loop: while images available, process each frame
|
||||
- `_process_single_frame(flight_id: str, image: Image) -> FrameResult` - Single frame processing pipeline
|
||||
- `_check_tracking_status(vo_result: VOResult) -> bool` - Determines if tracking is good or lost
|
||||
- `_update_flight_status(flight_id: str, status: FlightStatus)` - Updates state machine
|
||||
- `_get_flight_status(flight_id: str) -> FlightStatus` - Gets current flight status
|
||||
- `_is_processing_active(flight_id: str) -> bool` - Checks if processing should continue
|
||||
|
||||
## Unit Tests
|
||||
- Test `start_processing` initiates background loop
|
||||
- Test `stop_processing` gracefully terminates active processing
|
||||
- Test `process_frame` returns valid FrameResult with pose
|
||||
- Test flight status transitions: Processing -> Completed on last frame
|
||||
- Test flight status transitions: Processing -> Blocked on tracking loss
|
||||
- Test processing stops when `stop_processing` called mid-flight
|
||||
- Test processing handles empty image queue gracefully
|
||||
- Test state machine rejects invalid transitions
|
||||
|
||||
## Integration Tests
|
||||
- Test full pipeline: F05 -> F06 -> F07 -> F10 -> F14 flow
|
||||
- Test processing 10 consecutive frames with good tracking
|
||||
- Test real-time result publishing to F14/F15
|
||||
- Test concurrent access to flight status from multiple threads
|
||||
- Test processing resumes after Blocked -> Processing transition
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# Feature: Tracking Loss Recovery
|
||||
|
||||
## Description
|
||||
Handles recovery when visual odometry loses tracking. Implements progressive search strategy through F11 and manages user input workflow when automatic recovery fails. Coordinates the transition to BLOCKED status and back to PROCESSING upon successful recovery.
|
||||
|
||||
## Component APIs Implemented
|
||||
- `handle_tracking_loss(flight_id: str, frame_id: int) -> RecoveryStatus` - Initiates and manages tracking loss recovery
|
||||
- `apply_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResult` - Applies user-provided GPS anchor
|
||||
|
||||
## External Dependencies
|
||||
- **F11 Failure Recovery Coordinator**:
|
||||
- `start_search()` - Initiates progressive search
|
||||
- `try_current_grid()` - Attempts matching on current tile grid
|
||||
- `expand_search_radius()` - Expands search area
|
||||
- `mark_found()` - Marks successful recovery
|
||||
- `create_user_input_request()` - Creates request for user intervention
|
||||
- `apply_user_anchor()` - Applies user-provided anchor
|
||||
- **F15 SSE Event Streamer**: `send_user_input_request()` - Notifies client of required input
|
||||
|
||||
## Internal Methods
|
||||
- `_run_progressive_search(flight_id: str, frame_id: int) -> Optional[RecoveryResult]` - Executes 1->25 tile progressive search
|
||||
- `_request_user_input(flight_id: str, frame_id: int, request: UserInputRequest)` - Transitions to BLOCKED and notifies client
|
||||
- `_validate_user_fix(fix_data: UserFixRequest) -> bool` - Validates user input data
|
||||
- `_apply_fix_and_resume(flight_id: str, fix_data: UserFixRequest) -> UserFixResult` - Applies fix and resumes processing
|
||||
|
||||
## Unit Tests
|
||||
- Test `handle_tracking_loss` starts progressive search via F11
|
||||
- Test progressive search expands from 1 to 25 tiles
|
||||
- Test successful recovery returns RecoveryStatus.FOUND
|
||||
- Test failed recovery transitions status to BLOCKED
|
||||
- Test `apply_user_fix` validates input coordinates
|
||||
- Test `apply_user_fix` returns success on valid anchor
|
||||
- Test `apply_user_fix` transitions status to PROCESSING on success
|
||||
- Test `apply_user_fix` rejects fix when not in BLOCKED status
|
||||
|
||||
## Integration Tests
|
||||
- Test full recovery flow: tracking loss -> progressive search -> found
|
||||
- Test full blocked flow: tracking loss -> search fails -> user input -> resume
|
||||
- Test SSE notification sent when user input required
|
||||
- Test recovery integrates with F11 search grid expansion
|
||||
- Test user fix properly anchors subsequent frame processing
|
||||
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Feature: Chunk Lifecycle Orchestration
|
||||
|
||||
## Description
|
||||
Manages route chunk boundaries and creation during processing. Detects when new chunks should be created (tracking loss, sharp turns) and orchestrates chunk lifecycle through F12. Implements proactive chunk creation strategy where new chunks are created immediately on tracking loss rather than waiting for matching failures.
|
||||
|
||||
## Component APIs Implemented
|
||||
- `get_active_chunk(flight_id: str) -> Optional[ChunkHandle]` - Returns current active chunk for the flight
|
||||
- `create_new_chunk(flight_id: str, frame_id: int) -> ChunkHandle` - Creates new chunk starting at specified frame
|
||||
|
||||
## External Dependencies
|
||||
- **F12 Route Chunk Manager**:
|
||||
- `get_active_chunk()` - Retrieves current chunk
|
||||
- `create_chunk()` - Creates new chunk
|
||||
- `add_frame_to_chunk()` - Adds processed frame to chunk
|
||||
|
||||
## Internal Methods
|
||||
- `_detect_chunk_boundary(flight_id: str, frame_id: int, tracking_status: bool) -> bool` - Determines if chunk boundary detected
|
||||
- `_should_create_chunk_on_tracking_loss(flight_id: str) -> bool` - Checks if proactive chunk creation needed
|
||||
- `_create_chunk_on_tracking_loss(flight_id: str, frame_id: int) -> ChunkHandle` - Creates chunk proactively on tracking loss
|
||||
- `_add_frame_to_active_chunk(flight_id: str, frame_id: int, frame_result: FrameResult)` - Adds frame to current chunk
|
||||
|
||||
## Unit Tests
|
||||
- Test `get_active_chunk` returns current chunk handle
|
||||
- Test `get_active_chunk` returns None when no active chunk
|
||||
- Test `create_new_chunk` delegates to F12 and returns handle
|
||||
- Test chunk boundary detection on tracking loss
|
||||
- Test proactive chunk creation triggers on tracking loss
|
||||
- Test `_add_frame_to_active_chunk` delegates to F12
|
||||
- Test multiple chunks can exist for same flight
|
||||
|
||||
## Integration Tests
|
||||
- Test chunk creation flow: tracking loss -> new chunk -> frames added
|
||||
- Test chunk boundary detection integrates with VO tracking status
|
||||
- Test chunk handles are properly propagated to F10 factor graph
|
||||
- Test chunk lifecycle across multiple tracking loss events
|
||||
- Test chunk state consistency between F02.2 and F12
|
||||
|
||||
Reference in New Issue
Block a user