Revise acceptance criteria and restrictions documentation to clarify recent updates and specifications. Key changes include enhanced definitions for position accuracy, image processing quality, and operational parameters, as well as updates to camera specifications and validation requirements. This revision aims to improve clarity and ensure alignment with project goals.

2026-06-22 10:51:13 +00:00 · 2026-05-01 16:24:46 +03:00
parent 3f173c1bb7
commit 7e15868d39
62 changed files with 6878 additions and 13 deletions
@@ -0,0 +1,115 @@
+# Camera Ingest And Calibration
+
+## 1. High-Level Overview
+
+**Purpose**: Ingest navigation-camera frames, attach timestamps and calibration metadata, undistort/normalize imagery, detect total occlusion/blackout before VIO, and classify image quality before VIO or satellite matching consumes it.
+
+**Architectural Pattern**: Streaming adapter + validation gate.
+
+**Upstream dependencies**: Navigation camera, camera calibration files.
+
+**Downstream consumers**: BASALT VIO adapter, satellite retrieval, anchor verification, cache/tile lifecycle, FDR.
+
+## 2. Internal Interfaces
+
+### Interface: `FrameProvider`
+
+| Method | Input | Output | Async | Error Types |
+|--------|-------|--------|-------|-------------|
+| `next_frame` | `FrameRequest` | `FramePacket` | Yes | `FrameUnavailable`, `CalibrationMissing`, `InvalidFrame` |
+| `detect_occlusion` | `FramePacket` | `OcclusionReport` | No | `InvalidFrame` |
+| `classify_quality` | `FramePacket` | `ImageQualityReport` | No | `InvalidFrame` |
+
+**Input DTOs**:
+
+```yaml
+FrameRequest:
+  source: enum(live_camera, replay_file)
+  timestamp_ns: integer optional
+```
+
+**Output DTOs**:
+
+```yaml
+FramePacket:
+  frame_id: string
+  timestamp_ns: integer
+  image_ref: path_or_buffer
+  camera_calibration_id: string
+  altitude_hint_m: number optional
+  occlusion: OcclusionReport
+  quality: ImageQualityReport
+
+OcclusionReport:
+  status: enum(clear, partial_occlusion, total_occlusion, blackout)
+  reason: enum(cloud, lens_cover, whiteout, decode_failure, underexposed, overexposed, unknown) optional
+  usable_for_vio: boolean
+  usable_for_anchor: boolean
+
+ImageQualityReport:
+  usable_for_vio: boolean
+  usable_for_anchor: boolean
+  blackout_detected: boolean
+  blur_score: number
+  texture_score: number
+```
+
+## 3. Data Access Patterns
+
+| Query | Frequency | Hot Path | Index Needed |
+|-------|-----------|----------|--------------|
+| Load calibration by ID | Startup | Yes | No |
+| Read replay frame | Test/replay | Yes | File order |
+
+## 4. Implementation Details
+
+**State Management**: Maintains current camera calibration version and frame sequence state.
+
+**Key Dependencies**:
+
+| Library | Purpose |
+|---------|---------|
+| OpenCV | Decode, undistort, homography support, image metrics |
+| Camera SDK / V4L2 / GigE SDK | Live camera access once interface is selected |
+
+**Error Handling Strategy**:
+- Camera or decode errors emit degraded quality and FDR events.
+- Total occlusion or blackout sets `usable_for_vio=false`, bypasses BASALT for that frame, and emits a degradation signal to the safety/anchor wrapper.
+- Missing calibration blocks production startup.
+- ADTi public spec mismatch is tracked as a verification blocker until manufacturer spec is pinned.
+
+## 5. Extensions and Helpers
+
+| Helper | Purpose | Used By |
+|--------|---------|---------|
+| `geo_geometry_helper` | Coordinate transforms, GSD, WGS84/local conversions | Camera ingest, safety wrapper, cache lifecycle |
+
+## 6. Caveats & Edge Cases
+
+**Known limitations**:
+- Public ADTi pages list 2 fps continuous capture and -10..40 C operating range; project assumptions need manufacturer verification.
+- Live camera interface is TBD.
+- Total occlusion detection must be conservative: false positives cause temporary IMU-only degradation, while false negatives can feed unusable frames into VIO.
+
+**Performance bottlenecks**:
+- Full-resolution preprocessing must stay inside the <400 ms p95 pipeline budget.
+
+## 7. Dependency Graph
+
+**Must be implemented after**: none.
+
+**Can be implemented in parallel with**: cache/tile lifecycle, MAVLink/GCS integration.
+
+**Blocks**: BASALT VIO adapter, anchor verification, generated tile lifecycle.
+
+## 8. Logging Strategy
+
+| Log Level | When | Example |
+|-----------|------|---------|
+| ERROR | Camera unavailable or calibration missing | `camera_calibration_missing id=...` |
+| WARN | Frame degraded or occluded | `frame_quality_degraded occlusion=total_occlusion blur=... texture=...` |
+| INFO | Calibration loaded | `camera_calibration_loaded version=...` |
+
+**Log format**: FDR structured event.
+
+**Log storage**: FDR segment and health log.
@@ -0,0 +1,139 @@
+# Test Specification — Camera Ingest And Calibration
+
+## Acceptance Criteria Traceability
+
+| AC ID | Acceptance Criterion | Test IDs | Coverage |
+|-------|---------------------|----------|----------|
+| AC-2.1a | VO registration uses only normal usable frames | IT-01, AT-01 | Covered |
+| AC-3.5 | Visual blackout switches to degraded mode quickly | IT-02, AT-02 | Covered |
+| AC-4.1 | Capture-to-output latency budget | PT-01 | Covered |
+| AC-4.2 | Jetson memory budget | PT-01 | Covered |
+| AC-8.4 | Mid-flight tile generation input eligibility | IT-03 | Covered |
+| AC-8.5 | No raw frame retention | ST-01 | Covered |
+| AC-NEW-8 | Full blackout/occlusion degraded-mode trigger | IT-02, AT-02 | Covered |
+
+## Blackbox Tests
+
+### IT-01: Usable Frame Classification
+
+**Summary**: Verify normal nadir frames are marked usable for VIO and anchor matching.
+
+**Traces to**: AC-2.1a
+
+**Input data**: Project still images plus calibration metadata.
+
+**Expected result**: `FramePacket.quality.usable_for_vio=true`, `usable_for_anchor=true`, and `occlusion.status=clear` for normal daytime textured frames.
+
+**Max execution time**: 100 ms per frame.
+
+**Dependencies**: Calibration file, replay fixture.
+
+---
+
+### IT-02: Total Occlusion Gate Before VIO
+
+**Summary**: Verify total occlusion is detected before BASALT receives the frame.
+
+**Traces to**: AC-3.5, AC-NEW-8
+
+**Input data**: Black/white/covered-lens frames, corrupt frame fixture, low-texture whiteout frames.
+
+**Expected result**: `occlusion.status` is `total_occlusion` or `blackout`, `usable_for_vio=false`, `usable_for_anchor=false`, and a degradation signal is emitted to the safety wrapper.
+
+**Max execution time**: 100 ms per frame.
+
+**Dependencies**: Safety wrapper test double.
+
+---
+
+### IT-03: Tile Generation Eligibility Metadata
+
+**Summary**: Verify frame metadata required for generated tiles is available without persisting raw frames.
+
+**Traces to**: AC-8.4, AC-8.5
+
+**Input data**: Valid frame, altitude hint, calibration, pose fixture.
+
+**Expected result**: Frame metadata supports orthorectification handoff; raw frame is not retained after processing outside allowed FDR thumbnail exception.
+
+**Max execution time**: 100 ms per frame.
+
+**Dependencies**: Cache lifecycle test double.
+
+## Performance Tests
+
+### PT-01: Ingest And Quality Latency
+
+**Summary**: Verify decode, calibration lookup, occlusion detection, and quality classification stay inside the system latency budget.
+
+**Traces to**: AC-4.1, AC-4.2
+
+**Load scenario**:
+- Input rate: target camera/replay rate.
+- Duration: 30 minutes replay.
+- Dataset: project still images plus synthetic occlusion frames.
+
+| Metric | Target | Failure Threshold |
+|--------|--------|-------------------|
+| Per-frame ingest p95 | <=100 ms | >150 ms |
+| Memory contribution | <=1 GB | >1.5 GB |
+| Dropped frames | <=10% under sustained load | >10% |
+
+**Resource limits**: Jetson shared memory remains below system 8 GB cap.
+
+## Security Tests
+
+### ST-01: Raw Frame Retention Check
+
+**Summary**: Verify normal operation does not persist raw navigation frames.
+
+**Traces to**: AC-8.5
+
+**Attack vector**: Sensitive raw imagery remains on disk after processing.
+
+**Test procedure**:
+1. Run replay with normal and failed tile-generation frames.
+2. Inspect output directories and FDR artifacts.
+
+**Expected behavior**: Only metadata, generated tiles, and allowed low-rate failed-frame thumbnails are retained.
+
+**Pass criteria**: No raw full-resolution frames remain after teardown.
+
+## Acceptance Tests
+
+### AT-01: Normal Frame Enters VIO
+
+**Summary**: Confirm normal usable frames are passed to BASALT.
+
+**Traces to**: AC-2.1a
+
+| Step | Action | Expected Result |
+|------|--------|-----------------|
+| 1 | Feed a calibrated normal frame | Occlusion status is `clear` |
+| 2 | Process quality gate | Frame is emitted to BASALT adapter |
+
+---
+
+### AT-02: Occluded Frame Bypasses VIO
+
+**Summary**: Confirm full occlusion triggers IMU-only degraded path.
+
+**Traces to**: AC-3.5, AC-NEW-8
+
+| Step | Action | Expected Result |
+|------|--------|-----------------|
+| 1 | Feed total-occlusion frame | `usable_for_vio=false` |
+| 2 | Observe downstream routing | BASALT is bypassed and safety wrapper receives degradation signal |
+
+## Test Data Management
+
+| Data Set | Description | Source | Size |
+|----------|-------------|--------|------|
+| `project_60_still_images` | Normal nadir frames | `_docs/00_problem/input_data/` | Project data |
+| `synthetic_occlusion_frames` | Black/white/corrupt/whiteout frames | Generated fixture | Small |
+
+**Setup procedure**: Load calibration fixture and mount read-only frame data.
+
+**Teardown procedure**: Remove run-scoped temp directories and verify no raw-frame persistence.
+
+**Data isolation strategy**: Each run writes to a unique `test-results/<run-id>/` directory.