RSGISLib Raster GIS Module

The Raster GIS module contains functions for attributing and manipulating raster attribute tables.

class rsgislib.rastergis.BandAttPercentiles(percentile, fieldName)

This is passed to the populateRATWithPercentiles function

class rsgislib.rastergis.BandAttStats(band, minField=None, maxField=None, sumField=None, stdDevField=None, meanField=None)

This is passed to the populateRATWithStats function

class rsgislib.rastergis.FieldAttStats(field, minField=None, maxField=None, sumField=None, stdDevField=None, meanField=None)

This is passed to the calcRelDiffNeighStats function

class rsgislib.rastergis.ShapeIndex(colName, idx, colIdx=0)

This is passed to the calcShapeIndices function

rsgislib.rastergis.check_string_col_valid(clumps, str_col, rm_punc=False, rm_spaces=False, rm_non_ascii=False, rm_dashs=False)

A function which checks a string column to ensure nothing is invalid.

Parameters

  • clumps – input clumps image.

  • str_col – the column to check

  • rm_punc – If True removes punctuation from column name other than dashs and underscores.

  • rm_spaces – If True removes spaces from the column name, replacing them with underscores.

  • rm_non_ascii – If True removes characters which are not in the ascii range of characters.

  • rm_dashs – If True then dashs are removed from the column name.

rsgislib.rastergis.exportCols2GDALImage(clumps, outimage, gdalformat, datatype, fields, ratband=1, tempDIR=None)

Exports columns of the raster attribute table as bands in a GDAL image. Utility function, exports each column individually then stacks them.

Where:

Parameters

  • clumps – is a string containing the name of the input image file with RAT

  • outimage – is a string containing the name of the output gdal file

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

  • field – is a list of strings, providing the names of the column to be exported.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

clumps='./RATS/injune_p142_casi_sub_utm_clumps_elim_final_clumps_elim_final.kea'
outimage='./TestOutputs/RasterGIS/injune_p142_casi_rgb_export.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
fields = ['RedAvg','GreenAvg','BlueAvg']
rastergis.exportCols2GDALImage(clumps, outimage, gdalformat, datatype, fields)
rsgislib.rastergis.getRATColumns(clumps_img, rat_band=1)

A function which returns a list of column names within the RAT.

Parameters

  • clumps_img – path to the image file with the RAT

  • rat_band – the band within the image file for which the RAT is to read.

Returns

list of column names.

rsgislib.rastergis.getRATColumnsInfo(clumps_img, rat_band=1)

A function which returns a dictionary of column names with type (GFT_Integer, GFT_Real, GFT_String) and usage (e.g., GFU_Generic, GFU_PixelCount, GFU_Name, etc.) within the RAT.

Parameters

  • clumps_img – path to the image file with the RAT

  • rat_band – the band within the image file for which the RAT is to read.

Returns

dict of column information.

rsgislib.rastergis.getRATLength(clumps_img, rat_band=1)

A function which returns the length (i.e., number of rows) within the RAT.

Parameters

  • clumps_img – path to the image file with the RAT

  • rat_band – the band within the image file for which the RAT is to read.

rsgislib.rastergis.readRATNeighbours(clumps_img, start_row=None, end_row=None, rat_band=1)

A function which returns a list of clumps neighbours from a KEA RAT. Note, the neighbours are popualted using the function rsgislib.rastergis.findNeighbours. By default the whole datasets of neightbours is read to memory but the start_row and end_row variables can be used to read a subset of the RAT.

Parameters

  • clumps_img – path to the image file with the RAT

  • start_row – the row within the RAT to start reading, if None will start at 0 (Default: None).

  • end_row – the row within the RAT to end reading, if None will end at n_rows within the RAT. (Default: None)

  • rat_band – the band within the image file for which the RAT is to read.

Returns

list of lists with neighbour indexes.

Utilities

rsgislib.rastergis.populateStats(clumps=string, addclrtab=boolean, calcpyramids=boolean, ignorezero=boolean, ratband=int)

Populates statics for thematic images.

Where:

Parameters

  • clumps – is a string containing the name of the input clump file

  • addclrtab – is a boolean to specify whether a colour table should created and added (colours will be random) (Optional, default = True)

  • calcpyramids – is a boolean to specify where overview images could be created (Optional, default = True)

  • ignorezero – is a boolean specifying whether zero should be ignored (i.e., set as a no data value). (Optional, default = True)

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
clumps='injune_p142_casi_sub_utm_segs_nostats_addstats.kea'
pyramids=True
colourtable=True
rastergis.populateStats(clumps, colourtable, pyramids)
rsgislib.rastergis.ratutils.populateImageStats(inputImage, clumpsFile, outascii=None, threshold=0.0, calcMin=False, calcMax=False, calcSum=False, calcMean=False, calcStDev=False, calcMedian=False, calcCount=False, calcArea=False, calcLength=False, calcWidth=False, calcLengthWidth=False)

Attribute RAT with statistics from from all bands in an input image.

Where:

Parameters

  • inputImage – input image to calculate statistics from, if band names are avaialble these will be used for attribute names in the output RAT.

  • clumpsFile – input clumps file, statistics are added to RAT.

  • threshold – float, values below this are ignored (default=0)

  • outascii – string providing output CSV file (optional).

  • calcMin – Calculate minimum

  • calcMax – Calculate maximum

  • calcSum – Calculate sum

  • calcMean – Calculate mean

  • calcStDev – Calculate standard deviation

Example:

from rsgislib.rastergis import ratutils
inputImage = 'jers1palsar_stack.kea'
clumpsFile = 'jers1palsar_stack_clumps_elim_final.kea'
ratutils.populateImageStats(inputImage, clumpsFile, calcMean=True)
rsgislib.rastergis.collapseRAT(clumpsImage, selectField, outputFile, gdalformat, ratBand)

Collapses the image and rat to a set of selected rows (defined with a value of 1 in the selected column).

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • selectField – is a string containing the name of the binary column used to selected the rows to which the RAT is to be collapsed to.

  • outputFile – is a string with the output file name

  • gdalformat – is a string with the output image file format - note only KEA and HFA support RATs.

  • ratBand – is the image band with which the RAT is associated.

rsgislib.rastergis.ratutils.createClumpsSHPBBOX(clumpsImg, minXCol, maxXCol, minYCol, maxYCol, outShpLyrName, roundInt=False, ignoreFirstRow=False)

A function to create a shapefile of polygons with the bboxs of the clumps defined using the minX, maxX, minY and maxY coordinates for the features.

Where:

Parameters

  • clumpsImg – input clumps file.

  • minXCol – the minX column in RAT.

  • maxXCol – the maxX column in RAT.

  • minYCol – the minY column in RAT.

  • maxYCol – the maxY column in RAT.

  • outShpLyrName – The output shapefile name (layer name do not include the .shp it will be appended).

  • roundInt – Boolean specifying whether the coordinated should be rounded to integers (Default: False)

rsgislib.rastergis.ratutils.getColumnData(clumpsImg, columnName)

A function to read a column of data from a RAT.

Parameters

  • clumpsImg – Input clumps image

  • columnName – Name of the column to be read.

Returns

numpy array with values from the clumpsImg

Attribute Clumps

rsgislib.rastergis.calcBorderLength(inputImage, ignoreZeroEdges, outColsName)

Calculate the border length of clumps

Where:

Parameters

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

  • ignoreZeroEdges – is a bool

  • outColsName – is a string

rsgislib.rastergis.ratutils.calcDistBetweenClumps(clumpsImg, outColName, tmpDIR='./tmp', useIdx=False, maxDistThres=10)

Calculate the distance between all clumps

Parameters

  • clumpsImg – image clumps for which the distance will be calculated.

  • outColName – output column within the clumps image.

  • tmpDIR – directory out tempory files will be outputted to.

  • useIdx – use a spatial index when calculating the distance between clumps (needed for large number of clumps).

  • maxDistThres – if using an index than an upper limit on the distance between clumps can be defined.

