17 KiB
SBAS-InSAR GeoJSON Coverage And Result Management Design
Date: 2026-05-27
1. Purpose
Gamma SBAS-InSAR production has completed an end-to-end twelve-node run. The next step is to make production and results usable by geography, not only by time sequence and run status.
This design defines:
- how production pages show approximate geographic coverage with GeoJSON/bbox;
- how users select administrative regions or AOI to discover and produce SBAS stacks on demand;
- how completed SBAS runs become result products with searchable geographic extent;
- how the results page should display LOS velocity, LOS sigma, and monitoring-point curves.
2. Current Facts
The current successful run already contains usable geographic metadata:
run_id = sbas_7537cc71c998
stack center bucket = E129.2_N44.1
stack bbox = 128.7690438245, 43.7486321624, 129.6293024728, 44.3582486206
monitor point = 129.10207098755, 44.15041727515
Available metadata sources:
stack_manifest.scenes[*].bbox
stack_manifest.scenes[*].center_lon / center_lat
stack_manifest.stack.center_bucket
rdc_dem_summary.dem_source.stack_bbox
monitor_points_summary.monitor_outputs[*].metadata.approx_lonlat
published GeoTIFF bounds from GDAL metadata
Existing platform capabilities:
backend/geojson/全国行政区.geojson
backend/geojson/层级映射.json
GET /api/aoi/regions/children
GET /api/aoi/regions/{tree_id}/geometry
backend AOI helpers for region_tree_id / GeoJSON / uploaded AOI parsing
frontend Leaflet map and L.geoJSON support
frontend App.jsx existing source-scene footprint and AOI overlay patterns
The missing piece is productized SBAS-specific coverage and catalog behavior.
3. Design Principles
- SBAS production is temporal, but SBAS result consumption is geographic.
- Production UI should answer "am I processing the right place?" before a long workflow is submitted.
- Results UI should answer "where is this product, what time range does it cover, and can I download the main outputs?"
- One completed SBAS run is one result product bundle, not one product per GeoTIFF.
- GeoJSON/bbox coverage is enough for the first production UX. Full raster map rendering can come later.
- Administrative-region filtering should reuse existing AOI infrastructure rather than introduce a parallel region system.
4. Coverage Model
4.1 Stack Coverage
For stack discovery and production run display:
{
"center": {"lon": 129.199, "lat": 44.053},
"bbox": {
"min_lon": 128.769,
"min_lat": 43.749,
"max_lon": 129.629,
"max_lat": 44.358
},
"bbox_geojson": {
"type": "Feature",
"properties": {"role": "sbas_stack_bbox"},
"geometry": {
"type": "Polygon",
"coordinates": [[
[128.769, 43.749],
[129.629, 43.749],
[129.629, 44.358],
[128.769, 44.358],
[128.769, 43.749]
]]
}
},
"scene_bbox_count": 7,
"scene_footprints_geojson": null
}
First implementation may use stack bbox only. Per-scene rectangles can be added when the map needs to show coverage stability.
4.2 Product Coverage
For completed results:
{
"coverage_source": "stack_manifest_bbox_union",
"geotiff_bounds_verified": true,
"bbox": {...},
"center": {...},
"footprint_geojson": {...},
"administrative_hint": {
"province": "黑龙江省",
"city": null,
"county": null,
"method": "center_point_lookup"
}
}
The first administrative hint can be center-point based. Later it should become intersection-based and return all intersected regions with approximate overlap area.
5. Administrative Region And AOI Production
5.1 User Workflow
Production page should support three AOI sources:
1. Administrative region selection
province -> city -> county, backed by /aoi/regions endpoints
2. Map-drawn rectangle
converted to bbox GeoJSON
3. Uploaded GeoJSON/SHP
reuse existing AOI parsing helpers
The user flow:
select AOI / administrative region
discover SBAS stack candidates
show candidate time density + geographic coverage
select candidate
create production Run
submit Gamma SBAS workflow
5.2 Discovery Filter
Stack discovery should accept:
{
"region_tree_id": "230000",
"aoi_geojson": {},
"aoi_bbox": {
"min_lon": 128.7,
"min_lat": 43.7,
"max_lon": 129.7,
"max_lat": 44.4
},
"aoi_overlap_min": 0.0,
"stable_stack_overlap_min": 0.3
}
Initial filtering can use bbox intersection:
candidate stack is valid when union_bbox intersects AOI bbox
Second-stage filtering should use polygon intersection:
candidate_score += common_stack_area_intersection_ratio
candidate_score += scene_count / temporal_density
candidate_score -= sparse_time_gap_penalty
5.3 Production Guardrails
Before running workflow:
show bbox and administrative hint
show date list and max temporal gap
show DEM coverage status
warn when DEM covers center but not full stack bbox
warn when AOI overlap is low
The current run demonstrated a real issue:
DEM source covers stack center = true
DEM source covers full stack bbox = false
This must be visible in the production page before the user trusts the result.
6. Production Page UI
Add Geographic Coverage block to SbasInsarProductionPanel.
Minimum fields:
Center: lon / lat
BBox: min_lon, min_lat, max_lon, max_lat
Scene footprints: count
DEM coverage: bbox / center
Administrative hint
Monitor points if generated
Actions: view on map, copy GeoJSON, zoom to footprint
Map preview options:
Phase 1: small unframed Leaflet map with rectangle overlay
Phase 2: shared main map overlay using existing App.jsx layer mechanisms
Phase 3: per-scene footprints and monitor points overlay
The production page should not become the result browser. It only provides enough geographic context to avoid wrong-location production.
7. Result Management Module
7.1 Module Boundary
Create a separate SBAS-InSAR result management module:
navigation: Results / SBAS-InSAR Results
backend catalog: catalog_name = sbas_insar
product type: sbas_insar_bundle
source: completed Gamma SBAS production Run
Do not merge SBAS result semantics into D-InSAR result pages. Reuse the common catalog tables but keep service, API, and frontend module separate.
7.2 Product Row
One completed run becomes one product row:
result_products.catalog_name = sbas_insar
result_products.run_key = sbas run_id
result_products.engine_code = gamma
result_products.processor_code = gamma_ipta_sbas
result_products.display_name = platform / orbit / area / date span
Required product metadata:
platform
relative_orbit
orbit_direction
polarization
reference_date
start_date
end_date
scene_count
pair_count
bbox_min_lon / bbox_min_lat / bbox_max_lon / bbox_max_lat
center_lon / center_lat
administrative_hint
status
health_status
source_run_id
7.3 Asset Roles
Primary assets from the expert document:
primary_velocity_geotiff
current: publish/geotiff/los_rate_toward_m_per_year.tif
expert equivalent: geo_los_def_rate.tif
primary_velocity_preview
current: publish/geotiff/los_rate_toward_m_per_year.hls.geo_preview.png
expert equivalent: los_def_rate.bmp / geo_los_def_rate.bmp
primary_velocity_rgb_geotiff
current: publish/geotiff/los_rate_toward_m_per_year.hls.geo_rgb.tif
expert equivalent: geo_los_def_rate_rgb.tif
quality_sigma_geotiff
current: publish/geotiff/los_sigma_m_per_year.tif
expert equivalent: diff.sigma_ts / geo_diff.sigma_ts
quality_sigma_preview
current: publish/geotiff/los_sigma_m_per_year.cc.geo_preview.png
expert equivalent: diff.sigma_ts.masked.bmp with cc.cm
monitor_timeseries_csv
current: publish/monitor_points/*_timeseries.csv
expert equivalent: disp_prt_2d output table
monitor_timeseries_plot
current: publish/monitor_points/*_timeseries.png
support_manifest
run_manifest.json, workflow_summary.json, gamma_command_manifest.json
Default result display should foreground:
LOS velocity preview
LOS sigma preview
monitor point curve if present
footprint map
Audit/support files should be grouped separately.
8. Backend Design
8.1 Service
Add:
backend/app/services/sbas_insar_catalog_service.py
Responsibilities:
scan completed SBAS run directories
validate product bundle readiness
derive bbox/center/footprint GeoJSON
extract or verify GeoTIFF bounds
upsert result_products/result_assets/result_issues
provide list/detail/download APIs
bootstrap self-maintenance on startup
8.2 API
Add:
GET /api/sbas-insar-products/catalog-status
POST /api/sbas-insar-products/rebuild-catalog
GET /api/sbas-insar-products
GET /api/sbas-insar-products/{product_id}
GET /api/sbas-insar-products/{product_id}/assets/{asset_id}
List filters:
date_from
date_to
reference_date
platform
relative_orbit
orbit_direction
status
health_status
region_tree_id
aoi_bbox
aoi_geojson
intersects_bbox
has_monitor_points
limit / offset
8.3 Run Detail Extension
Extend production run detail:
{
"geographic_coverage": {
"center": {"lon": 129.199, "lat": 44.053},
"bbox": {"min_lon": 128.769, "min_lat": 43.749, "max_lon": 129.629, "max_lat": 44.358},
"bbox_geojson": {},
"scene_bbox_count": 7,
"dem_covers_stack_bbox": false,
"dem_covers_stack_center": true,
"monitor_points": [{"point_id": "auto_low_sigma_high_rate", "lon": 129.102, "lat": 44.150}]
}
}
8.4 Startup Self-Maintenance
On startup:
ensure result catalog tables exist through existing maintenance
bootstrap sbas_insar catalog state
scan completed SBAS run publish bundles
upsert missing product rows
record issues for:
missing bbox
missing primary velocity GeoTIFF
missing primary preview
missing sigma GeoTIFF
missing sigma preview
missing monitor files when monitor summary says ready
DEM coverage mismatch
This matches the current self-maintenance direction used by D-InSAR and PsInSAR catalogs.
9. Frontend Design
9.1 Production Page
Add:
GeographicCoveragePanel
bbox text
center text
administrative hint
DEM coverage status
mini map rectangle
copy GeoJSON
zoom/open on main map
Candidate stack cards should show:
date span
scene count
center bucket
center lon/lat
bbox short text
AOI overlap indicator when AOI is selected
9.2 Result Page
Add:
SbasInsarProductsPanel
List page:
filters: date range, administrative region, map AOI, platform, orbit, status
cards/table: product name, date span, bbox/admin hint, scene/pair count, preview thumbnail, health badge
actions: open detail, zoom to map, download primary GeoTIFF
Detail page:
footprint map
LOS velocity preview
LOS sigma preview
monitor curve
key metadata table
asset table grouped by role
quality and issue summary
link to production Run
9.3 Map Layer Strategy
Use GeoJSON for the first implementation:
bbox polygon for stack/product footprint
administrative region boundary layer from existing AOI endpoints
monitor point markers
optional per-scene footprints
Do not display RDC BMP as map layer. Only geocoded preview PNG/GeoTIFF-derived bounds should be used for map-oriented display.
10. Implementation Sequence
Recommended order:
1. Backend geographic_coverage in SBAS run detail.
2. Production page coverage block and bbox GeoJSON mini-map.
3. Add AOI/region filters to SBAS stack discovery request/response.
4. Add sbas_insar_catalog_service and catalog rebuild API.
5. Register current completed run as first SBAS result product.
6. Build SbasInsarProductsPanel list/detail.
7. Add map AOI filtering and administrative-region filtering to result page.
8. Add startup bootstrap/self-check output.
The first user-visible win is step 1-2: the operator can immediately see whether a Run covers the intended location.
10.1 Implementation Note 2026-05-27
Implemented the first slice after commit 9f0ba32:
backend/app/services/sbas_insar_production_service.py
frontend/src/SbasInsarProductionPanel.jsx
Backend now returns geographic_coverage from GET /api/sbas-insar-production/runs/{run_id}. The field is derived from stack_manifest.json, rdc_dem_summary.json, and monitor_points_summary.json without changing the Gamma expert workflow outputs.
The returned structure includes:
bbox
bbox_intersection
center
scene_bbox_count
scene_footprints_geojson
dem_coverage
dem_covers_stack_bbox
dem_covers_stack_center
monitor_points
geojson FeatureCollection
Frontend now displays the coverage block in two places:
candidate stack discovery detail
selected production Run detail
The mini-map uses the existing Leaflet/offline tile configuration and draws:
stack bbox rectangle
DEM coverage rectangle when available
monitor point markers when available
Validation against sbas_7537cc71c998:
geographic_coverage.bbox = 128.7690438245,43.7486321624,129.6293024728,44.3582486206
geojson feature count = 5
monitor point = auto_low_sigma_high_rate, 129.10207098755,44.15041727515
backend AST syntax check passed with configured Python
frontend npm run build passed
Remaining result-management work starts at catalog registration and a separate SBAS products page.
10.2 Implementation Note 2026-05-27 Result Catalog
Implemented the SBAS result-management slice:
backend/app/services/sbas_insar_catalog_service.py
backend/app/routers/sbas_insar_products.py
frontend/src/api/sbasInsarProducts.js
frontend/src/SbasInsarProductsPanel.jsx
Backend behavior:
catalog_name = sbas_insar
storage root = GAMMA_SBAS_WORK_ROOT/runs
source of truth = completed Gamma SBAS run folders
startup bootstrap = scan publish-ready runs and rebuild index when stale
manual rebuild = POST /api/sbas-insar-products/rebuild through job queue
list/detail = GET /api/sbas-insar-products and /{id}
asset serving = /api/sbas-insar-products/{id}/assets/{asset_id}
The catalog registers only database metadata and file pointers. It does not copy the large Gamma outputs.
Important registered assets:
LOS velocity geocoded preview
LOS sigma geocoded preview
LOS velocity GeoTIFF, toward radar positive
LOS velocity GeoTIFF, away from radar positive
LOS sigma GeoTIFF
Gamma ts_rate and sigma_rate GeoTIFFs
monitor-point PNG/CSV/metadata
run, stack, workflow, product, quality, and monitor summaries
Frontend behavior:
Production Management -> SBAS-InSAR 结果
catalog health cards
searchable result list
result detail
coverage map with stack bbox, DEM bbox, and monitor points
velocity/sigma/monitor preview panels
quality statistics
asset download/open links
issue list
Known next slices:
AOI / administrative-region filter for list and discovery
GeoTIFF raster overlay or server-side tile generation
multi-monitor-point comparison view
explicit orbit-trend/detrend quality diagnostics
11. Validation
Use sbas_7537cc71c998 as the first validation run.
Checks:
geographic_coverage.bbox is present
bbox_geojson draws a rectangle in Leaflet
admin hint is present or explicitly unknown
DEM coverage warning is visible when bbox is not fully covered
result product row exists after catalog rebuild
result detail opens velocity/sigma previews
asset downloads work
map zoom to footprint works
AOI filter returns this product when AOI intersects bbox
AOI filter excludes this product when AOI is far away
12. 2026-05-27 Center-Region UI Closeout
The gray footprint maps are no longer the primary SBAS UI contract. Production planning and result management now show a location summary instead:
center lon/lat
center administrative region
stack bbox and common-overlap bbox as text
scene footprint count
monitor point count
Administrative lookup uses the existing backend/geojson AOI region data. The lookup starts with center-point containment, repairs invalid administrative geometries where possible, and falls back to a clear unavailable/not-matched state instead of blocking SBAS production.
The SBAS result catalog now extracts dates from stack_manifest.scenes[*].date. This fixes the old list symptom:
before: - 至 - / 0景 / 6对
after : 20240422 至 20250908 / 7景 / 6对
The current validation run sbas_7537cc71c998 rebuilt successfully into the result catalog and matched:
center = 129.1949239855143, 44.053833584014285
admin region = 黑龙江省 / 牡丹江市
date range = 20240422 至 20250908
scene/pair count = 7 / 6
13. Open Questions
-
Administrative-region naming should start with center-point lookup or intersection lookup? Recommendation: center-point lookup first, intersection later.
-
Should stack discovery require AOI overlap, or only rank by AOI overlap? Recommendation: default to rank/filter by bbox intersection, expose minimum overlap later.
-
Should results use
sbas_insarorpsinsarcatalog name? Recommendation: usesbas_insar. The current Gamma product is SBAS-InSAR, and oldpsinsarcatalog semantics should not be overloaded. -
Should GeoTIFF raster be rendered on map immediately? Recommendation: not in the first slice. Start with footprint GeoJSON and preview images; raster tile rendering can be added after catalog registration is stable.