PRO Production

Estimate interferometric coherence between SAR acquisitions (direct, complex, or bundle modes).

workflow pro

## Workflow Narrative

SAR Interferogram and Coherence

### Problem It Solves

Can this SAR pair be converted into defensible interferogram/coherence products with auditable provenance and QA diagnostics?

### Who It Is For

- InSAR practitioners and SAR operations teams requiring repeatable pair-level coherence/interferogram products.

### Primary User

Infrastructure deformation monitoring teams, hazard intelligence groups, and SAR analytics operations.

### What It Does

- Produces interferogram, coherence, and valid-mask outputs from compatible SAR pairs in one dedicated workflow.
- Accepts either direct SAR rasters, supported SAR bundles, or complex split real/imag SAR inputs.
- Emits standardized machine-readable summary and optional HTML report artifacts for auditable downstream use.

### How It Works

- Resolves reference and moving SAR inputs from either direct raster mode, bundle mode, or complex component mode.
- Optionally performs internal `sar_coregistration` handoff when grids are mismatched, unless the caller explicitly asserts a prealigned pair.
- Computes either complex-domain interferometric phase and coherence magnitude (complex mode) or amplitude-domain proxy interferogram/coherence (scalar mode).
- Uses summed-area coherence kernels and parallel row-chunk evaluation to reduce runtime on larger scenes; optional fast mode can further decimate coherence sampling.
- Indicative formulas: $\phi = \mathrm{atan2}(\Im(z), \Re(z))$ for interferometric phase where $z = s_{ref}\,\overline{s_{mov}}$, and local-window coherence proxy from normalized cross-correlation magnitude.

### Why It Wins

- Unifies SAR pair ingest, optional alignment handoff, product generation, acceptance gating, and QA/report artifacts in one reproducible contract workflow.
- Operational note:
- When `auto_coregister_pair=true`, this tool invokes the existing `sar_coregistration` engine internally if the pair grids do not already match.
- If the pair is known to already be aligned, prefer `assume_prealigned_pair=true` and leave `auto_coregister_pair=false` to avoid unnecessary alignment work.
- Failed acceptance on the coreg residual gate indicates the pair/alignment should not be treated as registration-quality enough for trusted downstream interpretation.

### Typical Buying Trigger

Teams need a dedicated production stage for interferogram/coherence outputs instead of ad hoc post-processing scripts.

### Typical Presets

- scalar raster pair: direct amplitude-domain processing with optional auto-coregistration.
- bundle pair: bundle-native measurement resolution with identical output contract.
- complex split mode: complex-domain phase/coherence computation from explicit real/imag rasters.
- fast large-scene mode: reduced coherence workload via `performance_profile="fast"`, optional `coherence_decimation`, and selective artifact writing.

## Inputs

Parameter | Optional | Description
--- | --- | ---
reference_sar or reference_sar_bundle | no (unless complex mode) | Reference SAR source provided either as a direct raster path or supported SAR bundle root.
moving_sar or moving_sar_bundle | no (unless complex mode) | Moving SAR source provided either as a direct raster path or supported SAR bundle root.
reference_sar_real, reference_sar_imag, moving_sar_real, moving_sar_imag | no (complex mode) | Complex input mode components for explicit complex-domain interferogram/coherence processing.
reference_measurement_key, moving_measurement_key | yes | Optional bundle measurement selectors when SAR bundles include multiple measurement assets.
auto_coregister_pair, assume_prealigned_pair, coreg_mode | yes | Pair-alignment controls: either invoke internal `sar_coregistration` when needed or explicitly assert the pair is already aligned.
coreg_max_offset_px, coreg_decimation, coreg_min_overlap_fraction | yes | Optional scalar-mode coreg handoff tuning controls for search radius, sampling stride, and minimum overlap.
coherence_window, performance_profile, coherence_decimation | yes | Coherence kernel controls. Fast mode can reduce effective window size and decimate coherence sampling on very large scenes.
input_dem | yes | Optional DEM used for terrain-context masking and geometry-support pathways.
write_interferogram, write_coherence, write_valid_mask, write_html_report | yes | Optional artifact suppression controls used to reduce heavy-run output cost.
output_layout, output_compression, output_tile_size | yes | GeoTIFF write-profile controls for standard vs COG-style output and compression behavior.
output_prefix | yes | Output artifact prefix.

## Outputs

Parameter | Type | Description
--- | --- | ---
interferogram | optional GeoTIFF | Interferogram raster (complex phase in complex mode, amplitude-domain proxy in scalar mode) when writing is enabled.
coherence | optional GeoTIFF | Coherence magnitude raster from local-window pair statistics when writing is enabled.
valid_mask | optional GeoTIFF | Binary/flag mask indicating valid pair-support pixels used during computation when writing is enabled.
summary | JSON | Machine-readable summary report containing run metadata, QA diagnostics, timings, and artifact paths.
html_report | optional HTML | Human-readable customer-facing report generated from the summary contract for stakeholder review and QA traceability when writing is enabled.

## Python Example

    import whitebox_workflows as wbw

    wbe = wbw.WbEnvironment(include_pro=True, tier="pro")

    result = wbe.sar_interferogram_coherence(
        reference_sar="output/sar_coreg_reference.tif",
        moving_sar="output/sar_coreg_moving_aligned.tif",
        assume_prealigned_pair=True,
        coherence_window=7,
        performance_profile="balanced",
        output_prefix="output/sar_ifg_coh",
    )

    print(result)

## License Notice

Use of this function requires a license for Whitebox Workflows Professional (WbW-Pro). Please visit www.whiteboxgeo.com to purchase a license.

## Project Links

WbW Homepage User Manual Support WbW