RSGISLib Image Calculations

Band & Image Maths

rsgislib.imagecalc.band_math(output_img: str, exp: str, gdalformat: str, datatype: int, band_defs: list, exp_band_name: bool, output_exists: bool)

Performs band math calculation. The syntax for the expression is from the muparser library see here for available operations and syntax

Parameters:

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

  • exp – is a string containing the expression to run over the images, uses muparser syntax.

  • 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_*

  • band_defs – is a sequence of rsgislib.imagecalc.BandDefn objects that define the inputs

  • exp_band_name – is an optional bool specifying whether the band name should be the expression (Default = False).

  • output_exists – is an optional bool specifying whether the output image already exists and it should be edited rather than overwritten (Default=False).

import rsgislib
import rsgislib.imagecalc

# Calculating a product from multiple bands:
band_defns = list()
band_defns.append(rsgislib.imagecalc.BandDefn('b1', 'img.kea', 1))
band_defns.append(rsgislib.imagecalc.BandDefn('b2', 'img.kea', 2))
rsgislib.imagecalc.band_math('out.kea', 'b1*b2', 'KEA', rsgislib.TYPE_32FLOAT, band_defns)


# Apply if-else statement:
band_defns = list()
band_defns.append(rsgislib.imagecalc.BandDefn('b1', 'img1.kea', 1))
band_defns.append(rsgislib.imagecalc.BandDefn('b2', 'img2.kea', 1))
band_defns.append(rsgislib.imagecalc.BandDefn('b3', 'img3.kea', 2))
rsgislib.imagecalc.band_math('out.kea', '(b1==1) || (b2==1) || (b3==1)?1:0', 'KEA', rsgislib.TYPE_8UINT, band_defns)
rsgislib.imagecalc.image_math(input_img, output_img, exp, gdalformat, datatype, exp_band_name, output_exists)

Performs image math calculations. Produces an output image file with the same number of bands as the input image. This function applies the same calculation to each image band (i.e., b1 is the only variable). The syntax for the expression is from the muparser library see here for available operations and syntax

Parameters:

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

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

  • exp – is a string containing the expression to run over the images, uses myparser syntax.

  • 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_*

  • exp_band_name – is an optional bool specifying whether the band name should be the expression (Default = False).

  • output_exists – is an optional bool specifying whether the output image already exists and it should be edited rather than overwritten (Default=False).

import rsgislib
import rsgislib.imagecalc
rsgislib.imagecalc.image_math('img.kea', 'out.kea', 'b1*1000', 'KEA', rsgislib.TYPE_32UINT)


# Apply if-else statement:
rsgislib.imagecalc.image_math('img.kea', 'out.kea', 'b1<10?1:0', 'KEA', rsgislib.TYPE_8UINT)
rsgislib.imagecalc.image_band_math(input_img, output_img, exp, gdalformat, datatype, exp_band_name, output_exists)

Performs image band math calculations. Produces a single output file with a single image band. The image bands can be referred to individually using b1, b2 … bn. where n is the number of image bands, starting at 1. The syntax for the expression is from the muparser library see here for available operations and syntax

Parameters:

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

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

  • exp – is a string containing the expression to run over the images, uses myparser syntax.

  • 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_*

  • exp_band_name – is an optional bool specifying whether the band name should be the expression (Default = False).

  • output_exists – is an optional bool specifying whether the output image already exists and it should be editted rather than overwritten (Default=False).

import rsgislib
import rsgislib.imagecalc

# Calculate product of multiple bands:
rsgislib.imagecalc.image_band_math('img.kea', 'out.kea', '(b1+b2+b3+b4)/4', 'KEA', rsgislib.TYPE_32UINT)


# Apply if-else statement:
rsgislib.imagecalc.image_band_math('img.kea', 'out.kea', '(b1==1) || (b2==1) || (b3==1)?1:0', 'KEA', rsgislib.TYPE_8UINT)
rsgislib.imagecalc.all_bands_equal_to(input_img, output_img, img_val, out_true_val, out_false_val, gdalformat, datatype)

Tests whether all bands are equal to the same value

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

  • img_val – is a float specifying the value against which others are tested for equality TODO: Check this and below

  • out_true_val – is a float specifying the value in the output image representing true

  • out_false_val – is a float specifying the value in the output image representing false

  • 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_*

class rsgislib.imagecalc.BandDefn(band_name=None, input_img=None, img_band=None)

Create a list of these objects to pass to the band_math function as the ‘bands’ parameter.

Clustering

rsgislib.imagecalc.kmeans_clustering(input_img, out_file, n_clusters, max_n_iters, sub_sample, ignore_zeros, degree_change, init_cluster_method)

Performs K Means Clustering and saves cluster centres to a text file.

Parameters:

  • input_img – is a string providing the input image

  • out_file – is a string providing the output matrix (text file) to save the cluster centres to.

  • n_clusters – is the number of clusters to use.

  • max_n_iters – is the maximum number of itterations.

  • sub_sample – is an int specifying what fraction of the total pixels should be considered (e.g., 100 = 1/100 pixels).

  • ignore_zeros – is a bool specifying if zeros in the image should be treated as no data.

  • degree_change – is a float providing the minimum change between iterations before terminating.

  • init_cluster_method – the method for initialising the clusters and is one of INITCLUSTER_* values

import rsgislib
import rsgislib.imagecalc
inputImage = path + 'Rasters/injune_p142_casi_sub_right_utm.kea'
output = path + 'TestOutputs/kmeanscentres'
numClust = 10
maxIter = 200
degChange = 0.0025
subSample = 1
ignoreZeros = True
rsgislib.imagecalc.kmeans_clustering(inputImage, output, numClust, maxIter, subSample, ignoreZeros, degChange, rsgislib.INITCLUSTER_DIAGONAL_FULL_ATTACH)
rsgislib.imagecalc.isodata_clustering(input_img, out_file, n_clusters, max_n_iters, sub_sample, ignore_zeros, degree_change, init_cluster_method, min_dist_clusters, min_n_feats, max_std_dev, min_n_clusters, start_iter, end_iter)

Performs ISO Data Clustering and saves cluster centres to a text file.

Parameters:

  • input_img – is a string providing the input image

  • out_file – is a string providing the output matrix (text file) to save the cluster centres to.

  • n_clusters – is the number of clusters to start with.

  • max_n_iters – is the maximum number of iterations.

  • sub_sample – is an int specifying what fraction of the total pixels should be considered (e.g., 100 = 1/100 pixels).

  • ignore_zeros – is a bool specifying if zeros in the image should be treated as no data.

  • degree_change – is a float providing the minimum change between iterations before terminating.

  • init_cluster_method – the method for initialising the clusters and is one of INITCLUSTER_* values

  • min_dist_clusters – is a float

  • min_n_feats – is an int

  • max_std_dev – is a float

  • min_n_clusters – is an int

  • start_iter – is an int

  • end_iter – is an int

import rsgislib
from rsgislib import imagecalc
inputImage = path + 'Rasters/injune_p142_casi_sub_right_utm.kea'
output = './TestOutputs/isocentres'
imagecalc.isodata_clustering(inputImage, output, 10, 200, 1, True, 0.0025, rsgislib.INITCLUSTER_DIAGONAL_FULL_ATTACH, 2, 5, 5, 5, 8, 50)

Statistical Summary

rsgislib.imagecalc.image_pixel_column_summary(input_img, output_img, sum_stats, gdalformat, datatype, no_data_val, use_no_data)

Calculates summary statistics for a column of pixels.

