mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-23 04:11:13 +00:00
[AZ-777] Phase 1 hotfix (z/x/y) + Phase 2 Derkachi seed + ops
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>
This commit is contained in:
Oleksandr Bezdieniezhnykh
Vendored
+158
@@ -0,0 +1,158 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user