rsgislib.rastergis.ratutils.calcDistToLargeClumps(clumpsImg, outColName, sizeThres, tmpDIR='./tmp', useIdx=False, maxDistThres=10)

Calculate the distance from each small clump to a large clump. Split defined by the threshold provided.

Parameters

  • clumpsImg – image clumps for which the distance will be calculated.

  • outColName – output column within the clumps image.

  • sizeThres – is a threshold to seperate the sets of large and small clumps.

  • tmpDIR – directory out tempory files will be outputted to.

  • useIdx – use a spatial index when calculating the distance between clumps (needed for large number of clumps).

  • maxDistThres – if using an index than an upper limit on the distance between clumps can be defined.

rsgislib.rastergis.calcRelBorder(inputImage, outColsName, classNameField, className, ignoreZeroEdges)

Calculates the relative border length of the clumps to a class

Where:

Parameters

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

  • outColsName – is a string

  • classNameField – is a string

  • className – is a string

  • ignoreZeroEdges – is a bool

rsgislib.rastergis.calcRelDiffNeighStats(clumpsImage, fieldstats, ratBand)

Calculates the difference (relative or absolute) between each clump and it’s neighbours. The differences can be summarised as min, max, mean, std dev or sum.

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • fieldstats – has the following fields * field: string defining the field in the RAT to compare to. * minField: string defining the name of the field for min value * maxField: string defining the name of the field for max value * sumField: string defining the name of the field for sum value * meanField: string defining the name of the field for mean value * stdDevField: string defining the name of the field for standard deviation value

  • ratBand – is the image band with which the RAT is associated.

Example:

import rsgislib.rastergis
inputImage = './RapidEye_20130625_lat53lon389_tid3063312_oid167771_rad_toa_segs_neigh.kea'
ratBand = 1
rsgislib.rastergis.findNeighbours(inputImage, ratBand)
fieldInfo = rsgislib.rastergis.FieldAttStats(field='NIRMean', minField='MinNIRMeanDiff', maxField='MaxNIRMeanDiff')
rsgislib.rastergis.calcRelDiffNeighStats(inputImage, fieldInfo, False, ratBand)
rsgislib.rastergis.defineBorderClumps(clumpsImage, tileImage, outColsName, tileOverlap, tileBoundary, tileBody)

Defines the clumps which are on the border within the file of the clumps using a mask

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • tileImage – is a string containing the name of the input tile image

  • outColsName – is a string containing the name of the output column

  • tileOverlap – is an unsigned int defining the overlap between tiles

  • tileBoundary – is an unsigned int

  • tileBody – is an unsigned int

rsgislib.rastergis.defineClumpTilePositions(clumpsImage, tileImage, outColsName, tileOverlap, tileBoundary, tileBody)

Defines the position within the file of the clumps.

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • tileImage – is a string containing the name of the input tile image

  • outColsName – is a string containing the name of the output column

  • tileOverlap – is an unsigned int defining the overlap between tiles

  • tileBoundary – is an unsigned int

  • tileBody – is an unsigned int

rsgislib.rastergis.findBoundaryPixels(inputImage, outputFile, gdalformat, ratBand)

Identifies the pixels on the boundary of the clumps

Where:

Parameters

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

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

  • gdalformat – is a string containing the GDAL format for the output file - (Optional, Default = ‘KEA’)

  • ratBand – is an int containing band for which the neighbours are to be calculated for (Optional, Default = 1)

rsgislib.rastergis.findNeighbours(inputImage, ratBand)

Finds the clump neighbours from an image

Where:

Parameters

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

  • ratBand – is an int containing band for which the neighbours are to be calculated for (Optional, Default = 1)

rsgislib.rastergis.populateCategoryProportions(catsimage=string, clumps=string, outcolsname=string, majcolname=string, cpclassnames=boolean, majclassnamefield=string classnamefield=string, ratbandclumps=int, ratbandcats=int)

Populates the attribute table with the proportions of intersecting categories

Where:

Parameters

  • categoriesImage – is a string containing the name of the categories (classification) image file from which the propotions are calculated

  • clumpsImage – is a string containing the name of the input clump file to which the proportions are to be populated.

  • outColsName – is a string representing the base name for the output columns containing the proportions.

  • majorityColName – is a string for name of the field which will hold the majority class.

  • copyClassNames – is a boolean defining whether class names should be copied (Optional, Default = false).

  • majClassNameField – is a string for the output column within the clumps image with the majority class names field (Optional, only used if copyClassNames == True)

  • classNameField – is a string with the name of the column within the categories image for the class names (Optional, only used if copyClassNames == True)

  • ratbandclumps – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the clumps image.

  • ratbandcats – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the catagories image.

rsgislib.rastergis.populateRATWithPercentiles(valsimage=string, clumps=string, band=int, bandstats=rsgislib.rastergis.BandAttStats, histbins=int, ratband=int)

Populates an attribute table with a percentile of the pixel values from an image.

Where:

Parameters

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

  • clumpsImage – is a string containing the name of the input clump file

  • band – is an int which specifies the image band (from valsimage) for which the stats are to be calculated

  • bandPercentiles – is a sequence of objects that have attributes matching rsgislib.rastergis.BandAttPercentiles * percentile: float defining the percentile to calculate (Valid range is 0 - 100) * fieldName: string defining the name of the field to use for this percentile

  • histbins – is an optional (default = 200) integer specifying the number of bins within the histogram (note this governs the accuracy to which percentile can be calculated).

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
clumpsImage = './TestOutputs/RasterGIS/injune_p142_casi_sub_utm_segs_popstats.kea'
band=1
bandPercentiles = []
bandPercentiles.append(rastergis.BandAttPercentiles(percentile=25.0, fieldName='B1Per25'))
bandPercentiles.append(rastergis.BandAttPercentiles(percentile=50.0, fieldName='B1Per50'))
bandPercentiles.append(rastergis.BandAttPercentiles(percentile=75.0, fieldName='B1Per75'))
rastergis.populateRATWithPercentiles(inputImage, clumpsImage, band, bandPercentiles)
rsgislib.rastergis.populateRATWithStats(valsimage=string, clumps=string, bandstats=rsgislib.rastergis.BandAttStats, ratband=int)

Populates an attribute table with statistics from an input values image.

Where:

Parameters

  • valsimage – is a string containing the name of the input image file from which the clumps are to populated.

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

  • bandstats – is a sequence of rsgislib.rastergis.BandAttStats objects that have attributes in line with rsgis.cmds.RSGISBandAttStatsCmds * band: int defining the image band to process * minField: string defining the name of the field for min value * maxField: string defining the name of the field for max value * sumField: string defining the name of the field for sum value * meanField: string defining the name of the field for mean value * stdDevField: string defining the name of the field for standard deviation value

  • ratband is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
clumps='./TestOutputs/RasterGIS/injune_p142_casi_sub_utm_segs_popstats.kea'
input='./Rasters/injune_p142_casi_sub_utm.kea'
bs = []
bs.append(rastergis.BandAttStats(band=1, minField='b1Min', maxField='b1Max', meanField='b1Mean', sumField='b1Sum', stdDevField='b1StdDev'))
bs.append(rastergis.BandAttStats(band=2, minField='b2Min', maxField='b2Max', meanField='b2Mean', sumField='b2Sum', stdDevField='b2StdDev'))
bs.append(rastergis.BandAttStats(band=3, minField='b3Min', maxField='b3Max', meanField='b3Mean', sumField='b3Sum', stdDevField='b3StdDev'))
rastergis.populateRATWithStats(input, clumps, bs)
rsgislib.rastergis.populateRATWithMeanLitStats(valsimage=string, clumps=string, meanLitImage=string, meanlitBand=int, meanLitCol=string, pxlCountCol=string, bandstats=rsgislib.rastergis.BandAttStats, ratband=int)

