Oleksandr Bezdieniezhnykh
e86084da6b
Implement the first runtime component boundaries around the shared contracts so downstream batches can consume typed frame, MAVLink, tile, and FDR behavior with focused tests and batch evidence. Co-authored-by: Cursor <cursoragent@cursor.com>
3.3 KiB
Camera Ingest Calibration And Frame Quality
Task: AZ-223_camera_ingest_calibration Name: Camera Ingest Calibration And Frame Quality Description: Ingest navigation frames, attach calibration/timestamp metadata, classify quality, detect occlusion, and provide north-up normalization hints. Complexity: 5 points Dependencies: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry Component: Camera Ingest And Calibration Tracker: AZ-223 Epic: AZ-209
Problem
Downstream VIO, retrieval, anchor verification, Tile Manager, and FDR need trustworthy frame metadata and quality decisions before using image data.
Outcome
- Replay and live-source frames are exposed with timestamps, calibration ID, quality, occlusion, and normalization hints.
- Total occlusion/blackout frames are marked unusable for VIO and anchor paths.
Scope
Included
- Frame source abstraction for replay/live camera boundary.
- Calibration metadata loading and validation.
- Quality and occlusion reports.
- North-up/orthorectification hints as metadata, not unconditional frame mutation.
Excluded
- Tile writing and generated COG persistence.
- BASALT processing.
Dependencies
Document Dependencies
_docs/02_document/contracts/shared/runtime_contracts.md_docs/02_document/contracts/shared/geometry_time_sync.md_docs/02_document/contracts/shared/config_errors_telemetry.md
Acceptance Criteria
AC-1: Usable frame packet emitted Given a valid replay frame and calibration When the frame is ingested Then a frame packet includes timestamp, calibration ID, quality report, occlusion report, and normalization hint.
AC-2: Blackout bypass signal emitted Given an unreadable, covered, or total-occlusion frame When quality classification runs Then the frame is marked unusable for VIO and anchor matching.
AC-3: Raw frames are not retained Given normal runtime operation When a frame is processed Then only allowed metadata/references are retained outside explicit fixture/test paths.
Non-Functional Requirements
Performance
- Frame preprocessing must fit within the system p95 latency budget.
Reliability
- Missing calibration blocks production readiness.
Unit Tests
| AC Ref | What to Test | Required Outcome |
|---|---|---|
| AC-1 | Valid frame with calibration | Frame packet contains required metadata |
| AC-2 | Total occlusion input | usable_for_vio=false and usable_for_anchor=false |
| AC-3 | Processed frame cleanup | No raw-frame persistence |
Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|---|---|---|---|---|
| AC-1 | Derkachi replay fixture | Frame/telemetry alignment | Accepted frame packets are timestamped | Performance |
| AC-2 | Blackout fixture | Occlusion handling | Visual path degrades safely | Reliability |
Constraints
- Do not rotate every frame in ingest; emit normalization hints for downstream use.
- ADTi hardware assumptions remain blocked until exact specs are verified.
Risks & Mitigation
Risk 1: False-negative occlusion
- Risk: Bad frames enter VIO or matching.
- Mitigation: Conservative occlusion gate and explicit quality flags.