mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 11:41:12 +00:00
[AZ-219] [AZ-228] Generalize VIO component layout
Keep VIO package and native bridge paths backend-neutral so BASALT remains an implementation choice rather than a component boundary. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -16,7 +16,7 @@
|
||||
| AZ-225 | tile_manager_cache_manifest | 5 | AZ-220, AZ-221, AZ-222 | AZ-211 |
|
||||
| AZ-226 | generated_tile_orthorectification | 5 | AZ-223, AZ-225 | AZ-211 |
|
||||
| AZ-227 | fdr_event_recorder | 5 | AZ-220, AZ-222 | AZ-212 |
|
||||
| AZ-228 | basalt_vio_adapter | 5 | AZ-221, AZ-222, AZ-223, AZ-224 | AZ-213 |
|
||||
| AZ-228 | vio_adapter | 5 | AZ-221, AZ-222, AZ-223, AZ-224 | AZ-213 |
|
||||
| AZ-229 | satellite_service_sync | 3 | AZ-222, AZ-225, AZ-226 | AZ-214 |
|
||||
| AZ-230 | satellite_service_vpr_retrieval | 5 | AZ-223, AZ-225, AZ-229 | AZ-214 |
|
||||
| AZ-231 | anchor_verification_matching | 5 | AZ-223, AZ-225, AZ-230 | AZ-215 |
|
||||
|
||||
@@ -16,10 +16,13 @@ project-root/
|
||||
├── src/
|
||||
│ ├── __init__.py
|
||||
│ ├── camera_ingest_calibration/
|
||||
│ ├── basalt_vio_adapter/
|
||||
│ ├── vio_adapter/
|
||||
│ │ └── native/
|
||||
│ ├── safety_anchor_wrapper/
|
||||
│ ├── satellite_service/
|
||||
│ │ └── native/
|
||||
│ ├── anchor_verification/
|
||||
│ │ └── native/
|
||||
│ ├── tile_manager/
|
||||
│ ├── mavlink_gcs_integration/
|
||||
│ ├── fdr_observability/
|
||||
@@ -30,10 +33,6 @@ project-root/
|
||||
│ │ ├── config/
|
||||
│ │ ├── errors/
|
||||
│ │ └── telemetry/
|
||||
│ └── native/
|
||||
│ ├── basalt_bridge/
|
||||
│ ├── feature_matching/
|
||||
│ └── tensor_rt/
|
||||
├── migrations/
|
||||
│ ├── postgresql/
|
||||
│ └── seed/
|
||||
@@ -74,7 +73,7 @@ project-root/
|
||||
|
||||
### Layout Rationale
|
||||
|
||||
The runtime is organized directly under `src/` because this repository already represents the GPS-denied onboard system. Component directories live at the source root, with native bridges isolated under `src/native/` for BASALT, feature matching, and TensorRT-sensitive paths. Shared contracts, geometry, time-sync, configuration, error envelopes, and telemetry DTOs are centralized so component tasks consume a single public interface instead of duplicating cross-cutting logic.
|
||||
The runtime is organized directly under `src/` because this repository already represents the GPS-denied onboard system. Component directories live at the source root, and native bridges stay inside the component folder that owns the backend or hot path. Shared contracts, geometry, time-sync, configuration, error envelopes, and telemetry DTOs are centralized so component tasks consume a single public interface instead of duplicating cross-cutting logic.
|
||||
|
||||
The scaffold separates runtime source, migrations, tests, deployment assets, configuration, and mutable data. Production runs on Jetson hardware, while Docker/compose is used for replay, SITL, and deterministic CI environments.
|
||||
|
||||
@@ -98,8 +97,8 @@ The scaffold separates runtime source, migrations, tests, deployment assets, con
|
||||
|
||||
| Component | Interface | Methods | Exposed To |
|
||||
|-----------|-----------|---------|------------|
|
||||
| Camera ingest/calibration | `FrameProvider` | `next_frame`, `detect_occlusion`, `classify_quality` | BASALT VIO, Satellite Service, anchor verification, Tile Manager |
|
||||
| BASALT VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, e2e tests |
|
||||
| Camera ingest/calibration | `FrameProvider` | `next_frame`, `detect_occlusion`, `classify_quality` | VIO Adapter, Satellite Service, anchor verification, Tile Manager |
|
||||
| VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, e2e tests |
|
||||
| Safety/anchor wrapper | `LocalizationStateMachine` | `update_vio`, `consider_anchor`, `degrade`, `propagate_imu_only`, `tile_write_eligibility` | MAVLink/GCS, Tile Manager, FDR, e2e tests |
|
||||
| Satellite Service | `SatelliteService` | `import_mission_cache`, `load_index`, `retrieve`, `upload_generated_tiles` | Safety wrapper, anchor verification, Tile Manager |
|
||||
| Anchor verification | `AnchorVerifier` | `verify`, `benchmark_matcher` | Safety wrapper, FDR |
|
||||
@@ -174,7 +173,7 @@ tests/
|
||||
├── unit/
|
||||
│ ├── shared/
|
||||
│ ├── camera_ingest_calibration/
|
||||
│ ├── basalt_vio_adapter/
|
||||
│ ├── vio_adapter/
|
||||
│ ├── safety_anchor_wrapper/
|
||||
│ ├── satellite_service/
|
||||
│ ├── anchor_verification/
|
||||
@@ -245,7 +244,7 @@ Each deployable service exposes `/health/live`, `/health/ready`, and `/metrics`
|
||||
| 5 | MAVLink/GCS integration | Supplies FC telemetry DTOs and validates `GPS_INPUT` output contract early |
|
||||
| 6 | Tile Manager | Owns PostGIS cache manifest, sidecars, COG access, freshness gates, and generated-tile orthorectification |
|
||||
| 7 | FDR/observability | Provides audit path for all components and validation reports |
|
||||
| 8 | BASALT VIO adapter | Depends on frame and telemetry contracts, blocks wrapper integration |
|
||||
| 8 | VIO adapter | Depends on frame and telemetry contracts, blocks wrapper integration |
|
||||
| 9 | Satellite Service | Depends on tile schema and frame DTOs, feeds anchor verification, and handles pre-flight/post-flight package sync |
|
||||
| 10 | Anchor verification | Depends on retrieval candidates and cache tile access |
|
||||
| 11 | Safety/anchor wrapper | Consumes VIO, anchor, camera degradation, MAVLink, and FDR contracts |
|
||||
|
||||
+11
-10
@@ -1,21 +1,21 @@
|
||||
# BASALT VIO Adapter
|
||||
# VIO Adapter
|
||||
|
||||
**Task**: AZ-228_basalt_vio_adapter
|
||||
**Name**: BASALT VIO Adapter
|
||||
**Description**: Wrap BASALT as a replaceable relative VIO component with health and error behavior.
|
||||
**Task**: AZ-228_vio_adapter
|
||||
**Name**: VIO Adapter
|
||||
**Description**: Wrap the selected relative VIO backend as a replaceable component with health and error behavior.
|
||||
**Complexity**: 5 points
|
||||
**Dependencies**: AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry, AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway
|
||||
**Component**: BASALT VIO Adapter
|
||||
**Component**: VIO Adapter
|
||||
**Tracker**: AZ-228
|
||||
**Epic**: AZ-213
|
||||
|
||||
## Problem
|
||||
|
||||
The safety wrapper needs relative VIO state from calibrated frames and FC IMU without inheriting BASALT-specific internals.
|
||||
The safety wrapper needs relative VIO state from calibrated frames and FC IMU without inheriting backend-specific internals.
|
||||
|
||||
## Outcome
|
||||
|
||||
- BASALT initialization, processing, and health behavior are exposed through a replaceable adapter.
|
||||
- Backend initialization, processing, and health behavior are exposed through a replaceable adapter.
|
||||
- Tracking loss and timestamp mismatch are explicit.
|
||||
- The adapter never emits WGS84 coordinates or safety decisions.
|
||||
|
||||
@@ -61,7 +61,7 @@ Then the adapter reports current VIO readiness and degradation state.
|
||||
- Adapter processing must be profiled against Jetson latency/memory limits.
|
||||
|
||||
**Reliability**
|
||||
- BASALT failures are surfaced, not hidden.
|
||||
- Backend failures are surfaced, not hidden.
|
||||
|
||||
## Unit Tests
|
||||
|
||||
@@ -79,11 +79,12 @@ Then the adapter reports current VIO readiness and degradation state.
|
||||
|
||||
## Constraints
|
||||
|
||||
- BASALT is not the safety authority.
|
||||
- BASALT remains the current selected backend, but package and folder names must stay backend-neutral.
|
||||
- The VIO adapter is not the safety authority.
|
||||
- GPL VIO dependencies remain reference-only unless explicitly approved.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
**Risk 1: Nadir fixed-wing fit**
|
||||
- *Risk*: BASALT underperforms on low-parallax terrain.
|
||||
- *Risk*: The selected VIO backend underperforms on low-parallax terrain.
|
||||
- *Mitigation*: Representative replay and reference comparisons gate acceptance.
|
||||
@@ -4,7 +4,7 @@
|
||||
**Name**: Safety Anchor State Machine
|
||||
**Description**: Own authoritative localization state, confidence, anchor fusion, degraded modes, tile-write eligibility, and MAVLink output semantics.
|
||||
**Complexity**: 5 points
|
||||
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway, AZ-227_fdr_event_recorder, AZ-228_basalt_vio_adapter, AZ-231_anchor_verification_matching
|
||||
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway, AZ-227_fdr_event_recorder, AZ-228_vio_adapter, AZ-231_anchor_verification_matching
|
||||
**Component**: Safety And Anchor Wrapper
|
||||
**Tracker**: AZ-232
|
||||
**Epic**: AZ-216
|
||||
@@ -29,7 +29,7 @@ The product needs one safety authority that converts VIO, telemetry, camera qual
|
||||
- Tile-write eligibility decisions.
|
||||
|
||||
### Excluded
|
||||
- BASALT internals.
|
||||
- VIO backend internals.
|
||||
- MAVLink transport implementation.
|
||||
- Generated tile writing.
|
||||
|
||||
@@ -87,7 +87,7 @@ Then only sufficiently trusted poses are eligible for generated tile writes.
|
||||
|
||||
## Constraints
|
||||
|
||||
- BASALT is not the safety authority.
|
||||
- The VIO backend is not the safety authority.
|
||||
- The wrapper does not call Tile Manager directly during anchor acceptance; freshness/provenance arrives through anchor evidence.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
Reference in New Issue
Block a user