# 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)