RSGISLib Module

This namespace contains rsgislib Python bindings

Please be aware that the following variables have been defined to match enums within RSGISLib.

Data Types for images:

  • TYPE_UNDEFINED = 0

  • TYPE_8INT = 1

  • TYPE_16INT = 2

  • TYPE_32INT = 3

  • TYPE_64INT = 4

  • TYPE_8UINT = 5

  • TYPE_16UINT = 6

  • TYPE_32UINT = 7

  • TYPE_64UINT = 8

  • TYPE_32FLOAT = 9

  • TYPE_64FLOAT = 10

Methods for the Maximum Likelihood Classifier:

  • METHOD_SAMPLES = 0 # as calculated by ML

  • METHOD_AREA = 1 # priors set by the relative area

  • METHOD_EQUAL = 2 # priors all equal

  • METHOD_USERDEFINED = 3 # priors passed in to function

  • METHOD_WEIGHTED = 4 # priors by area but with a weight applied

Shape indexes used with RasterGIS:

  • SHAPE_SHAPENA = 0

  • SHAPE_SHAPEAREA = 1

  • SHAPE_ASYMMETRY = 2

  • SHAPE_BORDERINDEX = 3

  • SHAPE_BORDERLENGTH = 4

  • SHAPE_COMPACTNESS = 5

  • SHAPE_DENSITY = 6

  • SHAPE_ELLIPTICFIT = 7

  • SHAPE_LENGTH = 8

  • SHAPE_LENGTHWIDTH = 9

  • SHAPE_WIDTH = 10

  • SHAPE_MAINDIRECTION = 11

  • SHAPE_RADIUSLARGESTENCLOSEDELLIPSE = 12

  • SHAPE_RADIUSSMALLESTENCLOSEDELLIPSE = 13

  • SHAPE_RECTANGULARFIT = 14

  • SHAPE_ROUNDNESS = 15

  • SHAPE_SHAPEINDEX = 16

Methods of initialising KMEANS:

  • INITCLUSTER_RANDOM = 0

  • INITCLUSTER_DIAGONAL_FULL = 1

  • INITCLUSTER_DIAGONAL_STDDEV = 2

  • INITCLUSTER_DIAGONAL_FULL_ATTACH = 3

  • INITCLUSTER_DIAGONAL_STDDEV_ATTACH = 4

  • INITCLUSTER_KPP = 5

Methods of calculating distance:

  • DIST_UNDEFINED = 0

  • DIST_EUCLIDEAN = 1

  • DIST_MAHALANOBIS = 2

  • DIST_MANHATTEN = 3

  • DIST_MINKOWSKI = 4

  • DIST_CHEBYSHEV = 5

  • DIST_MUTUALINFO = 6

Methods of summerising data:

  • SUMTYPE_UNDEFINED = 0

  • SUMTYPE_MODE = 1

  • SUMTYPE_MEAN = 2

  • SUMTYPE_MEDIAN = 3

  • SUMTYPE_MIN = 4

  • SUMTYPE_MAX = 5

  • SUMTYPE_STDDEV = 6

  • SUMTYPE_COUNT = 7

  • SUMTYPE_RANGE = 8

  • SUMTYPE_SUM = 9

Constants specifying how bands should be treated when sharpening (see rsgislib.imageutils)

  • SHARP_RES_IGNORE = 0

  • SHARP_RES_LOW = 1

  • SHARP_RES_HIGH = 2

exception rsgislib.RSGISPyException(value)

A class representing the RSGIS exception.

Init for the RSGISPyException class

class rsgislib.RSGISPyUtils

A class with useful utilities within RSGISLib.

bbox_intersection(bbox1, bbox2)

A function which calculates the intersection of the two bboxes (xMin, xMax, yMin, yMax).

Parameters

  • bbox1 – is a bbox (xMin, xMax, yMin, yMax)

  • bbox2 – is a bbox (xMin, xMax, yMin, yMax)

Returns

bbox (xMin, xMax, yMin, yMax)

buffer_bbox(bbox, buf)

Buffer the input BBOX by a set amount.

Parameters

  • bbox – the bounding box (MinX, MaxX, MinY, MaxY)

  • buf – the amount of buffer by