Parameters:

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

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

  • sum_stats – is an rsgislib.imagecalc.StatsSummary object specifying the statistics to be calculated i.e., calc_min, calc_max, calc_sum, calc_mean, calc_stdev, calc_median, calc_mode.

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

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

  • no_data_val – is a float specifying what value is used to signify no data

  • use_no_data – is a boolean specifying whether the noDataValue should be used

rsgislib.imagecalc.calc_band_percentile(input_img, percentile, no_data_val)

Calculates image band percentiles for the input image and results a list of values

Parameters:

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

  • percentile – is a float between 0 – 1 specifying the percentile to be calculated.

  • no_data_val – is a float specifying the value used to represent no data (used None when no value is to be specified).

Returns:

list of floats

rsgislib.imagecalc.get_img_band_stats_in_env(input_img, img_band, no_data_val, lon_min, lon_max, lat_min, lat_max)

Calculates and returns statistics (min, max, mean, stddev, sum) for a region. defined by the bounding box (longMin, longMax, latMin, latMax) which is specified geographic latitude and longitude. The coordinates are converted to the projection of the input image at runtime (if required) and therefore the image projection needs to be correctly defined so please check this is the case and define it if necessary.

Parameters:

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

  • img_band – is an unsigned int specifying the image band starting from 1.

  • no_data_val – is a float specifying a no data value, to be ignored in the calculation. If a value of ‘None’ is provided then a no data value is not used.

  • lon_min – is a double specifying the minimum longitude of the BBOX

  • lon_max – is a double specifying the maximum longitude of the BBOX

  • lat_min – is a double specifying the minimum latitude of the BBOX

  • lat_max – is a double specifying the maximum latitude of the BBOX

Returns:

list with 5 values (min, max, mean, stddev, sum)

import rsgislib.imagecalc
stats = rsgislib.imagecalc.get_img_band_stats_in_env("./FinalSRTMTanzaniaDEM_30m.kea", 1, -32767.0, 30.0, 31.0, -7.0, -8.0)
print("Min: ", stats[0])
print("Max: ", stats[1])
print("Mean: ", stats[2])
print("StdDev: ", stats[3])
print("Sum: ", stats[4])
rsgislib.imagecalc.get_img_band_mode_in_env(input_img, img_band, bin_width, no_data_val, lon_min, lon_max, lat_min, lat_max)

Calculates and returns the image mode for a region. defined by the bounding box (longMin, longMax, latMin, latMax) which is specified geographic latitude and longitude. The coordinates are converted to the projection of the input image at runtime (if required) and therefore the image projection needs to be correctly defined so please check this is the case and define it if necessary.

Parameters:

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

  • img_band – is an unsigned int specifying the image band starting from 1.

  • bin_width – is a float specifying the binWidth for the histogram generated to calculate the mode.

  • no_data_val – is a float specifying a no data value, to be ignored in the calculation. If a value of ‘None’ is provided then a no data value is not used.

  • lon_min – is a double specifying the minimum longitude of the BBOX

  • lon_max – is a double specifying the maximum longitude of the BBOX

  • lat_min – is a double specifying the minimum latitude of the BBOX

  • lat_max – is a double specifying the maximum latitude of the BBOX

Returns:

float with image mode for the region within the BBOX.

rsgislib.imagecalc.calc_prop_true_exp(exp, band_defs, in_vld_img)

Calculates the proportion of the image where the expression is true. Optionally a mask defining the valid area can be used to restrict the area of the image used as the total number of pixels within the scene.

Parameters:

  • exp – is a string containing the expression to run over the images, uses muparser syntax. Must output a value of 1 to be true.

  • band_defs – is a sequence of rsgislib.imagecalc.BandDefn objects that define the inputs

  • in_vld_img – is an optional string specifying a valid area image mask (assume valid is pixel values 1 in band 1). If not specified then it won’t be used.

Returns:

Returns a float value with the proportion

import rsgislib.imagecalc
import rsgislib.imagecalc.BandDefn
expression = 'b1<20?1:b2>100?1:0'
band_defns = []
band_defns.append(rsgislib.imagecalc.BandDefn('b1', inFileName, 1))
band_defns.append(rsgislib.imagecalc.BandDefn('b2', inFileName, 2))
prop = rsgislib.imagecalc.calc_prop_true_exp(expression, band_defns)
print(prop)
rsgislib.imagecalc.calc_multi_img_band_stats(input_imgs, output_img, summary_stat, gdalformat, datatype, no_data_val, use_no_data)

Calculates the summary statistic (rsgislib.SUMTYPE_*) across multiple images on a per band basis .For example, if rsgislib.SUMTYPE_MIN is selected then for all the images the minimum value for band 1 (across all the images) and then band 2 etc. will be outputted as a new image with the same number of bands as the inputs (Note. all the input images must have the same number of bands).

Parameters:

  • input_imgs – is a list of input images (note. all inputs must have the same number of image bands).

  • output_img – is a string with the name and path of the output image.

  • summary_stat – is of type rsgislib.SUMTYPE_* and specifies which summary statistic is used to sumamrise the images.

  • gdalformat – is a string specifying the output image format (e.g., KEA).

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

  • no_data_val – float with the value of the no data value, the same value for all the input images (Optional)

  • use_no_data – is a boolean specifying whether the no data value should be used (Optional, default False)

rsgislib.imagecalc.get_img_band_min_max(input_img, img_band, use_no_data, no_data_val)

Calculate and reutrn the maximum and minimum values of the input image.

Parameters:

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

  • img_band – is an int specifying the image band

  • use_no_data – is a boolean specifying whether the no data value should be used (Optional, default is False)

  • no_data_val – is a string containing the GDAL format for the output file - eg ‘KEA’

import rsgislib
from rsgislib import imagecalc

inputImage = 'LS8_20131111_lat29lon8717_r40p140_vmsk_rad_srefdem.kea'
imgBand = 1

minMaxVals = imagecalc.get_img_band_min_max(inputImage, imgBand)
print('MIN: ', minMaxVals[0])
print('MAX: ', minMaxVals[1])
rsgislib.imagecalc.get_img_sum_stats_in_pxl(in_ref_img=string, in_stats_img=string, output_img=string, gdalformat=string, datatype=int, sum_stats=list, stats_img_band=int, use_no_data=bool, io_grid_x=int, io_grid_y=int)

A function which calculates a summary of the pixel values from the high resolution statsimage for the regions defined by the pixels in the lower resolution refimage. This is similar to zonal stats. Please note that the statsimage needs to have a pixel size which is a multiple of the refimage pixel size. For example, is the ref image has a resolution of 10 m the statsimage can have a resolution of 1 or 2 m but not 3 m for this function to work.

Parameters:

  • in_ref_img – is a string specifying the name and path for the reference image. Note, this is only used to define the summary areas and output image extent.

  • in_stats_img – is a string specifying the name and path to the higher resolution image which will be summarised.

  • output_img – is a string specifying the output image file name and path.

  • gdalformat – is a string with the GDAL output file format.

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

  • sum_stats – is a list of the type rsgislib.SUMTYPE_* and specifies the summary is calculated. Each summary statastic is saved as a different image band.:param stats_img_band: is an integer specifying the image band in the stats image to be used for the analysis. (Default: 1)

  • use_no_data – is a boolean specifying whether the image band no data value should be used. (Default: True)

  • io_grid_x – and io_grid_y are integers which control the image processing block size. The unit is pixels in the refimage. (Default: 16) where the pixel resolution between the two images is closer together these values can be increased but but where the statsimage pixel size is much smaller than the ref image reducing this will reduce the memory footprint significantly.

