RSGISLib Spectral Unmixing

Endmembers

rsgislib.imagecalc.specunmixing.extract_avg_endmembers(input_img, vec_file, vec_lyr, out_file, pxl_in_poly_method)

Extract the average endmembers per class which are saved as an appropriate matrix file to be used within the linear spectral unmixing commands. Each polygon defined is another endmember in the outputted matric file.

Parameters:

  • input_img – is a string containing the name of the input image.

  • vec_file – is a string containing the name of the input vector.

  • vec_lyr – is a string containing the name of the input vector layer name.

  • out_file – is a string containing name of the output matrix file - do not include the file extension (.mtxt). The file extension will get added during the analysis. Be aware of this when inputting this file into further processing steps as the file extension (.mtxt) will then be needed.

  • pxl_in_poly_method – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.

rsgislib.imagecalc.specunmixing.read_endmembers_mtxt(endmembers_file, gain=1, weight=None)

A function to read endmembers mtxt file

Parameters:

  • endmembers_file – File path to the mtxt input file.

  • gain – A gain for the endmembers (input endmember / gain = output endmember). If 1 then ignored.

  • weight – Optional (if None ignored) to provide a weight to implement the approach of Scarth et al (2010) adding a weight to the least squares optimisation to get the abundances to sum to 1.

Returns:

[m, n, end_mem_arr]; m size, n size and a numpy array with the end members

rsgislib.imagecalc.specunmixing.write_endmembers_mtxt(endmembers_np_arr, endmembers_file)

A function to creates endmembers mtxt file from a numpy array

Parameters:

  • endmembers_np_arr – Numpy array (m, n) with the endmembers.

  • endmembers_file – File path to the mtxt output file.

rsgislib.imagecalc.specunmixing.plot_endmembers(endmembers_file, endmember_names, out_plot_file, plot_title=None, gain=1, wavelengths=None)

A function to plot endmembers for visualisation.

Parameters:

  • endmembers_file – input endmembers file (.mtxt)

  • endmember_names – the names of the endmembers in the same order as the endmembers_file.

  • out_plot_file – the output plot file.

  • plot_title – A title for the plot (Optional)

  • gain – A gain to get the reflectance values as a percentage (Optional) (e.g., if multiplied by 1000 then the gain would be 10 if multiplied by 10,000 then the gain would be 100 )

  • wavelengths – A list of wavelengths for the image bands. Optional, if not provided then band numbers will be used.

rsgislib.imagecalc.specunmixing.are_endmembers_equal(ref_endmember_file, cmp_endmember_file, flt_dif=0.0001)

A function which compares two endmembers files to check whether they are equal or not.

Parameters:

  • ref_endmember_file – File path to the mtxt input file.

  • cmp_endmember_file – File path to the mtxt input file.

  • flt_dif – A threshold for comparing two floating point numbers as being identical - this avoids issues with rounding and the number of decimal figures stored.

Returns:

boolean

rsgislib.imagecalc.specunmixing.calc_ppi(input_img, output_img, gdalformat, niters=1000, lthres=0, uthres=0, img_gain=1, seed=None, calc_stats=True)

A function which calculate the pixel purity index (PPI). Using an appropriate number of iterations this can take a little while to run. Note, the whole input image is read into memory.

It is recommended that you use the an MNF/PCA output and rescale that so all bands have the same range to improve the PPI result.

Boardman J.W., Kruse F.A, and Green R.O., “Mapping Target Signatures via

Partial Unmixing of AVIRIS Data,” Pasadena, California, USA, 23 Jan 1995, URI: http://hdl.handle.net/2014/33635

Parameters:

  • input_img – image values image file path.

  • output_img – output image

  • gdalformat – GDAL file format (e.g., KEA) of the output image.

  • niters – number of iterations

  • thres – a threshold in the image space (after again as been applied) to select more pixels around the extreme (e.g., 1% reflectance)

  • img_gain – the gain by which the image was multipled, reflectance images are typically multiplied by 1000 or 10000. The result should be an image with a range 0-1.

  • seed – seed for the random squence of numbers being generated. Using the same seed will result in the same seqence and therefore the same output.

  • calc_stats – whether to calculate image statistics and pyramids on the output image.

