Refactor documentation to replace the Validation Harness with a separate E2E Test Suite, updating references throughout various documents. Adjust the autodev state to reflect the transition from the Decompose phase to the Implement phase, and revise the architecture documentation to clarify system boundaries and component relationships. Enhance risk mitigation documentation to specify affected components and update the component overview diagram accordingly.

This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 11:50:39 +03:00
parent 5bf2dbd85f
commit dd9afe2797
31 changed files with 1479 additions and 396 deletions
@@ -0,0 +1,89 @@
# 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.