API

Getting started

The RasterFuse class implements surface reflectance correction. This code segment uses it to correct an aerial image by fusing it with a Sentinel-2 reference. The images are taken from the homonim test data.

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)

In the next segment, we use RasterCompare to compare the source and corrected aerial images with a second reference. The tabulated results give an indication of surface reflectance accuracy before and after correction.

from homonim import RasterCompare

# url of independent landsat reference for evaluation
cmp_ref_file = (
    'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'
    'tests/data/reference/landsat8_byte.tif'
)

# Compare source and corrected similarity with the independent reference,
# cmp_ref_file, giving an indication of the improvement in surface reflectance
# accuracy.
summ_dict = {}
for cmp_src_file, cmp_src_label in zip(
    [src_file, corr_file],
    ['Source', 'Corrected'],
):
    with RasterCompare(cmp_src_file, cmp_ref_file) as compare:
        stats_dict = compare.process()
        summ_dict[cmp_src_label] = stats_dict['Mean']

# print comparison tables
print(RasterCompare.schema_table())
print('\n\n' + RasterCompare.stats_table(summ_dict))

The output:

ABBREV   DESCRIPTION
-------- -----------------------------------------
r²       Pearson's correlation coefficient squared
RMSE     Root Mean Square Error
rRMSE    Relative RMSE (RMSE/mean(ref))
N        Number of pixels

     Band    r²   RMSE   rRMSE     N
--------- ----- ------ ------- -----
   Source 0.390 93.517   2.454 28383
Corrected 0.924 16.603   0.489 28383

Take a look at the tutorials for more examples.

Reference

RasterFuse

class homonim.RasterFuse

__init__(*args, **kwargs)

Class for correcting an image to surface reflectance, by fusion with a reference.

For best results, reference and source image(s) should be concurrent, co-located and spectrally similar. Reference image extents must encompass those of the source image.

The reference image should contain bands that are approximate (wavelength) matches to the source image bands. Where source and reference images are RGB, or have center_wavelength metadata, bands are matched automatically based on wavelength. Where there are the same number of source and reference bands, and no center_wavelength metadata, bands are assumed to be in matching order. Subsets and ordering of source and reference bands can be specified with the src_bands and ref_bands parameters.

Note

Images downloaded with geedim have center_wavelength metadata compatible with homonim.

Parameters:

src_filename (str, Path) – Path to a source image file.
ref_filename (str, Path) – Path to a reference image file.
proc_crs (homonim.enums.ProcCrs, optional) – ProcCrs instance specifying which of the source/reference image CRS and pixel grid to use for processing. For most use cases, it can be left as the default of auto i.e. the lowest resolution of the source and reference image CRS’s.
src_bands (list of int, optional.) – Indexes of source spectral bands to be processed (1 based). If not specified, all bands with the center_wavelength property, or all non-alpha bands, are used.
ref_bands (list of int, optional.) – Indexes of reference spectral bands to match and fuse with source bands (1 based). Should contain at least as many elements as src_bands, or the number of valid bands in the source image file, if src_bands is not specified. If ref_bands is not specified, all reference bands with the center_wavelength property, or all non-alpha bands are used.
force (bool, optional) – Bypass auto wavelength matching, and any band-matching errors. Use with caution.

__new__(**kwargs)

Methods

`create_model_config`([mask_partial, ...])	Utility method to create a KernelModel configuration dictionary that can be passed to `KernelModel.__init__()` and `homonim.RasterFuse.process()`.
`create_block_config`([threads, max_block_mem])	Utility method to create a block processing configuration dictionary that can be passed to `RasterFuse.process()`.
`create_out_profile`([driver, dtype, nodata, ...])	Utility method to create a profile for the output image(s) that can be passed to `RasterFuse.process()`.
`process`(corr_filename[, model, ...])	Correct source image to surface reflectance by fusion with a reference.

Attributes

`src_bands`	Matched source band indices (1-based).
`ref_bands`	Matched reference band indices (1-based).
`proc_crs`	Which of the source and reference image CRS and pixel grids will be used for processing.
`closed`	True if both source and reference images are closed, otherwise False.

RasterCompare

