RSGISLib Vector Utils Module

The vector utils module performs geometry / attribute table operations on vectors.

Geometry

rsgislib.vectorutils.addFIDColumn(inputvector, outputvector, force)

A command to add an explicit FID column to a copy of a shapefile.

Where:

Parameters

  • inputvector – is a string containing the name of the input vector

  • outputvector – is a string containing the name of the output vector

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_psu_utm.shp'
outputVector = './TestOutputs/injune_p142_psu_utm_fid.shp'
vectorutils.addFIDColumn(inputVector, outputVector, True)
rsgislib.vectorutils.buffervector(inputvector, veclayername outputvector, outlayername, ogrdriver, bufferDist)

A command to buffer a vector by a specified distance.

Where:

Parameters

  • inputvector – is a string containing the name of the input vector

  • veclayername – is a string with the name of the vector layer name

  • outputvector – is a string containing the name of the output vector

  • outlayername – is a string containing the name of the output vector layer.:param ogrdriver: is a string with the gdal/ogr driver specified (e.g., GPKG)

  • bufferDist – is a float specifying the distance of the buffer, in map units.

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_stem_locations.gpkg'
lyrName = 'polygons'
outputVector = './TestOutputs/injune_p142_stem_locations_1mbuffer.gpkg'
bufferDist = 1
vectorutils.buffervector(inputVector, lyrName, outputVector, lyrName, 'GPKG', bufferDist)
rsgislib.vectorutils.generateConvexHullsGroups(inputfile, outputvector, outVecProj, force, eastingsColIdx, northingsColIdx, attributeColIdx)

A command to produce convex hulls for groups of (X, Y, Attribute) point locations.

Where:

Parameters

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

  • outputvector – is a string containing the name of the output vector

  • outVecProj – is a string specifying the projection of the output vector

  • force – is a bool, specifying whether to force removal of the output vector if it exists

  • eastingsColIdx – an integer specifying the easting column in the input text file

  • northingsColIdx – an integer specifying the northing column in the input text file

  • attributeColIdx – an integer specifying the attribute column in the input text file

rsgislib.vectorutils.createLinesOfPoints(inputVector, outputVector, step, force)

A function to create a regularly spaced set of points following a set of lines.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector (must be lines)

  • outputVector – is a string containing the name of the output vector (will be points)

  • step – is a double specifying the distance between points along the line.

  • force – is a bool, specifying whether to force removal of the output vector if it exists

rsgislib.vectorutils.fitPolygon2Points(inputVector, outputVector, alphaVal, force)

A command fit a polygon to the points inputted.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector (must be points)

  • outputVector – is a string containing the name of the output vector

  • alphaVal – is a double specifying the alpha value to use for the calculation (if negative optimal will be calculated; default)

  • force – is a bool, specifying whether to force removal of the output vector if it exists

rsgislib.vectorutils.fitPolygons2PointClusters(inputVector, outputVector, clusterField, alphaVal, force)

A command fit a polygon to the points inputted.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector (must be points)

  • outputVector – is a string containing the name of the output vector

  • clusterField – is a string specifying the column in the input shapefile which specifies the clusters

  • alphaVal – is a double specifying the alpha value to use for the calculation (if negative optimal will be calculated; default)

  • force – is a bool, specifying whether to force removal of the output vector if it exists

rsgislib.vectorutils.generateConvexHullsGroups(inputfile, outputvector, outVecProj, force, eastingsColIdx, northingsColIdx, attributeColIdx)

A command to produce convex hulls for groups of (X, Y, Attribute) point locations.

Where:

Parameters

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

  • outputvector – is a string containing the name of the output vector

  • outVecProj – is a string specifying the projection of the output vector

  • force – is a bool, specifying whether to force removal of the output vector if it exists

  • eastingsColIdx – an integer specifying the easting column in the input text file

  • northingsColIdx – an integer specifying the northing column in the input text file

  • attributeColIdx – an integer specifying the attribute column in the input text file

rsgislib.vectorutils.splitFeatures(inputvector, outputvectorbase, force)

A command to split features into seperate shapefiles.

Where:

Parameters

  • inputvector – is a string containing the name of the input vector

  • outputvectorbase – is a string containing the base path and name of the output vectors

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_psu_utm.shp'
outputVectorBase = './TestOutputs/injune_p142_psu_utm_'
vectorutils.splitFeatures(inputVector, outputVectorBase, True)
rsgislib.vectorutils.fitActiveContourBoundaries(inputVector, outputVector, exterForceImg, intAlphaVal, intBetaVal, intGammaVal, minExtThresVal, force)

A command fit a polygon to the points inputted.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector (must be polygons)

  • outputVector – is a string containing the name of the output vector

  • exterForceImg – is a string containing the name and path for the image file representing the external energy for the active contours

  • intAlphaVal – is a double specifying the alpha value for the active contour internal energy.

  • intBetaVal – is a double specifying the beta value for the active contour internal energy.

  • intGammaVal – is a double specifying the gamma value for the active contour internal energy.

  • minExtThresVal – is a double specifying a hard boundary for the external energy which can’t be crossed.

  • force – is a bool, specifying whether to force removal of the output vector if it exists

rsgislib.vectorutils.polygonsInPolygon(inputvector, inputcovervector, outputDIR, attributeName, force)

A command to create a new polygon containing only polygons within cover vector. Loops through attributes and creates a new shapefile for each polygon in the cover vector.

Where:

