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 11:01: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,93 @@
+# Anchor Verification
+
+## 1. High-Level Overview
+
+**Purpose**: Verify retrieved cache candidates with local feature matching and geometric checks before the safety wrapper considers an absolute anchor.
+
+**Architectural Pattern**: Validation pipeline.
+
+**Upstream dependencies**: Satellite retrieval, camera ingest/calibration, cache/tile lifecycle.
+
+**Downstream consumers**: Safety/anchor wrapper, FDR.
+
+## 2. Internal Interfaces
+
+### Interface: `AnchorVerifier`
+
+| Method | Input | Output | Async | Error Types |
+|--------|-------|--------|-------|-------------|
+| `verify` | `AnchorVerificationRequest` | `AnchorDecision` | Yes | `TileUnavailable`, `MatchFailed`, `GeometryFailed` |
+| `benchmark_matcher` | `MatcherBenchmarkRequest` | `MatcherBenchmarkReport` | Yes | `ModelUnavailable` |
+
+**Input DTOs**:
+
+```yaml
+AnchorVerificationRequest:
+  frame: FramePacket
+  candidates: list[VprCandidate]
+  matcher_profile: enum(aliked, disk, sift_orb_baseline)
+```
+
+**Output DTOs**:
+
+```yaml
+AnchorDecision:
+  candidate_id: string
+  accepted_by_geometry: boolean
+  estimated_pose_wgs84: object optional
+  inlier_count: integer
+  mre_px: number
+  homography: matrix optional
+  rejection_reason: string optional
+```
+
+## 3. Data Access Patterns
+
+| Query | Frequency | Hot Path | Index Needed |
+|-------|-----------|----------|--------------|
+| Read candidate COG footprint/window | Triggered only | No | Tile spatial metadata |
+| Read matcher model | Startup | No | No |
+
+## 4. Implementation Details
+
+**State Management**: Loads matcher/extractor models and tracks benchmark-selected profile.
+
+**Key Dependencies**:
+
+| Library | Purpose |
+|---------|---------|
+| ALIKED/DISK + LightGlue | Learned local matching |
+| OpenCV | RANSAC/USAC geometry and error metrics |
+
+**Error Handling Strategy**:
+- Low inlier count, high MRE, stale tile, or provenance failure returns a rejected decision with reason.
+- SuperPoint can be benchmarked only if legal approval allows its license use.
+
+## 5. Caveats & Edge Cases
+
+**Known limitations**:
+- ALIKED-LightGlue is not VIO by itself; it supplies correspondences. A full VIO path still needs state estimation and IMU fusion.
+- Optional frame-to-frame VO fallback must be benchmarked separately from cross-domain anchor verification.
+
+**Performance bottlenecks**:
+- Learned matching can exceed the Jetson budget if run per-frame; default invocation is trigger-based.
+
+## 6. Dependency Graph
+
+**Must be implemented after**: satellite retrieval candidate DTOs, cache tile access.
+
+**Can be implemented in parallel with**: BASALT VIO adapter.
+
+**Blocks**: accepted satellite-anchor path.
+
+## 7. Logging Strategy
+
+| Log Level | When | Example |
+|-----------|------|---------|
+| ERROR | Matcher model unavailable | `lightglue_model_unavailable profile=aliked` |
+| WARN | Candidate rejected | `anchor_geometry_rejected mre_px=... inliers=...` |
+| INFO | Anchor verified | `anchor_verified tile_id=... mre_px=...` |
+
+**Log format**: FDR structured event.
+
+**Log storage**: FDR segment.
@@ -0,0 +1,124 @@
+# Test Specification — Anchor Verification
+
+## Acceptance Criteria Traceability
+
+| AC ID | Acceptance Criterion | Test IDs | Coverage |
+|-------|---------------------|----------|----------|
+| AC-1.1 | 50 m frame-center accuracy via accepted anchors | AT-01 | Covered |
+| AC-1.2 | 20 m stretch accuracy via accepted anchors | AT-01 | Covered |
+| AC-2.1b | Satellite-anchor registration measured separately | IT-01 | Covered |
+| AC-2.2 | <2.5 px cross-domain MRE | IT-01, AT-01 | Covered |
+| AC-3.1 | Outlier rejection | ST-01 | Covered |
+| AC-4.1 | Trigger-path latency | PT-01 | Covered |
+| AC-4.2 | Memory budget | PT-01 | Covered |
+| AC-NEW-4 | False-position safety budget | ST-01 | Covered |
+| AC-NEW-6 | Stale imagery rejection evidence | IT-02, ST-02 | Covered |
+
+## Blackbox Tests
+
+### IT-01: Cross-Domain Match And RANSAC
+
+**Summary**: Verify ALIKED/DISK-LightGlue plus RANSAC produces measurable anchor evidence.
+
+**Traces to**: AC-2.1b, AC-2.2
+
+**Input data**: UAV frame, retrieved COG candidate window, ground-truth georegistration.
+
+**Expected result**: Accepted anchors have MRE <2.5 px, sufficient inliers, and homography/pose evidence.
+
+**Max execution time**: 2 seconds per candidate set.
+
+---
+
+### IT-02: Stale Candidate Verification
+
+**Summary**: Verify stale or provenance-failed candidates are rejected or marked unsafe.
+
+**Traces to**: AC-NEW-6
+
+**Input data**: Candidate list with stale tile metadata and valid-looking image content.
+
+**Expected result**: `AnchorDecision` is rejected or carries stale/provenance failure; safety wrapper cannot accept it as trusted.
+
+**Max execution time**: 2 seconds per candidate.
+
+## Performance Tests
+
+### PT-01: Local Matcher Runtime
+
+**Summary**: Verify learned matching stays bounded on Jetson when invoked.
+
+**Traces to**: AC-4.1, AC-4.2
+
+**Load scenario**:
+- Candidate sets: K=5, K=20, K=50.
+- Matcher profiles: ALIKED, DISK, SIFT/ORB baseline.
+
+| Metric | Target | Failure Threshold |
+|--------|--------|-------------------|
+| K=5 p95 | <=300 ms | >500 ms |
+| K=20 p95 | Reported and bounded | Unbounded/no report |
+| Memory contribution | <=2 GB | >3 GB |
+
+**Resource limits**: Total Jetson shared memory remains below 8 GB.
+
+## Security Tests
+
+### ST-01: False Match / Impossible Jump Rejection
+
+**Summary**: Verify visually plausible but geographically impossible matches are rejected.
+
+**Traces to**: AC-3.1, AC-NEW-4
+
+**Attack vector**: Candidate tile from wrong region with repetitive texture.
+
+**Test procedure**:
+1. Pair query with wrong-region candidate.
+2. Run matcher and RANSAC.
+3. Pass result to safety wrapper fixture.
+
+**Expected behavior**: Anchor is rejected by geometry or downstream consistency gates.
+
+**Pass criteria**: 0 accepted anchors from wrong-region fixtures.
+
+---
+
+### ST-02: Provenance Failure
+
+**Summary**: Verify unsigned/hash-failed candidate tiles cannot produce accepted anchors.
+
+**Traces to**: AC-NEW-6
+
+**Attack vector**: Tampered COG or sidecar.
+
+**Test procedure**: Run verification against tampered tile fixture.
+
+**Expected behavior**: `AnchorDecision` includes provenance failure and is not accepted.
+
+**Pass criteria**: 0 trusted anchors from tampered tiles.
+
+## Acceptance Tests
+
+### AT-01: Accepted Anchor Accuracy
+
+**Summary**: Verify accepted anchors support position accuracy thresholds.
+
+**Traces to**: AC-1.1, AC-1.2, AC-2.2
+
+| Step | Action | Expected Result |
+|------|--------|-----------------|
+| 1 | Verify satellite candidate against query | MRE <2.5 px |
+| 2 | Convert accepted anchor to WGS84 evidence | Error supports 50 m / 20 m aggregate thresholds |
+
+## Test Data Management
+
+| Data Set | Description | Source | Size |
+|----------|-------------|--------|------|
+| `anchor_match_fixture` | Query frames, COG windows, expected georegistration | ALTO/AerialVL/project cache | Dataset-dependent |
+| `tampered_tile_fixture` | Hash/signature/stale cases | Generated fixture | Small |
+
+**Setup procedure**: Load cache fixture and matcher model profile.
+
+**Teardown procedure**: Remove matcher outputs and reports.
+
+**Data isolation strategy**: Read-only imagery with per-run output folders.