mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 12:01:13 +00:00
Strip implementation details from AC; add design-independence rule
acceptance_criteria.md and restrictions.md were carrying internal component selections (DINOv2/SuperPoint/FAISS/ESKF), library pins (pymavlink/MAVSDK), autopilot parameter values (GPS1_TYPE=14, EK3_SRC1_*, VISO_QUAL_MIN), and v1/v1.1 phasing tied to specific ArduPilot PR numbers. Per IEEE 830 / Atlassian / GitScrum, acceptance criteria must be design-independent — outcomes only, not implementation. Cleaned both files (-35% combined size) while preserving every testable threshold and contract bullet. Output-schema label renamed: vo_extrapolated -> visual_propagated. FC scope broadened from ArduPilot-only to ArduPilot + iNav (both via standard MAVLink external-positioning interfaces). Encoded the lesson into the two skills that write/refine AC: - problem/SKILL.md (initial AC production) - research/steps/01_mode-a-initial-research.md (Phase 1 AC & Restrictions Assessment) Autodev state reset to greenfield Step 2 (Research) for the post-restart greenfield run; cycle 1, in-progress at sub-step ac-restrictions-assessment. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -1,59 +1,46 @@
|
||||
# Restrictions
|
||||
|
||||
> **Last revised**: 2026-05-01 (post Phase 1 AC/restrictions assessment clarifications).
|
||||
> Last revised 2026-05-07 (cleanup pass — design-independent, IEEE-830 style; only external dependencies, environmental constraints, integration boundaries).
|
||||
|
||||
## UAV & Flight
|
||||
|
||||
- Photos are taken by airplane (fixed-wing) type UAVs only.
|
||||
- Photos are taken by the navigation camera pointing downwards and fixed (not gimbal-stabilized).
|
||||
- Operational area is the eastern and southern parts of Ukraine (east/left of the Dnipro River).
|
||||
- Mission profile: 8-hour flights at ~60 km/h cruise. Two route shapes coexist:
|
||||
- **Sector**: up to **10 × 15 km = 150 km²** of dense coverage.
|
||||
- **Transit corridor**: ~**50 km × 1 km = 50 km²** strip in/out of the sector.
|
||||
- **Total operational area: up to ~400 km²** of pre-cached satellite imagery per mission. Cache is **persistent across flights** (not redownloaded each mission). Storage budget **~10 GB** for the satellite tile cache; see AC-NEW-3 for flight-data-recorder budget.
|
||||
- Altitude: pre-defined, **≤1 km AGL**. Terrain is assumed flat (operational area is rolling steppe / agricultural land); height differences are negligible.
|
||||
- Weather: predominantly sunny daytime operations. Validation must still cover the seasonal/visibility classes that affect visual matching in the operational area: summer crop/field patterns, autumn/winter bare fields, cloud/smoke/haze, snow if missions can occur in winter, and low-texture agricultural repetition.
|
||||
- Sharp turns occur but are the exception, not the rule. Two consecutive photos may share <5% overlap during a turn (see AC-3.2).
|
||||
- **No photo-count cap.** The previously stated "up to 3000 photos per flight" was a legacy operator number from a Mavic-class workflow; it is dropped because (a) it is inconsistent with 8 h × 3 fps, and (b) the system does **not store raw photos at all** (see AC-8.5). Storage is bounded by the tile-cache + FDR caps (~10 GB persistent + 64 GB / flight, AC-NEW-3).
|
||||
- Fixed-wing UAVs only; navigation camera fixed downward (no gimbal).
|
||||
- Operational area: eastern/southern Ukraine (east of Dnipro).
|
||||
- Mission profile: 8-hour flights, ~60 km/h cruise. Sector ≤150 km² + transit corridor ~50 km². Total cached area ≤~400 km², persistent across flights.
|
||||
- Altitude ≤1 km AGL; terrain assumed flat (rolling steppe / agricultural).
|
||||
- Weather: predominantly sunny daytime; validation must cover seasonal/visibility classes (summer crops, autumn/winter bare fields, cloud/haze, snow if winter, low-texture repetition).
|
||||
- Sharp turns are exceptions; consecutive photos may share <5% overlap (AC-3.2).
|
||||
- No raw-photo storage (AC-8.5); storage bounded by tile cache + per-flight FDR (AC-NEW-3).
|
||||
|
||||
## Cameras
|
||||
|
||||
- The UAV carries **two cameras**:
|
||||
1. **Navigation camera** — fixed, downward-pointing, not autostabilized. Consumed by the GPS-Denied system for position estimation.
|
||||
2. **AI camera** — main mission camera with operator-controllable gimbal angle and zoom. Consumed by onboard AI detection systems.
|
||||
- **Navigation camera**: **ADTi 20MP 20L V1, APS-C sensor, ~5472 × 3648 px (≈20 MP)**. APS-C sensor (~23.6 × 15.7 mm). Lens TBD — selected during solution-draft phase to land GSD in the **10–20 cm/px band at 1 km AGL** (drives a frame ground footprint of ~470 m × 314 m to ~980 m × 655 m depending on focal length). Other intrinsics (focal length, exact sensor dimensions, distortion coefficients) are pinned at module-selection time and used by Component-1b orthorectification (pre-flight checkerboard calibration, F-F2).
|
||||
- **AI camera pose information available to the GPS-Denied system**: gimbal angle and zoom only. The UAV's instantaneous bank/pitch is **not** published from the autopilot to the AI-camera reasoning path. Object-localization accuracy is therefore scoped to level flight (AC-7.1).
|
||||
- Cameras connect to the companion computer over USB, MIPI-CSI, or GigE (specific interface TBD at solution-draft phase, dependent on chosen module).
|
||||
- **Navigation camera (pinned)**: ADTi 20MP 20L V1, APS-C ~23.6 × 15.7 mm, ~5472 × 3648 px (≈20 MP). Lens chosen so GSD lands in 10–20 cm/px @ 1 km AGL (frame footprint ~470×314 m to ~980×655 m). Intrinsics + camera-to-body calibration must be obtained pre-flight (e.g., checkerboard).
|
||||
- **AI camera**: operator-controlled gimbal angle + zoom (consumed by AI detection systems). The GPS-Denied system supports object localization (AC-7.x) using gimbal angle + zoom only — UAV bank/pitch is not published to that path; AI-camera object localization is therefore scoped to level flight (AC-7.1).
|
||||
- Camera-to-companion interface: USB / MIPI-CSI / GigE (lens-module dependent).
|
||||
|
||||
## Satellite Imagery
|
||||
|
||||
- **Source: Azaion Suite Satellite Service** (a separate component of the wider Suite). The onboard system is a **consumer** of this service, not a direct customer of commercial providers. Upstream sourcing (Maxar / Airbus / partner agencies / commissioned tasking) is the Satellite Service's concern, not this build's.
|
||||
- **Onboard interface to the Service is offline-only**: the companion computer holds a local cache populated **before flight** by syncing from the Service for the operational area (AC-8.3). No satellite imagery is fetched in-flight from the Service.
|
||||
- **Mid-flight tile generation (AC-8.4)**: during the mission the companion computer generates fresh tiles from the navigation camera, orthorectified into the basemap projection, deduplicated against the existing cache, and stored locally. On landing, those new tiles are uploaded back to the Suite Satellite Service for ingestion, so the next mission's cache is refreshed by the previous flight.
|
||||
- **No raw photo storage** (AC-8.5): the tile is the unit of persistence. Raw nav-camera and AI-camera frames are not retained (except a low-rate failure-thumbnail log for forensics).
|
||||
- **Resolution at the cache interface**: 0.5 m/pixel minimum, 0.3 m/pixel ideal (AC-8.1). The architecture is provider-agnostic at the cache boundary; whatever the Suite Satellite Service supplies must meet that bar.
|
||||
- **Storage tile resolution convention**: cache imagery is specified by source pixel size, not by assuming a universal zoom-to-meter mapping. The cache interface accepts **0.5 m/px minimum, 0.3 m/px ideal** imagery, and every tile manifest records CRS, tile matrix convention, tile dimension, latitude-adjusted meters-per-pixel, capture date, source, and compression. If an XYZ/WebMercator tile pyramid is used, its zoom level is documented as a provider convention rather than treated as proof of physical resolution. The matcher (Component 3) needs <=~4x scale ratio between the UAV frame (~12 cm/px GSD at 1 km AGL with the 20 MP APS-C camera) and the reference; 0.3-0.5 m/px reference imagery gives a ~2.5-4.2x ratio. Storage budget across the 400 km² operational area remains capped at **10 GB** for the persistent cache and must be validated against the final provider format/compression. The 10 GB budget includes cache imagery, manifests, overviews, and any precomputed global/local descriptors unless the solution draft explicitly splits a separate descriptor/index budget. **VPR retrieval unit is decoupled from the storage tile** (see AC-8.6 below): VPR chunks are derived from the tile cache at ground-footprint scale (~600-800 m chunks with 40-50 % overlap), independent of the storage tile convention.
|
||||
- **Freshness gates** (AC-8.2 / AC-NEW-6) are enforced at runtime: tiles older than 6 months (active-conflict sectors) or 12 months (stable rear sectors) are rejected or down-confidence-weighted. Tiles generated mid-flight are timestamped with the current flight date and treated as fresh.
|
||||
- **Free public imagery (Sentinel-2 etc.)** is not on the runtime path. If the Suite Satellite Service ever returns Sentinel-class tiles, the cache rejects them as below the 0.5 m/px floor.
|
||||
- **Source**: Azaion Suite Satellite Service (separate Suite component). Onboard system is a consumer; upstream sourcing is the Service's concern.
|
||||
- **Onboard interface is offline-only**: companion holds a local cache populated pre-flight from the Service for the operational area (AC-8.3). No in-flight Service calls.
|
||||
- **Mid-flight tile generation (AC-8.4)**: companion orthorectifies nav-camera frames into basemap-projected tiles, deduplicates, stores locally; uploads on landing.
|
||||
- **Storage policy**: tile is the unit of persistence; no raw frames retained (AC-8.5).
|
||||
- **Resolution at cache interface**: ≥0.5 m/px, ideally 0.3 m/px (AC-8.1).
|
||||
- **Tile manifest schema**: CRS, tile matrix, dimension, lat-adjusted m/px, capture date, source, compression. Slippy/XYZ zoom (if used) is a provider convention, not a resolution proof.
|
||||
- **Cache budget**: 10 GB persistent across the ~400 km² area, including manifests, overviews, and any precomputed indices unless the solution carves out a separate descriptor budget.
|
||||
- **Freshness**: enforced per AC-8.2 / AC-NEW-6 (6-month active-conflict / 12-month rear). Mid-flight tiles timestamped current and treated as fresh.
|
||||
- **Sentinel-2 / free public imagery**: not on runtime path; cache rejects below the 0.5 m/px floor.
|
||||
|
||||
## Onboard Hardware
|
||||
|
||||
- Processing platform: **Jetson Orin Nano Super** — 67 TOPS sparse INT8, **8 GB shared LPDDR5** (CPU and GPU share the same memory pool), **25 W TDP**.
|
||||
- Companion computer runs JetPack (Ubuntu-based) with CUDA / TensorRT available.
|
||||
- Sustained GPU load may cause thermal throttling; the processing pipeline must stay within the thermal envelope. The cooling solution shall sustain the 25 W power mode for the 8-hour duty cycle at the upper environmental-envelope temperature (AC-NEW-5).
|
||||
- Onboard non-volatile storage: budget at least the satellite-cache (~10 GB) **plus** the flight-data-recorder cap (64 GB / flight, AC-NEW-3). Reuse-across-flights tile cache stays resident; per-flight FDR rolls over after cap.
|
||||
- **Companion computer (pinned)**: Jetson Orin Nano Super — 67 TOPS sparse INT8, 8 GB shared LPDDR5, 25 W TDP. JetPack (Ubuntu) with CUDA / TensorRT.
|
||||
- Cooling sized for 25 W continuous over 8 h at the upper environmental temp (AC-NEW-5).
|
||||
- Storage budget ≥ tile cache (~10 GB) + per-flight FDR (64 GB, AC-NEW-3).
|
||||
|
||||
## Sensors & Integration
|
||||
|
||||
- High-rate **IMU** data is available from the flight controller via MAVLink.
|
||||
- The original still-image sample does **not** include synchronized IMU or ground-truth pose. The Derkachi representative fixture adds cropped nadir video plus synchronized `SCALED_IMU2` and `GLOBAL_POSITION_INT` telemetry, which is enough for replay, synchronization, latency, VIO smoke tests, and trajectory comparison against the tlog GPS path. Final production acceptance still requires camera intrinsics, lens distortion, exact camera-to-body calibration, and representative synchronized navigation-camera frames, FC IMU/attitude/airspeed/altitude, emitted MAVLink messages, and ground-truth trajectory from a representative flight or replay rig.
|
||||
- The system communicates with the flight controller via MAVLink. Telemetry plumbing uses **MAVSDK**; the `GPS_INPUT` injection path is implemented via **pymavlink**, since MAVSDK does not expose a native `GPS_INPUT` API.
|
||||
- **Autopilot target: ArduPilot only** (with `GPS1_TYPE=14` for MAVLink GPS injection). PX4 is out of scope for the build; if it ever returns to scope it will use `VISION_POSITION_ESTIMATE`, not `GPS_INPUT`. (See `_docs/00_research/00_ac_assessment.md` Q-1.)
|
||||
- The system outputs WGS84 GPS coordinates to the flight controller as a replacement for the real GPS module (MAVLink GPS_INPUT, AC-4.3).
|
||||
- **Ground station: QGroundControl** is the supported GCS. Mission Planner is not in scope. Telemetry link is bandwidth-limited and is not the primary output channel; per-frame data stays on the local FDR (AC-NEW-3), GCS sees a 1–2 Hz downsampled summary (AC-6.1).
|
||||
- **High-rate IMU** available from FC via MAVLink.
|
||||
- **Communication protocol (pinned)**: MAVLink for both FC and GCS.
|
||||
- **Supported flight controllers**: ArduPilot, iNav (both via standard MAVLink). PX4 out of scope.
|
||||
- **Output to FC**: WGS84 GPS coordinates as a real-GPS replacement, via the MAVLink message type(s) the supported FCs accept for external positioning (per-FC message selection is a design choice; contract is AC-4.3).
|
||||
- **Ground station**: QGroundControl (Mission Planner out of scope). Telemetry link bandwidth-limited; per-frame data stays on local FDR (AC-NEW-3); GCS sees 1–2 Hz downsampled summary (AC-6.1).
|
||||
- **Representative data**: see `input_data/` (still images), `input_data/flight_derkachi/` (cropped nadir video + synchronized `SCALED_IMU2` + `GLOBAL_POSITION_INT`). Production acceptance still requires camera intrinsics, distortion, camera-to-body calibration, and synchronized representative flight data (frames + FC IMU/attitude/airspeed/altitude + emitted MAVLink + ground-truth trajectory).
|
||||
|
||||
## Failsafe & Safety
|
||||
|
||||
- If the GPS-Denied system fails to produce any position estimate for **>3 s**, the autopilot falls back to IMU-only dead reckoning (AC-5.2). N=3 s rides through one sharp turn at cruise speed without tripping the failsafe.
|
||||
- The system must satisfy the false-position safety budget in AC-NEW-4 (P(error >500 m) <0.1%, P(error >1 km) <0.01% per flight).
|
||||
- Cold-start time-to-first-fix budget is **<30 s** from companion-computer boot (AC-NEW-1); spoofing-promotion latency is **<3 s** from FC's GPS-loss signal (AC-NEW-2).
|
||||
- If no estimate produced for >3 s → autopilot falls back to IMU-only dead reckoning (AC-5.2). 3 s rides through one sharp turn at cruise.
|
||||
- False-position safety budget: AC-NEW-4 (P(>500 m) <0.1 %, P(>1 km) <0.01 % per flight).
|
||||
- Cold-start TTFF <30 s (AC-NEW-1); spoofing-promotion latency <3 s (AC-NEW-2).
|
||||
|
||||
Reference in New Issue
Block a user