Parameters

  • inputvector – is a string containing the name of the input vector

  • inputcovervector – is a string containing the name of the cover vector vector

  • outputDIR – is a string containing the name of the output directory

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_stem_locations.shp'
coverVector = './Vectors/injune_p142_psu_utm.shp'
outDIR = '/TestOutputs'
attribute = 'PSU'
vectorutils.polygonsInPolygon(inputVector, coverVector, outDIR, attribute, True)
rsgislib.vectorutils.bboxIntersectsVecLyr(vectorFile, vectorLyr, bbox)

A function which tests whether a feature within an inputted vector layer intersects with a bounding box.

Parameters

  • vectorFile – vector file/path

  • vectorLyr – vector layer name

  • bbox – the bounding box (xMin, xMax, yMin, yMax). Same projection as vector layer.

Returns

boolean (True = Intersection)

rsgislib.vectorutils.calcPolyCentroids(vecfile, veclyrname, outVecDrvr, vecoutfile, vecoutlyrname)

Create a vector layer of the polygon centroids.

Parameters

  • vecfile – input vector file

  • veclyrname – input vector layer within the input file.

  • outVecDrvr – the format driver for the output vector file (e.g., GPKG, ESRI Shapefile).

  • vecoutfile – output file path for the vector.

  • vecoutlyrname – output vector layer name.

rsgislib.vectorutils.checkValidateGeometries(inputVector, veclayer, outputVector, outVecDriver, printGeomErrs)

A command fit a polygon to the points inputted.

Where:

Parameters

  • inputVector – is a string containing the name and path of the input vector.

  • veclayer – is a string specifying name of the vector layer to be processed.

  • outputVector – is a string containing the name and path of the output vector.

  • outVecDriver – is a string specifying the output vector GDAL/OGR driver (e.g., GPKG).

  • printGeomErrs – is a bool, specifying whether were errors are found they are printed to the console.

rsgislib.vectorutils.getFeatEnvs(vecFile, vecLyr)

A function which returns a list of bounding boxes for each feature within the vector layer.

Parameters

  • vecFile – vector file.

  • vecLyr – layer within the vector file.

Returns

list of BBOXs

Create Vectors

rsgislib.vectorutils.readVecLyr2Mem(vecfile, veclyrname)

A function which reads a vector layer to an OGR in memory layer.

Parameters

  • vecfile – input vector file

  • veclyrname – input vector layer within the input file.

Returns

ogr_dataset, ogr_layer

rsgislib.vectorutils.writeVecLyr2File(veclyr, vecfile, veclyrname, vecDriver, options=['OVERWRITE=YES'], replace=False)

A function which reads a vector layer to an OGR in memory layer.

Parameters

  • veclyr – OGR vector layer object

  • vecfile – output vector file

  • veclyrname – output vector layer within the input file.

  • vecDriver – the OGR driver for the output file.

  • options – provide a list of driver specific options; see https://www.gdal.org/ogr_formats.html

  • replace – if true the output file is replaced (i.e., overwritten to anything in an existing file will be lost).

rsgislib.vectorutils.polygoniseRaster(inputImg, outShp, imgBandNo=1, maskImg=None, imgMaskBandNo=1)

A utillity to polygonise a raster to a ESRI Shapefile.

Where:

Parameters

  • inputImg – is a string specifying the input image file to be polygonised

  • outShp – is a string specifying the output shapefile path. If it exists it will be deleted and overwritten.

  • imgBandNo – is an int specifying the image band to be polygonised. (default = 1)

  • maskImg – is an optional string mask file specifying a no data mask (default = None)

  • imgMaskBandNo – is an int specifying the image band to be used the mask (default = 1)

rsgislib.vectorutils.polygoniseRaster2VecLyr(outvec, outlyr, vecdrv, inputImg, imgBandNo=1, maskImg=None, imgMaskBandNo=1, replace_file=True, replace_lyr=True, pxl_val_fieldname='PXLVAL')

A utility to polygonise a raster to a OGR vector layer.

Where:

Parameters

  • outvec – is a string specifying the output vector file path. If it exists it will be deleted and overwritten.

  • outlyr – is a string with the name of the vector layer.

  • vecdrv – is a string with the driver

  • inputImg – is a string specifying the input image file to be polygonised

  • imgBandNo – is an int specifying the image band to be polygonised. (default = 1)

  • maskImg – is an optional string mask file specifying a no data mask (default = None)

  • imgMaskBandNo – is an int specifying the image band to be used the mask (default = 1)

  • replace_file – is a boolean specifying whether the vector file should be replaced (i.e., overwritten). Default=True.

  • replace_lyr – is a boolean specifying whether the vector layer should be replaced (i.e., overwritten). Default=True.

  • pxl_val_fieldname – is a string to specify the name of the output column representing the pixel value within the input image.

rsgislib.vectorutils.exportPxls2Pts(image, outvecfile, mskval, force, outveclyr, vecdriver)

A command to export image pixel which have a specific value to a vector file of points. Note. the output vector file will be overwritten even if the layer name is different.

Where:

Parameters

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

  • outvecfile – is a string containing the name and path of the output vector file

  • maskVal – is a float specifying the value of the image pixels to be exported

  • force – is a bool, specifying whether to force removal of the output vector if it exists (Only for ESRI Shapefile format)

  • outveclyr – is an optional layer name for the output vector file.

  • vecdriver – is the output vector format for the output vector file. (Optional, default: ESRI Shapefile)

rsgislib.vectorutils.createPolySHP4LstBBOXs(csvFile, outSHP, epsgCode, minXCol=0, maxXCol=1, minYCol=2, maxYCol=3, ignoreRows=0, force=False)

This function takes a CSV file of bounding boxes (1 per line) and creates a polygon shapefile.