Returns

the buffered bbox (MinX, MaxX, MinY, MaxY)

createVarList(in_vals_lsts, val_dict=None)

A function which will produce a list of dictionaries with all the combinations of the input variables listed (i.e., the powerset).

Parameters

  • in_vals_lsts – dictionary with each value having a list of values.

  • val_dict – variable used in iterative nature of function which lists the variable for which are still to be looped through. Would normally not be provided by the user as default is None. Be careful if you set as otherwise.

Returns

list of dictionaries with the same keys are the input but only a single value will be associate with key rather than a list.

Example:

seg_vars_ranges = dict()
seg_vars_ranges['k'] = [5, 10, 20, 30, 40, 50, 60, 80, 100, 120]
seg_vars_ranges['d'] = [10, 20, 50, 100, 200, 1000, 10000]
seg_vars_ranges['minsize'] = [5, 10, 20, 50, 100, 200]
seg_vars = rsgis_utils.createVarList(seg_vars_ranges)
deleteDIR(dirPath)

A function which will delete a directory, if files and other directories are within the path specified they will be recursively deleted as well. So be careful you don’t delete things within meaning it.

deleteFileWithBasename(filePath)

Function to delete all the files which have a path and base name defined in the filePath attribute.

doGDALLayersHaveSameProj(layer1, layer2)

A function which tests whether two gdal compatiable layers are in the same projection/coordinate system. This is done using the GDAL SpatialReference function AutoIdentifyEPSG. If the identified EPSG codes are different then False is returned otherwise True.

Returns

boolean

doImageResMatch(img1, img2)

A function to test whether two images have the same image pixel resolution.

Returns

boolean

do_bboxes_intersect(bbox1, bbox2)

A function which tests whether two bboxes (MinX, MaxX, MinY, MaxY) intersect.

Parameters

  • bbox1 – The first bounding box (MinX, MaxX, MinY, MaxY)

  • bbox2 – The first bounding box (MinX, MaxX, MinY, MaxY)

Returns

boolean (True they intersect; False they do not intersect)

findCommonExtentOnGrid(baseExtent, baseGrid, otherExtent, fullContain=True)

A function which calculates the common extent between two extents but defines output on grid with defined resolutions. Useful for finding common extent on a particular image grid.

Parameters

  • baseExtent – is a bbox (xMin, xMax, yMin, yMax) providing the base for the grid on which output will be defined.

  • baseGrid – the size of the (square) grid on which output will be defined.

  • otherExtent – is a bbox (xMin, xMax, yMin, yMax) to be intersected with the baseExtent.

  • fullContain – is a boolean. True: moving output onto grid will increase size of bbox (i.e., intersection fully contained) False: move output onto grid will decrease size of bbox (i.e., bbox fully contained within intesection)

Returns

bbox (xMin, xMax, yMin, yMax)

findExtentOnGrid(baseExtent, baseGrid, fullContain=True)

A function which calculates the extent but defined on a grid with defined resolution. Useful for finding extent on a particular image grid.

Parameters

  • baseExtent – is a bbox (xMin, xMax, yMin, yMax) providing the base for the grid on which output will be defined.

  • baseGrid – the size of the (square) grid on which output will be defined.

  • fullContain – is a boolean. True: moving output onto grid will increase size of bbox (i.e., intersection fully contained) False: move output onto grid will decrease size of bbox (i.e., bbox fully contained within intesection)

Returns

bbox (xMin, xMax, yMin, yMax)

findExtentOnWholeNumGrid(baseExtent, baseGrid, fullContain=True, round_vals=None)

A function which calculates the extent but defined on a grid with defined resolution. Useful for finding extent on a particular image grid.

Parameters

  • baseExtent – is a bbox (xMin, xMax, yMin, yMax) providing the base for the grid on which output will be defined.

  • baseGrid – the size of the (square) grid on which output will be defined.

  • fullContain – is a boolean. True: moving output onto grid will increase size of bbox (i.e., intersection fully contained) False: move output onto grid will decrease size of bbox (i.e., bbox fully contained within intesection)

  • round_vals – specify whether outputted values should be rounded. None for no rounding (default) or integer for number of significant figures to round to.

