Skip to content

Latest commit

 

History

History
203 lines (129 loc) · 6.64 KB

README.rst

File metadata and controls

203 lines (129 loc) · 6.64 KB
Raw

Tests codecov PyPI version conda-forge docs License: AGPL v3

homonim

example

Correct drone, 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 homonim import RasterFuse, 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:

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},
}