Parameters

  • csvFile – input CSV file.

  • outSHP – output ESRI shapefile

  • epsgCode – EPSG code specifying the projection of the data (4326 is WSG84 Lat/Long).

  • minXCol – The index (starting at 0) for the column within the CSV file for the minimum X coordinate.

  • maxXCol – The index (starting at 0) for the column within the CSV file for the maximum X coordinate.

  • minYCol – The index (starting at 0) for the column within the CSV file for the minimum Y coordinate.

  • maxYCol – The index (starting at 0) for the column within the CSV file for the maximum Y coordinate.

  • ignoreRows – The number of rows to ignore from the start of the CSV file (i.e., column headings)

  • force – If the output file already exists delete it before proceeding.

rsgislib.vectorutils.createPolyVecBBOXs(vectorFile, vectorLyr, vecDriver, epsgCode, bboxs, atts=None, attTypes=None, overwrite=True)

This function creates a set of polygons for a set of bounding boxes. When creating an attribute the available data types are ogr.OFTString, ogr.OFTInteger, ogr.OFTReal

Parameters

  • vectorFile – output vector file/path

  • vectorLyr – output vector layer

  • vecDriver – the output vector layer type.

  • epsgCode – EPSG code specifying the projection of the data (e.g., 4326 is WSG84 Lat/Long).

  • bboxs – is a list of bounding boxes ([xMin, xMax, yMin, yMax]) to be saved to the output vector.

  • atts – is a dict of lists of attributes with the same length as the bboxs list. The dict should be named the same as the attTypes[‘names’] list.

  • attTypes – is a dict with a list of attribute names (attTypes[‘names’]) and types (attTypes[‘types’]). The list must be the same length as one another and the number of atts. Example type: ogr.OFTString

  • overwrite –

    • overwrite the vector file specified if it exists. Use False for GPKG where you want to add multiple layers.

rsgislib.vectorutils.extractImageFootprint(inputImg, outVec, tmpDIR='./tmp', rePrjTo=None)

A function to extract an image footprint as a vector.

Parameters

  • inputImg – the input image file for which the footprint will be extracted.

  • outVec – output shapefile path and name.

  • tmpDIR – temp directory which will be used during processing. It will be created and deleted once processing complete.

  • rePrjTo – optional command

rsgislib.vectorutils.createImgExtentLUT(imgList, vectorFile, vectorLyr, vecDriver, ignore_none_imgs=False, out_proj_wgs84=False, overwrite_lut_file=False)

Create a vector layer look up table (LUT) for a directory of images.

Parameters

  • imgList – list of input images for the LUT. All input images should be the same projection/coordinate system.

  • vectorFile – output vector file/path

  • vectorLyr – output vector layer

  • vecDriver – the output vector layer type (e.g., GPKG).

  • ignore_none_imgs – if a NULL epsg is returned from an image then ignore and don’t include in LUT else throw exception.

  • out_proj_wgs84 – if True then the image bounding boxes will be re-projected to EPSG:4326.

  • overwrite_lut_file – if True then output file will be overwritten. If false then not, e.g., can add extra layer to GPKG

Example:

import glob
import rsgislib.vectorutils
imgList = glob.glob('/Users/pete/Temp/GabonLandsat/Hansen*.kea')
rsgislib.vectorutils.createImgExtentLUT(imgList, './ImgExtents.gpkg', 'HansenImgExtents', 'GPKG')
rsgislib.vectorutils.createVectorGrid(outputVec, vecDriver, vecLyrName, epsgCode, grid_x, grid_y, bbox)

A function which creates a regular grid across a defined area.

Parameters

  • outputVec – outout file

  • epsgCode – EPSG code of the output projection

  • grid_x – the size in the x axis of the grid cells.

  • grid_y – the size in the y axis of the grid cells.

  • bbox – the area for which cells will be defined (MinX, MaxX, MinY, MaxY).

  • vecDriver – the output vector layer type.

  • vecLyrName – output vector layer

rsgislib.vectorutils.defineGrid(bbox, x_size, y_size, in_epsg_code, out_vec, out_vec_lyr, vec_drv='GPKG', out_epsg_code=None, utm_grid=False, utm_hemi=False)

Define a grid of bounding boxes for a specified bounding box. The output grid can be in a different projection to the inputted bounding box. Where a UTM grid is required and there are multiple UTM zones then the layer name will be appended with utmXX[n|s]. Note. this only works with formats such as GPKG which support multiple layers. A shapefile which only supports 1 layer will not work.

Parameters

  • bbox – a bounding box (xMin, xMax, yMin, yMax)

  • x_size – Output grid size in X axis. If out_epsg_code or utm_grid defined then the grid size needs to be in the output unit.

  • y_size – Output grid size in Y axis. If out_epsg_code or utm_grid defined then the grid size needs to be in the output unit.

  • in_epsg_code – EPSG code for the projection of the bbox

  • out_vec – output vector file.

  • out_vec_lyr – output vector layer name.

  • vec_drv – output vector file format (see OGR codes). Default is GPKG.

  • out_epsg_code – if provided the output grid is reprojected to the projection defined by this EPSG code. (note. the grid size needs to the in the unit of this projection). Default is None.

  • utm_grid – provide the output grid in UTM projection where grid might go across multiple UTM zones. Default is False. grid size unit should be metres.

  • utm_hemi – if outputting a UTM projected grid then decided whether to use hemispheres or otherwise. If False then everything will be projected northern hemisphere (e.g., as with landsat or sentinel-2). Default is False.

rsgislib.vectorutils.exportSpatialSelectFeats(vecFile, vecLyr, selVecFile, selVecLyr, outputVec, outVecLyrName, outVecDrvr)