Returns

bbox (xMin, xMax, yMin, yMax)

findFile(dirPath, fileSearch)

Search for a single file with a path using glob. Therefore, the file path returned is a true path. Within the fileSearch provide the file name with ‘*’ as wildcard(s).

Returns

string

findFileNone(dirPath, fileSearch)

Search for a single file with a path using glob. Therefore, the file path returned is a true path. Within the fileSearch provide the file name with ‘*’ as wildcard(s). Returns None is not found.

Returns

string

getBBoxGrid(bbox, x_size, y_size)

Create a grid with size x_size, y_size for the area represented by bbox.

Parameters

  • bbox – a bounding box within which the grid will be created (xMin, xMax, yMin, yMax)

  • x_size – Output grid size in X axis (same unit as bbox).

  • y_size – Output grid size in Y axis (same unit as bbox).

Returns

list of bounding boxes (xMin, xMax, yMin, yMax)

getEPSGCode(gdalLayer)

Using GDAL to return the EPSG code for the input layer.

Returns

EPSG code

getEPSGCodeFromWKT(wktString)

Using GDAL to return the EPSG code for inputted WKT string.

Returns

the EPSG code.

getEnvironmentVariable(var)

A function to get an environmental variable, if variable is not present returns None.

Returns

value of env var.

getFileExtension(gdalformat)

A function to get the extension for a given file format (NOTE, currently only KEA, GTIFF, HFA, PCI and ENVI are supported).

Returns

string

getGDALDataType(rsgislib_datatype)

Convert from RSGIS data type to GDAL data type int.

Returns

int

getGDALDataTypeFromImg(inImg)

Returns the GDAL datatype ENUM (e.g., GDT_Float32) for the inputted raster file.

Returns

ints

getGDALDataTypeNameFromImg(inImg)

Returns the GDAL datatype ENUM (e.g., GDT_Float32) for the inputted raster file.

Returns

int

getGDALFormatFromExt(fileName)

Get GDAL format, based on filename

Returns

string

getImageBBOX(inImg)

A function to retrieve the bounding box in the spatial coordinates of the image.

Returns

(MinX, MaxX, MinY, MaxY)

getImageBBOXInProj(inImg, outEPSG)

A function to retrieve the bounding box in the spatial coordinates of the image.

Returns

(MinX, MaxX, MinY, MaxY)

getImageBandCount(inImg)

A function to retrieve the number of image bands in an image file.

Returns

nBands

getImageBandStats(img, band, compute=True)

A function which calls the GDAL function on the band selected to calculate the pixel stats (min, max, mean, standard deviation).

Parameters

  • img – input image file path

  • band – specified image band for which stats are to be calculated (starts at 1).

  • compute – whether the stats should be calculated (True; Default) or an approximation or pre-calculated stats are OK (False).

Returns

stats (min, max, mean, stddev)

getImageFiles(inImg)

A function which returns a list of the files associated (e.g., header etc.) with the input image file.

Returns

lists

getImageNoDataValue(inImg, band=1)

A function to retrieve the no data value for the image (from band; default 1).

Returns

number

getImageRes(inImg)

A function to retrieve the image resolution.

Returns

xRes, yRes

getImageSize(inImg)

A function to retrieve the image size in pixels.

Returns

xSize, ySize

getImgBandColourInterp(inImg, band)

A function to get the colour interpretation for a specific band.

Returns

is a GDALColorInterp value:

  • GCI_Undefined=0,

  • GCI_GrayIndex=1,

  • GCI_PaletteIndex=2,

  • GCI_RedBand=3,

  • GCI_GreenBand=4,

  • GCI_BlueBand=5,

  • GCI_AlphaBand=6,

  • GCI_HueBand=7,

  • GCI_SaturationBand=8,

  • GCI_LightnessBand=9,

  • GCI_CyanBand=10,

  • GCI_MagentaBand=11,

  • GCI_YellowBand=12,

  • GCI_BlackBand=13,

  • GCI_YCbCr_YBand=14,

  • GCI_YCbCr_CbBand=15,

  • GCI_YCbCr_CrBand=16,

  • GCI_Max=16

