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 09:51: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,96 @@
+# Satellite Retrieval
+
+## 1. High-Level Overview
+
+**Purpose**: Convert a query frame and prior state into ranked satellite/cache VPR chunk candidates using DINOv2-VLAD descriptors and FAISS.
+
+**Architectural Pattern**: Query service / retrieval index adapter.
+
+**Upstream dependencies**: Camera ingest/calibration, cache/tile lifecycle, safety/anchor wrapper.
+
+**Downstream consumers**: Anchor verification, FDR.
+
+## 2. Internal Interfaces
+
+### Interface: `CandidateRetriever`
+
+| Method | Input | Output | Async | Error Types |
+|--------|-------|--------|-------|-------------|
+| `retrieve` | `RetrievalRequest` | `RetrievalResult` | Yes | `IndexUnavailable`, `DescriptorFailed` |
+| `load_index` | `IndexLoadRequest` | `IndexStatus` | No | `ManifestInvalid`, `IndexUnavailable` |
+
+**Input DTOs**:
+
+```yaml
+RetrievalRequest:
+  frame: FramePacket
+  prior_estimate: PositionEstimate optional
+  search_radius_m: number optional
+  max_candidates: integer
+```
+
+**Output DTOs**:
+
+```yaml
+RetrievalResult:
+  query_descriptor_id: string
+  candidates: list[VprCandidate]
+
+VprCandidate:
+  chunk_id: string
+  tile_id: string
+  score: number
+  footprint: geometry
+  freshness_status: enum
+```
+
+## 3. Data Access Patterns
+
+| Query | Frequency | Hot Path | Index Needed |
+|-------|-----------|----------|--------------|
+| Top-K FAISS search | Triggered only | No steady-state | FAISS index |
+| Load chunk metadata | Per candidate | No | PostgreSQL/PostGIS spatial and chunk indexes |
+
+## 4. Implementation Details
+
+**State Management**: Holds loaded descriptor model and FAISS index handles.
+
+**Key Dependencies**:
+
+| Library | Purpose |
+|---------|---------|
+| DINOv2 / ONNX / TensorRT candidate path | Query descriptor extraction |
+| FAISS CPU | Top-K retrieval |
+
+**Error Handling Strategy**:
+- If descriptor extraction or index load fails, return no candidates and trigger degraded mode.
+- Optimized engines are allowed only after descriptor-fidelity tests pass.
+
+## 5. Caveats & Edge Cases
+
+**Known limitations**:
+- VPR result is only a candidate, never an accepted fix.
+- Cross-domain retrieval can be wrong under seasonal, lighting, or terrain ambiguity.
+
+**Performance bottlenecks**:
+- Descriptor extraction on Jetson must be trigger-limited and profiled separately from BASALT.
+
+## 6. Dependency Graph
+
+**Must be implemented after**: cache manifest/index schema, camera frame DTOs.
+
+**Can be implemented in parallel with**: anchor verification.
+
+**Blocks**: satellite relocalization flow.
+
+## 7. Logging Strategy
+
+| Log Level | When | Example |
+|-----------|------|---------|
+| ERROR | Index unavailable | `faiss_index_unavailable id=...` |
+| WARN | No candidates | `vpr_no_candidates frame_id=...` |
+| INFO | Retrieval invoked | `vpr_query candidates=... latency_ms=...` |
+
+**Log format**: FDR structured event.
+
+**Log storage**: FDR segment.
@@ -0,0 +1,153 @@
+# Test Specification — Satellite Retrieval
+
+## Acceptance Criteria Traceability
+
+| AC ID | Acceptance Criterion | Test IDs | Coverage |
+|-------|---------------------|----------|----------|
+| AC-3.2 | Sharp-turn relocalization | IT-02, AT-01 | Covered |
+| AC-3.3 | >=3 disconnected segments | IT-03 | Covered |
+| AC-3.4 | Relocalization request after loss | IT-02 | Covered |
+| AC-4.1 | Trigger path latency | PT-01 | Covered |
+| AC-4.2 | Memory budget | PT-01 | Covered |
+| AC-8.1 | Cache imagery interface | IT-01 | Covered |
+| AC-8.3 | Preloaded/preprocessed cache | IT-01 | Covered |
+| AC-8.6 | VPR chunks, multi-scale, dynamic K | IT-01, IT-04 | Covered |
+| AC-NEW-1 | Cold-start first fix support | PT-02 | Covered |
+| AC-NEW-6 | Freshness-aware retrieval | IT-04, ST-01 | Covered |
+
+## Blackbox Tests
+
+### IT-01: Index Load And Chunk Coverage
+
+**Summary**: Verify preloaded VPR chunks and FAISS index cover the operational area.
+
+**Traces to**: AC-8.1, AC-8.3, AC-8.6
+
+**Input data**: PostgreSQL/PostGIS cache manifest, VPR chunk metadata, FAISS index.
+
+**Expected result**: Every test frame footprint falls inside at least one VPR chunk; fine and coarse descriptors are present where required.
+
+**Max execution time**: 2 minutes per mission cache.
+
+---
+
+### IT-02: Sharp-Turn Retrieval Trigger
+
+**Summary**: Verify sharp-turn state requests candidates rather than relying on frame-to-frame VO.
+
+**Traces to**: AC-3.2, AC-3.4
+
+**Input data**: Wrapper relocalization request with sharp-turn/loss reason.
+
+**Expected result**: Retrieval returns bounded top-K candidates based on sector/covariance policy.
+
+**Max execution time**: 2 seconds per query.
+
+---
+
+### IT-03: Disconnected Segment Retrieval
+
+**Summary**: Verify at least three disconnected segments can each retrieve candidate chunks.
+
+**Traces to**: AC-3.3
+
+**Input data**: Three disconnected query frames with approximate prior/covariance.
+
+**Expected result**: Each query returns a candidate set including the ground-truth region when covered by the cache fixture.
+
+**Max execution time**: Dataset-dependent.
+
+---
+
+### IT-04: Dynamic K And Freshness Filter
+
+**Summary**: Verify K varies by sector and covariance, and stale candidates are tagged.
+
+**Traces to**: AC-8.6, AC-NEW-6
+
+**Input data**: Stable and active-conflict sector cache fixtures with fresh/stale tiles.
+
+**Expected result**: K=5 for stable low-covariance, K=20 for active-conflict, K=50 fallback; stale candidates are flagged for rejection/down-confidence.
+
+**Max execution time**: 2 seconds per query.
+
+## Performance Tests
+
+### PT-01: Retrieval Query Runtime
+
+**Summary**: Verify descriptor extraction and FAISS query fit trigger-path budget.
+
+**Traces to**: AC-4.1, AC-4.2
+
+**Load scenario**:
+- Query set: 100 representative relocalization frames.
+- Environment: Jetson and replay workstation.
+
+| Metric | Target | Failure Threshold |
+|--------|--------|-------------------|
+| Retrieval p95 | <=300 ms trigger path share | >400 ms |
+| Memory contribution | <=2 GB | >3 GB |
+| Candidate count policy | Exact | Any wrong K |
+
+**Resource limits**: Total system memory remains below 8 GB.
+
+---
+
+### PT-02: Cold-Start Index Load
+
+**Summary**: Verify retrieval readiness supports first fix <30 s.
+
+**Traces to**: AC-NEW-1
+
+**Load scenario**:
+- Cold boot 50 runs.
+- Cache/index mounted locally.
+
+| Metric | Target | Failure Threshold |
+|--------|--------|-------------------|
+| Index ready p95 | <=10 s | >15 s |
+| First retrieval p95 | Fits <30 s first-fix budget | Exceeds budget |
+
+## Security Tests
+
+### ST-01: Stale Candidate Handling
+
+**Summary**: Verify stale imagery cannot silently appear as a trusted retrieval candidate.
+
+**Traces to**: AC-NEW-6
+
+**Attack vector**: Manipulated cache manifest marks stale tile as available.
+
+**Test procedure**:
+1. Load cache fixture with stale capture dates.
+2. Query against stale region.
+
+**Expected behavior**: Candidate carries stale status; anchor path cannot accept it as `satellite_anchored`.
+
+**Pass criteria**: 0 stale candidates without explicit stale/down-confidence metadata.
+
+## Acceptance Tests
+
+### AT-01: Relocalization Candidate Returned
+
+**Summary**: Verify a relocalization request returns usable candidates for anchor verification.
+
+**Traces to**: AC-3.2, AC-8.6
+
+| Step | Action | Expected Result |
+|------|--------|-----------------|
+| 1 | Submit sharp-turn query | Retrieval invokes VPR |
+| 2 | Read output | Candidate list includes chunk IDs, tile IDs, scores, footprints, freshness |
+
+## Test Data Management
+
+| Data Set | Description | Source | Size |
+|----------|-------------|--------|------|
+| `cache_vpr_fixture` | PostGIS manifest, COGs, descriptors, FAISS index | Generated/cache fixture | Mission-dependent |
+| `aerial_vpr_queries` | Aerial query frames with ground-truth regions | ALTO/AerialVL/representative | Dataset-dependent |
+
+**Setup procedure**: Restore isolated PostgreSQL schema and mount read-only descriptor/index files.
+
+**Teardown procedure**: Drop schema and remove generated retrieval reports.
+
+**Data isolation strategy**: Per-run schema and read-only cache fixture volume.