Populates an attribute table with statistics from an input values image where only the pixels with a band value above a defined threshold are used. This is something referred to as the mean-lit statistics, i.e., the sunlit pixels within the object.

Where:

Parameters

  • valsimage – is a string containing the name of the input image file from which the clumps are to populated.

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

  • meanLitImage – is a string containing the name of the input image containing the band to be used for the mean-lit stats.

  • meanLitBand – is an unsigned integer specifying the image band to be used within the meanLitImage.

  • meanLitCol – is a string specifying the column to be used for the ‘mean’ for each object in the mean-lit calculation

  • pxlCountCol – is a string specifying the output column in the RAT where the count for the number of pixels within each clump used for the stats is outputted.

  • bandstats – is a sequence of rsgislib.rastergis.BandAttStats objects that have attributes in line with rsgis.cmds.RSGISBandAttStatsCmds * band: int defining the image band to process * minField: string defining the name of the field for min value * maxField: string defining the name of the field for max value * sumField: string defining the name of the field for sum value * meanField: string defining the name of the field for mean value * stdDevField: string defining the name of the field for standard deviation value

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
inputImage = "RapidEye_20130625_lat53lon389_tid3063312_oid167771_rad_toa.kea"
segmentClumps = "RapidEye_20130625_lat53lon389_tid3063312_oid167771_rad_toa_segs.kea"
ndviImage = "RapidEye_20130625_lat53lon389_tid3063312_oid167771_rad_toa_ndvi.kea"
bandStats = []
bandStats.append(rastergis.BandAttStats(band=1, meanField='BlueMeanML', stdDevField='BlueStdDevML'))
bandStats.append(rastergis.BandAttStats(band=2, meanField='GreenMeanML', stdDevField='GreenStdDevML'))
bandStats.append(rastergis.BandAttStats(band=3, meanField='RedMeanML', stdDevField='RedStdDevML'))
bandStats.append(rastergis.BandAttStats(band=4, meanField='RedEdgeMeanML', stdDevField='RedEdgeStdDevML'))
bandStats.append(rastergis.BandAttStats(band=5, meanField='NIRMeanML', stdDevField='NIRStdDevML'))
rastergis.populateRATWithMeanLitStats(valsimage=inputImage, clumps=segmentClumps, meanLitImage=ndviImage, meanlitBand=1, meanLitCol='NDVIMean', pxlCountCol='MLPxlCount', bandstats=bandStats, ratband=1)
rsgislib.rastergis.selectClumpsOnGrid(clumpsImage, inSelectField, outSelectField, eastingsCol, northingsCol, metricField, methodStr, rows, cols)

Selects a segment within a regular grid pattern across the scene. The clump is selected based on the minimum, maximum or closest to the mean.

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • inSelectField – is a string which defines the column name where a value of 1 defines the clumps which will be included in the analysis.

  • outSelectField – is a string which defines the column name where a value of 1 defines the clumps selected by the analysis.

  • eastingsCol – is a string which defines a column with a eastings for each clump.

  • northingsCol – is a string which defines a column with a northings for each clump.

  • metricField – is a string which defines a column with a value for each clump which will be used for the distance, min, or max anaylsis.

  • methodStr – is a string which defines whether the minimum, maximum or mean method of selecting a clump will be used (values can be either min, max or mean).

  • rows – is an unsigned integer which defines the number of rows within which a clump will be selected.

  • cols – is an unsigned integer which defines the number of columns within which a clump will be selected.

rsgislib.rastergis.spatialLocation(clumps=string, eastings=string, northings=string, ratband=int)

Adds spatial location columns to the attribute table

Where:

Parameters

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

  • eastingsField – is a string containing the name of the eastings field

  • northingsField – is a string containing the name of the northings field

  • ratband – is an integer containing the band number for the RAT (Optional, default = 1)

Example:

from rsgislib import rastergis
image = 'injune_p142_casi_sub_utm_segs_spatloc_eucdist.kea'
eastings = 'Easting'
northings = 'Northing'
rastergis.spatialLocation(image, eastings, northings)
rsgislib.rastergis.spatialExtent(clumps=string, minXX=string, minXY=string, maxXX=string, maxXY=string, minYX=string, minYY=string, maxYX=string, maxYY=string, ratband=int)

Adds spatial extent for each clump to the attribute table

Where:

Parameters

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

  • minXX – is a string containing the name of the min X X field

  • minXY – is a string containing the name of the min X Y field

  • maxXX – is a string containing the name of the max X X field

  • maxXY – is a string containing the name of the max X Y field

  • minYX – is a string containing the name of the min Y X field

  • minYY – is a string containing the name of the min Y Y field

  • maxYX – is a string containing the name of the max Y X field

  • maxYY – is a string containing the name of the max Y Y field

  • ratband – is an integer containing the band number for the RAT (Optional, default = 1)

Example:

from rsgislib import rastergis
image = 'injune_p142_casi_sub_utm_segs_spatloc_eucdist.kea'
minX_X = 'minXX'
minX_Y = 'minXY'
maxX_X = 'maxXX'
maxX_Y = 'maxXY'
minY_X = 'minYX'
minY_Y = 'minYY'
maxY_X = 'maxYX'
maxY_Y = 'maxYY'
rastergis.spatialExtent(image, minX_X, minX_Y, maxX_X, maxX_Y, minY_X, minY_Y, maxY_X, maxY_Y)
rsgislib.rastergis.strClassMajority(baseclumps, infoclumps, baseclasscol, infoclasscol, ignorezero=True, baseratband=1, inforatband=1)

Finds the majority for class (string - field) from a set of small objects to large objects

Where:

Parameters

  • baseSegment – is a the base clumps file, to be attribured.

  • infoSegment – is the file to take attributes from.

  • baseclasscol – the output column name in the baseSegment file.

  • infoclasscol – is the colum name in the infoSegment file.

  • ignoreZero – is a boolean specifying if zeros should be ignored in input layer. If set to false values of 0 will be included when calculating the class majority, otherwise the majority calculation will only consider objects with a value greater than 0.

  • baseratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the base clumps.

  • inforatband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the info clumps.

Example:

from rsgislib import rastergis
clumps='./TestOutputs/RasterGIS/injune_p142_casi_sub_utm_segs_popstats.kea'
classRAT='./TestOutputs/RasterGIS/reInt_rat.kea'
rastergis.strClassMajority(clumps, classRAT, 'class_dst', 'class_src')
rsgislib.rastergis.populateRATWithMode(valsimage=string, clumps=string, outcolsname=string, usenodata=boolean, nodataval=long, outnodata=boolean, modeband=uint, ratband=uint)

Populates the attribute table with the mode of from a single band in the input image. Note this only makes sense if the input pixel values are integers.

Where:

Parameters

  • valsimage – is a string containing the name of the input image file from which the mode is calculated

  • clumpsImage – is a string containing the name of the input clump file to which the mode will be populated.

  • outColsName – is a string representing the name for the output column containing the mode.

  • usenodata – is a boolean defining whether the no data value should be ignored (Optional, Default = False).

  • nodataval – is a long defining the no data value to be used (Optional, Default = 0)

  • outnodata – is a boolean to specify that although the no data value should be used for the calculation it should not be outputted to the RAT as a output value unless there is no valid data within the clump. (Default = True)

  • modeband – is an optional (default = 1) integer parameter specifying the image band for which the mode is to be calculated.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the clumps image.

rsgislib.rastergis.populateRATWithPropValidPxls(valsimage=string, clumps=string, outcolsname=string, nodataval=float, ratband=uint)

Populates the attribute table with the proportion of valid pixels within the clump.

Where:

Parameters

  • valsimage – is a string containing the name of the input image file from which the valid pixels are to be identified

  • clumpsImage – is a string containing the name of the input clump file to which the proportion will be populated.

  • outColsName – is a string representing the name for the output column containing the proportion.

  • nodataval – is a float defining the no data value to be used.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the clumps image.