Single Endmember Linear Unmixing

rsgislib.imagecalc.specunmixing.spec_unmix_spts_ucls(input_img, valid_msk_img, valid_msk_val, output_img, endmembers_file, gdalformat='KEA', gain=1, weight=None, calc_stats=True)

This function performs spectral unmixing using an unconstrain model using the pysptools module

Note, pysptools needs to be installed to use this function.

Parameters:

  • input_img – input image file.

  • valid_msk_img – an image file representing the valid data region

  • valid_msk_val – image pixel value in the mask for the valid data region

  • output_img – the output image file

  • endmembers_file – the endmembers (*.mtxt) file extracted using the specunmixing.extractAvgEndMembers function

  • gdalformat – the output file format. (Default: KEA)

  • gain – A gain for the endmembers and image spectra (input spectra / gain = output spectra). If 1 then ignored.

  • weight – Optional (if None ignored) to provide a weight to implement the approach of Scarth et al (2010) adding a weight to the least squares optimisation to get the abundances to sum to 1.

  • calc_stats – Boolean specifying whether to calculate pyramids and metadata stats (Default: True)

References:

Scarth, P., Roder, A., & Schmidt, M. (2010). Tracking grazing pressure and climate interaction—The role of Landsat fractional cover in time series analysis. Proceedings of the 15th Australasian Remote Sensing and Photogrammetry Conference Australia: Alice Springs. http://dx.doi.org/10.6084/m9.figshare.94250.

rsgislib.imagecalc.specunmixing.spec_unmix_spts_nnls(input_img, valid_msk_img, valid_msk_val, output_img, endmembers_file, gdalformat='KEA', gain=1, weight=None, calc_stats=True)

This function performs spectral unmixing using non-negative least squares using the pysptools module

Note, pysptools needs to be installed to use this function.

Parameters:

  • input_img – input image file.

  • valid_msk_img – an image file representing the valid data region

  • valid_msk_val – image pixel value in the mask for the valid data region

  • output_img – the output image file

  • endmembers_file – the endmembers (*.mtxt) file extracted using the specunmixing.extractAvgEndMembers function

  • gdalformat – the output file format. (Default: KEA)

  • gain – A gain for the endmembers and image spectra (input spectra / gain = output spectra). If 1 then ignored.

  • weight – Optional (if None ignored) to provide a weight to implement the approach of Scarth et al (2010) adding a weight to the least squares optimisation to get the abundances to sum to 1.

  • calc_stats – Boolean specifying whether to calculate pyramids and metadata stats (Default: True)

References:

Scarth, P., Roder, A., & Schmidt, M. (2010). Tracking grazing pressure and climate interaction—The role of Landsat fractional cover in time series analysis. Proceedings of the 15th Australasian Remote Sensing and Photogrammetry Conference Australia: Alice Springs. http://dx.doi.org/10.6084/m9.figshare.94250.

rsgislib.imagecalc.specunmixing.spec_unmix_spts_fcls(input_img, valid_msk_img, valid_msk_val, output_img, endmembers_file, gdalformat='KEA', gain=1, calc_stats=True)

This function performs spectral unmixing using a full constrained (non-negative and sum to 1) module using the pysptools module

Note, pysptools and cvxopt modules need to be installed to use this function.

Parameters:

  • input_img – input image file.

  • valid_msk_img – an image file representing the valid data region

  • valid_msk_val – image pixel value in the mask for the valid data region

  • output_img – the output image file

  • endmembers_file – the endmembers (*.mtxt) file extracted using the specunmixing.extractAvgEndMembers function

  • gdalformat – the output file format. (Default: KEA)

  • gain – A gain for the endmembers and image spectra (input spectra / gain = output spectra). If 1 then ignored.

  • calc_stats – Boolean specifying whether to calculate pyramids and metadata stats (Default: True)

