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.

3.3 KiB Raw Blame History