rsgislib.imagecalc.get_img_idx_for_stat(input_imgs=list, output_img=string, gdalformat=string, no_data_val=float, stat=rsgislib.SUMTYPE_)

A function which calculates the index (starting at 1) of the image in the list of input images which has the stat selected. The output image can be used within the rsgislib.imageutils.createMaxNDVICompositeImg function. :param input_imgs: is a list of input images, which must each just have single image band. :param output_img: is a string with the name and path of the output image. No data value is 0 and indexes start at 1. :param gdalformat: is a string with the GDAL output file format. :param no_data_val: is the no data value in the input images (all images have the same no data value). :param stat: is of type rsgislib.SUMTYPE_* and specifies how the index is calculated. Available options are: rsgislib.SUMTYPE_MEDIAN, rsgislib.SUMTYPE_MIN, rsgislib.SUMTYPE_MAX.

import rsgislib
import rsgislib.imagecalc
import rsgislib.imageutils
import rsgislib.rastergis

import glob
import os.path

# Get List of input images:
inImages = glob.glob('./Outputs/*stdsref.kea')

# Generate Comp Ref layers:
refLyrsLst = []
refLayerPath = './CompRefLyrs/'
idx = 1
for img in inImages:
    print('In Image ('+str(idx) + '):       ' + img)
    baseImgName = os.path.splitext(os.path.basename(img))[0]
    refLyrImg = os.path.join(refLayerPath, baseImgName+'_ndvi.kea')
    rsgislib.imagecalc.calc_ndvi(img, 3, 4, refLyrImg)
    refLyrsLst.append(refLyrImg)
    idx = idx + 1

# Create REF Image
pxlRefImg = 'LS5TM_19851990CompRefImg_lat7lon3896_r65p166_vmsk_mclds_topshad_rad_srefdem_stdsref.kea'
rsgislib.imagecalc.get_img_idx_for_stat(refLyrsLst, pxlRefImg, 'KEA', -999, rsgislib.SUMTYPE_MAX)

# Pop Ref Image with stats
rsgislib.rastergis.populateStats(pxlRefImg, True, True, True)

# Create Composite Image
outCompImg = 'LS5TM_19851990CompRefImgMAX_lat7lon3896_r65p166_vmsk_mclds_topshad_rad_srefdem_stdsref.kea'
rsgislib.imageutils.createRefImgCompositeImg(inImages, outCompImg, pxlRefImg, 'KEA', rsgislib.TYPE_16UINT, 0.0)

# Calc Stats
rsgislib.imageutils.pop_img_stats(outCompImg, usenodataval=True, nodataval=0, calcpyramids=True)
rsgislib.imagecalc.identify_min_pxl_value_in_win(input_img=string, output_img=string, out_ref_img=string, img_bands=list, win_size=int, gdalformat=string, no_data_val=float, use_no_data=boolean)

A function to identify the minimum value across the image bands specified within a window.

Parameters:

  • input_img – is a string specifying input image file.

  • output_img – is a string specifying image with the minimum pixel value.

  • out_ref_img – is a string specifying the output file for the reference image - i.e., the band index.

  • img_bands – is a list of image bands (indexing starts at 1) from the input image.

  • win_size – is an integer specifying the window size (must be an odd number).

  • gdalformat – is a string with the GDAL output file format.

  • no_data_val – is a float specifying the no data value.

  • use_no_data – is a boolean specifiying whether to use the no data value.

rsgislib.imagecalc.calc_img_mean_in_mask(input_img=string, in_msk_img=string, msk_val=int, img_bands=list, no_data_val=float, use_no_data=boolean)

A function to calculate the mean value of all the pixels specified within the mask and across all the image bounds.

Parameters:

  • input_img – is a string specifying input image file.

  • in_msk_img – is a string specifying image with the mask file.

  • msk_val – the mask value (integer), within the input image mask, specifying the pixels over which the mean will be taken.

  • img_bands – is a list of image bands (indexing starts at 1).

  • no_data_val – is a float specifying the no data value.

  • use_no_data – is a boolean specifiying whether to use the no data value.

Returns:

float with mean value.

rsgislib.imagecalc.count_pxls_of_val(input_img: str, vals: List[int], img_band: int = None)

Function which counts the number of pixels of a set of values returning a list in the same order as the list of values provided.

Parameters:

  • input_img – the input image

  • vals – is a list of pixel values to be counted

  • img_band – specify the image band for which the analysis is to be undertaken. If None (default) then all bands will be used.

Returns:

list of pixel counts in same order as the vals input list

rsgislib.imagecalc.get_unique_values(input_img, img_band=1)

Find the unique image values within an image band. Note, the whole image band gets read into memory.

Parameters:

  • input_img – input image file path

  • img_band – image band to be processed (starts at 1)

Returns:

array of unique values.

rsgislib.imagecalc.calc_imgs_pxl_mode(input_imgs, output_img, gdalformat, no_data_val=0)

Function which calculates the mode of a group of images.

Warning, this function can be very slow!!! You probably want to use rsgislib.imagecalc.imagePixelColumnSummary

Parameters:

  • input_imgs – the list of images

  • output_img – the output image file name and path (will be same dimensions as the input)

  • gdalformat – the GDAL image file format of the output image file.

rsgislib.imagecalc.calc_img_basic_stats_for_ref_region(in_ref_img, in_stats_imgs, output_img, gdalformat='KEA')

A function which calculates the mean and standard deviation through a series of input images. The region for processing is defined by the reference image and images padded with no-data where no data is present.

The output image has twice the number of bands as the input image providing a mean and standard deviation for each input band.

If the input images has 2 bands then the output bands will have the following order:

  1. band 1 mean

  2. band 1 std dev

  3. band 2 mean

  4. band 2 std dev

Parameters:

  • in_ref_img – reference image which defines the output image

  • in_stats_imgs – a list of input images over which the stats will be calculated.

  • output_img – the output image path and file name

  • gdalformat – the output image file format. Default KEA.

rsgislib.imagecalc.calc_sum_stats_msk_vals(input_img: str, img_band: int, img_msk: str, msk_band: int, msk_vals: List[int] = None, use_no_data: bool = True, no_data_val: float = None, out_no_data_val: float = -9999)

A function which reads the image bands (values and mask) into memory calculate standard summary statistics (min, max, mean, std dev, median)

Parameters:

  • input_img – image values image file path.

  • img_band – values image band

  • img_msk – file path for image mask.

  • msk_band – mask image band

  • msk_vals – a list of values within the mask can be provided to just consider a limited number of mask values when calculating the histograms. If None (default) then calculated for all mask values.

  • use_no_data – Use no data value for the input image.

  • no_data_val – no data value for the input image (if None then read from input image header)

  • out_no_data_val – output no data value written to output dict if there are no valid pixel values.

Returns:

returns a dict summary statistics (Min, Max, Mean, Std Dev, Median)

rsgislib.imagecalc.count_imgs_int_val_occur(input_imgs: List[str], output_img: str, bin_vals: List[int], gdalformat: str = 'KEA')

Function which calculates the histogram for each pixel across all the input images and bands within the those images.

Note, when the list of input images is very large (i.e., over 200) an error cannot occur but if you stack the images into a VRT then more images can be processed.

Parameters:

  • input_imgs – the list of images

  • output_img – the output image file name and path. The number of bands with be equal to the length of the bin_vals lists.

  • bin_vals – list of integer bin used to calculate the histograms

  • gdalformat – the GDAL image file format of the output image file.

rsgislib.imagecalc.calc_imgs_pxl_percentiles(input_imgs, percentiles, output_img, gdalformat, no_data_val=0)

