Command line interface

Getting started

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

Running examples

The examples that follow use the homonim test images. You can get these by downloading the repository directly:

curl -LO# "https://github.com/leftfield-geospatial/homonim/archive/refs/heads/main.zip"
tar -xf main.zip

Alternatively, you can clone the repository with git:

git clone https://github.com/leftfield-geospatial/homonim.git

After you have the repository, navigate to <homonim root>/tests/data, and create a corrected sub-directory to contain processed images:

cd <homonim root>/tests/data
mkdir corrected

The commands that follow use relative paths, and should be run from <homonim root>/tests/data (<homonim root> will be one of homonim-main or homonim, depending on your download method).

Basic fusion and comparison

The gain-blk-offset model and kernel shape of 5 x 5 pixels are the default fusion settings and work reasonably well for a variety of problems. Here we specify these settings to correct the test aerial images with the Sentinel-2 reference.

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

The corrected images are placed in the corrected sub-directory, and named with a FUSE_cREF_mGAIN-BLK-OFFSET_k5_5 postfix describing the fusion parameters.

To investigate the change in surface reflectance accuracy, we compare source and corrected images with a second reference image not used for fusion, i.e. a Landsat-8 reference.

homonim compare ./source/*rgb_byte*.tif ./corrected/*FUSE*.tif ./reference/landsat8_byte.tif

This command prints a series of tables describing the per-band similarity between each source/corrected and reference image pair. The last table summarises these results per-image:

...
Summary over bands:

                                              File    r²   RMSE   rRMSE     N
-------------------------------------------------- ----- ------ ------- -----
                                ngi_rgb_byte_1.tif 0.390 93.517   2.454 28383
                                ngi_rgb_byte_2.tif 0.488 94.049   2.380 28166
                                ngi_rgb_byte_3.tif 0.386 88.610   2.323 27676
                                ngi_rgb_byte_4.tif 0.607 89.409   2.412 27342
ngi_rgb_byte_1_FUSE_cREF_mGAIN-BLK-OFFSET_k5_5.tif 0.924 16.603   0.489 28383
ngi_rgb_byte_2_FUSE_cREF_mGAIN-BLK-OFFSET_k5_5.tif 0.906 15.590   0.445 28166
ngi_rgb_byte_3_FUSE_cREF_mGAIN-BLK-OFFSET_k5_5.tif 0.881 15.531   0.456 27676
ngi_rgb_byte_4_FUSE_cREF_mGAIN-BLK-OFFSET_k5_5.tif 0.897 15.702   0.474 27342

The first four rows list the source images, and the last four, the corrected images.

It is possible to combine the above fuse and compare commands, using the --compare option as follows:

homonim fuse -m gain-blk-offset -k 5 5 -od ./corrected --compare ./reference/landsat8_byte.tif --overwrite  ./source/*rgb_byte*.tif ./reference/sentinel2_b432_byte.tif

Band matching

homonim automatically matches source to reference spectral bands when these images are either RGB or have center_wavelength metadata (as is the case with the homonim test data). Subsets of source and/or reference bands to use for matching can be specified with the --src-band and --ref-band options.

Let’s correct the red, green and blue bands of the Landsat-8 reference with the MODIS NBAR reference. The --src-band option is used to specify the Landsat-8 band numbers corresponding to red, green and blue. homonim then finds the matching MODIS NBAR bands.

homonim --verbose fuse --src-band 4 --src-band 3 --src-band 2 -od ./corrected ./reference/landsat8_byte.tif ./reference/modis_nbar.tif

With the --verbose option specified above, homonim prints a table showing which source and reference bands have been matched:

Source    Source                   Source  Ref                   Ref                        Ref
Name      Description             Wavelen  Name                  Description            Wavelen
--------  --------------------  ---------  --------------------  -------------------  ---------
SR_B2     Band 2 (blue)             0.482  Nadir_Reflectance_Ba  NBAR at local solar      0.469
          surface reflectance              nd3                   noon for band 3
SR_B3     Band 3 (green)            0.562  Nadir_Reflectance_Ba  NBAR at local solar      0.555
          surface reflectance              nd4                   noon for band 4
SR_B4     Band 4 (red) surface      0.655  Nadir_Reflectance_Ba  NBAR at local solar      0.645
          reflectance                      nd1                   noon for band 1

In the case where source and reference are not RGB, and don’t have center_wavelength metadata, it is up to the user to specify matching bands. This can be done simply by providing source and reference files with the same number of bands in the matching order (i.e. source bands 1, 2, .., N correspond to reference bands 1, 2, …, N). Or, by specifying matching order subsets of source and reference bands with the --src-band and --ref-band options.

Let’s repeat the previous example to see how this would look. Here, we also specify the matching reference bands with the --ref-band option (source bands 4, 3, 2 match reference bands 1, 4, 3 - in that order).

homonim --verbose fuse --src-band 4 --src-band 3 --src-band 2 --ref-band 1 --ref-band 4 --ref-band 3 -od ./corrected --overwrite ./reference/landsat8_byte.tif ./reference/modis_nbar.tif

Note

Images downloaded with geedim have center_wavelength metadata compatible with homonim.

You can use gdalinfo (from the gdal package) to inspect the center_wavelength, and other metadata of an image, e.g:

gdalinfo ./reference/sentinel2_b432_byte.tif

Output file format

By default homonim writes output files as GeoTIFFs with DEFLATE compression, float32 data type and nan nodata value. These options are all configurable.

Here we create a JPEG compressed image in GeoTIFF format, with uint8 data type:

homonim fuse -od ./corrected --driver GTiff --dtype uint8 --nodata null -co COMPRESS=JPEG -co INTERLEAVE=PIXEL -co PHOTOMETRIC=YCBCR ./source/ngi_rgb_byte_4.tif ./reference/sentinel2_b432_byte.tif

Setting nodata to null forces the writing of an internal mask. This avoids lossy compression transparency artifacts. JPEG compression is configured to sub-sample YCbCr colour space values with the -co INTERLEAVE=PIXEL -co PHOTOMETRIC=YCBCR creation options.

Next, the corrected image is formatted as a 12 bit JPEG compressed GeoTIFF. A null nodata value is used again to write an internal mask, and the uint16 data type gets truncated to 12 bits:

homonim fuse -od ./corrected --driver GTiff --dtype uint16 --nodata null -co COMPRESS=JPEG -co NBITS=12 ./source/ngi_rgb_byte_4.tif ./reference/sentinel2_b432_byte.tif

The -co INTERLEAVE=PIXEL -co PHOTOMETRIC=YCBCR creation options could also be used with this example, to further compress the RGB image.

Note

Support for 12 bit JPEG compression is rasterio build / package dependent.

See the GDAL docs for available drivers and their parameters.

Usage

homonim

Surface reflectance correction toolkit.

homonim [OPTIONS] COMMAND [ARGS]...

Options

-v, --verbose: Increase verbosity.

-q, --quiet: Decrease verbosity.

--version: Show the version and exit.

Commands

compare: Compare image(s) with a reference.

fuse: Correct image(s) to surface reflectance.

stats: Report parameter statistics.

homonim fuse

Correct image(s) to surface reflectance.

Correct source multi-spectral aerial or satellite imagery to approximate surface reflectance, by fusion with a reference satellite image.

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(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. Where there are the same number of source and reference bands, and no center_wavelength metadata, bands are assumed to be in matching order. The --src-band and --ref-band options allow subsets and ordering of source and reference bands to be specified.

Corrected image(s) are named automatically based on the source file name and option values.

Examples:

Correct source.tif with reference.tif using the default options:

homonim fuse source.tif reference.tif

Correct source.tif with reference.tif using the gain-blk-offset model, a kernel of 5 x 5 pixels, and place the corrected images in the corrected directory:

homonim fuse --model gain-blk-offset --kernel-shape 5 5 --out-dir ./corrected source.tif reference.tif

Correct files matching source*.tif with reference1.tif using the gain-offset model and a kernel of 15 x 15 pixels. Produce parameter images, mask partially covered pixels in the corrected images, and statistically compare source and corrected images with reference2.tif:

homonim fuse -m gain-offset -k 15 15 --param-image --mask-partial --compare reference2.tif source*.tif reference1.tif

Correct bands 2 and 3 of source.tif, with bands 7 and 8 of reference.tif, using the default correction options:

homonim fuse -sb 2 -sb 3 -rb 7 -rb 8 source.tif reference.tif

homonim fuse [OPTIONS] SOURCE... REFERENCE

Options

-m, --model <model>

Correction model.

gain: Gain-only model, suitable for haze-free and zero offset images.
gain-blk-offset: Gain-only model applied to offset normalised blocks. Suitable for most source-reference combinations.
gain-offset: Gain and offset model. Most accurate model, but sensitive to differences between source and reference.

Default:: gain-blk-offset
Options:: gain | gain-blk-offset | gain-offset

-k, --kernel-shape <HEIGHT WIDTH>

Kernel height and width in pixels of the --proc-crs image. Larger kernels are less susceptible to over-fitting, but provide lower resolution correction.

Default:: 5, 5

-sb, --src-band <src_bands>

Source band index(es) to process (1 based).

Default:: all spectral or non-alpha bands.

-rb, --ref-band <ref_bands>

Reference band index(es) to match with source band(s) (1 based).

Default:: all spectral or non-alpha bands.

-od, --out-dir <out_dir>

Directory in which to place corrected image(s).

Default:: source image directory.

-o, --overwrite

Overwrite existing output file(s).

Default:: False

-cmp, --compare <FILE>: Compare source and corrected images with this reference image. If no FILE value is given, source and corrected images are compared with REFERENCE.

-cb, --cmp-band <cmp_bands>

Comparison reference band index(es) that correspond (spectrally) to --src-band (s).

Default:: all spectral or non-alpha bands.

-bo, --build-ovw, -nbo, --no-build-ovw

Build overviews for the output image(s).

Default:: True

-c, --conf <conf>: Path to a yaml configuration file specifying advanced options (as follow below).

-pi, --param-image, -npi, --no-param-image

Write the model parameters and R² values for each corrected image to a parameter image file.

Default:: False

-mp, --mask-partial, -nmp, --no-mask-partial

Mask output pixels produced from partial kernel or source / reference image coverage.

Default:: False

-t, --threads <threads>

Number of image blocks to process concurrently (0 = use all processors).

Default:: 2

-mbm, --max-block-mem <max_block_mem>

Maximum image block size in megabytes (0 = block corresponds to a whole band).

Default:: 100

-ds, --downsampling <downsampling>

Resampling method for re-projecting from high to low resolution. See the rasterio docs for details.

Default:: average
Options:: nearest | bilinear | cubic | cubic_spline | lanczos | average | mode | max | min | med | q1 | q3 | sum | rms

-us, --upsampling <upsampling>

Resampling method for re-projecting from low to high resolution. See the rasterio docs for details.

Default:: cubic_spline
Options:: nearest | bilinear | cubic | cubic_spline | lanczos | average | mode | max | min | med | q1 | q3 | sum | rms

-rit, --r2-inpaint-thresh <FLOAT 0-1>

R² threshold below which to inpaint model parameters from surrounding areas (0 = turn off inpainting). Valid for gain-offset --model only.

Default:: 0.25

-pc, --proc-crs <proc_crs>

The image CRS in which to estimate correction parameters.

auto: lowest resolution of the source and reference CRS’s (recommended).
src: source image CRS.
ref: reference image CRS.

Default:: auto
Options:: auto | src | ref

--driver <TEXT>

Output image format driver. See the GDAL docs for details.

Default:: GTiff
Options:: SAGA | XYZ | NITF | SGI | PCIDSK | R | BLX | GIF | Terragen | VRT | LCP | HFA | CALS | JP2OpenJPEG | ADRG | GPKG | BT | ILWIS | GRIB | RMF | PDF | KMLSUPEROVERLAY | NWT_GRD | AAIGrid | netCDF | PNM | MFF | XPM | KRO | Rasterlite | BMP | PCRaster | ZMap | MBTiles | PNG | SRTMHGT | USGSDEM | SIGDEM | RST | PDS4 | BYN | WEBP | GTiff | ISIS3 | HF2 | EHdr | JPEG | BAG | DTED | ERS | MRF | GTX | NTv2

--dtype <dtype>

Output image data type. If an integer type, values are rounded and clipped to its range. Valid for corrected images only, parameter images always use float32.

Default:: float32
Options:: uint8 | uint16 | int16 | uint32 | int32 | float32 | float64

--nodata <NUMBER|null|nan>

Output image nodata value. Valid for corrected images only, parameter images always use nan. If null, an internal mask is written (recommended for lossy compression).

Default:: nan

-co, --creation-options <NAME=VALUE>: Driver specific image creation option(s) for the output image(s). See the GDAL docs for details.

-f, --force-match

Bypass auto wavelength matching, and any band-matching errors. Use with caution.

Default:: False

Arguments

SOURCE...: Path/URL(s) of source image(s) to be corrected.

REFERENCE: Path or URL of a reference image.

homonim compare

Compare image(s) with a reference.

Report similarity statistics between input image(s) and a reference image. Typically, this is used to compare the before and after accuracy of surface reflectance correction, by comparing source and corrected images with a new reference image.

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

The reference image should contain bands that are approximate (wavelength) matches to the input image bands. Where input and reference images are RGB, or have center_wavelength metadata, bands are matched automatically. Where there are the same number of input and reference bands, and no center_wavelength metadata, bands are assumed to be in matching order. The --src-band and --ref-band options allow subsets and ordering of input and reference bands to be specified.

Examples:

Compare source.tif and corrected.tif with reference.tif:

homonim compare source.tif corrected.tif reference.tif

homonim compare [OPTIONS] IMAGE... REFERENCE

Options

-sb, --src-band <src_bands>

Source band index(es) to process (1 based).

Default:: all spectral or non-alpha bands.

-rb, --ref-band <ref_bands>

Reference band index(es) to match with source band(s) (1 based).

Default:: all spectral or non-alpha bands.

-op, --output <output>: Write results to this json file.

-t, --threads <threads>

Number of image blocks to process concurrently (0 = use all processors).

Default:: 2

-mbm, --max-block-mem <max_block_mem>

Maximum image block size in megabytes (0 = block corresponds to a whole band).

Default:: 100

-ds, --downsampling <downsampling>

Resampling method for re-projecting from high to low resolution. See the rasterio docs for details.

Default:: average
Options:: nearest | bilinear | cubic | cubic_spline | lanczos | average | mode | max | min | med | q1 | q3 | sum | rms

-us, --upsampling <upsampling>

Resampling method for re-projecting from low to high resolution. See the rasterio docs for details.

Default:: cubic_spline
Options:: nearest | bilinear | cubic | cubic_spline | lanczos | average | mode | max | min | med | q1 | q3 | sum | rms

-pc, --proc-crs <proc_crs>

The image CRS in which to compare images.

auto: lowest resolution of the source and reference CRS’s (recommended).
src: source image CRS.
ref: reference image CRS.

Default:: auto
Options:: auto | src | ref

-f, --force-match

Bypass auto wavelength matching, and any band-matching errors. Use with caution.

Default:: False

Arguments

IMAGE...: Path(s) to image(s) to compare with REFERENCE.

REFERENCE: Path or URL of a reference image.

homonim stats

Report parameter statistics.

Report the minimum, maximum, mean etc. values of a parameter image generated with the --param-image option of the fuse command.

homonim stats [OPTIONS] PARAM...

Options

-op, --output <output>: Write results to this json file.

Arguments

PARAM...: Path(s) to parameter image(s).