Band Registration Pipeline (NIR ↔ RGB)

Robust multi-band image registration pipeline for aligning target bands (e.g., R/G/B) to a reference band (e.g., NIR). The pipeline detects keypoints, computes descriptors, matches features, filters correspondences (ratio-test, NMS, RANSAC), estimates displacement, and optionally applies pixel translation to align patches. Visualization, diagnostics, and logging are built-in and configurable via YAML.

---

Table of Contents

• Features
• Project Structure
• Installation
• Quick Start
• Configuration
• CLI Usage
• Pipeline Overview
• Module Reference
• Outputs
• Logging
• Troubleshooting
• Roadmap
• Contributing
• License

---

Features

• Keypoint detectors: ORB, HARRIS (hooks for SIFT/SURF/FAST)
• Descriptors: HOG, Simple (and ORB native descriptors)
• Matchers: Brute-Force, FLANN, correlation, KNN with Lowe's ratio test
• Filters: ratio test, non-maximum suppression, RANSAC (translation/affine/homography)
• Displacement estimation with robust aggregation (median/trimmed-mean/mean)
• Preprocessing: CLAHE, optional histogram equalization, Gaussian blur
• Subpixel shift and configurable interpolation
• Visualizations for keypoints, matches (raw/filtered), and overlays
• YAML configuration, JSON/CSV diagnostics, structured logs

---

Project Structure

band_registration/
  configs/
    default.yml           # Main pipeline configuration
  logs/
    registration.log      # Runtime logs (created/rotated by app)
  outputs/                # Registered images and artifacts
  utils/
    config_loader.py      # YAML → dataclass-like config
    data_io.py            # I/O, preprocessing, OpenCV helpers
    descriptor.py         # HOG/Simple descriptors
    displacement.py       # Displacement estimation & stats
    filtering.py          # Ratio test, NMS, RANSAC, thresholds
    keypoints.py          # ORB/HARRIS (extensible)
    matching.py           # BF/FLANN/correlation/KNN
    registration.py       # Higher-level registration utilities
    visualization.py      # Keypoints/matches/overlay plots
  main.py                 # CLI entrypoint
  README.md               # This file
  requirements.txt        # Python dependencies

---

Installation

1. Python 3.9+ recommended.

2. Create and activate a virtual environment:

python -m venv .venv
# Windows PowerShell
. .venv\Scripts\Activate.ps1

3. Install dependencies:

pip install --upgrade pip
pip install -r requirements.txt

---

Quick Start

1. Point the config to your reference and target band files in configs/default.yml (see Configuration).

2. Run the pipeline:

python main.py --config configs/default.yml

3. Inspect outputs in outputs/, plots in plots/ (if enabled), diagnostics in reports/, and logs in logs/.

---

Configuration

All behavior is driven by a YAML file. Key fields from configs/default.yml:

data:
  reference_band: "/path/to/NIR.tif"
  target_bands:
    - "/path/to/RED.tif"
  output_dir: "./outputs"
  overwrite: true
  driver: "GTiff"
  dtype: "float32"

patch:
  x: 4556
  y: 900
  width: 512
  height: 512

preprocess:
  equalize_hist: false
  clahe: true
  blur_kernel: 0

detector:
  method: "ORB"        # SIFT, SURF, ORB, FAST, HARRIS
  nfeatures: 1000

descriptor:
  method: "HOG"        # HOG, Simple

matcher:
  method: "BF"         # BF, FLANN, CORRELATION, KNN
  cross_check: true
  norm_type: "L2"
  knn_k: 2
  ratio: 0.75

filters:
  apply_ratio_test: true
  apply_nms: true
  nms_radius: 8
  apply_ransac: true
  ransac:
    model: "translation"  # translation | affine | homography
    threshold_px: 3.0
    min_inliers: 6

aggregation:
  method: "median"        # median | trimmed_mean | mean
  trim_fraction: 0.1
  reject_outliers: true
  outlier_sigma: 2.5

transform:
  apply_shift: true
  subpixel: true
  interpolation: "linear" # nearest | linear | cubic

visualization:
  show_keypoints: true
  show_matches_raw: true
  show_matches_filtered: true
  show_overlay: true
  show_plots: true
  save_plots: true
  plot_dir: "./plots"
  overlay_alpha: 0.5
  figsize: [10, 5]
  dpi: 150

diagnostics:
  save_json: true
  save_csv: true
  report_dir: "./reports"

logging:
  level: "INFO"
  log_file: "./logs/registration.log"

Notes:

• For ORB, descriptors are produced by the detector; for HARRIS, select a descriptor in descriptor.method.

---

CLI Usage

python main.py --config <path_to_yaml>

# Example
python main.py --config configs/default.yml

Arguments:

• --config, -c Path to the YAML config (default: configs/default.yml).

---

Pipeline Overview

1. Load configuration and images
2. Extract reference/target patches
3. Optional preprocessing (CLAHE, equalization, blur)
4. Detect keypoints (e.g., ORB/HARRIS)
5. Compute descriptors (HOG/Simple or ORB-native)
6. Match features (BF/FLANN/correlation/KNN)
7. Filter matches (ratio test, NMS, RANSAC)
8. Estimate displacement with robust aggregation
9. Optional subpixel shift and write registered outputs
10. Visualize keypoints, matches, and overlays; export diagnostics

This example uses ORB (Oriented FAST and Rotated BRIEF) algorithm to extract keypoints and describe them.

Next, BF (Brute-Force) matcher is used to match the keypoints.

Applying RANSAC (Random Sample Consensus) to filter matches.

Overlaying target image over reference image.

---

Module Reference

• utils/config_loader.py: Loads YAML into a structured config object.
• utils/data_io.py: Raster I/O, patch extraction, preprocessing, OpenCV conversions.
• utils/keypoints.py: Keypoint detection for ORB/HARRIS and extensions.
• utils/descriptor.py: Descriptor extraction (HOG/Simple) for detector-agnostic workflows.
• utils/matching.py: BF/FLANN/correlation matching; KNN and ratio test support.
• utils/filtering.py: Post-match filtering: ratio test, NMS, RANSAC, distance thresholds.
• utils/displacement.py: Computes displacement and summary statistics.
• utils/registration.py: Utilities for applying transforms and writing outputs.
• utils/visualization.py: Plots for keypoints, matches, and overlays.

---

Outputs

• Each stage can be visualised by configuring YAMl file in visualization section.

---

Logging

• Logs are written to logs/registration.log at the level set by logging.level.
• Log file path can be changed via logging.log_file.

---

Troubleshooting

• No/too few matches: Increase detector.nfeatures, enable preprocess.clahe, relax filters.ransac.threshold_px.
• Mismatches: Tighten matcher.ratio, enable filters.apply_ransac, reduce preprocess.blur_kernel.
• Artifacts in overlay: Use transform.subpixel: true and transform.interpolation: cubic.
• Large misalignment: Start with larger patches or try filters.ransac.model: affine.

---

Roadmap

• Add SIFT/SURF fallbacks (patent-free implementations or via optional packages)
• Full-image tiling and mosaic alignment
• Automatic patch suggestion and QA metrics
• GPU-accelerated matching and RANSAC

---

Contributing

Issues and pull requests are welcome. Please keep changes focused and include before/after visualizations where relevant.

---