rsgislib.rastergis.ratutils.defineClassNames(clumps, classNumCol, classNameCol, classNamesDict)

A function to create a class names column in a RAT based on segmented clumps where a number of clumps have the same number class.

Parameters

  • clumps – input clumps image.

  • classNumCol – column specifying the class number (e.g., where clumps are segments in a segmentation)

  • classNameCol – the output column name where a string will be created if it doesn’t already exists.

  • classNamesDict – Dictionary to look up the class names. The key needs to the integer number for the class

rsgislib.rastergis.ratutils.calcDist2Classes(clumpsImg, classCol, outImgBase, tmpDIR='./tmp', tileSize=2000, maxDist=1000, nodata=1000, nCores=- 1)

A function which will calculate proximity rasters for a set of classes defined within the RAT.

Parameters

  • clumpsImg – is a string specifying the input image with the associated RAT

  • classCol – is the column in the RAT which has the classification

  • outImgBase – is the base name of the output image - output files will be KEA files.

  • tmpDIR – 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).

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

  • maxDist – is the maximum distance in units of the geographic units of the projection of the input image (Default: 1000).

  • nodata – is the value applied to the pixels outside of the maxDist threshold (Default: 1000; i.e., the same as maxDist).

  • nCores – 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)

rsgislib.rastergis.ratutils.setColumnData(clumpsImg, columnName, columnData)

A function to read a column of data from a RAT.

Parameters

  • clumpsImg – Input clumps image

  • columnName – Name of the column to be written.

  • columnData – Data to be written to the column.

Sampling

rsgislib.rastergis.histoSampling(clumps=string, varCol=string, outSelectCol=string, propOfSample=float, binWidth=float, classColumn=string, classVal=string, ratband=int)

This function performs a histogram based sampling of the RAT for a specific column. The output is a binary column within the RAT where rows with a value of 1 are the selected clumps.

Where:

Parameters

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

  • varCol – is a string containing the name of the field with the values used for the sampling.

  • outSelectCol – is a string containing the name of the field where the binary output will be written (1 for selected clumps).

  • propOfSample – is a float specifying the proportion of the datasets which should be within the outputted sample. Values range of 0-1. 0.5 would be a 50% sample.:param binWidth: is a float specifying the width of each histogram bin.

  • classColumn – is a string specifying a field within which classes have been defined. This can be used to only apply the sampling to a thematic subset of the RAT. If set as None then this is ignored. (Default = None)

  • classVal – is a string specifying the class it will be limited to.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis

rastergis.histoSampling(clumps='N00E103_10_grid_knn.kea', varCol='HH', outSelectCol='HHSampling', propOfSample=0.25, binWidth=0.01, classColumn='Class', classVal='2')
rsgislib.rastergis.ratutils.takeRandomSample(clumpsImg, inColName, inColVal, outColName, sampleRatio, seed=0)

A function to take a random sample of an input column.

Parameters

  • clumpsImg – clumps image.

  • inColName – input column name.

  • inColVal – numeric value for which the random sample is to be taken for.

  • outColName – output column where value of 1 is selected within the random sample and 0 is not selected.

  • sampleRatio – the size of the sample (0 - 1.0; i.e., 10% = 0.1) to be taken of the number of rows within input value.

  • seed – is the seed for the random number generation (optional; default is 0).

Classification

rsgislib.rastergis.binaryClassification(clumpsImage, xmlBlock, outColumn, ratBand)

Calculates a binary classification (1, 0) given a set of logical conditions.

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • xmlBlock – is a string with a block of XML which is to be parsed for the logical expression.

  • outColumn – is a string with the name out of the output column.

  • ratBand – is an (optional; default 1) integer with the image band with which the RAT is associated.

Example:

#!/usr/bin/env python

from rsgislib import rastergis
import xml.etree.cElementTree as ET

ET.register_namespace("rsgis", "http://www.rsgislib.org/xml/")
rootElem = ET.Element("{http://www.rsgislib.org/xml/}ratlogicexps")
expRoot = ET.SubElement(rootElem, "{http://www.rsgislib.org/xml/}expression", {'operation':'and'})
ET.SubElement(expRoot, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'eq','column':'ClustersClass','threshold':'6'})
ET.SubElement(expRoot, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'gt','column':'NIRMean','threshold':'300'})

xmlBlock = ET.tostring(rootElem, encoding='utf8', method='xml').decode("utf-8")
print(xmlBlock)

inputimage = "RapidEye_20130625_lat53lon389_tid3063312_oid167771_rad_toa_segs.kea"
outClassColumn = "Classification"

rastergis.binaryClassification(inputimage, xmlBlock, outClassColumn)
rsgislib.rastergis.regionGrowClass(clumpsImage, xmlBlock, classColumn, classVal, maxNumIter, ratBand)

Using a logical expression a class (classVal) defined within the classColumn is grown until. either the maximum number of iterations (maxNumIter) is reached or there all clumps meeting the criteria have been met (set maxNumIter to be -1).

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • xmlBlock – is a string with a block of XML which is to be parsed for the logical expression.

  • classColumn – is a string with the name column containing the classification.

  • classVal – is a string with the name of the class to be grown

  • maxNumIter – is the maximum number of iterations to used for the growth (optional; default is -1, i.e., no max number of iterations

  • ratBand – is an (optional; default 1) integer with the image band with which the RAT is associated.

Example:

from rsgislib import rastergis
import xml.etree.cElementTree as ET
ET.register_namespace("rsgis", "http://www.rsgislib.org/xml/")
rootElem = ET.Element("{http://www.rsgislib.org/xml/}ratlogicexps")
expRoot = ET.SubElement(rootElem, "{http://www.rsgislib.org/xml/}expression", {'operation':'or'})
ET.SubElement(expRoot, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'gt','column':'GreenMean','threshold':'150'})
ET.SubElement(expRoot, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'gt','column':'RedMean','threshold':'150'})
xmlBlock = ET.tostring(rootElem, encoding='utf8', method='xml').decode("utf-8")
print(xmlBlock)
inputimage = "RapidEye_20130625_lat53lon389_tid3063312_oid167771_rad_toa_segs.kea"
classColumn = "ClustersClass"
classVal = "6"
maxIters = -1
rastergis.findNeighbours(inputimage)
rastergis.regionGrowClass(inputimage, xmlBlock, classColumn, classVal, maxIters)
rsgislib.rastergis.regionGrowClassNeighCritera(clumpsImage, xmlBlockGrowCriteria, xmlBlockNeighCriteria, classColumn, classVal, maxNumIter, ratBand)

Using a logical expression a class (classVal) defined within the classColumn is grown until. either the maximum number of iterations (maxNumIter) is reached or there all clumps meeting the criteria have been met (set maxNumIter to be -1).

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • xmlBlockGrowCriteria – is a string with a block of XML which is to be parsed for the logical expression for the region growing.

  • xmlBlockNeighCriteria – is a string with a block of XML which is to be parsed for the logical expression for stating whether a feature is a neighbour which can be considered.

  • classColumn – is a string with the name column containing the classification.

  • classVal – is a string with the name of the class to be grown

  • maxNumIter – is the maximum number of iterations to used for the growth (optional; default is -1, i.e., no max number of iterations

  • ratBand – is an (optional; default 1) integer with the image band with which the RAT is associated.

Example:

from rsgislib import rastergis
import xml.etree.cElementTree as ET

ET.register_namespace("rsgis", "http://www.rsgislib.org/xml/")
rootElemCriteria = ET.Element("{http://www.rsgislib.org/xml/}ratlogicexps")
andElem = ET.SubElement(rootElemCriteria, "{http://www.rsgislib.org/xml/}expression", {'operation':'and'})
ET.SubElement(andElem, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'gt','column':'HHdB','threshold':'-10'})
ET.SubElement(andElem, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'lt','column':'dist2Sea','threshold':'2000'})
xmlBlockGrowCriteria = ET.tostring(rootElemCriteria, encoding='utf8', method='xml').decode("utf-8")

