mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 08:41:13 +00:00
Update demo replay validation and testing documentation
ci/woodpecker/push/02-build-push Pipeline failed
ci/woodpecker/push/02-build-push Pipeline failed
- Modified the autodev state to reflect the current testing phase and details of the new `jetson-e2e` tests. - Enhanced the "How to Test" documentation to provide clearer instructions on the demo replay validation process, including video and tlog alignment steps. - Updated architectural documentation to include the new demo replay operator flow and its dependencies. - Documented the removal of deprecated auto-sync features and clarified the operator-facing UI for replay validation. - Added new entries in the dependencies table for upcoming tasks related to the demo replay flow. These changes improve clarity and usability for operators and developers working with the demo replay system.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -19,6 +19,7 @@
|
||||
| F8 | Companion reboot recovery | Companion process restart while FC remains armed | C8 (FC IMU pose ingest), C5, C10 (warm-cache verify), C13 | Medium |
|
||||
| F9 | GCS telemetry stream | Per-frame estimate available + GCS link healthy | C5, C8, [[QGroundControl]] | Medium |
|
||||
| F10 | Post-landing tile upload | Operator triggers C12 `PostLandingUploadOrchestrator`; orchestrator confirms `flight_footer.clean_shutdown == True` and invokes C11 `TileUploader` | C12 `PostLandingUploadOrchestrator` (operator-side; reads FDR footer), C11 `TileUploader` (operator-side), C6 (read), [[`satellite-provider`]] (D-PROJ-2 endpoint, planned) | High |
|
||||
| F11 | Demo replay validation (operator) | Operator uploads `(video, tlog, calibration)` in suite UI; aligns timelines; runs full GPS-denied replay verdict | [[`suite/ui`]] (AZ-897), `replay_api` (AZ-973), `replay_input` (AZ-970–972), C12 `seed-cache-from-tlog` (AZ-974), C11 route seed, C10, airborne replay (`config.mode=replay`) | High |
|
||||
|
||||
## Flow Dependencies
|
||||
|
||||
@@ -34,6 +35,7 @@
|
||||
| F8 | F1 + F2 (warm cache survives reboot via content-hash verify) | F3 (resumes once warm), F5 (degraded mode if recovery fails) |
|
||||
| F9 | F3 | n/a (read-only outbound) |
|
||||
| F10 | F4 (locally-saved tiles), C13 `flight_footer` written on clean shutdown, parent-suite D-PROJ-2 endpoint availability | F1 of the next flight (uploaded tiles enter the basemap once promoted to `trusted`) |
|
||||
| F11 | F1 route-driven variant (AZ-974) OR warm cache; E-DEMO-REPLAY (AZ-265) | F1 (corridor cache), replay JSONL + map artifacts consumed by suite UI |
|
||||
|
||||
**Cross-cutting**: F13 FDR-write is not a flow per se — every flow above has an FDR write side-effect. AC-NEW-3 requires every payload class (estimate, IMU, MAVLink, mid-flight tile, system health, failed-tile thumbnail) to be present; rollover is logged, never silent.
|
||||
|
||||
@@ -53,7 +55,7 @@ This flow is offline and not time-critical. **Only Phase 0 reaches `flights` RES
|
||||
|
||||
#### Phase 1 variant — route-driven seeding (cycle 3 — Epic AZ-835 / AZ-836 + AZ-838 + AZ-839)
|
||||
|
||||
A tlog-driven alternative to bbox download lets the operator (or the post-flight replay harness) pre-commit the cache to the precise corridor the drone actually flew. The path is exercised today by the e2e fixture `tests/e2e/replay/conftest.py::operator_pre_flight_setup` (AZ-839) and the orchestrator test `tests/e2e/replay/test_az835_e2e_real_flight.py` (AZ-840); the C12 production CLI binding for this variant is deferred to a future cycle.
|
||||
A tlog-driven alternative to bbox download lets the operator pre-commit the cache to the precise corridor the drone actually flew. **Production bindings** (Epic AZ-969): C12 `seed-cache-from-tlog` (AZ-974) and the `replay_api` demo job (AZ-973) call the same `operator_replay.cache_seed` module. The e2e fixture `operator_pre_flight_setup` (AZ-839) is a thin wrapper over that production path — not a parallel implementation.
|
||||
|
||||
Phase-1 sub-steps in the route-driven variant (replaces the bbox download for that invocation):
|
||||
|
||||
@@ -1083,6 +1085,96 @@ flowchart TD
|
||||
|
||||
---
|
||||
|
||||
## Flow F11: Demo replay validation (operator)
|
||||
|
||||
### Description
|
||||
|
||||
Post-flight **product demo** and **validation** flow. The operator uploads a nav-camera video and ArduPilot `.tlog` through the suite UI (AZ-897), visually aligns the two recordings on dual timeline bars, and runs the same airborne GPS-denied pipeline used in live flight — against a corridor cache seeded from the tlog GPS trace. Output: per-tick estimated positions (JSONL), accuracy map, and PASS/FAIL verdict against tlog ground truth (AZ-696 AC-3).
|
||||
|
||||
This is **not** a test-harness shortcut. E2E tests (AZ-840) call the same `replay_api` orchestration (AZ-973) and `operator_replay.cache_seed` (AZ-974) as the UI.
|
||||
|
||||
**Phases** (sequenced by `replay_api` demo job or manual CLI equivalents):
|
||||
|
||||
1. **Preview** (AZ-970) — parse tlog IMU2 activity + video metadata for UI timelines.
|
||||
2. **Align** (AZ-897 + AZ-971) — operator coarse offset; backend refine via optical-flow + IMU cross-correlation.
|
||||
3. **Export** (AZ-972) — write AZ-896 canonical CSV with `Time=0` at aligned video frame 0 (single canonical clock for replay).
|
||||
4. **Seed cache** (AZ-974) — `extract_route_from_tlog` → `SatelliteProviderRouteClient.seed_route` → tile download → FAISS build (F1 route-driven variant).
|
||||
5. **Replay** — `gps-denied-replay --video … --imu aligned.csv` with `config.mode=replay`; C1–C5 identical to live.
|
||||
6. **Verdict** — horizontal-error distribution + map artifact returned to UI.
|
||||
|
||||
Advanced bypass: operator may upload a pre-aligned `(video, CSV)` per AZ-959 without steps 1–3.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Operator workstation runs `replay_api` (docker-compose or native) with network to `satellite-provider`.
|
||||
- Camera calibration JSON for the flight's nav camera.
|
||||
- Tlog contains `SCALED_IMU2` (or `RAW_IMU`) and `GLOBAL_POSITION_INT` / `GPS_RAW_INT`.
|
||||
- Video covers the active flight segment after alignment.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Operator
|
||||
participant UI as [[suite/ui]] AZ-897
|
||||
participant API as replay_api AZ-973
|
||||
participant Align as replay_input alignment AZ-971
|
||||
participant Export as tlog_to_csv AZ-972
|
||||
participant Seed as operator_replay cache_seed AZ-974
|
||||
participant Sat as [[satellite-provider]]
|
||||
participant Replay as gps-denied-replay
|
||||
participant Pipeline as C1..C5 replay mode
|
||||
|
||||
Operator->>UI: upload video + tlog + calibration
|
||||
UI->>API: POST /replay/preview
|
||||
API-->>UI: video metadata + IMU2 activity timeline
|
||||
Operator->>UI: drag video bar / refine
|
||||
UI->>API: POST /replay/align/refine
|
||||
API->>Align: refine_video_offset
|
||||
Align-->>UI: refined_offset_ms + confidence
|
||||
Operator->>UI: Run demo
|
||||
UI->>API: POST /replay/demo
|
||||
API->>Export: export_aligned_csv
|
||||
API->>Seed: extract_route + seed_route + FAISS
|
||||
Seed->>Sat: POST /api/satellite/route
|
||||
Sat-->>Seed: mapsReady
|
||||
API->>Replay: subprocess --video --imu
|
||||
Replay->>Pipeline: per-frame loop
|
||||
Pipeline-->>API: results.jsonl
|
||||
API-->>UI: map URL + verdict report
|
||||
```
|
||||
|
||||
### Data flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | UI | replay_api | video + tlog multipart | HTTP |
|
||||
| 2 | replay_api | UI | timeline preview JSON | JSON |
|
||||
| 3 | UI | replay_api | `video_offset_ms` | JSON |
|
||||
| 4 | replay_api | disk | aligned `data_imu.csv` | AZ-896 CSV |
|
||||
| 5 | replay_api | satellite-provider | `RouteSpec` waypoints | JSON POST |
|
||||
| 6 | replay_api | airborne binary | video + CSV + cache config | subprocess |
|
||||
| 7 | replay_api | UI | JSONL path, map URL, verdict md | JSON job result |
|
||||
|
||||
### Error scenarios
|
||||
|
||||
| Error | Detection | Recovery |
|
||||
|-------|-----------|----------|
|
||||
| Missing IMU in tlog | preview 422 | Operator message; cannot align |
|
||||
| Refine hard-fail (< 95 % frame match) | align/refine response | Operator adjusts bar or aborts |
|
||||
| Route seed terminal failure | `RouteTerminalFailureError` | Job failed; operator retries |
|
||||
| ESKF divergence (no cache) | replay exit ≠ 0 | Ensure step 4 completed; check AZ-963 |
|
||||
|
||||
### Performance expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Preview latency | p95 < 5 s | tlog parse + video probe |
|
||||
| Full demo (Derkachi) | ≤ 15 min cold | matches AZ-835 AC-7 |
|
||||
| Warm cache reuse | ≤ 30 s seed skip | named volume / cache_root reuse |
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting: FDR write side-effect
|
||||
|
||||
Every flow above produces FDR records (per AC-NEW-3). The cross-cutting rules are:
|
||||
|
||||
Reference in New Issue
Block a user