getNumpyDataType(rsgislib_datatype)

Convert from RSGISLib data type to numpy datatype

Parameters

rsgis_datatype –

Returns

numpy datatype

getProjEPSGFromVec(inVec, vecLyr=None)

A function which gets the EPSG projection from the inputted vector file.

Parameters

  • inVec – is a string with the input vector file name and path.

  • vecLyr – is a string with the input vector layer name, if None then first layer read. (default: None)

Returns

EPSG representation of projection

getProjWKTFromVec(inVec, vecLyr=None)

A function which gets the WKT projection from the inputted vector file.

Parameters

  • inVec – is a string with the input vector file name and path.

  • vecLyr – is a string with the input vector layer name, if None then first layer read. (default: None)

Returns

WKT representation of projection

getRSGISLibDataType(gdaltype)

Convert from GDAL data type string to RSGISLib data type int.

Returns

int

getRSGISLibDataTypeFromImg(inImg)

Returns the rsgislib datatype ENUM (e.g., rsgislib.TYPE_8INT) for the inputted raster file

Returns

int

getUTMZone(inImg)

A function which returns a string with the UTM (XXN | XXS) zone of the input image but only if it is projected within the UTM projection/coordinate system.

Returns

string

getVecFeatCount(inVec, layerName=None, computeCount=True)

Get a count of the number of features in the vector layers.

Parameters

  • inVec – is a string with the input vector file name and path.

  • layerName – is the layer for which extent is to be calculated (Default: None) if None assume there is only one layer and that will be read.

  • computeCount – is a boolean which specifies whether the layer extent should be calculated (rather than estimated from header) even if that operation is computationally expensive.

Returns

nfeats

getVecLayerExtent(inVec, layerName=None, computeIfExp=True)

Get the extent of the vector layer.

Parameters

  • inVec – is a string with the input vector file name and path.

  • layerName – is the layer for which extent is to be calculated (Default: None) if None assume there is only one layer and that will be read.

  • computeIfExp – is a boolean which specifies whether the layer extent should be calculated (rather than estimated from header) even if that operation is computationally expensive.

Returns

boundary box is returned (MinX, MaxX, MinY, MaxY)

getWKTFromEPSGCode(epsgCode)

Using GDAL to return the WKT string for inputted EPSG Code.

Parameters

epsgCode – integer variable of the epsg code.

Returns

string with WKT representation of the projection.

getWKTProjFromImage(inImg)

A function which returns the WKT string representing the projection of the input image.

Returns

string

get_dir_name(in_file)

A function which returns just the name of the directory of the input file without the rest of the path.

Parameters

in_file – string for the input file name and path

Returns

directory name

get_file_basename(filepath, checkvalid=False, n_comps=0)

Uses os.path module to return file basename (i.e., path and extension removed)

Parameters

  • filepath – string for the input file name and path

  • checkvalid – if True then resulting basename will be checked for punctuation characters (other than underscores) and spaces, punctuation will be either removed and spaces changed to an underscore. (Default = False)

  • n_comps – if > 0 then the resulting basename will be split using underscores and the return based name will be defined using the n_comps components split by under scores.

Returns

basename for file

in_bounds(x, lower, upper, upper_strict=False)

Checks whether a value is within specified bounds.

Parameters

  • x – value or array of values to check.

  • lower – lower bound

  • upper – upper bound

  • upper_strict – True is less than upper; False is less than equal to upper

Returns

boolean

isNumber(strVal)

A function which tests whether the input string contains a number of not.

Returns

boolean

mixed_signs(x)

Check whether a list of numbers has a mix of postive and negative values.

Parameters

x – list of values.

Returns

boolean

negative(x)

Is the maximum number in the list negative. :param x: list of values

Returns

boolean

numProcessCores()

A functions which returns the number of processing cores available on the machine

Returns

int

readTextFile2List(file)

Read a text file into a list where each line is an element in the list.

Parameters

file – File path to the input file.

Returns

list

readTextFileNoNewLines(file)

Read a text file into a single string removing new lines.

Parameters

file – File path to the input file.

Returns

string

renameGDALLayer(cFileName, oFileName)

Rename all the files associated with a GDAL layer.

