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 Learn More