rsgislib.imagecalc.specunmixing.spec_unmix_pymcr_nnls(input_img, valid_msk_img, valid_msk_val, output_img, endmembers_file, gdalformat='KEA', gain=1, weight=None, calc_stats=True)

This function performs spectral unmixing using non-negative least squares using the pymcr module

Note, pymcr needs to be installed to use this function.

Parameters:

  • input_img – input image file.

  • valid_msk_img – an image file representing the valid data region

  • valid_msk_val – image pixel value in the mask for the valid data region

  • output_img – the output image file

  • endmembers_file – the endmembers (*.mtxt) file extracted using the specunmixing.extractAvgEndMembers function

  • gdalformat – the output file format. (Default: KEA)

  • gain – A gain for the endmembers and image spectra (input spectra / gain = output spectra). If 1 then ignored.

  • weight – Optional (if None ignored) to provide a weight to implement the approach of Scarth et al (2010) adding a weight to the least squares optimisation to get the abundances to sum to 1.

  • calc_stats – Boolean specifying whether to calculate pyramids and metadata stats (Default: True)

References:

Scarth, P., Roder, A., & Schmidt, M. (2010). Tracking grazing pressure and climate interaction—The role of Landsat fractional cover in time series analysis. Proceedings of the 15th Australasian Remote Sensing and Photogrammetry Conference Australia: Alice Springs. http://dx.doi.org/10.6084/m9.figshare.94250.

rsgislib.imagecalc.specunmixing.spec_unmix_pymcr_fcls(input_img, valid_msk_img, valid_msk_val, output_img, endmembers_file, gdalformat='KEA', gain=1, calc_stats=True)

This function performs spectral unmixing using a full constrained (non-negative and sum to 1) module using the pymcr module

Note, pymcr needs to be installed to use this function.

Parameters:

  • input_img – input image file.

  • valid_msk_img – an image file representing the valid data region

  • valid_msk_val – image pixel value in the mask for the valid data region

  • output_img – the output image file

  • endmembers_file – the endmembers (*.mtxt) file extracted using the specunmixing.extractAvgEndMembers function

  • gdalformat – the output file format. (Default: KEA)

  • gain – A gain for the endmembers and image spectra (input spectra / gain = output spectra). If 1 then ignored.

  • calc_stats – Boolean specifying whether to calculate pyramids and metadata stats (Default: True)

rsgislib.imagecalc.specunmixing.exhcon_linear_spec_unmix(input_img, output_img, gdalformat, datatype, endmember_file, step_res, gain, offset)

Performs an exhaustive constrained linear spectral unmixing of the input image for a set of endmembers.

Warning. This methods is slow (!!) to execute

Endmember polygons are extracted using rsgislib.imagecalc.specunmixing.extract_avg_endmembers() where each polygon defines an endmember.

Parameters:

  • input_img – is a string containing the name of the input image file

  • output_img – is a string containing the name of the output image file

  • gdalformat – is a string containing the GDAL format for the output file - eg KEA

  • datatype – is an containing one of the values from rsgislib.TYPE_*

  • endmember_file – is a string containing the names of the file containing the end members (.mtxt)

  • step_res – is a float specifying the gap between steps in the search space. Value needs to be between 0 and 1. (i.e., 0.05)

  • gain – is a float specifying a gain which can be applied to the output pixel values (outvalue = offset + (gain * value)). Optional, default = 1.

  • offset – is a float specifying an offset which can be applied to the output pixel values (outvalue = offset + (gain * value)). Optional, default = 0.

import rsgislib.imagecalc.specunmixing
import rsgislib

imageLSImage = "./LS8_20130519_lat52lon42_r24p204_rad_srefstdmdl.kea"
unmixedImage = "./LS8_20130519_lat52lon42_r24p204_rad_srefstdmdl_unmix.kea"
roiSHP = "./ROIs.shp"
roiSHPLyr = "ROIs"
endmembersFile = "./endmembers"

rsgislib.imagecalc.specunmixing.extract_avg_endmembers(imageLSImage, roiSHP, roiSHPLyr, endmembersFile)