Function which calculates percentiles on a per-pixel basis for a group of images. Note, all bands in all the input images are used for the analysis.

Parameters:

  • input_imgs – the list of images - note all bands are used.

  • percentiles – a list of percentiles (0-100) to be calculated.

  • output_img – the output image file name and path (will be same dimensions as the input and then number of bands will be the same at the number of percentiles.)

  • gdalformat – the GDAL image file format of the output image file.

class rsgislib.imagecalc.StatsSummary(min=0.0, max=0.0, sum=0.0, median=0.0, stdev=0.0, mean=0.0, mode=0.0, calc_min=False, calc_max=False, calc_sum=False, calc_mean=False, calc_stdev=False, calc_median=False, calc_mode=False)

This is passed to the imagePixelColumnSummary function

Update Pixel Values

rsgislib.imagecalc.recode_int_raster(input_img, output_img, recode_dict, keep_vals_not_in_dict=True, gdalformat='KEA', datatype=3)

A function recodes an input image. Assuming image only has a single image band so it will be band 1 which is recoded. The recode is provided as a dict where the key is the value to be recoded and the value of the dict is the output value.

Parameters:

  • input_img – Input image file.

  • output_img – Output image file.

  • recode_dict – dict for recode (key: int to be recoded, value: int to recode to)

  • keep_vals_not_in_dict – boolean whether pixels not being recoded should be copied to the output (True) or whether only those pixels recoded should be outputted (False) (default: True)

  • gdalformat – output file format (default: KEA)

  • datatype – is a rsgislib.TYPE_* value providing the data type of the output image.

rsgislib.imagecalc.calc_fill_regions_knn(in_ref_img, ref_no_data, in_fill_regions_img, fill_region_val, output_img, k=5, summary=1, gdalformat='KEA', datatype=3)

A function will fills regions (defined by having a value == fill_region_val) of the in_fill_regions_img image using a KNN approach based of pixels within the in_ref_img image. The KNN distance is the spatial distance based off the pixel locations.

The in_ref_img and in_fill_regions_img must both be in the same projection.

Parameters:

  • in_ref_img – The reference image (can be a different resolution) from which the KNN will be trained.

  • ref_no_data – The no data value used within the reference image.

  • in_fill_regions_img – A mask image defining the regions to be filled.

  • fill_region_val – The pixel value specifying the pixels in the in_fill_regions_img image for the KNN value will be calculated.

  • output_img – The output image file name and path.

  • k – The k parameter of the KNN.

  • summary – Summary method (rsgislib.SUMTYPE_*) to be used (Default is Mode). Options: Mode, Median, Sum, Mean, Range, Min, Max.

  • gdalformat – output file format (default: KEA)

  • datatype – is a rsgislib.TYPE_* value providing the data type of the output image.

rsgislib.imagecalc.create_categories_sgl_band(input_img: str, output_img: str, recode_lut: List[Tuple[int, Tuple[float, float]]], img_band: int = 1, gdalformat: str = 'KEA', datatype: int = 5, backgrd_val: int = 0)

A function which categories a continuous image band based on a look up table (LUT) provided. The LUT should be a list specifying the output value and lower (>=) and upper (<) thresholds for that category. For example, (1, (10, 20)). If you do not want to specify a lower or upper value then use math.nan. For example, (2, (math.nan, 10)) or (3, (20, math.nan)).

Parameters:

  • input_img – The input image file path.

  • output_img – The output image where the distance has been recoded to categories using the recode_lut.

  • recode_lut – The recoding LUT specifying the categories to split the continuous band into.

  • img_band – The image band within the image (note. band indexes start at 1). Default = 1.

  • gdalformat – the output image file format (default: KEA)

  • datatype – the output image file data type (default: rsgislib.TYPE_8UINT)

  • backgrd_val – The background value used when recoding the distance image. i.e., if a pixel does not fall into any of the categories specified then it will be given this value.

Statistics

rsgislib.imagecalc.image_pixel_linear_fit(input_img: str, output_img: str, gdalformat: str, band_values: list, no_data_val: float, use_no_data: bool)

Performs a linear regression on each column of pixels.

Parameters:

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

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

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

  • band_values – is a list of values, one for each band (e.g. wavelength, day of year)

  • no_data_val – is a float specifying what value is used to signify no data

  • use_no_data – is a boolean specifying whether the noDataValue should be used

image = 'injune_p142_casi_sub_utm.kea'
output = 'injune_p142_casi_sub_utm_linear_fit.kea'
gdalformat = 'KEA'
bandValues = [446,530,549,569,598,633,680,696,714,732,741,752,800,838]

imagecalc.image_pixel_linear_fit(image, output, gdalformat, bandValues, 0, True)
rsgislib.imagecalc.pca(input_img, eigen_vec_file, output_img, n_comps, gdalformat, dataType)

Performs a principal components analysis of an image using a defined set of eigenvectors. The eigenvectors can be calculated using the rsgislib.imagecalc.getPCAEigenVector function.

Parameters:

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

  • eigen_vec_file – is a string containing the name of the file of eigen vectors for the PCA

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

  • n_comps – is an int containing number of components to use for PCA

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

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

import rsgislib.imageutils
import rsgislib.imagecalc
inputImg = 'Input.kea'
eigenVecFile = 'EigenVec.mtxt'
outputImg = './Output.kea'
eigenVec, varExplain = rsgislib.imagecalc.getPCAEigenVector(inputImg, 1000, None, eigenVecFile)
rsgislib.imagecalc.pca(inputImg, eigenVecFile, outputImg, varExplain.shape[0], 'KEA', rsgislib.TYPE_32FLOAT)
rsgislib.imageutils.pop_img_stats(outputImg, usenodataval, nodataval, True)
rsgislib.imagecalc.get_pca_eigen_vector(input_img, pxl_n_sample, no_data_val=None, out_matrix_file=None)

A function which takes a sample from an input image and uses it to generate eigenvector for a PCA. Note. this can be used as input to rsgislib.imagecalc.pca

Parameters:

  • input_img – the image from which the random sample will be taken.

  • pxl_n_sample – the sample to be taken (e.g., a value of 100 will sample every 100th pixel)

  • no_data_val – provide a no data value which is to be ignored during processing. If None then ignored (Default: None)

  • out_matrix_file – path and name for the output rsgislib matrix file. If None file is not created (Default: None)

Returns:

1. array with the eigenvector, 2. array with the ratio of the explained variance

rsgislib.imagecalc.perform_image_pca(input_img, output_img, out_eigen_vec_file, n_comps=None, pxl_n_sample=100, gdalformat='KEA', datatype=9, no_data_val=None, calc_stats=True)

A function which performs a PCA on the input image.

Parameters:

  • input_img – the image from which the random sample will be taken.

  • output_img – the output image transformed using the calculated PCA

  • out_eigen_vec_file – path and name for the output rsgislib matrix file containing the eigenvector for the PCA.

  • n_comps – the number of PCA compoents outputted. A value of None is all components (Default: None)

  • pxl_n_sample – the sample to be taken (e.g., a value of 100 will sample every 100th pixel) (Default: 100)

  • gdalformat – the output gdal supported file format (Default KEA)

  • datatype – the output data type of the input image (Default: rsgislib.TYPE_32FLOAT)

  • no_data_val – provide a no data value which is to be ignored during processing. If None then ignored (Default: None)

  • calc_stats – Boolean specifying whether pyramids and statistics should be calculated for the output image. (Default: True)

Returns:

an array with the ratio of the explained variance per band.

