mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 08:21:13 +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
@@ -9,7 +9,7 @@
|
||||
|
||||
1. Each product component owns one top-level directory under `src/`.
|
||||
2. Shared contracts and cross-cutting helpers live under `src/shared/`.
|
||||
3. Native hot-path or third-party bridge code lives under `src/native/` and is owned by the component that wraps it.
|
||||
3. Native hot-path or third-party bridge code lives inside the owning component folder under `native/`.
|
||||
4. Public API surface per component is limited to `__init__.py`, `types.py`, and `interfaces.py` unless a component entry lists another public file.
|
||||
5. Tests live under `tests/` by test type and component; implementation tasks must not place tests inside the component tree unless a later test task explicitly changes this layout.
|
||||
|
||||
@@ -29,25 +29,24 @@
|
||||
- `src/camera_ingest_calibration/_*.py`
|
||||
- **Owns (exclusive write during implementation)**: `src/camera_ingest_calibration/**`
|
||||
- **Imports from**: shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: BASALT VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability
|
||||
- **Consumed by**: VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability
|
||||
|
||||
### Component: BASALT VIO Adapter
|
||||
### Component: VIO Adapter
|
||||
|
||||
- **Epic**: AZ-213
|
||||
- **Directory**: `src/basalt_vio_adapter/`
|
||||
- **Native Directory**: `src/native/basalt_bridge/`
|
||||
- **Technologies**: Python adapter, C++ native bridge, BASALT, Eigen/Sophus or BASALT math stack, OpenCV 4.x, shared time-sync contracts
|
||||
- **Directory**: `src/vio_adapter/`
|
||||
- **Native Directory**: `src/vio_adapter/native/`
|
||||
- **Technologies**: Python adapter, C++ native bridge, BASALT as current backend, Eigen/Sophus or backend-native math stack, OpenCV 4.x, shared time-sync contracts
|
||||
- **Public API**:
|
||||
- `src/basalt_vio_adapter/__init__.py`
|
||||
- `src/basalt_vio_adapter/types.py`
|
||||
- `src/basalt_vio_adapter/interfaces.py`
|
||||
- `src/vio_adapter/__init__.py`
|
||||
- `src/vio_adapter/types.py`
|
||||
- `src/vio_adapter/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/basalt_vio_adapter/internal/*`
|
||||
- `src/basalt_vio_adapter/_*.py`
|
||||
- `src/native/basalt_bridge/**`
|
||||
- `src/vio_adapter/internal/*`
|
||||
- `src/vio_adapter/_*.py`
|
||||
- `src/vio_adapter/native/**`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/basalt_vio_adapter/**`
|
||||
- `src/native/basalt_bridge/**`
|
||||
- `src/vio_adapter/**`
|
||||
- **Imports from**: Camera Ingest And Calibration, MAVLink And GCS Integration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability
|
||||
|
||||
@@ -64,14 +63,14 @@
|
||||
- `src/safety_anchor_wrapper/internal/*`
|
||||
- `src/safety_anchor_wrapper/_*.py`
|
||||
- **Owns (exclusive write during implementation)**: `src/safety_anchor_wrapper/**`
|
||||
- **Imports from**: BASALT VIO Adapter, Anchor Verification, MAVLink And GCS Integration, Camera Ingest And Calibration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Imports from**: VIO Adapter, Anchor Verification, MAVLink And GCS Integration, Camera Ingest And Calibration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: MAVLink And GCS Integration, Tile Manager, FDR And Observability
|
||||
|
||||
### Component: Satellite Service
|
||||
|
||||
- **Epic**: AZ-214
|
||||
- **Directory**: `src/satellite_service/`
|
||||
- **Native Directory**: `src/native/tensor_rt/`
|
||||
- **Native Directory**: `src/satellite_service/native/`
|
||||
- **Technologies**: Python service adapter, DINOv2-VLAD descriptors, ONNX/TensorRT candidate path, CPU FAISS, offline package sync client
|
||||
- **Public API**:
|
||||
- `src/satellite_service/__init__.py`
|
||||
@@ -80,10 +79,9 @@
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/satellite_service/internal/*`
|
||||
- `src/satellite_service/_*.py`
|
||||
- `src/native/tensor_rt/**`
|
||||
- `src/satellite_service/native/**`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/satellite_service/**`
|
||||
- `src/native/tensor_rt/**`
|
||||
- **Imports from**: Camera Ingest And Calibration, Tile Manager, Safety And Anchor Wrapper, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Anchor Verification, FDR And Observability
|
||||
- **Network invariant**: external Satellite Service sync is allowed only pre-flight or post-flight; no mid-flight satellite-provider or suite-service calls.
|
||||
@@ -92,7 +90,7 @@
|
||||
|
||||
- **Epic**: AZ-215
|
||||
- **Directory**: `src/anchor_verification/`
|
||||
- **Native Directory**: `src/native/feature_matching/`
|
||||
- **Native Directory**: `src/anchor_verification/native/`
|
||||
- **Technologies**: Python validation pipeline, ALIKED/DISK + LightGlue, OpenCV RANSAC/USAC, SIFT/ORB baseline, native feature-matching bridge
|
||||
- **Public API**:
|
||||
- `src/anchor_verification/__init__.py`
|
||||
@@ -101,10 +99,9 @@
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/anchor_verification/internal/*`
|
||||
- `src/anchor_verification/_*.py`
|
||||
- `src/native/feature_matching/**`
|
||||
- `src/anchor_verification/native/**`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/anchor_verification/**`
|
||||
- `src/native/feature_matching/**`
|
||||
- **Imports from**: Satellite Service, Camera Ingest And Calibration, Tile Manager, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability
|
||||
|
||||
@@ -141,7 +138,7 @@
|
||||
- `src/mavlink_gcs_integration/_*.py`
|
||||
- **Owns (exclusive write during implementation)**: `src/mavlink_gcs_integration/**`
|
||||
- **Imports from**: Safety And Anchor Wrapper, shared/contracts, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: BASALT VIO Adapter, Safety And Anchor Wrapper, FDR And Observability
|
||||
- **Consumed by**: VIO Adapter, Safety And Anchor Wrapper, FDR And Observability
|
||||
|
||||
### Component: FDR And Observability
|
||||
|
||||
@@ -189,7 +186,7 @@
|
||||
- **Technologies**: Python timestamp utilities, monotonic-clock validation, MAVLink/camera timestamp normalization, replay ordering checks
|
||||
- **Purpose**: Monotonic timestamp checks, frame-to-IMU alignment, clock-domain metadata, replay ordering, and gap/jitter metrics.
|
||||
- **Owned by**: time-sync task under AZ-207.
|
||||
- **Consumed by**: Camera Ingest And Calibration, BASALT VIO Adapter, MAVLink And GCS Integration, FDR And Observability.
|
||||
- **Consumed by**: Camera Ingest And Calibration, VIO Adapter, MAVLink And GCS Integration, FDR And Observability.
|
||||
|
||||
### shared/config
|
||||
|
||||
@@ -225,7 +222,7 @@ Read top-to-bottom; an upper layer may import from a lower layer but never the r
|
||||
| Layer | Components | May import from |
|
||||
|-------|------------|-----------------|
|
||||
| 4. Runtime Output / Coordination | Safety And Anchor Wrapper, MAVLink And GCS Integration, FDR And Observability | 1, 2, 3 public interfaces |
|
||||
| 3. Perception / Satellite Anchor | BASALT VIO Adapter, Satellite Service, Anchor Verification | 1, 2 public interfaces |
|
||||
| 3. Perception / Satellite Anchor | VIO Adapter, Satellite Service, Anchor Verification | 1, 2 public interfaces |
|
||||
| 2. Data Ingest / Persistence | Camera Ingest And Calibration, Tile Manager | 1 |
|
||||
| 1. Shared / Foundation | shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry | none |
|
||||
|
||||
@@ -242,5 +239,5 @@ The e2e replay/SITL/Jetson validation suite is not a product component and must
|
||||
- Every runtime component under `_docs/02_document/components/` has a mapping entry.
|
||||
- Cross-cutting epics AZ-206, AZ-207, and AZ-208 have shared ownership entries.
|
||||
- Layering covers all components and keeps shared code at the bottom.
|
||||
- Component-owned paths do not overlap, except explicitly assigned native directories.
|
||||
- Component-owned paths do not overlap; native bridge paths live inside the component that owns them.
|
||||
- Paths follow the project `src/` layout already confirmed by `AZ-219_initial_structure`.
|
||||
|
||||
Reference in New Issue
Block a user