Add SARscape Go wrapper workflow

2026-05-29 19:52:32 +08:00
parent 46474274c2
commit 5c24c0e64c
16 changed files with 1517 additions and 22 deletions
@@ -0,0 +1,45 @@
+# Repository Layout
+
+```text
+.
+|-- dist/
+|   `-- windows/
+|       `-- gf3wrapper.exe
+|-- docs/
+|   |-- repository_layout.md
+|   `-- sarscape_go_wrapper.md
+|-- src/
+|   `-- gf3_l1a2l2/
+|-- tests/
+|   `-- fixtures/
+|-- tools/
+|   `-- gf3_sarscape_wrapper/
+|       |-- assets/
+|       |-- idl/
+|       |-- go.mod
+|       `-- main.go
+|-- README.md
+|-- environment.yml
+`-- pyproject.toml
+```
+
+## What Belongs In Git
+
+- Python package source.
+- Go wrapper source.
+- IDL/SARscape source scripts.
+- Small embedded runtime assets needed to build the wrapper.
+- Small sanitized tests and fixtures.
+- Documentation and reproducible build instructions.
+- Small convenience binaries when the team explicitly wants a ready-to-run Windows artifact.
+
+## What Does Not Belong In Git
+
+- Raw GF-3 production archives.
+- Extracted scenes.
+- SARscape output directories.
+- Local wrapper config files such as `gf3wrapper.json`.
+- Runtime folders such as `.gf3_extract` and `.gf3_runtime`.
+- DEM files and other large environment-specific dependencies.
+
+Use NAS or object storage for production data and record exact paths in run logs or issue notes.
@@ -0,0 +1,112 @@
+# SARscape Go Wrapper
+
+`gf3wrapper.exe` is a Windows command-line wrapper for the SARscape/IDL GF-3 processing workflow. It embeds `gf3_sarscape_cli.sav`, starts `idlrt.exe`, and passes scene metadata, output directory, DEM, and polarization arguments to SARscape.
+
+This path is intended for operational runs where ENVI/IDL Runtime and SARscape are installed and licensed.
+
+## Requirements
+
+- Windows host.
+- ENVI/IDL Runtime, default path:
+  `C:\Program Files\Harris\ENVI56\IDL88\bin\bin.x86_64\idlrt.exe`
+- SARscape available to the IDL Runtime environment.
+- DEM file, for example:
+  `D:\DEM\COPDEM_GLO30_China_4326_DEM`
+- GF-3 L1A input as `*.tar.gz`, `*.meta.xml`, or a directory containing multiple scenes.
+
+The IDL Runtime path can be overridden with `-idlrt` or the `IDLRT_PATH` environment variable.
+
+## Quick Start
+
+Use the prebuilt executable:
+
+```powershell
+.\dist\windows\gf3wrapper.exe `
+  -input "D:\GF3\L1A_BATCH" `
+  -output "E:\GF3\L2_SARscape" `
+  -dem "D:\DEM\COPDEM_GLO30_China_4326_DEM" `
+  -pol "HH,HV"
+```
+
+Double-click mode is also supported. When launched without arguments, the wrapper prompts for input, output, DEM, polarizations, and IDL Runtime path. Press Enter to reuse saved defaults.
+
+## Inputs
+
+The wrapper supports:
+
+- A single GF-3 archive: `GF3_....tar.gz`
+- A single extracted scene metadata file: `GF3_....meta.xml`
+- A directory containing many archives and/or extracted scenes
+
+Directory mode recursively scans for `*.tar.gz`, `*.tgz`, and `*.meta.xml`. If both archive and metadata exist for the same scene name, the archive is preferred. Internal `.gf3_extract` folders are skipped.
+
+## Outputs
+
+Each scene is processed into its own output directory:
+
+```text
+E:\GF3\L2_SARscape\
+  GF3_SCENE_NAME\
+    .gf3_extract\          Extracted archive, when input was .tar.gz
+    *_slc.sml
+    *_ml.sml
+    *_filt.sml
+    *_geo.sml
+```
+
+The embedded SAV is materialized under:
+
+```text
+<output>\.gf3_runtime\gf3_sarscape_cli.sav
+```
+
+## Saved Defaults
+
+After a successful run, the wrapper writes `gf3wrapper.json` next to the executable:
+
+```json
+{
+  "idlrt_path": "C:\\Program Files\\Harris\\ENVI56\\IDL88\\bin\\bin.x86_64\\idlrt.exe",
+  "dem_file": "D:\\DEM\\COPDEM_GLO30_China_4326_DEM",
+  "polarizations": "HH,HV",
+  "last_input": "D:\\GF3\\L1A_BATCH",
+  "last_output": "E:\\GF3\\L2_SARscape",
+  "keep_extracted": true
+}
+```
+
+Command-line flags override saved defaults. If `-input`, `-output`, `-dem`, or `-pol` are omitted, saved values are reused when available.
+
+## Build
+
+From the repository root:
+
+```powershell
+cd .\tools\gf3_sarscape_wrapper
+$env:GOTELEMETRY = "off"
+go build -o ..\..\dist\windows\gf3wrapper.exe .
+```
+
+If Go cannot write to the default user cache directory, set local cache paths:
+
+```powershell
+$env:GOCACHE = "C:\Temp\go-build-cache"
+$env:APPDATA = "C:\Temp\go-appdata"
+```
+
+## Source Files
+
+```text
+tools/gf3_sarscape_wrapper/main.go
+tools/gf3_sarscape_wrapper/assets/gf3_sarscape_cli.sav
+tools/gf3_sarscape_wrapper/idl/gf3_sarscape_cli.pro
+tools/gf3_sarscape_wrapper/idl/gf3_sarscape_pipeline.pro
+```
+
+`assets/gf3_sarscape_cli.sav` is embedded into the Go executable at build time.
+
+## Notes
+
+- Keep production archives and generated products outside Git.
+- Keep only small sanitized fixtures in `tests/fixtures`.
+- The prebuilt executable in `dist/windows` is a convenience artifact for Windows users. Rebuild it after changing `main.go` or the embedded `.sav`.