Parameters

  • cFileName – The current name of the GDAL layer.

  • oFileName – The output name of the GDAL layer.

reprojBBOX(bbox, inProjObj, outProjObj)

A function to reproject a bounding box.

Parameters

  • bbox – input bounding box (MinX, MaxX, MinY, MaxY)

  • inProjObj – an osr.SpatialReference() object representing input projection.

  • outProjObj – an osr.SpatialReference() object representing output projection.

Returns

(MinX, MaxX, MinY, MaxY)

reprojBBOX_epsg(bbox, inEPSG, outEPSG)

A function to reproject a bounding box.

Parameters

  • bbox – input bounding box (MinX, MaxX, MinY, MaxY)

  • inEPSG – an EPSG code representing input projection.

  • outEPSG – an EPSG code representing output projection.

Returns

(MinX, MaxX, MinY, MaxY)

reprojPoint(inProjOSRObj, outProjOSRObj, x, y)

Reproject a point from ‘inProjOSRObj’ to ‘outProjOSRObj’ where they are gdal osgeo.osr.SpatialReference objects.

Returns

x, y. (note if returning long, lat you might need to invert)

setImageNoDataValue(inImg, noDataValue, band=None)

A function to set the no data value for an image. If band is not specified sets value for all bands.

setImgBandColourInterp(inImg, band, clrItrpVal)

A function to set the colour interpretation for a specific band. input is a GDALColorInterp value:

  • GCI_Undefined=0,

  • GCI_GrayIndex=1,

  • GCI_PaletteIndex=2,

  • GCI_RedBand=3,

  • GCI_GreenBand=4,

  • GCI_BlueBand=5,

  • GCI_AlphaBand=6,

  • GCI_HueBand=7,

  • GCI_SaturationBand=8,

  • GCI_LightnessBand=9,

  • GCI_CyanBand=10,

  • GCI_MagentaBand=11,

  • GCI_YellowBand=12,

  • GCI_BlackBand=13,

  • GCI_YCbCr_YBand=14,

  • GCI_YCbCr_CbBand=15,

  • GCI_YCbCr_CrBand=16,

  • GCI_Max=16

uidGenerator(size=6)

A function which will generate a ‘random’ string of the specified length based on the UUID

Parameters

size – the length of the returned string.

Returns

string of length size.

writeData2File(data_val, out_file)

Write some data (a string or can be converted to a string using str(data_val) to an output text file.

Parameters

  • data_val – Data to be written to the output file.

  • out_file – File path to the output file.

writeList2File(dataList, outFile)

Write a list a text file, one line per item.

Parameters

  • dataList – List of values to be written to the output file.

  • out_file – File path to the output file.

class rsgislib.RSGISTime

Class to calculate run time for a function, format and print out (similar to for XML interface).

Need to call start before running function and end immediately after. Example:

t = RSGISTime()
t.start()
rsgislib.segmentation.clump(kMeansFileZonesNoSgls, initClumpsFile, gdalformat, False, 0) 
t.end()

Note, this is only designed to provide some general feedback, for benchmarking the timeit module is better suited.

calcDiff(preceedStr='', postStr='')

Calculate time difference, format and print. :param preceedStr: A string which is printed ahead of time difference :param postStr: A string which is printed after the time difference

end(reportDiff=True, preceedStr='', postStr='')

End timer and optionally print difference. If preceedStr or postStr have a value then they will be used instead of the generic wording around the time.

preceedStr + time + postStr

Parameters

  • reportDiff – A boolean specifiying whether time difference should be printed to console.

  • preceedStr – A string which is printed ahead of time difference

  • postStr – A string which is printed after the time difference

start(printStartTime=False)

Start timer, optionally printing start time

Parameters

printStartTime – A boolean specifiying whether the start time should be printed to console.

class rsgislib.TQDMProgressBar

Uses TQDM TermProgress to print a progress bar to the terminal

displayError(text)
displayException(trace)
displayInfo(text)
displayWarning(text)
reset()
setLabelText(text)
setProgress(progress)
setTotalSteps(steps)
wasCancelled()
rsgislib.getRSGISLibVersion()

Calls rsgis-config to get the version number.