Function to get a list of attribute values from features which intersect with the select layer.

Parameters

  • vecFile – vector layer from which the attribute data comes from.

  • vecLyr – the layer name from which the attribute data comes from.

  • selVecFile – the vector file which will be intersected within the vector file.

  • selVecLyr – the layer name which will be intersected within the vector file.

  • outputVec – output vector file/path

  • outVecLyrName – output vector layer

  • outVecDrvr – the output vector layer type.

rsgislib.vectorutils.selectIntersectFeats(vecFile, vecLyr, roiVecFile, roiVecLyr, out_vec_file, out_vec_lyr, out_vec_format='GPKG')

Function to select the features which intersect with region of interest (ROI) features which will be outputted into a new vector layer.

Parameters

  • vecFile – vector layer from which the attribute data comes from.

  • vecLyr – the layer name from which the attribute data comes from.

  • roiVecFile – the vector file which will be intersected within the vector file.

  • roiVecLyr – the layer name which will be intersected within the vector file.

  • out_vec_file – the vector file which will be outputted.

  • out_vec_lyr – the layer name which will be outputted.

  • out_vec_format – output vector format (default GPKG)

rsgislib.vectorutils.splitVecLyr(vecFile, vecLyr, nfeats, outVecDrvr, outdir, outvecbase, outvecend)

A function which splits the input vector layer into a number of output layers.

Parameters

  • vecFile – input vector file.

  • vecLyr – input layer name.

  • nfeats – number of features within each output file.

  • outVecDrvr – output file driver.

  • outdir – output directory for the created output files.

  • outvecbase – output layer name will be the same as the base file name.

  • outvecend – file ending (e.g., .shp).

rsgislib.vectorutils.subsetEnvsVecLyrObj(lyrVecObj, bbox, epsg=None)

Function to get an ogr vector layer for the defined bounding box. The returned layer is returned as an in memory ogr Layer object.

Parameters

  • lyrVecObj – OGR Layer Object.

  • bbox – region of interest (bounding box). Define as [xMin, xMax, yMin, yMax].

  • epsg – provide an EPSG code for the layer if not well defined by the input layer.

Returns

OGR Layer and Dataset objects.

rsgislib.vectorutils.writePts2Vec(vectorFile, vectorLyr, vecDriver, epsgCode, ptsX, ptsY, atts=None, attTypes=None, replace=True, file_opts=[], lyr_opts=[])

This function creates a set of polygons for a set of bounding boxes. When creating an attribute the available data types are ogr.OFTString, ogr.OFTInteger, ogr.OFTReal

Parameters

  • vectorFile – output vector file/path

  • vectorLyr – output vector layer

  • vecDriver – the output vector layer type.

  • epsgCode – EPSG code specifying the projection of the data (e.g., 4326 is WSG84 Lat/Long).

  • ptsX – is a list of x coordinates.

  • ptsY – is a list of y coordinates.

  • atts – is a dict of lists of attributes with the same length as the ptsX & ptsY lists. The dict should be named the same as the attTypes[‘names’] list.

  • attTypes – is a dict with a list of attribute names (attTypes[‘names’]) and types (attTypes[‘types’]). The list must be the same length as one another and the number of atts. Example type: ogr.OFTString

  • replace – if the output vector file exists overwrite.

  • file_opts – Options passed when creating the file. Default: []. Common value might be [“OVERWRITE=YES”]

  • lyr_opts – Options passed when create the layer Default: []. Common value might be [“OVERWRITE=YES”]

Attributes

rsgislib.vectorutils.writeVecColumn(vectorFile, vectorLayer, colName, colDataType, colData)

A function which will write a column to a vector file

Where:

Parameters

  • vectorFile – The file / path to the vector data ‘file’.

  • vectorLayer – The layer to which the data is to be added.

  • colName – Name of the output column

  • colDataType – ogr data type (e.g., ogr.OFTString, ogr.OFTInteger, ogr.OFTReal)

  • colData – A list of the same length as the number of features in vector file.

Example:

from rsgislib import vectorutils
import rsgislib
import osgeo.ogr as ogr

rsgisUtils = rsgislib.RSGISPyUtils()
requiredScenes = rsgisUtils.readTextFile2List("GMW_JERS-1_ScenesRequired.txt")
requiredScenesShp = "JERS-1_Scenes_Requred_shp"
vectorutils.writeVecColumn(requiredScenesShp+'.shp', requiredScenesShp, 'ScnName', ogr.OFTString, requiredScenes)
rsgislib.vectorutils.writeVecColumn2Layer(lyr, colName, colDataType, colData)

A function which will write a column to a vector layer.

Where:

Parameters

  • lyr – GDAL/OGR vector layer object

  • colName – Name of the output column

  • colDataType – ogr data type (e.g., ogr.OFTString, ogr.OFTInteger, ogr.OFTReal)

  • colData – A list of the same length as the number of features in vector file.

rsgislib.vectorutils.readVecColumn(vectorFile, vectorLayer, colName)

A function which will reads a column from a vector file

Where:

Parameters

  • vectorFile – The file / path to the vector data ‘file’.

  • vectorLayer – The layer to which the data is to be read from.

  • colName – Name of the input column

rsgislib.vectorutils.readVecColumns(vectorFile, vectorLayer, attNames)

A function which will reads a column from a vector file

Where:

Parameters

  • vectorFile – The file / path to the vector data ‘file’.

  • vectorLayer – The layer to which the data is to be read from.

  • attNames – List of input attribute column names to be read in.

rsgislib.vectorutils.vectorMaths(inputVector, outputVector, outputColName, expression, variables, force)