rsgislib.imagecalc.perform_image_mnf(input_img, output_img, n_comps=None, pxl_n_sample=100, in_img_no_data=None, tmp_dir='tmp', gdalformat='KEA', datatype=9, calc_stats=True)

A function which takes a sample from an input image and uses it to generate eigenvector for a MNF. Note. this can be used as input to rsgislib.imagecalc.pca

Parameters:

  • input_img – the image to which the MNF will be applied

  • output_img – the output image file with the MNF result

  • n_comps – the number of components to be outputted

  • pxl_n_sample – the sample to be taken (e.g., a value of 100 will sample every 100th pixel) for the PCA

  • in_img_no_data – provide a no data value which is to be ignored during processing. If None then try to read from input image.

  • tmp_dir – a directory where temporary output files will be stored. If it doesn’t exist it will be created.

  • gdalformat – output image file format

  • datatype – data type for the output image. Note, it is common to have negative values.

  • calc_stats – whether image statistics and pyramids could be calculated.

Returns:

array with the ratio of the explained variance

rsgislib.imagecalc.calculate_img_band_rmse(in_a_img, img_a_band, in_b_img, img_b_band)

Calculates the root mean squared error between two images

Parameters:

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

  • img_a_band – is an integer defining which band should be processed from inputImageA

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

  • img_b_band – is an integer defining which band should be processed from inputImageB

Returns:

float

rsgislib.imagecalc.correlation_window(input_img, output_img, win_size, band_a, band_b, gdalformat, datatype)

Calculates the correlation between two image bands within a window.

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

  • win_size – is an int providing the size of the window to calculate the correlation over

  • band_a – is an int providing the first band to use.

  • band_b – is an int providing the second band to use.

  • 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_*

image = path + 'injune_p142_casi_sub_utm.kea'
output = path + 'injune_p142_casi_sub_utm_correlation.kea'
window = 9
bandA = 1
bandB = 1
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
imagecalc.correlation_window(image, output, window, bandA, bandB, gdalformat, datatype)
rsgislib.imagecalc.calc_img_correlation(in_a_img: str, in_b_img: str, img_a_band: int, img_b_band: int, img_a_no_data: float = None, img_b_no_data: float = None, corr_stat_method: int = 1) -> (<class 'float'>, <class 'float'>)

A function which calculates the correlation between two input image bands.

Parameters:

  • in_a_img – The path to input image A.

  • in_b_img – The path to input image B.

  • img_a_band – The band within input image A

  • img_b_band – The band within input image B

  • img_a_no_data – The no data value in image A. If None then read from image header.

  • img_b_no_data – The no data value in image B. If None then read from image header.

  • corr_stat_method – The correlation method rsgislib.STATS_CORR_. Default: rsgislib.STATS_CORR_PEARSONS

Returns:

correlation coefficient and p value

rsgislib.imagecalc.calc_mask_img_pxl_val_prob(input_img, img_bands, in_msk_img, msk_val, output_img, gdalformat, bin_widths, use_no_data, rescale_probs)

Calculates the probability of each image pixel value occurring as defined by the distribution of image pixel values within the masked region of the image.

