homonim 0.4.0

Correct aerial and satellite imagery to surface reflectance.

homonim

Correct aerial and satellite imagery to surface reflectance.

Description

homonim provides a command line interface and API for correcting remotely sensed imagery to approximate surface reflectance. It implements a form of spectral harmonisation, that adjusts for spatially varying atmospheric and anisotropic (BRDF) effects, by fusion with satellite surface reflectance data. Manual reflectance measurements and target placements are not required.

homonim is useful for pre-processing in quantitative mapping applications, and for reducing seamlines and other visual artefacts in image mosaics. It can be applied to multi-spectral drone, aerial and satellite imagery. The consistency of multi-temporal and multi-sensor data can improved through its use.

See the documentation site for more detail: https://homonim.readthedocs.io/.

Installation

homonim is available as a python 3 package, via pip or conda.

pip

pip install homonim

conda

conda install -c conda-forge homonim

Getting started

Command line interface

homonim command line functionality is accessed through the commands:

• fuse: Correct image(s) to surface reflectance.

• compare: Compare image(s) with a reference.

• stats: Report parameter statistics.

Get help on homonim with:

homonim --help

and help on a homonim command with:

homonim <command> --help

Examples

Correct source.tif to surface reflectance by fusion with reference.tif, using the default settings:

homonim fuse source.tif reference.tif

Correct images matching source*.tif to surface reflectance by fusion with reference.tif. Use a 5 x 5 pixel kernel and the gain-blk-offset model for correction, and place corrected images in the ./corrected directory:

homonim fuse -k 5 5 -m gain-blk-offset -od ./corrected source*.tif reference.tif

Statistically compare source.tif and corrected.tif with reference.tif.

homonim compare source.tif corrected.tif reference.tif

API

Example

Surface reflectance correction of an aerial image using a Sentinel-2 reference.

from pathlib import Path
from homonim import RasterFuse, RasterCompare, Model

# urls of source and reference test images
src_file = (
    'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'
    'tests/data/source/ngi_rgb_byte_1.tif'
)
ref_file = (
    'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'
    'tests/data/reference/sentinel2_b432_byte.tif'
)

# path to corrected file to create
corr_file = './corrected.tif'

# Correct src_file to surface reflectance by fusion with ref_file, using the
# `gain-blk-offset` model and a kernel of 5 x 5 pixels.
with RasterFuse(src_file, ref_file) as fuse:
    fuse.process(corr_file, Model.gain_blk_offset, (5, 5), overwrite=True)

Reference imagery

geedim can be used as a companion tool for searching and downloading cloud-free reference imagery. Alternatively, satellite imagery is available from a number of sources, including the Google, Amazon and Microsoft repositories.

Usage

See the documentation here.

Terminology

homonim is shorthand for homogenise image and is a reference to the paper on which it is based.

Credits

homonim relies on these excellent packages:

• rasterio

• opencv

• numpy

License

homonim is licensed under the terms of the AGPLv3. This project is developed in collaboration with InnovUS at Stellenbosch University, alternative licenses can be arranged by contacting them.

Citation

Please cite use of the code as:

• Dugal Harris & Adriaan Van Niekerk (2019) Radiometric homogenisation of aerial images by calibrating with satellite data, International Journal of Remote Sensing, 40:7, 2623-2647, DOI: https://doi.org/10.1080/01431161.2018.1528404.

Bibtex:

@article{doi:10.1080/01431161.2018.1528404,
    author = {Dugal Harris and Adriaan Van Niekerk},
    title = {Radiometric homogenisation of aerial images by calibrating with satellite data},
    journal = {International Journal of Remote Sensing},
    volume = {40},
    number = {7},
    pages = {2623-2647},
    year  = {2019},
    publisher = {Taylor & Francis},
    doi = {10.1080/01431161.2018.1528404},
    URL = {https://doi.org/10.1080/01431161.2018.1528404},
}