spectralmatch: Performant Relative Radiometric Normalization toolkit with Pseudo-Invariant Features, seamlines, and other utilities for mosaics and time series

Overview

spectralmatch provides a Python library, command line interface, and QGIS plugin with multiple algorithms to perform Relative Radiometric Normalization (RRN). It also includes utilities for generating seamlines, cloud masks, Pseudo-Invariant Features, statistics, preprocessing, and more.

Features

• Automated, Efficient, and Scalable: Designed for large-scale workflows with no manual steps, leveraging multiprocessing and Cloud Optimized GeoTIFF support for fast, efficient processing across images, windows, and bands.

• Resumable Processing: Save image stats and block maps for quicker reprocessing.

• Integrated Seamline and Cloud Masking: Generate seamlines and detect clouds within the same workflow.

• Specify Model Images Include all or specified images in the matching solution to bring all images to a central tendency or selected images spectral profile.

• Consistent Multi-image Analysis: Performs minimal necessary adjustments to achieve inter-image consistency while preserving the original spectral characteristics.

• Sensor and Unit Agnostic: Supports optical imagery from handheld cameras, drones, crewed aircraft, and satellites for reliable single sensor and multi-sensor analysis, while preserving spectral integrity across all pixel units—including negative values and reflectance.

• Enhanced Imagery: Helpful when performing mosaics and time series analysis by blending large image collections and normalizing them over time, providing consistent, high-quality data for machine learning and other analytical tasks.

• Open Source and Collaborative: Free under the MIT License with a modular design that supports community contributions and easy development of new features and workflows. Accessible through a python library, command line interface, and QGIS plugin.

---

Current Matching Algorithms

Global to local matching

This technique is derived from 'An auto-adapting global-to-local color balancing method for optical imagery mosaic' by Yu et al., 2017 (DOI: 10.1016/j.isprsjprs.2017.08.002). It is particularly useful for very high-resolution imagery (satellite or otherwise) and works in a two phase process. First, this method applies least squares regression to estimate scale and offset parameters that align the histograms of all images toward a shared spectral center. This is achieved by constructing a global model based on the overlapping areas of adjacent images, where the spectral relationships are defined. This global model ensures that each image conforms to a consistent radiometric baseline while preserving overall color fidelity. However, global correction alone cannot capture intra-image variability so a second local adjustment phase is performed. The overlap areas are divided into smaller blocks, and each block’s mean is used to fine-tune the color correction. This block-wise tuning helps maintain local contrast and reduces visible seams, resulting in seamless and spectrally consistent mosaics with minimal distortion.

Mean spectral profiles of five cloud masked Landsat images before and after applying Normalized Difference Vegetation Index masking, global regression, and local block adjustment with spectralmatch.

Assumptions

• Consistent Spectral Profile: The true spectral response of overlapping areas remains the same throughout the images.

• Least Squares Modeling: A least squares approach can effectively model and fit all images' spectral profiles.

• Scale and Offset Adjustment: Applying scale and offset corrections can effectively harmonize images.

• Minimized Color Differences: The best color correction is achieved when color differences are minimized.

• Geometric Alignment: Images are assumed to be geometrically aligned with known relative positions via a geotransform. However, they only need to be roughly aligned as pixel co-registration is not required.

• Global Consistency: Overlapping color differences are consistent across the entire image.

• Local Adjustments: Block-level color differences result from the global application of adjustments.

---

Installation (Detailed methods)

Installation as a QGIS Plugin

Install the spectralmatch plugin in QGIS and find the tools in the Processing Toolbox. Install the spectralmatch Python library with the tools in the setup toolbox or manually.

Installation as a Python Library and CLI

Ensure you have the following system-level prerequisites: Python ≥ 3.10, pip, PROJ ≥ 9.3, and GDAL = 3.10.2. Use this command to install the library:

pip install spectralmatch

---

Usage

Example scripts and sample data are provided to verify a successful installation and help you get started quickly in the repository at /docs/examples and downloadable here.

This is an example mosaic workflow using folders for each step:

working_directory = "/path/to/working/directory"
input_folder = os.path.join(working_directory, "Input")
global_folder = os.path.join(working_directory, "GlobalMatch")
local_folder = os.path.join(working_directory, "LocalMatch")
aligned_folder = os.path.join(working_directory, "Aligned")
clipped_folder = os.path.join(working_directory, "Clipped")

global_regression(
    input_images=input_folder,
    output_images=global_folder,
)

local_block_adjustment(
    input_images=global_folder,
    output_images=local_folder,
)

align_rasters(
    input_images=local_folder,
    output_images=aligned_folder,
    tap=True,
)

voronoi_center_seamline(
    input_images=aligned_folder,
    output_mask=os.path.join(working_directory, "ImageMasks.gpkg"),
    image_field_name="image",
)

mask_rasters(
    input_images=aligned_folder,
    output_images=clipped_folder,
    vector_mask=("include", os.path.join(working_directory, "ImageMasks.gpkg"), "image"),
)

merge_rasters(
    input_images=clipped_folder,
    output_image_path=os.path.join(working_directory, "MergedImage.tif"),
)

---

Documentation

Documentation is available at spectralmatch.github.io/spectralmatch/.

---

Contributing Guide

Contributing Guide is available at spectralmatch.github.io/spectralmatch/contributing.

---

License

This project is licensed under the MIT License. See LICENSE for details.