mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 08:51:12 +00:00
Oleksandr Bezdieniezhnykh
b15454b9a9
Phase 1 hotfix:
- C11 HttpTileDownloader adapted to satellite-provider v2.0.0
z/x/y inventory contract (bulk POST keyed by slippy-map coords).
- Unit tests rewritten to exercise the new inventory schema.
- E2E smoke test updated to match the v2.0.0 wire.
Phase 2 (Derkachi seed + smoke-validated on Jetson):
- tests/fixtures/derkachi_c6/{README,bbox.yaml,seed_region.py}
drives POST /api/satellite/region against satellite-provider
with Google Maps as the imagery source. Smoke run produced
4 regions, 175 tiles, inventory 32/32.
- scripts/mint_dev_jwt.py + run-tests-jetson.sh auto-mint and
export SATELLITE_PROVIDER_API_KEY using JWT_SECRET / JWT_ISSUER
/ JWT_AUDIENCE env vars (no host port mappings; e2e-runner
reaches SP via internal docker network only).
Spec amendment: AZ-777 todo spec updated to record the
Google Maps imagery source decision and STOP-gate state.
AZ-777 Phase 3+ work is superseded by Epic AZ-835 (see next
commit).
Co-authored-by: Cursor <cursoragent@cursor.com>
159 lines
7.9 KiB
YAML
159 lines
7.9 KiB
YAML
# Derkachi reference tile catalog — bbox + zoom + imagery source metadata
|
|
#
|
|
# This file drives `seed_region.py`, which calls the parent-suite
|
|
# `satellite-provider` Region API (`POST /api/satellite/request`) to seed
|
|
# the satellite-provider DB with the Derkachi tiles the C6 reference
|
|
# catalog needs for AZ-777 Phase 2+.
|
|
#
|
|
# Authoritative spec: ../_docs/02_tasks/todo/AZ-777_derkachi_c6_reference_fixture.md
|
|
# Probe-confirmed wire format (2026-05-22): {id, latitude, longitude,
|
|
# sizeMeters, zoomLevel, stitchTiles} — see AZ-812 for the planned
|
|
# latitude/longitude -> lat/lon OSM rename.
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Bounding box — per AZ-777 spec
|
|
# ---------------------------------------------------------------------
|
|
# Spec bbox covers the Derkachi village area generously so the operator
|
|
# can fly any route within the box without re-seeding the catalog. This
|
|
# is INTENTIONALLY larger than the specific Derkachi flight extent (see
|
|
# `actual_flight_extent` below for the real per-flight footprint).
|
|
bbox:
|
|
lat_min: 50.05
|
|
lat_max: 50.15
|
|
lon_min: 36.05
|
|
lon_max: 36.15
|
|
# Approximate at lat ~50: 11.1 km (lat) x 7.14 km (lon) = ~79 km^2
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Actual Derkachi flight extent (derived from data_imu.csv, 2026-05-22)
|
|
# ---------------------------------------------------------------------
|
|
# The real flight is much smaller than the spec bbox. Documented here
|
|
# for transparency. If only the specific Derkachi clip needs coverage,
|
|
# re-running seed_region.py with `--right-sized-flight` would seed
|
|
# ~60 tiles instead of ~4570 tiles (~98% reduction).
|
|
actual_flight_extent:
|
|
source: _docs/00_problem/input_data/flight_derkachi/data_imu.csv
|
|
lat_min: 50.080870
|
|
lat_max: 50.083159
|
|
lon_min: 36.107000
|
|
lon_max: 36.113401
|
|
# ~254 m (lat) x ~457 m (lon), centered at (50.082, 36.110)
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Zoom levels — per AZ-777 spec
|
|
# ---------------------------------------------------------------------
|
|
zoom_levels:
|
|
- 15 # ~5 m / pixel — coarse coverage
|
|
- 16 # ~2.4 m / pixel — mid-altitude search
|
|
- 17 # ~1.2 m / pixel — close-altitude search
|
|
- 18 # ~0.6 m / pixel — VPR descriptor lock (primary)
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Region API chunking strategy
|
|
# ---------------------------------------------------------------------
|
|
# Region API caps `sizeMeters` at 10000 (10 km side). The Derkachi bbox
|
|
# is 11.1 km along the lat axis, so a single region call cannot cover
|
|
# the full bbox. seed_region.py splits the bbox into N north-south
|
|
# chunks per zoom level (default: 2 chunks, each centered to cover the
|
|
# corresponding half of the bbox with sizeMeters=10000). Overlap is
|
|
# deduplicated server-side by the producer's UPSERT-on-tile-coord
|
|
# behavior so we do not pay Google Maps cost twice for overlapping
|
|
# tiles.
|
|
chunking:
|
|
chunks_per_zoom: 2
|
|
size_meters_per_chunk: 10000
|
|
stitch_tiles: false # individual tiles, not stitched composite
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Imagery source — IMPORTANT: amended 2026-05-22 (see AZ-777 risk 4)
|
|
# ---------------------------------------------------------------------
|
|
# AZ-777 was originally specced with CARTO Voyager Basemap (CC-BY-3.0)
|
|
# as the upstream imagery source. The 2026-05-22 black-box probe of
|
|
# the running satellite-provider revealed the actual upstream is Google
|
|
# Maps (verified via satellite-provider/_docs/02_document/architecture.md
|
|
# line 49 + producer logs: `mt0..mt3.google.com/vt/lyrs=s`).
|
|
#
|
|
# Dev/research use is acceptable. Production deploy requires either:
|
|
# (a) Google Maps Platform licensing review for offline-cache use, OR
|
|
# (b) parent-suite ticket to add a true CC-BY satellite imagery
|
|
# provider to satellite-provider (Esri World Imagery, Mapbox
|
|
# satellite, Sentinel-2 via Copernicus, etc.).
|
|
imagery_source:
|
|
provider: google_maps
|
|
layer: lyrs=s # Google Maps satellite layer (high-resolution overhead)
|
|
resolution_at_z18_lat50_m_per_px: 0.384 # probe-measured 2026-05-22
|
|
fetch_pattern: mt[0-3].google.com/vt/lyrs=s&x={x}&y={y}&z={z}&token={session_token}
|
|
|
|
# ---------------------------------------------------------------------
|
|
# License attribution (operators must propagate to end users)
|
|
# ---------------------------------------------------------------------
|
|
license:
|
|
source: Google Maps Platform Terms of Service
|
|
url: https://cloud.google.com/maps-platform/terms
|
|
attribution_text: "Imagery © Google"
|
|
dev_use_only: true
|
|
production_warning: |
|
|
The Google Maps Platform ToS may restrict offline caching of map
|
|
tiles for use as a derivative reference dataset (e.g. a long-lived
|
|
VPR reference base). This catalog is approved for dev/research use
|
|
only. Before any production deployment, EITHER:
|
|
1. Obtain Google Maps Platform licensing approval for the C6
|
|
offline-cache use case, OR
|
|
2. Migrate to a CC-BY satellite imagery provider on the
|
|
satellite-provider side (parent-suite ticket TBD).
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Catalog size budget — OVER BUDGET WARNING
|
|
# ---------------------------------------------------------------------
|
|
# Per AZ-777 spec line 178: "The seeded Derkachi catalog size budget is
|
|
# 100 MB on the satellite-provider DB side. Over budget -> reduce
|
|
# zoom-level coverage; document in bbox.yaml."
|
|
#
|
|
# Actual estimate against the spec bbox + zoom 15-18: ~11386 tiles
|
|
# (per seed_region.py --dry-run), ~148 MB (at probe-measured 13 KB/tile
|
|
# avg). This is ~48% OVER the spec's 100 MB budget.
|
|
#
|
|
# The original spec budget was likely calibrated for CARTO Voyager
|
|
# tiles, which are smaller than the Google Maps satellite tiles we
|
|
# actually fetch (CARTO is street-feature vector overlay; Google
|
|
# satellite is high-detail overhead JPEG). The reality is heavier.
|
|
#
|
|
# Three mitigation options (operator picks at run time):
|
|
# 1. Drop z=18 from `zoom_levels` -> ~3000 tiles, ~40 MB (in budget),
|
|
# but loses primary VPR descriptor-lock zoom. NOT RECOMMENDED for
|
|
# AC-4 / AZ-699 passes.
|
|
# 2. Reduce bbox -> e.g. 5x5 km tight to the flight cluster instead
|
|
# of the full village area. Coverage shrinks proportionally.
|
|
# 3. Use `--right-sized-flight` -> ~60 tiles, ~1 MB. Tight to the
|
|
# specific Derkachi clip; cannot fly an alternative path within
|
|
# the original spec bbox without re-seeding.
|
|
#
|
|
# Default behavior (no flag): seed the full spec bbox EVEN THOUGH IT
|
|
# EXCEEDS THE BUDGET. seed_region.py will print a loud warning at the
|
|
# start of the run if the estimated size is over budget, and the
|
|
# operator can interrupt + re-run with one of the mitigations above.
|
|
catalog_size_budget:
|
|
max_bytes_db_side: 104857600 # 100 MB (spec budget)
|
|
estimated_tile_count_spec_bbox: 11386
|
|
estimated_tile_count_right_sized: 60
|
|
estimated_avg_bytes_per_tile: 13046 # probe-measured 2026-05-22
|
|
estimated_total_bytes_spec_bbox: 148581256 # ~141.7 MB (~48% OVER)
|
|
estimated_total_bytes_right_sized: 782760 # ~0.75 MB
|
|
over_budget_warning: |
|
|
Default spec bbox seeding exceeds the spec's 100 MB budget by ~48%
|
|
when seeding all 4 zoom levels (15-18) with Google Maps satellite
|
|
imagery. Operator must choose: accept the overage, drop a zoom
|
|
level, reduce the bbox, or use --right-sized-flight.
|
|
|
|
# ---------------------------------------------------------------------
|
|
# Provenance
|
|
# ---------------------------------------------------------------------
|
|
provenance:
|
|
created_for: AZ-777 (gps-denied-onboard Derkachi C6 reference fixture)
|
|
bbox_source: AZ-777 spec outcome line 31 (50.05-50.15 lat, 36.05-36.15 lon)
|
|
flight_extent_source: data_imu.csv computed 2026-05-22
|
|
api_contract_source: probe-confirmed against running satellite-provider on Jetson, 2026-05-22
|
|
related_tickets:
|
|
- AZ-808 # validation for region-request endpoint
|
|
- AZ-812 # rename latitude/longitude -> lat/lon (consumer must update after AZ-812 lands)
|