A command to calculate a number column from data in existing columns.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector

  • outputVector – is a string containing the name of the output vector file

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

  • expression – is a string containing the muparser expression to be calculated.

  • variables – is a list defining the names of the variables used within the expression and defining which columns they are in the inputVector. The must be a list and contain two fields ‘name’ and ‘fieldName’.

  • force – is a bool, specifying whether to force removal of the output vector if it exists

rsgislib.vectorutils.removeattributes(inputvector, outputvector, force)

A command to copy the geometry, dropping attributes.

Where:

Parameters

  • inputvector – is a string containing the name of the input vector

  • outputvector – is a string containing the name of the output vector

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_stem_locations.shp'
outputVector = './TestOutputs/injune_p142_stem_locations_noatts.shp'
vectorutils.removeattributes(inputVector, outputVector, True)
rsgislib.vectorutils.findreplacetext(inputvector, attribute, find, replace)

A command to undertake find and replace on a given attribute with the shapefile

Where:

Parameters

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

  • attribute – is a string containing the name of field in the attribute table.

  • find – is a string to find.

  • replace – is a string to replace ‘find’.

Example:

from rsgislib import vectorutils
inputVector = './TestOutputs/injune_p142_psu_utm_findreplace.shp'
attribute = 'PSU'
find = '142'
replace = '142'
vectorutils.findreplacetext(inputVector, attribute, find, replace)
rsgislib.vectorutils.calcarea(inputvector, outputvector, force)

A command to add the area of each polygon to the attribute table, area in the same units as the input dataset (likely m^2 or degrees^2).

Where:

Parameters

  • inputvector – is a string containing the name of the input vector

  • outputvector – is a string containing the name of the output vector

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_psu_utm.shp'
outputVector = './TestOutputs/injune_p142_psu_utm_area.shp'
vectorutils.calcarea(inputVector, outputVector, True)
rsgislib.vectorutils.populateGeomZField(InputVector, InputImage, imgBand, OutputVector, force)

A command to populate the z field within the vector file making it a 3D vector rather than just a 2d file.

Where:

Parameters

  • InputVector – is a string containing the name of the input vector

  • InputImage – is a string containing the name of the image (DEM) image

  • imgBand – is an unsigned int specifying the image band in the image file to be used (note image bands indexes start at 1)

  • OutputVector – is a string containing the name of the output vector file

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

import rsgislib.vectorutils
inputVector = './Polys2D.shp'
inputImage = './SRTM_90m.kea'
imgBand = 1
outputVector = './Polys3D.shp'
force = True
rsgislib.vectorutils.populateGeomZField(inputVector, inputImage, imgBand, outputVector, force)
rsgislib.vectorutils.calcMaxDist2NearestGeom(inputVector)

A command to calculate the maximum minimum distance between the geometries.

Where:

Parameters

inputVector – is a string containing the name of the input vector

rsgislib.vectorutils.dist2NearestGeom(inputVector, outputVector, minDistCol, force, useIdx, maxSearchDist)

A command to calculate the distance from each geometry to its nearest neighbouring geometry. The function also returns the maximum minimum distance between the geometries.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector

  • outputVector – is a string containing the name of the output vector

  • minDistCol – is a string with the name of the output column name

  • force – is a bool, specifying whether to force removal of the output vector if it exists

  • useIdx – is a bool, specifying whether a spatial index and max search limit should be used

  • maxSearchDist – is a float, with maximum search distance from each feature - only used within a spatial index.

rsgislib.vectorutils.dist2NearestSecGeomSet(inputVector, inDistToVector, outputVector, minDistCol, force, useIdx, maxSearchDist)

A command to calculate the distance from each geometry to its nearest neighbouring geometry. The function also returns the maximum minimum distance between the geometries.

Where:

Parameters

  • inputVector – is a string containing the name of the input vector

  • inDistToVector – is a string containing the name of the input vector for which the distance to features from the input vector will be calculated.

  • outputVector – is a string containing the name of the output vector

  • minDistCol – is a string with the name of the output column name

  • force – is a bool, specifying whether to force removal of the output vector if it exists

  • useIdx – is a bool, specifying whether a spatial index and max search limit should be used

  • maxSearchDist – is a float, with maximum search distance from each feature - only used within a spatial index.

rsgislib.vectorutils.spatialGraphClusterGeoms(inputVector, outputVector, useMinSpanTree, sdEdgeLen, maxEdgeLen, force, outShpEdges, outH5EdgeLens)

A command to spatial cluster using a minimum spanning tree approach (Bunting et al 2010).

Where:

Parameters

  • inputVector – is a string containing the name of the input vector

  • outputVector – is a string containing the name of the output vector

  • useMinSpanTree – is a boolean specifying whether a minimum spanning tree should be used rather than just a graph.

  • sdEdgeLen – is a float

  • maxEdgeLen – is a double

  • force – is a bool, specifying whether to force removal of the output vector if it exists

  • outShpEdges – is a string containing the path for an output vector to export minimum spanning tree edges as a shapefile.

  • outH5EdgeLens – is a string containing the path for an output hdf5 file to export the minimum spanning tree edge lengths.

rsgislib.vectorutils.copyRATCols2VectorLyr(vec_file, vec_lyr, rat_row_col, clumps_img, ratcols, outcolnames=None, outcoltypes=None)

A function to copy columns from RAT to a vector layer. Note, the vector layer needs a column, which already exists, that specifies the row from the RAT the feature is related to. If you created the vector using the polygonise function then that column will have been created and called ‘PXLVAL’.

