PRO Production

Workflow-grade Pro analysis with audit-ready outputs.

workflow pro

## Workflow Narrative

Image Registration Diagnostics

### Problem It Solves

Which pairs are registration-ready, and do we have enough correspondence quality to proceed confidently?

### Who It Is For

- Geospatial registration specialists, EO preprocessing teams, and image-fusion analysts.

### Primary User

Teams building repeatable image registration pipelines (RGB-RGB, thermal-RGB, and cross-date alignment).

### What It Does

- Runs image-pair or image-set registration diagnostics using a RootSIFT feature engine.
- Produces tie-point outputs and pair-level quality metrics with full fallback attempt traces.
- Handles cross-modal pairs (e.g., thermal LWIR to RGB visible) via automatic histogram equalization preprocessing.
- Optionally emits annotated side-by-side pair visualizations with tie-point overlays.
- Emits workflow-level readiness status for registration-first pipelines.

### How It Works

- Builds pair candidates (single pair mode or ranked set mode).
- Extracts RootSIFT descriptors from a Gaussian scale-space pyramid; descriptor distances are computed with wide-SIMD acceleration.
- Applies cross-verified nearest-neighbor matching with ratio test filtering.
- On match shortfall, escalates through a six-strategy fallback chain: `baseline` → `high_feature_baseline` → `relaxed_ratio` → `high_feature_relaxed` → `preprocess_eq_right` → `preprocess_eq_both`; the final two strategies apply histogram equalization to recover keypoints from low-contrast inputs such as LWIR thermal imagery.
- Records the full strategy attempt trace per pair in diagnostics for auditable QA.
- Reports per-pair keypoint counts, match counts, confidence summary, inlier-style proxy metrics, strategy used, and fallback policy.
- Indicative rule: accept match if d1 / d2 <= ratio_test, where d1 and d2 are first/second nearest descriptor distances.

### Why It Wins

- Combines pair planning, RootSIFT matching with automatic cross-modal fallback, auditable attempt tracing, and tie-point artifacts in one reproducible workflow contract.

### Typical Buying Trigger

Manual registration workflows are inconsistent and teams need auditable pair diagnostics before downstream warping/fusion steps.

### Typical Presets

- pair mode: targeted diagnostics for one known pair.
- set mode: ranked pair diagnostics for an image collection.
- balanced defaults (`max_features_per_image=500`, `ratio_test=0.80`) for operational throughput.
- cross-modal pairs (e.g., thermal LWIR to RGB): preprocessing fallback strategies activate automatically on match shortfall; no additional configuration required.

## Inputs

Parameter | Optional | Description
--- | --- | ---
mode: set | pair | no | Execution mode for set-wide pair planning or explicit pair diagnostics.
images_dir | no (set mode) | Input image directory used when mode is set.
left_image, right_image | no (pair mode) | Explicit pair inputs used when mode is pair.
max_pairs | yes | Maximum number of candidate pairs evaluated in set mode.
max_features_per_image | yes | Upper bound on extracted keypoints per image.
ratio_test | yes | Descriptor ratio-test threshold controlling match strictness.
min_matches | yes | [pro] Minimum accepted match count per pair; drives the QA gate, fallback routing, and pass/review/fail classification.
output_prefix | yes | Prefix used to name workflow outputs.
emit_pair_match_viz | yes | If true, writes annotated side-by-side pair images with tie-point lines. Defaults to `false`.
max_pair_visualizations | yes | Maximum number of pair visualizations to write when emit_pair_match_viz is true. Defaults to `8`.
max_lines_per_pair | yes | Maximum number of tie-point lines drawn per visualization. Defaults to `150`.
viz_scale | yes | Downscale factor applied to visualization images, in [0.05, 1.0]. Defaults to `0.5`.

## Outputs

Parameter | Type | Description
--- | --- | ---
pair_diagnostics | JSON | Pair-level diagnostics including candidate score, keypoint counts, match quality, confidence proxies, strategy used, fallback flag, and full strategy attempt trace (`*_pair_diagnostics.json`).
match_summary | JSON | Workflow summary contract with aggregate match metrics, status, and fallback policy record (`*_match_summary.json`).
html_report | HTML | Human-readable customer-facing report generated from the workflow summary contract for stakeholder review and QA traceability.
tie_points | CSV | Tie-point table (`pair_id,left_x,left_y,right_x,right_y,confidence`) for downstream registration workflows (`*_tie_points.csv`).
pair_match_viz | directory | Annotated side-by-side JPEG images per pair with tie-point lines overlaid, written when emit_pair_match_viz is true.

## Python Example

    import whitebox_workflows as wbw

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

    result = wbe.registration_oriented_feature_workflow(
        mode="set",
        images_dir="data/uav_mission/images",
        max_pairs=24,
        max_features_per_image=500,
        ratio_test=0.80,
        min_matches=24,
        output_prefix="output/registration_workflow",
        emit_pair_match_viz=True,
    )

    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