feat(isce2): harden managed production flow

- add one-time base DEM preparation utility and prepared-first DEM resolution - support geocode resume/full-geocode and guard large unprepared DEMs - repair missing completion files during in-place ISCE2 publish rebuild - add ISCE2 stabilization update log
2026-04-27 07:52:20 +08:00
parent 1e44101eb2
commit 5290b071b3
10 changed files with 995 additions and 45 deletions
@@ -0,0 +1,69 @@
+# ISCE2 Stabilization Update Log
+
+Date: `2026-04-27`
+
+## Scope
+
+This update hardens the managed `ISCE2` LT-1 stripmap D-InSAR production path against
+large raw DEM reuse, long geocode stalls, and incomplete recovered-run metadata.
+
+## Delivered Changes
+
+### 1. Managed ISCE2 pipeline hardening
+
+- Added `--resume-from unwrap|geocode|export` support to the LT-1 pipeline.
+- Added `--full-geocode` support. The default path now geocodes only the export-critical
+  products instead of ISCE2's full default list.
+- Added stage-aware logging with stdout flush to improve long-run observability.
+- Added geocode DEM subset preparation so resumed geocode/export runs do not reprocess the
+  full base DEM.
+- Added a guard that blocks fresh runs when the selected DEM resolves to a very large raw
+  base raster without a prepared `.wgs84` sibling.
+
+### 2. Engine and runtime configuration fixes
+
+- `ISCE2` now prefers an existing prepared `.wgs84` DEM over the raw base path.
+- `PyINT` DEM resolution now follows the same prepared-first preference.
+- The WSL ISCE2 runner now passes `resume_from` and `full_geocode` through to the pipeline.
+- The WSL runner now sets both `PROJ_DATA` and `PROJ_LIB`.
+
+### 3. Recovery and catalog self-healing
+
+- Added a completion-file repair helper for managed ISCE2 runs.
+- In-place ISCE2 publish/rebuild now repairs missing:
+  - `execution_manifest.json`
+  - `current/isce2__<profile>.json`
+- This allows recovered runs to be reintroduced into the managed result catalog without
+  hand-editing completion markers.
+
+### 4. One-time DEM preparation tooling
+
+- Added `backend/app/isce2_pipeline/prepare_isce2_base_dem.py`.
+- The script resolves DEM paths from `.env`, validates existing prepared outputs, and can
+  generate a reusable `WGS84` `.wgs84` DEM from an `EGM96` base DEM.
+- The script also auto-configures `PROJ` paths for standalone execution.
+
+### 5. Configuration guidance
+
+- Updated `.env.example` comments to distinguish:
+  - raw SARscape/ENVI DEM source path
+  - prepared ISCE2/PyINT `.wgs84` path
+
+## Validation
+
+- Python syntax validation was run for the modified ISCE2 pipeline, engine, runtime, and
+  result-catalog modules.
+- The one-time full DEM preparation completed successfully and produced:
+  - `.wgs84`
+  - `.wgs84.xml`
+  - `.wgs84.vrt`
+- The prepared DEM metadata was verified to report `WGS84`.
+
+## Required Local Follow-Up
+
+These operational steps are intentionally not committed:
+
+- Point local `.env` `ISCE2_DEM_PATH` to the prepared `.wgs84` file.
+- Point local `.env` `PYINT_PREPARED_DEM_PATH` to the same prepared `.wgs84` file.
+- Restart the backend so the running process reloads the updated `.env`.
+