Parameters

  • vec_file – The vector file to be used.

  • vec_lyr – The name of the layer within the vector file.

  • rat_row_col – The column in the layer which specifies the RAT row the feature corresponds with.

  • clumps_img – The clumps image with the RAT from which information should be taken.

  • ratcols – The names of the columns in the RAT to be copied.

  • outcolnames – If you do not want the same column names as the RAT then you can specify alternatives. If None then the names will be the same as the RAT. (Default = None)

  • outcoltypes – The data types used for the columns in vector layer. If None then matched to RAT. Default is None

rsgislib.vectorutils.getAttLstSelectBBoxFeats(vec_file, vec_lyr, attNames, bbox, bbox_epsg=None)

Function to get a list of attribute values from features which intersect with the select layer.

Parameters

  • vec_file – the OGR file from which the attribute data comes from.

  • vec_lyr – the layer name within the file from which the attribute data comes from.

  • attNames – a list of attribute names to be outputted.

  • bbox – the bounding box for the region of interest (xMin, xMax, yMin, yMax).

  • bbox_epsg – the projection of the BBOX (if None then ignore).

Returns

list of dictionaries with the output values.

rsgislib.vectorutils.getAttLstSelectBBoxFeatsLyrObjs(vecLyrObj, attNames, bbox, bbox_epsg=None)

Function to get a list of attribute values from features which intersect with the select layer.

Parameters

  • vecLyrObj – the OGR layer object from which the attribute data comes from.

  • attNames – a list of attribute names to be outputted.

  • bbox – the bounding box for the region of interest (xMin, xMax, yMin, yMax).

  • bbox_epsg – the projection of the BBOX (if None then ignore).

Returns

list of dictionaries with the output values.

rsgislib.vectorutils.getAttLstSelectFeats(vecFile, vecLyr, attNames, selVecFile, selVecLyr)

Function to get a list of attribute values from features which intersect with the select layer.

Parameters

  • vecFile – vector layer from which the attribute data comes from.

  • vecLyr – the layer name from which the attribute data comes from.

  • attNames – a list of attribute names to be outputted.

  • selVecFile – the vector file which will be intersected within the vector file.

  • selVecLyr – the layer name which will be intersected within the vector file.

Returns

list of dictionaries with the output values.

rsgislib.vectorutils.getAttLstSelectFeatsLyrObjs(vecLyrObj, attNames, selVecLyrObj)

Function to get a list of attribute values from features which intersect with the select layer.

Parameters

  • vecLyrObj – the OGR layer object from which the attribute data comes from.

  • attNames – a list of attribute names to be outputted.

  • selVecLyrObj – the OGR layer object which will be intersected within the vector file.

Returns

list of dictionaries with the output values.

rsgislib.vectorutils.popBBOXCols(vecFile, vecLyr, xminCol='xmin', xmaxCol='xmax', yminCol='ymin', ymaxCol='ymax')

A function which adds a polygons boundary bbox as attributes to each feature.

Parameters

  • vecFile – vector file.

  • vecLyr – layer within the vector file.

  • xminCol – column name.

  • xmaxCol – column name.

  • yminCol – column name.

  • ymaxCol – column name.

rsgislib.vectorutils.performSpatialJoin(base_vec_file, join_vec_file, output_vec_file, base_lyr=None, join_lyr=None, output_lyr=None, outVecDrvr=None, join_how='inner', join_op='within')

A function to perform a spatial join between two vector layers. This function uses geopandas so this needs to be installed. You also need to have the rtree package to generate the index used to perform the intersection.

For more information see: http://geopandas.org/mergingdata.html#spatial-joins

Parameters

  • base_vec_file – the base vector file with the geometries which will be outputted.

  • join_vec_file – the vector with the attributes which will be joined to the base vector geometries.

  • output_vec_file – the output vector file.

  • base_lyr – the layer name for the base vector, not needed if input file is a shapefile (Default None).

  • join_lyr – the layer name for the join vector, not needed if input file is a shapefile (Default None).

  • output_lyr – the layer name for the output vector, not needed if input file is a shapefile (Default None).

  • outVecDrvr – The output vector file format, if none then shapefile outputted (Default None)

  • join_how – Specifies the type of join that will occur and which geometry is retained. The options are [left, right, inner]. The default is ‘inner’

  • join_op – Defines whether or not to join the attributes of one object to another. The options are [intersects, within, contains] and default is ‘within’

Querying

rsgislib.vectorutils.queryFileLUT(lut_file, lut_lyr, roi_file, roi_lyr, out_dest, targz_out, cp_cmds)

A function which allows the file LUT to be queried (intersection) and commands generated for completing operations. Must select (pass true) for either targz_out or cp_cmds not both. If both are False then the list of intersecting files will be returned.

