# 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.