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:

  • 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, outputvector, bufferDist, force)

A command to buffer a vector by a specified distance.

Where:

  • inputvector is a string containing the name of the input vector
  • outputvector is a string containing the name of the output vector
  • bufferDist is a float specifying the distance of the buffer, in map units.
  • 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_1mbuffer.shp'
bufferDist = 1
vectorutils.buffervector(inputVector, outputVector, bufferDist, True)
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:

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

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

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

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

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

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

  • 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

Create Vectors

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

A utillity to polygonise a raster to a ESRI Shapefile.

Where:

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

Example:

from rsgislib import vectorutils
 
inputVector = 'crowns.shp'
inputImage = 'injune_p142_casi_sub_utm.kea'
outputImage = 'psu142_crowns.kea'
    
vectorutils.copyShapefile2RAT(inputVector, inputImage, outputImage)
rsgislib.vectorutils.exportPxls2Pts(inputimg, outputvector, maskVal, force)

A command to export image pixel which have a specific value to a shapefile as points.

Where:

  • inputimg is a string containing the name of the input image
  • outputvector is a string containing the name of the output vector
  • 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

Attributes

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

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

Where:

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

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

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

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

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

  • inputVector is a string containing the name of the input vector
rsgislib.vectorutils.dist2NearestGeom(inputVector, outputVector, force)

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:

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

  • 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.writeVecColumn(vectorFile, vectorLayer, colName, colDataType, colData)

A function which will write a column to a vector file

Where:

  • 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
from osgeo import 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)

Management

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:

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

Rasterisation

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

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

Where:

  • 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.copyShapefile2RAT(inputVec, 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:

  • 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.copyShapefile2RAT(inputVector, 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:

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

Utilities

rsgislib.vectorutils.printpolygeom(inputvector)

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

Where:

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