class homonim.RasterCompare

__init__(*args, **kwargs)

Class to compare source and reference images.

Reference and source image(s) should be co-located and spectrally similar. Reference image extents must encompass those of the source image(s).

The reference image should contain bands that are approximate (wavelength) matches to the source image bands. Where source and reference images are RGB, or have center_wavelength metadata, bands are matched automatically based on wavelength. Where there are the same number of source and reference bands, and no center_wavelength metadata, bands are assumed to be in matching order. Subsets and ordering of source and reference bands can be specified with the src_bands and ref_bands parameters.

Note

Images downloaded with geedim have center_wavelength metadata compatible with homonim.

Parameters:

src_filename (str, pathlib.Path) – Path or URL of the source image file.
ref_filename (str, pathlib.Path) – Path or URL of the reference image file.
proc_crs (homonim.enums.ProcCrs, optional) – ProcCrs instance specifying which of the source/reference image CRS and pixel grid to use for processing. For most use cases, it can be left as the default of auto i.e. the lowest resolution of the source and reference image CRS’s.
src_bands (list of int, optional.) – Indexes of source spectral bands to be processed (1 based). If not specified, all bands with the center_wavelength property, or all non-alpha bands, are used.
ref_bands (list of int, optional.) – Indexes of reference spectral bands to match and fuse with source bands (1 based). Should contain at least as many elements as src_bands, or the number of valid bands in the source image file, if src_bands is not specified. If ref_bands is not specified, all reference bands with the center_wavelength property, or all non-alpha bands are used.
force (bool, optional) – Bypass auto wavelength matching, and any band-matching errors. Use with caution.

__new__(**kwargs)

Methods

`process`(**kwargs)	Compare source and reference images.
`create_config`([threads, max_block_mem, ...])	Utility method to create a RasterCompare configuration dictionary whose items can be passed as keyword arguments to `RasterCompare.process()`.
`schema_table`()	Return a table string describing the `RasterCompare.process()` statistics.
`stats_table`(stats_dict[, key_header])	Return a table string for the provided comparison statistics.

Attributes

`src_bands`	Matched source band indices (1-based).
`ref_bands`	Matched reference band indices (1-based).
`schema`	Dictionary describing the statistics returned by `RasterCompare.process()`.
`proc_crs`	Which of the source and reference image CRS and pixel grids will be used for processing.
`closed`	True if both source and reference images are closed, otherwise False.

ParamStats

class homonim.ParamStats

__init__(param_filename: Path | str)

Class to calculate the statistics of a parameter image.

Parameters:: param_filename (pathlib.Path, str) – Path to a parameter image file, as created by homonim.RasterFuse.process() with the param_filename argument specified.

__new__(**kwargs)

Methods

`stats`([threads])	Find parameter image statistics.
`schema_table`()	Return a table string describing statistics returned by `ParamStats.stats()`.
`stats_table`(stats_list)	Return a table string for the provided parameter statistics.

Attributes

`schema`	Dictionary describing the statistics returned by `ParamStats.stats()`.
`metadata`	Parameter metadata string.
`closed`	True if the parameter file is closed, otherwise False.

enums

Model

class homonim.enums.Model

Linear model variants for correcting to surface reflectance.

Roughly speaking, gain compensates for atmospheric absorption and anisotropic (BRDF) effects, and offset (when present) compensates for atmospheric reflectance and haze.

gain = 'gain': Gain-only model, suitable for haze-free and zero offset images (i.e. images where a surface reflectance of zero corresponds to a pixel value of ± zero).

gain_blk_offset = 'gain-blk-offset': Gain-only model applied to offset normalised image blocks. Suitable for most source-reference combinations.

gain_offset = 'gain-offset': Gain and offset model. The most accurate model, but sensitive to differences between source and reference, such as shadowing and land cover changes. Suitable for well-matched source / reference image pairs.

__new__(value)

ProcCrs

class homonim.enums.ProcCrs

CRS and pixel grid in which images will be processed.

__new__(value)

auto = 'auto': Lowest resolution of the source and reference image CRS’s (recommended).

src = 'src': Source image CRS.

ref = 'ref': Reference image CRS.