print(xmlBlockGrowCriteria)

ET.register_namespace("rsgis", "http://www.rsgislib.org/xml/")
rootElemNeigh = ET.Element("{http://www.rsgislib.org/xml/}ratlogicexps")
ET.SubElement(rootElemNeigh, "{http://www.rsgislib.org/xml/}expression", {'operation':'evaluate','operator':'lt','column':'dist2Sea'})
xmlBlockNeighCriteria = ET.tostring(rootElemNeigh, encoding='utf8', method='xml').decode("utf-8")

print(xmlBlockNeighCriteria)

inputimage = "N00E103_classification_grown.kea"
classColumn = "Classification"
classVal = "Mangroves"
maxIters = -1
rastergis.findNeighbours(inputimage)
rastergis.regionGrowClassNeighCritera(inputimage, xmlBlockGrowCriteria, xmlBlockNeighCriteria, classColumn, classVal, maxIters)
rsgislib.rastergis.ratutils.identifySmallUnits(clumpsImg, classCol, tmpPath, outColName, smallClumpsThres, useTiledClump=False, nCores=2, tileWidth=4000, tileHeight=4000)

Identify small connected units within a classification. The threshold to define small is provided by the user in pixels. Note, the outColName and smallClumpsThres variables can be provided as lists to identify a number of thresholds of small units.

Parameters

  • clumpsImg – string for the clumps image file containing input classification

  • classCol – string for the column name representing the classification as integer values

  • tmpPath – directory path where temporary layers are stored (if directory is created within the function it will be deleted once function is complete).

  • outColName – a list of output column names (i.e., one for each threshold)

  • smallClumpsThres – a list of thresholds for identifying small clumps.

  • useTiledClump – a boolean to specify whether the tiled clumping algorithm should be used (Default is False; select True for large datasets)

  • nCores – if the tiled version of the clumping algorithm is being used then there is an option to use multiple processing cores; specify the number to be used (Default is 2).

  • tileWidth – is the width of the image tile (in pixels) if tiled clumping is used.

  • tileHeight – is the height of the image tile (in pixels) if tiled clumping is used.

Example:

from rsgislib.rastergis import ratutils

clumpsImg = "LS2MSS_19750620_lat10lon6493_r67p250_rad_srefdem_30m_clumps.kea"
tmpPath = "./tmp/"
classCol = "OutClass"
outColName = ["SmallUnits25", "SmallUnits50", "SmallUnits100"]
smallClumpsThres = [25, 50, 100]
rastergis.identifySmallUnits(clumpsImg, classCol, tmpPath, outColName, smallClumpsThres)
rsgislib.rastergis.ratutils.populateClumpsWithClassTraining(clumpsImg, classesDict, tmpPath, classesIntCol, classesNameCol)

A function to populate a clumps file with training from a series of shapefiles (1 per class)

Where:

Parameters

  • clumpsImg – input clumps file.

  • classesDict – A dict structure with the class names as keys and the values are an array of two values [int class val, file path for a vector file (e.g., shapefile)].

  • tmpPath – File path (which needs to exist) where files can temporally be written.

  • classesIntCol – Output column name for integer values representing each class.

  • classesNameCol – Output column name for string class names.

Extrapolation

rsgislib.rastergis.applyKNN(clumps=string, inExtrapField=string, outExtrapField=string, trainRegionsField=string, applyRegionsField=string, fields=list<string>, kFeat=uint, distKNN=int, summeriseKNN=int, distThres=float, ratband=int)

This function uses the KNN algorithm to allow data values to be extrapolated to segments.

Where:

Parameters

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

  • inExtrapField – is a string containing the name of the field with the values used for the extrapolation.

  • outExtrapField – is a string containing the name of the field where the extrapolated values will be written to.

  • trainRegionsField – is a string containing the name of the field specifying the clumps to be used as training - binary column (1 == training region).

  • applyRegionsField – is a string containing the name of the field specifying the regions for which KNN is to be applued - binary column (1 == regions to be calculated). If None then ignored and applied to all.:param fields: is a list of strings specifying the fields which will be used to calculate distance.

  • kFeat – is an unsigned integer specifying the number of nearest features (i.e., K) to be used (Default: 12)

  • distKNN – specifies how the distance to identify NN is calculated (rsgislib.DIST_EUCLIDEAN, rsgislib.DIST_MANHATTEN, rsgislib.DIST_MAHALANOBIS, rsgislib.DIST_MINKOWSKI, rsgislib.DIST_CHEBYSHEV; Default: rsgislib.DIST_MAHALANOBIS).

  • summeriseKNN – specifies how the extrapolation value is calculated (rsgislib.SUMTYPE_MODE, rsgislib.SUMTYPE_MEAN, rsgislib.SUMTYPE_MEDIAN, rsgislib.SUMTYPE_MIN, rsgislib.SUMTYPE_MAX, rsgislib.SUMTYPE_STDDEV; Default: rsgislib.SUMTYPE_MEDIAN). Mode is used for classification.

  • distThres – is a maximum distance threshold over which features will not be included within the ‘k’.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
from rsgislib import imageutils
import rsgislib

forestClumpsImg='./LS5TM_20110428_forestclumps.kea'

rastergis.applyKNN(clumps=forestClumpsImg, inExtrapField='HP95', outExtrapField='HP95Pred', trainRegionsField='LiDARForest', applyRegionsField=None, fields=['RedRefl','GreenRefl','BlueRefl'], kFeat=12, distKNN=rsgislib.DIST_EUCLIDEAN, summeriseKNN=rsgislib.SUMTYPE_MEDIAN, distThres=25)

# Export predicted column to GDAL image
forestHeightImg='./LS5TM_20110428_forest95Height.kea'
rastergis.exportCol2GDALImage(forestClumpsImg, forestHeightImg, 'KEA', rsgislib.TYPE_32FLOAT, 'HP95Pred')
imageutils.popImageStats(forestHeightImg,True,0.,True)

Change Detection

rsgislib.rastergis.findChangeClumpsFromStdDev(clumpsImage, classfield, changeField, attFields, classChangeFields)

Identifies segments which have changed by looking for statistical outliers (std dev) from class population.

Where:

Parameters

  • clumps – is a string containing the name of the input clump file

  • classfield – is a string providing the name of the column containing classes.

  • change – is a string providing the output name of the change field

  • attributes – is a sequence of strings containing the columns to use when detecting change.

  • classChangeFields – is a sequence of python objects having the following attributes: * name - The class name in which change is going to be search for * outName - An integer to uniquely identify the clumps identify as change * threshold - The number of standard deviations away from the mean above which segments are identified as change.

  • ratBand – is an int containing band for which the neighbours are to be calculated for (Optional, Default = 1)

Example:

import collections
from rsgislib import rastergis
clumpsImage='injune_p142_casi_sub_utm_segs_popstats.kea'
ChangeFeat = collections.namedtuple('ChangeFeats', ['name', 'outName', 'threshold'])
changeFeatVals = []
changeFeatVals.append(ChangeFeat(name='Forest', outName=1, threshold=thresholdAll))
changeFeatVals.append(ChangeFeat(name='Scrub-Shrub', outName=1, threshold=thresholdAll))
rastergis.findChangeClumpsFromStdDev(clumpsImage, 'ClassName', 'ChangeFeats', ['NDVI'], changeFeatVals)
rsgislib.rastergis.getGlobalClassStats(clumpsImage, classfield, attFields, classChangeFields)

Similar to ‘findChangeClumpsFromStdDev’ but rather than applying a threshold to calculate change clumps adds global (over all objects) class mean and standard deviation to RAT.

Where:

Parameters

  • clumps – is a string containing the name of the input clump file

  • classfield – is a string providing the name of the column containing classes.

  • attributes – is a sequence of strings containing the columns to use when detecting change.

  • classChangeFields – is a sequence of python objects having the following attributes: * name - The class name in which change is going to be search for

  • ratBand – is an int containing band for which the neighbours are to be calculated for (Optional, Default = 1)

Example:

import collections   from rsgislib import rastergis
clumpsImage='injune_p142_casi_sub_utm_segs_popstats.kea'
ChangeFeat = collections.namedtuple('ChangeFeats', ['name', 'outName', 'threshold'])
changeFeatVals = []
changeFeatVals.append(ChangeFeat(name='Forest'))
changeFeatVals.append(ChangeFeat(name='Scrub-Shrub))
rastergis.getGlobalClassStats(clumpsImage, 'ClassName', ['NDVI'], changeFeatVals)
rsgislib.rastergis.classSplitFitHistGausianMixtureModel(clumps=string, outCol=string, varCol=string, binWidth=float, classColumn=string, classVal=string, ratband=int)

This function fits a Gaussian mixture model to the histogram for a variable in the RAT and uses it to split the class into a series of subclasses.

Where:

Parameters

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

  • outCol – is a string for a HDF5 with the fitted Gaussians.

  • varCol – is a string containing the name of the field with the values used for the sampling.

  • binWidth – is a float specifying the width of each histogram bin.

  • classColumn – is a string specifying a field within which classes have been defined.

  • classVal – is a string specifying the class it will be limited to.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis

rastergis.classSplitFitHistGausianMixtureModel(clumps='FrenchGuiana_10_ALL_sl_HH_lee_UTM_mosaic_dB_segs.kea', outCol='MangroveSubClass', varCol='HVdB', binWidth=0.1, classColumn='Classes', classVal='Mangroves')
rsgislib.rastergis.ratutils.calcPlotGaussianHistoModel(clumpsFile, outGausH5File, outHistH5File, outPlotFile, varCol, binWidth, classColumn, classVal, plotTitle)
Extracts a column from the RAT, masking by a class calculating the histogram and

fitting a Gaussian mixture model to the histogram. Outputs include a plot and HDF5 files of the histogram and gaussian parameters.

Where:

Parameters

  • clumpsFile – input clumps file with populated RAT.

  • outGausH5File – the output HDF5 file for the Gaussian Mixture Model

  • outHistH5File – the output HDF5 file for the histogram.

  • outPlotFile – the output PDF file for the plot

  • varCol – Column within the RAT for the variable to be used for the histogram

  • binWidth – Bin width for the histogram

  • classColumn – Column where the classes are specified

  • classVal – Class used to mask the input variable

  • plotTitle – title for the plot

Example:

from rsgislib.rastergis import ratutils

clumpsFile = "FrenchGuiana_10_ALL_sl_HH_lee_UTM_mosaic_dB_segs.kea"
outGausH5File = "gaufit.h5"
outHistH5File = "histfile.h5"
outPlotFile = "Plot.pdf"
varCol = "HVdB"
binWidth = 0.1
classColumn = "Classes"
classVal = "Mangrove"
plotTitle = "HV dB Backscater from Mangroves; French Guiana"

ratutils.calcPlotGaussianHistoModel(clumpsFile, outGausH5File, outHistH5File, outPlotFile, varCol, binWidth, classColumn, classVal, plotTitle)
rsgislib.rastergis.ratutils.findChangeClumpsHistSkewKurtTest(inputClumps, inClassCol, classOfInterest, changeVarCol, outChangeFeatCol, noDataVals=[], thresMeasure=<RSGISRATThresMeasure.auto: 4>, exportPlot=None, showAllThreshPlot=False)

This function identifies potential change features from both sides of the histogram by slicing the histogram and finding an optimal skewness and kurtosis.

Where:

Parameters

  • inputClumps – input clumps file.

  • inClassCol – The column specifiying the classes, one of which change will be found.

  • classOfInterest – The class (as defined in inClassCol) on which changed is being found.

  • changeVarCol – Variable(s) to be used to find change. Expecting column name. Needs to be numeric. If a list of column names is provided then they are combined using PCA and the first PC is used for the change process.

  • outChangeFeatCol – the output column. Regions lower than lower threshold have value 1. Regions higher than upper threshold have value 2. No change had threshold 0.

  • noDataVals – list of no data values to be ignored.

  • thresMeasure – needs to be of type RSGISRATThresMeasure (default is auto)

  • exportPlot – file name for exporting a histogram plot with thresholds annotated. No plot is create if None is passed (default is none).

  • showAllThreshPlot – option when plotting to put all the thresholds on to the plot rather than just the one being used.

Returns

list of lower [0] and upper [1] thresholds used to define the no change region.

rsgislib.rastergis.ratutils.findChangeClumpsHistSkewKurtTestLower(inputClumps, inClassCol, classOfInterest, changeVarCol, outChangeFeatCol, noDataVals=[], thresMeasure=<RSGISRATThresMeasure.auto: 4>, exportPlot=None, showAllThreshPlot=False)

This function identifies potential change features from just the lower (left) side of the histogram by slicing the histogram and finding an optimal skewness and kurtosis.

Where:

Parameters

  • inputClumps – input clumps file.

  • inClassCol – The column specifiying the classes, one of which change will be found.

  • classOfInterest – The class (as defined in inClassCol) on which changed is being found.

  • changeVarCol – changeVarCol - Variable(s) to be used to find change. Expecting column name. Needs to be numeric. If a list of column names is provided then they are combined using PCA and the first PC is used for the change process.

  • outChangeFeatCol – the output column. Regions lower than lower threshold have value 1. Regions higher than upper threshold have value 2. No change had threshold 0.

  • noDataVals – list of no data values to be ignored.

  • thresMeasure – needs to be of type RSGISRATThresMeasure (default is auto)

  • exportPlot – file name for exporting a histogram plot with thresholds annotated. No plot is create if None is passed (default is none).

  • showAllThreshPlot – option when plotting to put all the thresholds on to the plot rather than just the one being used.

Returns

list of lower [0] and upper [1] thresholds used to define the no change region.

rsgislib.rastergis.ratutils.findChangeClumpsHistSkewKurtTestUpper(inputClumps, inClassCol, classOfInterest, changeVarCol, outChangeFeatCol, noDataVals=[], thresMeasure=<RSGISRATThresMeasure.auto: 4>, exportPlot=None, showAllThreshPlot=False)

This function identifies potential change features from just the upper (right) side of the histogram by slicing the histogram and finding an optimal skewness and kurtosis.

Where:

Parameters

  • inputClumps – input clumps file.

  • inClassCol – The column specifiying the classes, one of which change will be found.

  • classOfInterest – The class (as defined in inClassCol) on which changed is being found.

  • changeVarCol – changeVarCol - Variable(s) to be used to find change. Expecting column name. Needs to be numeric. If a list of column names is provided then they are combined using PCA and the first PC is used for the change process.

  • outChangeFeatCol – the output column. Regions lower than lower threshold have value 1. Regions higher than upper threshold have value 2. No change had threshold 0.

  • noDataVals – list of no data values to be ignored.

  • thresMeasure – needs to be of type RSGISRATThresMeasure (default is auto)

  • exportPlot – file name for exporting a histogram plot with thresholds annotated. No plot is create if None is passed (default is none).

  • showAllThreshPlot – option when plotting to put all the thresholds on to the plot rather than just the one being used.

Returns

list of lower [0] and upper [1] thresholds used to define the no change region.

rsgislib.rastergis.ratutils.findChangeClumpsHistSkewKurtTestVoteMultiVars(inputClumps, inClassCol, classOfInterest, outChangeFeatCol, vars=[])

A function to call one of the findChangeClumpsHistSkewKurtTest functions for multiple variables and then combine together by voting to find change features.

Where:

Parameters

  • inputClumps – input clumps file.

  • inClassCol – The column specifiying the classes, one of which change will be found.

  • classOfInterest – The class (as defined in inClassCol) on which changed is being found.

  • outChangeFeatCol – the output column with the vote scores.

  • vars – a list of RSGISRATChangeVarInfo objects used to specify the variables and function to be called.

rsgislib.rastergis.ratutils.findClumpsWithinExistingThresholds(inputClumps, inClassCol, classOfInterest, outFeatsCol, vars=[])

A function to use the thresholds stored in the RSGISRATChangeVarInfo objects (var) and populated from the findChangeClumpsHistSkewKurtTest functions to assess another class creating a binary column as to whether a feature is within the threshold or now. Where multiple variables (i.e., len(var) > 1) then variables are combined with an and operation.

Where:

Parameters

  • inputClumps – input clumps file.

  • inClassCol – The column specifiying the classes, one of which change will be found.

  • classOfInterest – The class (as defined in inClassCol) on which changed is being found.

  • outFeatsCol – the output binary column specifying whether a feature is within the thresholds.

  • vars – a list of RSGISRATChangeVarInfo objects used to specify the variables and function to be called.

Statistics

rsgislib.rastergis.fitHistGausianMixtureModel(clumps=string, outH5File=string, outHistFile=string, varCol=string, binWidth=float, classColumn=string, classVal=string, ratband=int)

This function fits a Gaussian mixture model to the histogram for a variable in the RAT.

Where:

Parameters

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

  • outH5File – is a string for a HDF5 with the fitted Gaussians.

  • outHistFile – is a string to output the Histrogram as a HDF5 file.

  • varCol – is a string containing the name of the field with the values used for the sampling.

  • binWidth – is a float specifying the width of each histogram bin.

  • classColumn – is a string specifying a field within which classes have been defined.

  • classVal – is a string specifying the class it will be limited to.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis

rastergis.fitHistGausianMixtureModel(clumps='FrenchGuiana_10_ALL_sl_HH_lee_UTM_mosaic_dB_segs.kea', outH5File='gaufit.h5', outHistFile='histfile.h5', varCol='HVdB', binWidth=0.1, classColumn='Classes', classVal='Mangrove')
rsgislib.rastergis.ratutils.calcPlotGaussianHistoModel(clumpsFile, outGausH5File, outHistH5File, outPlotFile, varCol, binWidth, classColumn, classVal, plotTitle)
Extracts a column from the RAT, masking by a class calculating the histogram and

fitting a Gaussian mixture model to the histogram. Outputs include a plot and HDF5 files of the histogram and gaussian parameters.

Where:

Parameters

  • clumpsFile – input clumps file with populated RAT.

  • outGausH5File – the output HDF5 file for the Gaussian Mixture Model

  • outHistH5File – the output HDF5 file for the histogram.

  • outPlotFile – the output PDF file for the plot

  • varCol – Column within the RAT for the variable to be used for the histogram

  • binWidth – Bin width for the histogram

  • classColumn – Column where the classes are specified

  • classVal – Class used to mask the input variable

  • plotTitle – title for the plot

Example:

from rsgislib.rastergis import ratutils

clumpsFile = "FrenchGuiana_10_ALL_sl_HH_lee_UTM_mosaic_dB_segs.kea"
outGausH5File = "gaufit.h5"
outHistH5File = "histfile.h5"
outPlotFile = "Plot.pdf"
varCol = "HVdB"
binWidth = 0.1
classColumn = "Classes"
classVal = "Mangrove"
plotTitle = "HV dB Backscater from Mangroves; French Guiana"

ratutils.calcPlotGaussianHistoModel(clumpsFile, outGausH5File, outHistH5File, outPlotFile, varCol, binWidth, classColumn, classVal, plotTitle)
rsgislib.rastergis.calc1DJMDistance(clumps=string, varcol=string, binwidth=float, classcol=string, class1=string, class2=string, ratband=uint)

Calculate the Jeffries and Matusita distance for a single variable between two classes.

Where:

Parameters

  • clumps – is a string containing the name of the input clump file

  • varcol – is a string specifying the name of the variable column.

  • binwidth – is a float specifying the bin width for the histogram.

  • classcol – is a string specifying the column name with the class names.

  • class1 – is a string specifying the first class.

  • class2 – is a string specifying the second class.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the clumps image.

Returns

double for distance

rsgislib.rastergis.calc2DJMDistance(clumps=string, var1col=string, var2col=string, var1binWidth=float, var2binWidth=float, classcol=string, class1=string, class2=string, ratband=uint)

Calculate the Jeffries and Matusita distance for two variables between two classes.

Where:

Parameters

  • clumps – is a string containing the name of the input clump file

  • var1col – is a string specifying the name of the first variable column.

  • var2col – is a string specifying the name of the second variable column.

  • var1binwidth – is a float specifying the bin width for the histogram for variable 1.

  • var2binwidth – is a float specifying the bin width for the histogram for variable 2.

  • classcol – is a string specifying the column name with the class names.

  • class1 – is a string specifying the first class.

  • class2 – is a string specifying the second class.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the clumps image.

Returns

double for distance

rsgislib.rastergis.calcBhattacharyyaDistance(clumps=string, varcol=string, classcol=string, class1=string, class2=string, ratband=uint)

Calculate the Bhattacharyya distance for a single variable between two classes.

Where:

Parameters

  • clumps – is a string containing the name of the input clump file

  • varcol – is a string specifying the name of the variable column.

  • classcol – is a string specifying the column name with the class names.

  • class1 – is a string specifying the first class.

  • class2 – is a string specifying the second class.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated in the clumps image.

Returns

double for distance

Copy & Export

rsgislib.rastergis.export2Ascii(clumps, outfile, fields, ratband=1)

Exports selected columns from a GDAL RAT to ASCII file (comma separated). The first column is the object ID (FID).

Where:

Parameters

  • clumps – is a string containing the name of the input RAT.

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

  • fields – is a sequence of strings containing the field names.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
clumps='./RATS/injune_p142_casi_sub_utm_clumps_elim_final_clumps_elim_final.kea'
outfile='./TestOutputs/RasterGIS/injune_p142_casi_rgb_exportascii.txt'
fields = ['BlueAvg', 'GreenAvg', 'RedAvg']
rastergis.export2Ascii(clumps, outfile, fields)
rsgislib.rastergis.exportCol2GDALImage(clumps, outimage, gdalformat, datatype, field, ratband=1)

Exports column of the raster attribute table as bands in a GDAL image.

Where:

Parameters

  • clumps – is a string containing the name of the input image file with RAT

  • outimage – is a string containing the name of the output gdal file

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

  • field – is a string, providing the name of the column to be exported.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

clumps='./RATS/injune_p142_casi_sub_utm_clumps_elim_final_clumps_elim_final.kea'
outimage='./TestOutputs/RasterGIS/injune_p142_casi_rgb_export.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
field = 'RedAvg'
rastergis.exportCol2GDALImage(clumps, outimage, gdalformat, datatype, field)
rsgislib.rastergis.exportCols2GDALImage(clumps, outimage, gdalformat, datatype, fields, ratband=1, tempDIR=None)

Exports columns of the raster attribute table as bands in a GDAL image. Utility function, exports each column individually then stacks them.

Where:

Parameters

  • clumps – is a string containing the name of the input image file with RAT

  • outimage – is a string containing the name of the output gdal file

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

  • field – is a list of strings, providing the names of the column to be exported.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

clumps='./RATS/injune_p142_casi_sub_utm_clumps_elim_final_clumps_elim_final.kea'
outimage='./TestOutputs/RasterGIS/injune_p142_casi_rgb_export.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32FLOAT
fields = ['RedAvg','GreenAvg','BlueAvg']
rastergis.exportCols2GDALImage(clumps, outimage, gdalformat, datatype, fields)
rsgislib.rastergis.exportClumps2Images(clumps, outimgbase, binout, outimgext, gdalformat, ratband=1)

Exports each clump to a seperate raster which is the minimum extent for the clump.

Where:

Parameters

  • clumps – is a string containing the name of the input image file with RAT

  • outimgbase – is a string containing the base name of the output image file (C + FID will be added to identify files).

  • outimgext – is a sting with the output file extension (e.g., kea) without the preceeding dot to be appended to the file name.

  • binout – is a boolean specifying whether the output images should be binary or if the pixel value should be the FID of the clump.

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

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

import rsgislib
from rsgislib import rastergis
clumps='./DefineTiles.kea'
outimgbase='./Tiles/OutputImgTile_'
outimgext='kea'
gdalformat = 'KEA'
binaryOut = False
rastergis.exportClumps2Images(clumps, outimgbase, binaryOut, outimgext, gdalformat, ratband)
rsgislib.rastergis.copyGDALATTColumns(clumps, outimage, fields, copycolours=True, copyhist=True, ratband=1)

Copies GDAL RAT columns from one image to another

Where:

Parameters

  • clumps – is a string containing the name and path for the image with RAT from which columns are to copied from.

  • outimage – is a string containing the name of the file to which the columns are to be copied.

  • fields – is a sequence of strings containing the names of the fields to copy

  • copycolours – is a bool specifying if the colour columns should be copied (default = True)

  • copyhist – is a bool specifying if the histogram should be copied (default = True)

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
table = './RATS/injune_p142_casi_sub_utm_clumps_elim_final_clumps_elim_final.kea'
image = './TestOutputs/RasterGIS/injune_p142_casi_sub_utm_segs_cpcols.kea'
fields = ['NIRAvg', 'BlueAvg', 'GreenAvg', 'RedAvg']
rastergis.copyGDALATTColumns(image, table, fields)

To copy a subset of columns from one RAT to a new file the following can be used:

import rsgislib
import rsgislib.imageutils
from rsgislib import rastergis
ratband=1
table='inRAT.kea'
output='outRAT_nir_only.kea'
bands = [ratband]
rsgislib.imageutils.selectImageBands(table, output,'KEA', rsgislib.TYPE_32INT, bands)
fields = ['NIRAvg']
rastergis.copyGDALATTColumns(table, output, fields, copycolours=True, copyhist=True, ratband=ratband)
rsgislib.rastergis.copyRAT(clumps, outimage, ratband=1)

Copies a GDAL RAT from one image to another

Where:

Parameters

  • clumps – is a string containing the name and path for the image with RAT from which columns are to copied from.

  • outimage – is a string containing the name of the file to which the columns are to be copied.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
clumps = './RATS/injune_p142_casi_sub_utm_clumps_elim_final_clumps_elim_final.kea'
outimage = './TestOutputs/RasterGIS/injune_p142_casi_sub_utm_segs_cptab.kea'
rastergis.copyRAT(clumps, outimage)
rsgislib.rastergis.interpolateClumpValues2Image(clumpsImage, selectField, eastingsField, northingsField, methodStr, valueField, outputFile, gdalformat, gdaltype, ratBand)

Interpolates values from clumps to the whole image of pixels.

Where:

Parameters

  • clumpsImage – is a string containing the name of the input clump file

  • selectField – is a string which defines the column name where a value of 1 defines the clumps which will be included in the analysis.

  • eastingsField – is a string which defines a column with a eastings for each clump.

  • northingsField – is a string which defines a column with a northings for each clump.

  • methodStr – is a string which defines a column with a value for each clump which will be used for the distance, nearestneighbour or naturalneighbour or naturalnearestneighbour or knearestneighbour or idwall anaylsis.

  • valueField – is a string which defines a column containing the values to be interpolated creating the new image.

  • outputFile – is a string for the path to the output image file.

  • gdalformat – is string defining the GDAL format of the output image.

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

  • ratBand – is the image band with which the RAT is associated.

rsgislib.rastergis.importVecAtts(clumps, vector, veclyr, fidcol, colnames, ratband=1)

Copies the attributes from an input shapefile to the RAT.

Where:

Parameters

  • clumps – is a string containing the name of the input file with RAT

  • vector – is a string containing the file path of the input vector file

  • veclyr – is a string containing the layer name within the input vector file

  • fidcol – is a string with the name of a column which has the clumps pixel value associated with the vector feature.

  • colnames – is a list of strings specifying the columns to be copied to the RAT. If ‘None’ then all attributes will be copied.

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

from rsgislib import rastergis
clumps = 'clumpsFiles.kea'
vectorFile = 'vectorFile.shp'
veclyr = 'vectorFile'
rastergis.importVecAtts(clumps, vectorFile, veclyr, 'pxlval', None)

Colour Tables

rsgislib.rastergis.colourClasses(clumps, field, classcolours, ratband)

Sets a colour table for a set of classes within the attribute table

Where:

Parameters

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

  • field – is a string containing the name of the input class field (class can be a string or integer).

  • classcolours – is dict mapping int class ids to an object having the following attributes: * red: int defining the red colour component (0 - 255) * green: int defining the green colour component (0 - 255) * blue: int defining the bluecolour component (0 - 255) * alpha: int defining the alpha colour component (0 - 255)

  • ratband – is an optional (default = 1) integer parameter specifying the image band to which the RAT is associated.

Example:

import collections
from rsgislib import rastergis
clumps='./TestOutputs/RasterGIS/injune_p142_casi_sub_utm_segs_col.kea'
field = 'outClass'
classcolours = {}
colourCat = collections.namedtuple('ColourCat', ['red', 'green', 'blue', 'alpha'])
classcolours[0] = colourCat(red=200, green=50, blue=50, alpha=255)
classcolours[1] = colourCat(red=200, green=240, blue=50, alpha=255)
rastergis.colourClasses(clumps, field, classcolours)
rsgislib.rastergis.ratutils.setClassNamesColours(clumpsImg, classNamesCol, classInfoDict)

A function to define a class names column and define the class colours.

classInfoDict = dict() classInfoDict[1] = {‘classname’:’Forest’, ‘red’:0, ‘green’:255, ‘blue’:0} classInfoDict[2] = {‘classname’:’Water’, ‘red’:0, ‘green’:0, ‘blue’:255}

Parameters

  • clumpsImg – Input clumps image - expecting a classification (rather than segmentation) where the number is the pixel value.

  • classNamesCol – The output column for the class names.

  • classInfoDict – a dict where the key is the pixel value for the class.

Data Structures / Enums

rsgislib.rastergis.BandAttStats(band, minField=None, maxField=None, sumField=None, stdDevField=None, meanField=None)

This is passed to the populateRATWithStats function

rsgislib.rastergis.FieldAttStats(field, minField=None, maxField=None, sumField=None, stdDevField=None, meanField=None)

This is passed to the calcRelDiffNeighStats function

rsgislib.rastergis.BandAttPercentiles(percentile, fieldName)

This is passed to the populateRATWithPercentiles function

rsgislib.rastergis.ShapeIndex(colName, idx, colIdx=0)

This is passed to the calcShapeIndices function

rsgislib.rastergis.ratutils.RSGISRATChangeVarInfo(changeVarCol='', outChangeFeatCol='', noDataVals=[], thresMeasure=<RSGISRATThresMeasure.auto: 4>, thresDirection=<RSGISRATThresDirection.lower: 1>, exportPlot=None, showAllThreshPlot=False, lowerThreshold=0.0, upperThreshold=0.0)

A class to store the change variable information required for some of the change functions.

rsgislib.rastergis.ratutils.RSGISRATThresMeasure(value, names=None, *, module=None, qualname=None, type=None, start=1)

An enumeration.

rsgislib.rastergis.ratutils.RSGISRATThresDirection(value, names=None, *, module=None, qualname=None, type=None, start=1)

An enumeration.