Parameters

  • lut_file – OGR vector file with the LUT.

  • lut_lyr – name of the layer within the LUT file.

  • roi_file – region of interest OGR vector file.

  • roi_lyr – layer name within the ROI file.

  • out_dest – the destination for outputs from command (e.g., where are the files to be copied to or output file name for tar.gz file.

  • targz_out – boolean which specifies that the command for generating a tar.gz file should be generated.

  • cp_cmds – boolean which specifies that the command for copying the LUT files to a out_dest should be generated.

Returns

returns a list of commands to be executed.

Management

rsgislib.vectorutils.getMemVecLyrSubset(vecFile, vecLyr, bbox)

Function to get an ogr vector layer for the defined bounding box. The returned layer is returned as an in memory ogr Layer object.

Parameters

  • vecFile – vector layer from which the attribute data comes from.

  • vecLyr – the layer name from which the attribute data comes from.

  • bbox – region of interest (bounding box). Define as [xMin, xMax, yMin, yMax].

Returns

OGR Layer and Dataset objects.

rsgislib.vectorutils.reProjVectorLayer(inputVec, outputVec, outProjWKT, outDriverName='ESRI Shapefile', outLyrName=None, inLyrName=None, inProjWKT=None, force=False)

A function which reprojects a vector layer. You might also consider using rsgislib.vectorutils.vector_translate, particularly if you are reprojecting the data and changing between coordinate units (e.g., degrees to meters)

Parameters

  • inputVec – is a string with name and path to input vector file.

  • outputVec – is a string with name and path to output vector file.

  • outProjWKT – is a string with the WKT string for the output vector file.

  • outDriverName – is the output vector file format. Default is ESRI Shapefile.

  • outLyrName – is a string for the output layer name. If None then ignored and assume there is just a single layer in the vector and layer name is the same as the file name.

  • inLyrName – is a string for the input layer name. If None then ignored and assume there is just a single layer in the vector.

  • inProjWKT – is a string with the WKT string for the input shapefile (Optional; taken from input file if not specified).

rsgislib.vectorutils.mergeShapefiles(inFileList, outVecFile)

Function which will merge a list of shapefiles into an single shapefile using ogr2ogr.

Where:

Parameters

  • inFileList – is a list of input files.

  • outVecFile – is the output shapefile

rsgislib.vectorutils.mergeVectors2SQLiteDB(inFileList, outDBFile, lyrName, exists)

Function which will merge a list of vector files into an single output SQLite database using ogr2ogr.

Where:

Parameters

  • inFileList – is a list of input files.

  • outDBFile – is the output SQLite database (*.sqlite)

  • lyrName – is the layer name in the output database (i.e., you can merge layers into single layer or write a number of layers to the same database).

  • exists – boolean which specifies whether the database file exists or not.

rsgislib.vectorutils.mergeVectors2SQLiteDBIndLyrs(inFileList, outDBFile)

Function which will merge a list of vector files into an single output SQLite database where each input file forms a new layer using the existing layer name. This function wraps the ogr2ogr command.

Where:

Parameters

  • inFileList – is a list of input files.

  • outDBFile – is the output SQLite database (*.sqlite)

rsgislib.vectorutils.mergeVectorLyrs2GPKG(inputFile, outFile, lyrName, exists)

Function which will merge all the layers in the input vector file into an single output GeoPackage (GPKG) file using ogr2ogr.

Where:

Parameters

  • inputFile – is a vector file which contains multiple layers which are to be merged

  • outFile – is the output GPKG database (*.gpkg)

  • lyrName – is the layer name in the output database (i.e., you can merge layers into single layer or write a number of layers to the same database).

  • exists – boolean which specifies whether the database file exists or not.

rsgislib.vectorutils.mergeVectors2GPKG(inFileList, outFile, lyrName, exists)

Function which will merge a list of vector files into an single output GeoPackage (GPKG) file using ogr2ogr.

Where:

Parameters

  • inFileList – is a list of input files.

  • outFile – is the output GPKG database (*.gpkg)

  • lyrName – is the layer name in the output database (i.e., you can merge layers into single layer or write a number of layers to the same database).

  • exists – boolean which specifies whether the database file exists or not.

rsgislib.vectorutils.mergeVectors2GPKGIndLyrs(inFileList, outFile, rename_dup_lyrs=False, geom_type=None)

Function which will merge a list of vector files into an single output GPKG file where each input file forms a new layer using the existing layer name. This function wraps the ogr2ogr command.

Where:

Parameters

  • inFileList – is a list of input files.

  • outFile – is the output GPKG database (*.gpkg)

  • rename_dup_lyrs – If False an exception will be throw if any input layers has the same name. If True a layer will be renamed - with a random set of letters/numbers on the end.

  • geom_type – Force the output vector to have a particular geometry type (e.g., ‘POLYGON’). Same options as ogr2ogr.

Rasterisation

rsgislib.vectorutils.rasterise2Image(inputVec, inputImage, outImage, gdalformat='KEA', burnVal=1, shpAtt=None, shpExt=False)

* Deprecated * A utillity to rasterise a shapefile into an image covering the same region and at the same resolution as the input image.

Where:

Parameters

  • inputVec – is a string specifying the input vector (shapefile) file

  • inputImage – is a string specifying the input image defining the grid, pixel resolution and area for the rasterisation (if None and shpExt is False them assumes output image already exists and just uses it as is burning vector into it)

  • outImage – is a string specifying the output image for the rasterised shapefile

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

  • burnVal – is the value for the output image pixels if no attribute is provided.

  • shpAtt – is a string specifying the attribute to be rasterised, value of None creates a binary mask and “FID” creates a temp shapefile with a “FID” column and rasterises that column.

  • shpExt – is a boolean specifying that the output image should be cut to the same extent as the input shapefile (Default is False and therefore output image will be the same as the input).

Example:

from rsgislib import vectorutils

inputVector = 'crowns.shp'
inputImage = 'injune_p142_casi_sub_utm.kea'
outputImage = 'psu142_crowns.kea'  
vectorutils.rasterise2Image(inputVector, inputImage, outputImage, 'KEA', shpAtt='FID')
rsgislib.vectorutils.rasteriseVecLyr(inputVec, inputVecLyr, inputImage, outImage, gdalformat='KEA', burnVal=1, datatype=5, vecAtt=None, vecExt=False, thematic=True, nodata=0)

A utillity to rasterise a vector layer to an image covering the same region and at the same resolution as the input image.

Where:

Parameters

  • inputVec – is a string specifying the input vector file

  • inputVecLyr – is a string specifying the input vector layer name.

  • inputImage – is a string specifying the input image defining the grid, pixel resolution and area for the rasterisation (if None and vecExt is False them assumes output image already exists and just uses it as is burning vector into it)

  • outImage – is a string specifying the output image for the rasterised shapefile

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

  • burnVal – is the value for the output image pixels if no attribute is provided.

  • datatype – of the output file, default is rsgislib.TYPE_8UINT

  • vecAtt – is a string specifying the attribute to be rasterised, value of None creates a binary mask and “FID” creates a temp shapefile with a “FID” column and rasterises that column.

  • vecExt – is a boolean specifying that the output image should be cut to the same extent as the input shapefile (Default is False and therefore output image will be the same as the input).

  • thematic – is a boolean (default True) specifying that the output image is an thematic dataset so a colour table will be populated.

  • nodata – is a float specifying the no data value associated with a continous output image.

Example:

from rsgislib import vectorutils

inputVector = 'crowns.shp'
inputVectorLyr = 'crowns'
inputImage = 'injune_p142_casi_sub_utm.kea'
outputImage = 'psu142_crowns.kea'  
vectorutils.rasteriseVecLyr(inputVector, inputVectorLyr, inputImage, outputImage, 'KEA', vecAtt='FID')
rsgislib.vectorutils.rasteriseVecLyrObj(vec_lyr_obj, outImage, burnVal=1, vecAtt=None, calcstats=True, thematic=True, nodata=0)

A utility to rasterise a vector layer to an image covering the same region.

Where:

Parameters

  • vec_lyr_obj – is a OGR Vector Layer Object

  • outImage – is a string specifying the output image, this image must already exist and intersect within the input vector layer.

  • burnVal – is the value for the output image pixels if no attribute is provided.

  • vecAtt – is a string specifying the attribute to be rasterised, value of None creates a binary mask and “FID” creates a temp shapefile with a “FID” column and rasterises that column.

  • calcstats – is a boolean specifying whether image stats and pyramids should be calculated.

  • thematic – is a boolean (default True) specifying that the output image is an thematic dataset so a colour table will be populated.

  • nodata – is a float specifying the no data value associated with a continous output image.

rsgislib.vectorutils.copyVec2RAT(vecfile, vecLyr, inputImage, outputImage)

A utillity to create raster copy of a shapefile. The output image is a KEA file and the attribute table has the attributes from the shapefile.

Where:

Parameters

  • inputVec – is a string specifying the input vector (shapefile) file

  • inputImage – is a string specifying the input image defining the grid, pixel resolution and area for the rasterisation

  • outputImage – is a string specifying the output KEA image for the rasterised shapefile

Example:

from rsgislib import vectorutils

inputVector = 'crowns.shp'
inputImage = 'injune_p142_casi_sub_utm.kea'
outputImage = 'psu142_crowns.kea'

vectorutils.copyVec2RAT(inputVector, 'crowns', inputImage, outputImage)

Image Information

rsgislib.vectorutils.findCommonImgExtent(inputImages, outputvector, force)

A command to create a shapefile representing the region of common extent for the list of input images.

Where:

Parameters

  • inputImages – is a list of strings containing the names of the input image files

  • outputvector – is a string containing the name of the output vector

  • force – is a bool, specifying whether to force removal of the output vector if it exists

Example:

from rsgislib import vectorutils
inputImages = ['img1.kea', 'img2.kea', 'img3.kea', 'img4.kea', 'img5.kea']
outputVector = 'imgSubExtent.shp'
vectorutils.findCommonImgExtent(inputImages, outputVector, True)
rsgislib.vectorutils.does_vmsk_img_intersect(input_vmsk_img, roi_vec_file, roi_vec_lyr, tmp_dir, vec_epsg=None)

This function checks whether the input binary raster mask intesects with the input vector layer. A check is first done as to whether the bounding boxes intersect, if they do then the intersection between the images is then calculated. The input image and vector can be in different projections but the projection needs to be well defined.

Parameters

  • input_vmsk_img – Input binary mask image file.

  • roi_vec_file – The input vector file.

  • roi_vec_lyr – The name of the input layer.

  • tmp_dir – a temporary directory for files generated during processing.

  • vec_epsg – If projection is poorly defined by the vector layer then it can be specified.

Utilities

rsgislib.vectorutils.printpolygeom(inputvector)

A command to print the polygon geometries (to the console) of the inputted shapefile

Where:

Parameters

inputvector – is a string containing the name of the input vector

Example:

from rsgislib import vectorutils
inputVector = './Vectors/injune_p142_psu_utm.shp'
vectorutils.printpolygeom(inputVector)
rsgislib.vectorutils.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)

rsgislib.vectorutils.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

rsgislib.vectorutils.getProjWKTFromVec(inVec, layerName=None)
Parameters

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

Returns

WKT representation of projection

rsgislib.vectorutils.getVecLyrsLst(vecFile)

A function which returns a list of available layers within the inputted vector file.

Parameters

vecFile – file name and path to input vector layer.

Returns

list of layer names (can be used with gdal.Dataset.GetLayerByName()).

rsgislib.vectorutils.lstveclyrcols(vecfile, veclyr)

A function which returns a list of columns from the input vector layer.

Parameters

  • vecfile – input vector file.

  • veclyr – input vector layer

Returns

list of column names

rsgislib.vectorutils.ogrVectorColDataTypeFromGDALRATColType(rat_datatype)

Returns the data type to create a column in a OGR vector layer for equalivant to rat_datatype.

Parameters

rat_datatype – the datatype (GFT_Integer, GFT_Real, GFT_String) for the RAT column.

Returns

OGR datatype (OFTInteger, OFTReal, OFTString)