lsumGain = 1.0
lsumOffset = 0.0

endmembersFile = "./endmembers.mtxt"
stepResolution = 0.1
rsgislib.imagecalc.specunmixing.exhcon_linear_spec_unmix(imageLSImage, "KEA", rsgislib.TYPE_32FLOAT, unmixedImage, endmembersFile, stepResolution, lsumGain, lsumOffset)

Mutli Endmember Linear Unmixing

rsgislib.imagecalc.specunmixing.summarise_multi_endmember_linear_unmixing(input_img, in_unmixed_datasets, out_unmix_img, out_ref_img, tmp_dir='tmp', gdalformat='KEA', calc_stats=True)

A function which merges multiple linear spectral unmixing results using different methods of unmixing, endmembers and number of endmembers so create a single combined unmixed result. The Root Mean Square Percentage Error (RMSPE) is used to identified which unmixing is the ‘best’ on a per-pixel basis.

Parameters:

  • input_img – the original input reflectance image file.

  • in_unmixed_datasets – a list of ImageEndmemberInfo objects with the unmixed image, endmember file and list of endmember names.

  • out_unmix_img – the output summarised unmixed image.

  • out_ref_img – the output reference image referencing the image/endmembers associated with each pixel. If the KEA format is used then the RAT will be populated with the file path to the endmembers

  • tmp_dir – a tmp directory where outputs will be written during processing and can be deleted once processing is finished.

  • gdalformat – output image file format (Default: KEA)

  • calc_stats – Specify whether image pyramids and statistics will be calculated. (Default: True). If True and the output file format is KEA then the reference image RAT will be populated with the endmember file names.

Utilties

rsgislib.imagecalc.specunmixing.rescale_unmixing_results(input_img, output_img, gdalformat='KEA', calc_stats=True)

A function which rescales an output from a spectral unmixing (e.g., rsgislib.imagecalc.specunmixing.spec_unmix_spts_ucls) so that negative values are removed (set to 0) and each pixel sums to 1.

Parameters:

  • inputImg – Input image with the spectral unmixing result (pixels need to range from 0-1)

  • outputImg – Output image with the result of the rescaling (pixel values will be in range 0-1 without scale factor > 1)

  • gdalformat – the file format of the output file.

  • calc_stats – if true then image statistics and pyramids for the output image.

rsgislib.imagecalc.specunmixing.predict_refl_linear_unmixing(in_unmix_coefs_img, endmembers_file, output_img, gdalformat='KEA', calc_stats=True)

A function to calculate the predicted pixel value using the inputted abundances and endmembers.

Parameters:

  • in_unmix_coefs_img – The unmixed abundance coefficients.

  • endmembers_file – The endmembers file used for the unmixing in the RSGISLib mtxt format.

  • output_img – The file path to the GDAL writable output image

  • gdalformat – The output image format to be used.

  • calc_stats – If True (default) then image statistics and pyramids are calculated for the output images

rsgislib.imagecalc.specunmixing.calc_unmixing_rmse_residual_err(input_img, input_unmix_img, endmembers_file, output_img, gdalformat='KEA', calc_stats=True)

A function to calculate the prediction residual, RMSE and RMSPE using the defined abundances and endmembers.

RMSE: Root Mean Squared Error RMSPE: Root Mean Squared Percentage Error

Note. the residual and RMSE will be scaled with the input data so if you have multiplied your reflectance values by 1000 (i.e., range 0 - 1000) then the residual and RMSE values will also be in this range.

Parameters:

  • input_refl_img – The original input reference image.

  • input_unmix_coef_img – The unmixed abundance coefficients.

  • endmembers_file – The endmembers file used for the unmixing in the RSGISLib mtxt format.

  • output_image – The file path to the GDAL writable output image (Band 1: RMSE, Band 2: RMSPE, Band 3: Residual)

  • gdalformat – The output image format to be used.

  • calc_stats – If True (default) then image statistics and pyramids are calculated for the output images