Parameters:

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

  • img_bands – is a list containing the image bands for which the probability will be calculated. (Note. number of output bands will equal number of bands specified here.

  • in_msk_img – is a string containing the name/path of the input mask image file.

  • msk_val – is an integer corresponding to the pixel value in the mask image defining mask used for this calculation.

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

  • gdalformat – is a string specifying output image format.

  • bin_widths – is list of floating point values for the width of the histogram bins used to calculate the probability (one value for each band specified) (Note. larger bin widths will increase the difference between high and low probabilities) This parameter is optional and if not specified or value is less than 0 then the bin width will be estimated from the data.

  • use_no_data – is a boolean specifying whether (if specified) the no data value specified in the band header should be excluded from the histogram (Optional and if not specified defaults to True).

  • rescale_probs – is a boolean specifying whether the probabilities should be rescaled to a range of 0-1 as values can be very small when a number of variables are used. (Optional and if not specified the default is True).

rsgislib.imagecalc.calc_img_difference(in_a_img, in_b_img, output_img, gdalformat, datatype)

Calculate the difference between two images (Image1 - Image2). Note the two images must have the same number of image bands.

Parameters:

  • in_a_img – is a string containing the name of the first input file

  • in_b_img – is a string containing the name of the second input file

  • output_img – is a string containing the name of the output 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_*

import rsgislib
from rsgislib import imagecalc
from rsgislib import imageutils

inputImage1 = 'output_orig/LS8_20131111_lat29lon8717_r40p140_vmsk_rad_srefdem.kea'
inputImage2 = 'output_lutinterp/LS8_20131111_lat29lon8717_r40p140_vmsk_rad_srefdem.kea'
outputImage = 'LS8_20131111_lat29lon8717_r40p140_srefdemDiff.kea'

imagecalc.calc_img_difference(inputImage1, inputImage2, outputImage, 'KEA', rsgislib.TYPE_32FLOAT)
imageutils.pop_img_stats(outputImage, usenodataval=False, nodataval=0, calcpyramids=True)

Thresholding

rsgislib.imagecalc.calc_split_win_thresholds(input_img: str, win_size: int = 500, thres_meth: int = 1, output_file: str = None, no_data_val: float = None, lower_valid: float = None, upper_valid: float = None, min_n_vals: int = 100, **thres_kwrds) → Dict[int, List[float]]

A function which undertakes a split window based thresholding where a threshold is calculated for each window (tile) within the scene and a list of thresholds is returned from which a single or range of thresholds can be calculated.

If you know the range of values within which the threshold should exist it would probably be useful to use the upper and lower bounds thresholds to limit the data used within the thresholding and therefore the thresholds returned are more likely to be useful…

Parameters:

  • input_img – the input image

  • win_size – the window size

  • thres_meth – the thresholding method rsgislib.THRES_METH_*. Default if otsu thresholding. For details of other thresholding methods see rsgislib.tools.stats for function descriptions.

  • output_file – An optional JSON output file with a list of the thresholds for each band within the input file.

  • no_data_val – an optional no data value for the input image pixel values. If provided these values will be ignored in the input image.

  • lower_valid – a lower bounds for pixel values to be used for the analysis.

  • upper_valid – an upper bounds for pixel values to be used for the analysis.

  • min_n_vals – the minimum number of values used to calculate the threshold within a window.

  • thres_kwrds – some of the thresholding methods have arguments which need to be provided. Use this key words arguments to provide those inputs. See rsgislib.tools.stats for function inputs.

Returns:

dict of bands and a list of thresholds for the bands.

Histogram

rsgislib.imagecalc.histogram(input_img, in_msk_img, output_file, img_band, msk_val, bin_width, calc_min_max, min_val, max_val)

Generates a histogram for the region of the mask selected

Parameters:

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

  • in_msk_img – is a string containing the name of the image mask file

  • output_file – is a string containing the name of the file for histogram output

  • img_band – is an integer for the band within the image (band indexing start at 1)

  • msk_val – is a float for the value within the input mask for the regions the histogram will be calculated

  • bin_width – is a float specifying the width of the histogram bins

  • calc_min_max – is a boolean specifying whether inMin and inMax should be calculated

  • min_val – is a float for the minimum image value to be included in the histogram

  • max_val – is a floatf or the maximum image value to be included in the histogram

rsgislib.imagecalc.get_histogram(input_img, img_band, bin_width, calc_min_max, min_val, max_val)

Generates and returns a histogram for the image.

Parameters:

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

  • img_band – is an unsigned int specifying the image band starting from 1.

  • bin_width – is a float specifying the width of the histogram bins

  • calc_min_max – is a boolean specifying whether inMin and inMax should be calculated

  • min_val – is a float for the minimum image value to be included in the histogram

  • max_val – is a float or the maximum image value to be included in the histogram

Returns:

list of ints

rsgislib.imagecalc.get_2d_img_histogram(in_a_img, in_b_img, output_img, gdalformat, img_a_band, img_b_band, n_bins, img_a_min, img_a_max, img_b_min, img_b_max, img_a_scale, img_b_scale, img_a_offset, img_b_offset, normalise)

Calculates at 2D histogram between two bands of two input images

Parameters:

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

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

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

  • gdalformat – is a string specifying output image format.

  • img_a_band – is an unsigned integer specifying the image band from image a to be used.

  • img_b_band – is an unsigned integer specifying the image band from image b to be used.

  • n_bins – is an unsigned integer specifying the number of bins to be used on each histogram axis (it’ll produce a square histogram).

  • img_a_min – is a double specifying the minimum image value for image a to be used in the histogram.

  • img_a_max – is a double specifying the maximum image value for image a to be used in the histogram.

  • img_b_min – is a double specifying the minimum image value for image b to be used in the histogram.

  • img_b_max – is a double specifying the maximum image value for image b to be used in the histogram.

  • img_a_scale – is a double specifying a scale for the pixel value in image a.

  • img_b_scale – is a double specifying a scale for the pixel value in image b.

  • img_a_offset – is a double specifying an offset value for the pixel values in image a.

  • img_b_offset – is a double specifying an offset value for the pixel values in image b.

  • normalise – is a boolean specifying whether the output histogram should be normalised to unit volume.

Returns:

(double with bin width of the axis of image 1), (double with bin width of the axis of image 2)

rsgislib.imagecalc.calc_histograms_for_msk_vals(input_img, img_band, img_msk, msk_band, min_val, max_val, bin_width, msk_vals=None)

A function which reads the image bands (values and mask) into memory and creates a histogram for each value within the mask value. Within the mask 0 is considered to be no data.

Parameters:

  • input_img – image values image file path.

  • img_band – values image band

  • img_msk – file path for image mask.

  • msk_band – mask image band

  • min_val – minimum value for the histogram bins

  • max_val – maximum value for the histogram bins

  • bin_width – the width of the histograms bins.

  • msk_vals – a list of values within the mask can be provided to just consider a limited number of mask values when calculating the histograms. If None (default) then calculated for all mask values.

Returns:

returns a dict of mask values with an array for the histogram.

Normalise

rsgislib.imagecalc.normalise_image_band(input_img, band, output_img, gdal_format='KEA')

Perform a simple normalisation a single image band (val - min)/range.

Parameters:

  • input_img – The input image file.

  • band – the image band (starts at 1) to be normalised

  • output_img – the output image file (will just be a single band).

  • gdal_format – The output image format.

rsgislib.imagecalc.calc_img_rescale(input_imgs, output_img, gdalformat, datatype, c_no_data_val, c_offset, c_gain, n_no_data_val, n_offset, n_gain)

A function which can take either a list of images or a single image to produce a single stacked output image. The image values are rescaled applying the input (current; c) gain and offset and then applying the new (n) gain and offset to the output image. Note, the nodata image value is also defined and can be changed. For reference gain/offset are applied as: ImgVal = (gain x DN) + offset

Parameters:

  • input_imgs – can be either a single input image file or a list of images to be stacked.

  • output_img – is the output image file.

  • gdalformat – output raster format (e.g., KEA)

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

  • c_no_data_val – is a float for the current (existing) no-data value for the imagery (note, all input images have the same no-data value).

  • c_offset – is a float for the current offset value.

  • c_gain – is a float for the current gain value.

  • n_no_data_val – is a float for the new no-data value for the imagery (note, all input images have the same no-data value).

  • n_offset – is a float for the new offset value.

  • n_gain – is a float for the new gain value.

rsgislib.imagecalc.rescale_img_pxl_vals(input_img, output_img, gdalformat, datatype, band_rescale_objs, trim_to_limits=True)

Function which rescales an input image base on a list of rescaling parameters.

Parameters:

  • input_img – the input image

  • output_img – the output image file name and path (will be same dimensions as the input)

  • gdalformat – the GDAL image file format of the output image file.

  • band_rescale_objs – list of ImageBandRescale objects

  • trim_to_limits – whether to trim the output to the output min/max values.

class rsgislib.imagecalc.ImageBandRescale(band=0, in_min=0.0, in_max=0.0, no_data_val=0, out_min=0.0, out_max=0.0, out_no_data=0.0)

Data structure for rescaling information for rescale_img_pxl_vals function. :param band: specified image band (band numbering starts at 1). :param in_min: the input image band minimum value for rescaling. :param in_max: the input image band maximum value for rescaling. :param no_data_val: no data value for the input image band. :param out_min: the output image band minimum value for rescaling. :param out_max: the output image band maximum value for rescaling. :param out_no_data: no data value for the output image band.

Parameters:

  • band – specified image band (band numbering starts at 1).

  • in_min – the input image band minimum value for rescaling.

  • in_max – the input image band maximum value for rescaling.

  • no_data_val – no data value for the input image band.

  • out_min – the output image band minimum value for rescaling.

  • out_max – the output image band maximum value for rescaling.

  • out_no_data – no data value for the output image band.

Geometry

rsgislib.imagecalc.mahalanobis_dist_filter(input_img, output_img, win_size, gdalformat, datatype)

Performs mahalanobis distance window filter.

Parameters:

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

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

  • win_size – is an int defining the size of the window to be used

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

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

rsgislib.imagecalc.mahalanobis_dist_to_img_filter(input_img, output_img, win_size, gdalformat, datatype)

Performs mahalanobis distance image to window filter.

Parameters:

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

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

  • win_size – is an int defining the size of the window to be used

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

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

rsgislib.imagecalc.calc_dist_to_img_vals(input_img: str, output_img: str, pxl_vals: List[int], img_band: int = 1, gdalformat: str = 'KEA', max_dist: float = None, no_data_val: float = None, out_no_data_val: float = None, unit_geo: bool = True)

A function to calculate the distance to the nearest pixel value with one of the specified values.

Parameters:

  • input_img – is a string specifying the input image file.

  • output_img – is a string specfiying the output image file.

  • pxl_vals – is a number of list of numbers specifying the features to which the distance from should be calculated.

  • img_band – is an integer specifying the image band of the input image to be used (Default = 1).

  • gdalformat – is a string specifying the output image format (Default = KEA)

  • max_dist – is a number specifying the maximum distance to be calculated, if None not max value is used (Default = None).

  • no_data_val – is the no data value in the input image for which distance should not be calculated for (Default = None; None = no specified no data value).

  • out_no_data_val – is output image no data value. If None then set as the max_dist value.

  • unit_geo – is a boolean specifying the output distance units. True = Geographic units (e.g., metres), False is in Pixels (Default = True).

import rsgislib.imagecalc
cloudsImg = 'LS5TM_20110701_lat52lon421_r24p204_clouds.kea'
dist2Clouds = 'LS5TM_20110701_lat52lon421_r24p204_distclouds.kea'
# Pixel value 1 == Clouds
# Pixel value 2 == Cloud Shadows
rsgislib.imagecalc.calc_dist_to_img_vals(cloudsImg, dist2Clouds, pxl_vals=[1,2], out_no_data_val=-9999)
rsgislib.imagecalc.calc_dist_to_img_vals_tiled(input_img, output_img, pxl_vals, img_band=1, max_dist=1000, no_data_val=1000, out_no_data_val=None, gdalformat='KEA', unit_geo=True, tmp_dir='tmp', tile_size=2000, n_cores=-1)

A function to calculate the distance to the nearest pixel value with one of the specified values.

Parameters:

  • input_img – is a string specifying the input image file.

  • output_img – is a string specfiying the output image file.

  • pxl_vals – is a number of list of numbers specifying the features to which the distance from should be calculated.

  • img_band – is an integer specifying the image band of the input image to be used (Default = 1).

  • gdalformat – is a string specifying the output image format (Default = KEA)

  • max_dist – is a number specifying the maximum distance to be calculated, if None not max value is used (Default = None).

  • no_data_val – is the no data value in the input image for which distance should not be calculated for (Default = None; None = no specified no data value).

  • out_no_data_val – is output image no data value. If None then set as the max_dist value.

  • unit_geo – is a boolean specifying the output distance units. True = Geographic units (e.g., metres), False is in Pixels (Default = True).

  • tmp_dir – is a directory to be used for storing the image tiles and other temporary files - if not directory does not exist it will be created and deleted on completion (Default: tmp).

  • tile_size – is an int specifying in pixels the size of the image tiles used for processing (Default: 2000)

  • n_cores – is the number of processing cores which are available to be used for this processing. If -1 all available cores will be used. (Default: -1)

import rsgislib.imagecalc
cloudsImg = 'LS5TM_20110701_lat52lon421_r24p204_clouds.kea'
dist2Clouds = 'LS5TM_20110701_lat52lon421_r24p204_distclouds.kea'
# Pixel value 1 == Clouds
# Pixel value 2 == Cloud Shadows
rsgislib.imagecalc.calc_dist_to_img_vals_tiled(cloudsImg, dist2Clouds, pxl_vals=[1,2])
rsgislib.imagecalc.buffer_img_pxl_vals(input_img: str, output_img: str, pxl_vals: List[int], buf_thres: float, tmp_dir: str, gdalformat: str = 'KEA', img_band: int = 1, unit_geo: bool = True)

A function which uses the calc_dist_to_img_vals function and a threshold to buffer image pixel value(s) to create a binary mask

Parameters:

  • input_img – The input image

  • output_img – the output image

  • pxl_vals – a list of pixel values defining the region to be buffered

  • buf_thres – the threshold below which the buffered region will be defined.

  • tmp_dir – a tmp directory for intermediate outputs

  • gdalformat – output image format

  • img_band – the input image bands

  • unit_geo – is a boolean specifying the buf_thres distance units. True = Geographic units (e.g., metres), False is in Pixels (Default = True).

Image Indices

rsgislib.imagecalc.calcindices.calc_ndvi(input_img, img_red_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Normalised difference Vegetation Index (NDVI) ((NIR-RED)/(NIR+RED)). Note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

import rsgislib
from rsgislib import imagecalc

input_image = "L1C_T45RYH_A019936_20201230T044924.tif"
red_band = 4
nir_band = 5
out_image = "L1C_T45RYH_A019936_20201230T044924_NIR.kea:
calc_stats = True
gdalformat = "KEA"

calc_ndvi(input_image, red_band, nir_band, out_image, calc_stats, gdalformat)
rsgislib.imagecalc.calcindices.calc_wbi(input_img, img_blue_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Water Band Index (WBI) (Blue/NIR. Note, the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_blue_band – is an int specifying the blue band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_ndwi(input_img, img_nir_band, img_swir1_band, output_img, calc_stats=True, gdalformat='KEA')
Helper function to calculate Normalised Difference Water Index (NDWI)

((NIR-SWIR)/(NIR+SWIR)), note the output no data value is -999.

See: Xu, H. (2006). Modification of normalised difference water index (NDWI) to enhance open water features in remotely sensed imagery. International Journal of Remote Sensing, 27(14), 3025–3033. http://doi.org/10.1080/01431160600589179

Parameters:

  • input_img – is a string specifying the input image file.

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • img_swir1_band – is an int specifying the swir band (e.g., Landsat TM Band 5) in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_gndwi(input_img, img_green_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Green-Normalised Water Different Index (NDWI) ((GREEN-NIR)/(GREEN+NIR)), note the output no data value is -999.

See: Xu, H. (2006). Modification of normalised difference water index (NDWI) to enhance open water features in remotely sensed imagery. International Journal of Remote Sensing, 27(14), 3025–3033. http://doi.org/10.1080/01431160600589179

Parameters:

  • input_img – is a string specifying the input image file.

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_gmndwi(input_img, img_green_band, img_swir1_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Green/SWIR-Normalised Difference Water Index (NDWI) ((GREEN-SWIR)/(GREEN+SWIR)). Note, the output no data value is -999.

See: Xu, H. (2006). Modification of normalised difference water index (NDWI) to enhance open water features in remotely sensed imagery. International Journal of Remote Sensing, 27(14), 3025–3033. http://doi.org/10.1080/01431160600589179

Parameters:

  • input_img – is a string specifying the input image file.

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_swir1_band – is an int specifying the swir band (e.g., Landsat TM Band 5) in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_whiteness(input_img, img_blue_band, img_green_band, img_red_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate whiteness, note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_blue_band – is an int specifying the blue band in the input image (band indexing starts at 1)

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_brightness(input_img, img_blue_band, img_green_band, img_red_band, output_img, calc_stats=True, gdalformat='KEA', scale_factor=1000)

Helper function to calculate visible brightness, note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_blue_band – is an int specifying the blue band in the input image (band indexing starts at 1)

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

  • scale_factor – is a float which can be used retrieved reflectance between 0-1 (Default: 1000 to match rsgislib/arcsi)

rsgislib.imagecalc.calcindices.calc_brightness_scaled(input_img, img_blue_band, img_green_band, img_red_band, output_img, calc_stats=True, gdalformat='KEA', scale_factor=1000)

Helper function to calculate visible brightness, note the output no data value is -999. The difference between this function calc_brightness is that the output image is rescaled so the maximum value is 1.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_blue_band – is an int specifying the blue band in the input image (band indexing starts at 1)

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

  • scale_factor – is a float which can be used retrieved reflectance between 0-1 (Default: 1000 to match rsgislib/arcsi)

rsgislib.imagecalc.calcindices.calc_ctvi(input_img, img_red_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Corrected Transformed Vegetation Index ((NDVI + 0.5)/sqrt(abs(NDVI + 0.5))), note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_red_band – is an int specifying the blue band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_ndsi(input_img, img_green_band, img_swir1_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Normalised Difference Snow Index (NDSI) ((Green-SWIR)/(Green+SWIR)), note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_swir1_band – is an int specifying the swir band (e.g., Landsat TM Band 5) in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_nbr(input_img, img_nir_band, img_swir2_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Normalised Burn Ratio (NBR) ((NIR-SWIR#2)/(NIR+SWIR#2)). Note, the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • img_swir2_band – is an int specifying the swir #2 band (e.g., Landsat TM Band 7) in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_bai(input_img, img_nir_band, img_red_band, output_img, calc_stats=True, gdalformat='KEA', scale_factor=1000)

Helper function to calculate Burn Area Index (BAI) 1/((0.1 - red)*(0.1 - red) + (0.06 - nir)*(0.06 - nir)). Note, the output no data value is -999.

Burn Area Index (BAI): Chuvieco, E.; Martín, M.P.; Palacios, A. Assessment of different spectral indices in the red-near-infrared spectral domain for burned land discrimination. Int. J. Remote Sens. 2002, 23, 5103–5110.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

  • scale_factor – is a float which can be used retrieved reflectance between 0-1 (Default: 1000 to match rsgislib/arcsi)

rsgislib.imagecalc.calcindices.calc_mvi(input_img, img_green_band, img_nir_band, img_swir1_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Mangrove Vegetation Index (MFI) ((NIR-Green)/(SWIR-Green)). Note, the output no data value is -999.

Baloloya, A.B, Blancoab, A.C, Ana, R.R.C.S, Nadaokac, K (2020). Development and application of a new mangrove vegetation index (MVI) for rapid and accurate mangrove mapping. ISPRS Journal of Photogrammetry and Remote Sensing. 166. pp95-177. https://doi.org/10.1016/j.isprsjprs.2020.06.001

Parameters:

  • input_img – is a string specifying the input image file.

  • img_green_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • img_swir1_band – is an int specifying the swir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_remi(input_img, img_green_band, img_red_band, img_re_band, img_swir_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Red-Edge Mangrove Index (REMI) ((REDEDGE-RED)/(SWIR1+GREEN)). Note the output no data value is -999. Red-edge band is typically the 6th (5 ignoring coastal Band) Sentinel-2 band (740 nm).

Chen, Z., Zhang, M., Zhang, H., Liu, Y., 2023. Mapping mangrove using a red-edge mangrove index (REMI) based on Sentinel-2 multispectral images. IEEE Trans. Geosci. Remote Sens. PP, 1–1. https://doi.org/10.1109/tgrs.2023.3323741

Parameters:

  • input_img – is a string specifying the input image file.

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • img_re_band – is an int specifying the red-edge band in the input image (band indexing starts at 1)

  • img_swir_band – is an int specifying the swir1 band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_gndvi(input_img, img_green_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA')

Helper function to calculate Green Normalised difference Vegetation Index (GNDVI) ((NIR-RED)/(NIR+RED)). Note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_evi(input_img, img_blue_band, img_red_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA', g=2.5, c1=6.0, c2=7.5, l=1, refl_scale_factor=0.001)

Helper function to calculate Enhanced Vegetation Index (EVI) G * ((NIR - Red) / (NIR + C1 * Red – C2 * BLue + L)). Note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_blue_band – is an int specifying the blue band in the input image (band indexing starts at 1)

  • img_green_band – is an int specifying the green band in the input image (band indexing starts at 1)

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

rsgislib.imagecalc.calcindices.calc_evi2(input_img, img_red_band, img_nir_band, output_img, calc_stats=True, gdalformat='KEA', g=2.5, c=2.4, l=1, refl_scale_factor=0.001)

Helper function to calculate Enhanced Vegetation Index 2 (EVI2) G * (nir - red)/(nir + 2.4 * red + 1). Note the output no data value is -999.

Parameters:

  • input_img – is a string specifying the input image file.

  • img_red_band – is an int specifying the red band in the input image (band indexing starts at 1)

  • img_nir_band – is an int specifying the nir band in the input image (band indexing starts at 1)

  • output_img – is a string specifying the output image file.

  • calc_stats – is a boolean specifying whether pyramids and stats should be calculated (Default: True)

  • gdalformat – is a string specifying the output image file format (Default: KEA)

Equalivance

rsgislib.imagecalc.are_imgs_equal(in_ref_img, in_cmp_img, prop_eql=1.0, flt_dif=0.0001)

A function to check whether two images have equal pixel values within the spatial overlap. Note, if the two input images only have a partial overlap (i.e., one is a subset of the other) then they are still be equal if the overlapping region has matching pixel values.

Parameters:

  • in_ref_img – The input reference image for the comparison.

  • in_cmp_img – The input comparison image to be compared to the reference image.

  • prop_eql – The proportion of pixels within the scene which need to be identified as identical to return True. Range is 0 - 1. Default is 1.0 (i.e., 100 % of pixels have to be identical to return True).

  • 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 (match), float (proportion of pixels which matched)

rsgislib.imagecalc.are_img_bands_equal(in_ref_img, img_ref_band, in_cmp_img, img_cmp_band, prop_eql=1.0, flt_dif=0.0001)

A function to check whether two image bands have equal pixel values within the spatial overlap. Note, if the two input images only have a partial overlap (i.e., one is a subset of the other) then they are still be equal if the overlapping region has matching pixel values.

Parameters:

  • in_ref_img – The input reference image for the comparison.

  • img_ref_band – The band from the reference image

  • in_cmp_img – The input comparison image to be compared to the reference image.

  • img_cmp_band – The band from the comparison image

  • prop_eql – The proportion of pixels within the scene which need to be identified as identical to return True. Range is 0 - 1. Default is 1.0 (i.e., 100 % of pixels have to be identical to return True).

  • 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 (match), float (proportion of pixels which matched)

Least Cost Path

rsgislib.imagecalc.leastcostpath.perform_least_cost_path_calc(cost_surface_img: str, output_img: str, start_coord: list, stop_coord: list, gdalformat: str = 'KEA', cost_img_band: int = 1)

Calculates least cost path for a raster surface from start coord to stop coord:

Version of code from: https://pcjericks.github.io/py-gdalogr-cookbook/raster_layers.html#create-least-cost-path

Parameters:

  • cost_surface_img – Input image to calculate cost path from

  • output_img – Output image

  • start_coord – Start coordinate (e.g., (263155.9, 291809.1))

  • stop_coord – End coordinate (e.g., (263000.1, 292263.7))

  • gdalformat – GDAL format (default=KEA)

  • cost_img_band – Band in input image to use for cost analysis (default=1)

Calc Image Point Samples

rsgislib.imagecalc.calc_pt_win_smpls.calc_pt_smpl_img_vals(input_img: str, vec_file: str, vec_lyr: str, calc_objs: List[RSGISCalcSumVals], out_vec_file: str, out_vec_lyr: str, out_format: str, interp_method: int = 2, angle_col: str = None, x_box_col: str = 'xbox', y_box_col: str = 'ybox', no_data_val: float = None)

A function which calculates, for each point within the input vector layer, summary values for a window of image data around the point. The image window size is defined in the attribute table of the vector layer and optionally an angle (relative to north; 0.0; default) to reorientate image window. The summary values calculated are using an implementation of the RSGISCalcSumVals class.

Parameters:

  • input_img – input image file.

  • vec_file – input vector file - needs to be a point type.

  • vec_lyr – input vector layer name.

  • calc_objs – An implementation of the RSGISCalcSumVals class to calculate the summary values for the image data.

  • out_vec_file – output vector file path.

  • out_vec_lyr – output vector layer name.

  • out_format – output vector file format (e.g., GeoJSON)

  • interp_method – the interpolation method used when reorientating the image data. Default: rsgislib.INTERP_CUBIC

  • angle_col – name of the column within the vector attribute table defining the rotation (relative to north; 0 = North) for each point. If None (Default) then no rotation applied. (Unit is degrees)

  • x_box_col – name of the column within the vector attribute table defining the size of the bbox in the x axis. Note, this is half the bbox width. (Unit is image pixels)

  • y_box_col – name of the column within the vector attribute table defining the size of the bbox in the y axis. Note, this is half the bbox height. (Unit is image pixels)

  • no_data_val – the image no data value. If None then taken from the input image header.

class rsgislib.imagecalc.calc_pt_win_smpls.RSGISCalcSumVals

Abstract class for calculating summary values for a GDAL image Dataset. Provided to calc_pt_smpl_img_vals function.

Parameters:

  • self.n_out_vals – the number of output values. Length of list of names.

  • self.out_val_names – list of output names. Defined in implementation.