Image Registration Diagnostics

Purpose

Image Registration Diagnostics extracts and matches robust image features (corners, edges, keypoints) across multiple images to facilitate registration, tie-point generation, and multi-temporal alignment without explicit ground control.

Typical Questions This Tool Helps Answer

• Is this image pair geometrically aligned well enough to support meaningful change analysis without ground control points?
• Where are spatial registration errors largest, and which areas should be excluded or flagged for downstream interpretation?
• Can adequate tie-point coverage be achieved automatically, or does the image geometry require manual GCP support?

Background

Background sections in this workflow family should make explicit how signal change can be confounded by acquisition geometry, atmosphere, calibration drift, and georegistration error. A reliable interpretation pipeline therefore separates physical signal change from acquisition artifacts through normalization, alignment, and uncertainty-aware thresholds.

Operationally, users should treat these tools as evidence-weighting systems rather than single-threshold detectors. The most robust workflows combine pre-processing diagnostics, method-specific quality indicators, and post-run plausibility checks before decisions are escalated.

Feature-oriented registration relies on stable keypoints, robust correspondence filtering, and outlier rejection (for example RANSAC) to estimate transforms. Registration confidence should be interpreted with both residual statistics and spatial distribution of tie points.

Methodological Considerations

• Ensure geometric alignment is within the tolerance required by the downstream metric (pixel-level for many raster differences, sub-pixel for interferometric phase workflows).
• Separate radiometric normalization from change inference so threshold choices reflect physical behavior rather than acquisition artifacts.
• Prefer multi-run sensitivity checks on normalization and detection thresholds when decisions depend on marginal signal differences.

Practical Interpretation Pitfalls

Common failure modes include treating sensor noise as change signal, over-trusting single-date anomalies, and ignoring confidence/context layers when operational prioritization is made.

Inputs

Parameters

The runtime also accepts output as an alias for output_prefix.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Important summary fields

Returned payload keys

The workflow returns these output keys:

• pair_diagnostics
• match_summary
• summary (same file as match_summary)
• tie_points
• pair_qc_table
• qc_summary
• html_report
• pair_match_viz_dir when visualization is enabled

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.registration_oriented_feature_workflow(
        mode="pair",
        left_image="frame_001.jpg",
        right_image="frame_002.jpg",
        max_features_per_image=750,
        ratio_test=0.80,
        min_matches=24,
        emit_pair_match_viz=True,
        max_pair_visualizations=4,
        max_lines_per_pair=120,
        viz_scale=0.5,
        output_prefix="registration_pair_a",
)

• Which image pairings in this stack provide robust tie-point support for stable geometric registration?

• Which image pairs have too few matches or low inlier quality, and do those fall below the minimum match threshold requiring fallback strategies or manual intervention?

• Are registration residuals and inlier ratios within acceptable thresholds for reliable change analysis?

• Lowe, D. G. (2004). Distinctive image features from scale-invariant keypoints. IJCV.

• Bay, H., Tuytelaars, T., & Van Gool, L. (2006). "SURF: Speeded Up Robust Features." ECCV, 404-417.

Parameter Interaction Notes

• min_matches is the strongest QA threshold. It affects fallback acceptance and the final status.
• min_match_count and min_inlier_ratio define pair-level QC gate criteria and drive pair_qc_table.csv and qc_summary.json status counts.
• qc_policy scales pair-level QC thresholds (strict tightens, permissive relaxes) and should be recorded with each production run.
• ratio_test and max_features_per_image interact: one changes descriptor strictness and the other changes feature yield.
• In set mode, max_pairs limits the ranked output list, not necessarily the number of candidate combinations considered internally.
• Visualization parameters only change the optional PNG outputs, not the actual scoring.

QA and Acceptance Criteria

1. Verify mode-specific required arguments are correct.
2. Verify the example uses actual runtime argument names.
3. Verify the tie-point CSV header exactly matches the documented schema.
4. Verify both JSON outputs contain the documented fields.
5. Verify the returned payload contains the documented keys.
6. If visualization is enabled, verify the directory and PNG count match the summary.

The workflow fails if the mode is invalid, if required mode-specific paths are missing, if image files do not exist, if numeric limits are out of range, if min_match_count < 1, if min_inlier_ratio is outside [0, 1], if qc_policy is not one of strict, balanced, permissive, or if output_prefix / output is provided as an empty string.

Advanced Operational Guidance

• Use pair mode for deterministic review of a known image pair.
• Use set mode when the workflow needs to nominate promising pairs from a larger image collection.
• Review pair_failures before dismissing a dataset; some failures are decode or image-quality issues rather than geometric incompatibility.
• For cross-modal imagery, inspect attempt_trace and strategy_used to see whether preprocessing fallback was necessary.

Implementation Patterns

• Pair QA run: one explicit pair, no visualization, for automated diagnostics.
• Pair review run: same pair with visualization enabled for human inspection.
• Set planning run: directory-based candidate ranking before downstream registration.
• Threshold tuning run: vary min_matches, ratio_test, and max_features_per_image on the same imagery.

Related Tools

• sar_coregistration
• sar_analysis_readiness
• guided_uav_image_intake_workflow

When To Use This Workflow

Use this workflow when you need evidence about registration readiness rather than a finished registered image. It is especially useful when teams must justify which pairs are good enough for downstream alignment and which ones require manual review.

What this workflow helps you do:

• Rank and screen candidate image pairs.
• Inspect fallback behavior rather than hiding it.
• Hand off tie points and QA evidence to downstream registration steps.

Results Delivery Checklist

1. Deliver pair_diagnostics.json, match_summary.json, and tie_points.csv together.
2. State clearly whether the run used mode=pair or mode=set.
3. Record the final min_matches, min_match_count, min_inlier_ratio, qc_policy, ratio_test, and max_features_per_image values.
4. If visualization was enabled, include the visualization directory and note the scaling settings.
5. Review status, low_quality_pairs, and pairs_requiring_fallback before approving downstream registration.

Common Questions

Q: Why can a run have many matches and still end up as review?
A: Because review is triggered when match count alone is not enough. Low mean_inlier_proxy or pairs below min_matches can still keep the run out of pass.

Q: What is the main misinterpretation risk with tie_points.csv?
A: Treating it as a final registration model. It only contains tie points, not a solved transformation or warped image.

Q: Which settings matter most for scenario sensitivity?
A: min_matches, ratio_test, and max_features_per_image because they determine whether fallback is needed and whether pairs stay above the QA gate.

Q: When should teams enable the optional visualizations?
A: Enable them when a pair is borderline, cross-modal, or heading to manual review. They are evidence outputs for people, not part of the scoring itself.