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.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:

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

Utilities

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

Populates statics for thematic images.

Where:

  • 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:

  • 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:

  • 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:

  • 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.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.

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

Attribute Segments

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

Calculate the border length of clumps

Where:

  • inputImage is a string containing the name of the input image file
  • ignoreZeroEdges is a bool
  • outColsName is a string
rsgislib.rastergis.calcRelBorder(inputImage, outColsName, classNameField, className, ignoreZeroEdges)

Calculates the relative border length of the clumps to a class

Where:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

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

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:

  • 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.* 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')

Classification

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

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

Where:

  • 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:

  • 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:

  • 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.

  • 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:

  • 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 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:

  • 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.* 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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.

Return:

  • 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:

  • 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.

Return:

  • 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:

  • 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.

Return:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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.

Return:

  • 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:

  • 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.

Return:

  • 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:

  • 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.

Return:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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, colnames, ratband=1)

Copies the attributes from an input shapefile to the RAT.

Where:

  • 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
  • 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'
rastergis.importVecAtts(clumps, vectorFile, None)

Colour Tables

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

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

Where:

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

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.