Add a dolphin geocode CLI tool to deocode radar-coordinate results (#684)

* Add a radar geocoding module + cli

* Add tests, and add isce2 detection

* Add docs on geocoding to a How To guide

Author: scottstanie

docs/faq.md

@@ -0,0 +1,16 @@
+## Frequently Asked Questions
+
+### 1. What's the sign convention of the line-of-sight data?
+
+**Summary**:
+
+- In the `timeseries/` folder, positive means motion *toward* the sensor, and negative means motion *away* from the sensor.
+- In the `interferograms/` folder, the sign is flipped and positive phase means motion *away* from the sensor.
+
+`dolphin` follows similar sign conventions to other InSAR software such as isce2 and MintPy.
+Inteferograms in `dolphin` are formed as `reference_slc * conj(secondary_slc)`. The phase of the complex values in the `interferograms/` folder indicates an increase in the line-of-sight (LOS) direction from the sensor, while a negative value indicates a decrease (motion towards the sensor).
+
+After unwrapping, the sign convention is flipped and converted to meters (if the `wavelength` parameter is set) for the outputs in the `timeseries` folder.
+Assuming the `wavelength` parameter is set, the unwrapped phase is multiplied by $-4\pi / \lambda$, so positive values in the timeseries rasters indicate motion *toward* the sensor, and negative values indicate motion *away* from the sensor. Thus, when combining two LOS rasters from ascending and descending geometries, postive values in both indicate that uplift is occurring.
+
+Note that `dolphin` is able to process coregistered SLCs from arbitrary processing software, and does not always attempt to guess what sensor the SLCs are derived from. If the `wavelength` (within the `input_options` group) is not set in during configuration, the outputs in the `timeseries` folder will remain in radians, but keep the same sign convention (positive = motion toward the sensor).

docs/how-to-geocode-radar-results.md

@@ -0,0 +1,120 @@
+# How to geocode dolphin results (ISCE2 / ISCE3)
+
+After running dolphin on radar-geometry data processed with ISCE2 or ISCE3, the
+outputs (interferograms, unwrapped phase, time series, velocity) are still in
+swath/radar coordinates. The `dolphin geocode` command transforms them to
+geographic coordinates using per-pixel latitude/longitude arrays from ISCE's
+geometry products.
+
+It auto-detects the geolocation file naming convention:
+
+| Processor           | Geometry directory       | Lat file  | Lon file  |
+| ------------------- | ------------------------ | --------- | --------- |
+| ISCE3 / dolphin     | `geometry/`              | `y.tif`   | `x.tif`   |
+| ISCE2 topsStack     | `merged/geom_reference/` | `lat.rdr` | `lon.rdr` |
+| ISCE2 stripmapStack | `geom_reference/`        | `lat.rdr` | `lon.rdr` |
+
+## Bulk geocode a dolphin work directory
+
+The simplest way to geocode all outputs at once. This discovers rasters in
+`timeseries/`, `unwrapped/`, etc. and writes geocoded results to
+`<dolphin-dir>/geocoded/`, mirroring the directory structure.
+
+```bash
+dolphin geocode \
+    -d ./dolphin_output \
+    -g ./geometry \
+    -c dolphin_config.yaml
+```
+
+The `-c` flag reads `output_options.strides` from your config so the
+geolocation arrays (which are at full resolution) are properly subsampled to
+match your multilooked outputs.
+
+## ISCE2 topsStack example
+
+```bash
+dolphin geocode \
+    -d ./dolphin_output \
+    -g ./merged/geom_reference \
+    -c dolphin_config.yaml
+```
+
+## ISCE2 stripmapStack example
+
+```bash
+dolphin geocode \
+    -d ./dolphin_output \
+    -g ./geom_reference \
+    -c dolphin_config.yaml
+```
+
+## Geocode specific files
+
+You can also pass individual files instead of a whole directory:
+
+```bash
+# Single file
+dolphin geocode -i velocity.tif -g geometry/
+
+# Multiple files to an output directory
+dolphin geocode \
+    -i timeseries/velocity.tif \
+    -i unwrapped/20220101_20220201.unw.tif \
+    -g geometry/ \
+    -o geocoded/
+```
+
+## Reproject to UTM with a specific pixel spacing
+
+```bash
+dolphin geocode \
+    -d ./dolphin_output \
+    -g ./geometry \
+    -c dolphin_config.yaml \
+    --srs 32610 \
+    -s 30
+```
+
+This reprojects to UTM zone 10N (EPSG:32610) with 30-meter pixel spacing.
+
+## Apply a mask during geocoding
+
+Pass a binary mask (0 = invalid, nonzero = valid) to mark pixels as nodata in
+the geocoded output. The mask can be at the strided resolution or at full
+resolution (it will be subsampled automatically if strides are set).
+
+```bash
+dolphin geocode \
+    -i velocity.tif \
+    -g geometry/ \
+    -c dolphin_config.yaml \
+    --mask water_mask.tif
+```
+
+## Include additional products
+
+By default, bulk mode geocodes time series and unwrapped interferograms. Use
+flags to include more:
+
+```bash
+dolphin geocode \
+    -d ./dolphin_output \
+    -g ./geometry \
+    --include-interferograms \
+    --include-auxiliary
+```
+
+| Flag                       | What it adds                                                       |
+| -------------------------- | ------------------------------------------------------------------ |
+| `--include-unwrapped`      | Unwrapped interferograms (on by default)                           |
+| `--include-interferograms` | Wrapped interferograms, similarity, temporal/multilooked coherence |
+| `--include-auxiliary`      | CRLB, amplitude dispersion                                         |
+
+## Parallel processing
+
+Geocoding is parallelized across files. Control the number of workers with `-j`:
+
+```bash
+dolphin geocode -d ./dolphin_output -g ./geometry -j 4
+```

docs/how-to-guides.md

@@ -0,0 +1,3 @@
+# How-to Guides
+
+- [How to geocode dolphin results (ISCE2 / ISCE3)](./how-to-geocode-radar-results.md)

docs/index.md

@@ -8,7 +8,7 @@
 1. [Getting started](./getting-started.md)
 1. [Overview of processing modules](./overview.md)
 1. [Tutorials](tutorials.md)
+1. [How-To Guides](how-to-guides.md)
+1. [FAQ](faq.md)
 1. [Code Reference](reference/summary.md)
 1. [Changelog](changelog.md)
-<!-- 1. [How-To Guides](how-to-guides.md) -->
-<!-- 1. [Background theory](background-theory.md) -->

mkdocs.yml

@@ -61,9 +61,9 @@ nav:
 # - Tutorials:
 #   - Notebook page: notebooks/walkthrough-basic.ipynb
 #   # - Notebook page2: notebooks/walkthrough-basic.html
-# - how-to-guides.md
+- how-to-guides.md
+- faq.md
 # https://mkdocstrings.github.io/recipes/#generate-a-literate-navigation-file
 # trailing slash: that mkdocs-literate-nav knows a summary.md file is in that folder.
 - developer-setup.md
 - Code Reference: reference/
-# - background-theory.md

src/dolphin/cli.py

@@ -17,6 +17,7 @@ def main() -> int:
     import tyro
 
     from dolphin.filtering import filter_rasters
+    from dolphin.geocode import run as run_geocode
     from dolphin.timeseries import run as run_timeseries
     from dolphin.unwrap import run as run_unwrap
     from dolphin.workflows._cli_config import ConfigCli
@@ -28,6 +29,7 @@ def main() -> int:
             "unwrap": run_unwrap,
             "timeseries": run_timeseries,
             "filter": filter_rasters,
+            "geocode": run_geocode,
         },
         prog=__package__,
     )