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 10:31:12 +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.