Modules

Area module

CamEnv module

DEM module

The DEM module contains functionality for handling DEM data and implementing this data into the PyTrx.CamEnv.CamEnv object class.

DEM.DEM_FromMat(matfile)

Function for loading a DEM array from a Matlab (.mat) file containing separate X, Y, Z matrices

Parameters:

matfile (str) – DEM .mat filepath

Returns:

A DEM object

Return type:

PyTrx.DEM.ExplicitRaster

DEM.DEM_FromTiff(tiffFile)

Function for loading a DEM array from a .tiff file containing raster-formatted data. The tiff data importing is handled by GDAL

Parameters:

tiffFile (str) – DEM .tif filepath

Returns:

A DEM object

Return type:

PyTrx.DEM.ExplicitRaster

class DEM.ExplicitRaster(X, Y, Z, nodata=nan)

Bases: object

A class to represent a numeric Raster with explicit XY cell referencing in each grid cell

Variables:

  • _data (arr) – DEM data array

  • _nodata (float) – Nodata value

  • _extents (list) – DEM extent [X0, X1, Y0, Y1]

densify(densefac=2)

Function to densify the DEM array by a given densification factor. The array is multiplied by the given densification factor and then subsequently values are interpolated using the SciPy function RectBivariateSpline. The densification factor is set to 2 by default, meaning that the size of the DEM array is doubled

Parameters:

densefac (int) – Densification factor

Returns:

Densified DEM

Return type:

PyTrx.DEM.ExplicitRaster

getCols()

Return the number of columns in the DEM data array

getData(dim=None)

Return DEM data. XYZ dimensions can be individually called with the dim input variable (integer: 0, 1, or 2)

Parameters:

dim (int) – Dimension to retrieve (0, 1, or 2), default to None

Returns:

DEM dimension as array

Return type:

arr

getExtent()

Return DEM extent

getNoData()

Return fill value for no data in DEM array

getRows()

Return the number of rows in the DEM data array

getShape()

Return the shape of the DEM data array

getZ()

Return height (Z) data of DEM

getZcoord(x, y)

Return height (Z) at a given XY coordinate in DEM

Parameters:

  • x (int) – X coordinate

  • y (int) – Y coordinate

Returns:

DEM Z value for given coordinate

Return type:

int

reportDEM()

Self reporter for DEM class object. Returns the number of rows and columns in the array, how NaN values in the array are filled, and the data extent coordinates

subset(cmin, cmax, rmin, rmax)

Return a specified subset of the DEM array

Parameters:

  • cmin (int) – Column minimum extent

  • cmax (int) – Column maximum extent

  • rmin (int) – Row minimum extent

  • rmax (int) – Row maximum extent

Returns:

Subset of DEM

Return type:

PyTrx.DEM.ExplicitRaster

class DEM.TestDEM(methodName='runTest')

Bases: TestCase

test_ExplicitRaster()
test_getRows()
test_subset()
test_voxelviewshed()
DEM.load_DEM(demfile)

Function for loading DEM data from different file types, which is automatically detected. Recognised file types: .mat and .tif

Parameters:

demfile (str) – DEM filepath

Returns:

DEM object

Return type:

PyTrx.DEM.ExplicitRaster

DEM.voxelviewshed(dem, viewpoint)

Calculate a viewshed over a DEM from a given viewpoint in the DEM scene. This function is based on the viewshed function (voxelviewshed.m) available in ImGRAFT. The ImGRAFT voxelviewshed.m script is available at: http://github.com/grinsted/ImGRAFT/blob/master/voxelviewshed.m

Parameters:

  • dem (PyTrx.DEM.ExplicitRaster) – DEM object

  • viewpoint (list) – 3-element vector specifying the viewpoint

Returns:

vis – Boolean visibility matrix (which is the same size as dem)

Return type:

arr

FileHandler module

Th FileHandler module contains all the functions called by a PyTrx object to load and export data.

FileHandler.checkMatrix(matrix)

Function to support the calibrate function. Checks and converts the intrinsic matrix to the correct format for calibration with OpenCV

Parameters:

matrix (arr) – Inputted matrix for checking

Returns:

mat – Validated matrix

Return type:

arr

FileHandler.importAreaData(xyzfile, pxfile)

Import xyz and px data from text files

Parameters:

  • xyzfile (str) – File directory to xyz coordinates

  • pxfile (str) – File directory to uv coordinates

Returns:

areas – Coordinates and areas of detected areas

Return type:

list

FileHandler.importAreaFile(fname, dimension)

Import pixel polygon data from text file and compute pixel extents

Parameters:

  • fname (str) – Path to the text file containing the UV coordinate data

  • dimension (int) – Integer denoting the number of dimensions in coordinates

Returns:

areas – UV coordinates for polygons and pixel areas for polygons

Return type:

list

FileHandler.importLineData(xyzfile, pxfile)

Import xyz and px data from text files

Parameters:

  • xyzfile (str) – File directory to xyz coordinates

  • pxfile (str) – File directory to uv coordinates

Returns:

lines – Coordinates and lengths of detected lines

Return type:

list

FileHandler.importLineFile(fname, dimension)

Import XYZ line data from text file and compute line lengths

Parameters:

  • fname (str) – Path to the text file containing the XYZ coordinate data

  • dimension (int) – Number of dimensions in point coordinates i.e. 2 or 3

Returns:

lines – List containing line coordinates and lengths

Return type:

list

FileHandler.lineSearch(lineList, search)

Function to supplement the readCalib function. Given an input parameter to search within the file, this will return the line numbers of the data

Parameters:

  • lineList (list) – List of strings within a file line

  • search (str) – Target keyword to search for

Returns:

datalines – Line numbers with keyword match

Return type:

list

FileHandler.readCalib(fileName, paramList)

Function to find camera calibrations from a file given a list or Matlab file containing the required parameters. Returns the parameters as a dictionary object. Compatible file structures: 1) .txt file (“RadialDistortion [k1,k2,k3…k8], TangentialDistortion [p1,p2], IntrinsicMatrix [fx 0. 0.][s fy 0.][cx cy 1] End”); 2) .mat file (Camera calibration file output from the Matlab Camera Calibration App (available in the Computer Vision Systems toolbox)

Parameters:

  • fileName (str) – File directory for calibration file

  • paramList (list) – List of strings denoting keywords to look for in calibration file

Returns:

calib – Calibration parameters denoted by keywords

Return type:

list

FileHandler.readGCPs(fileName)

Function to read ground control points from a .txt file. The data in the file is referenced to under a header line. Data is appended by skipping the header line and finding the world and image coordinates from each line

Parameters:

fileName (str) – File path directory for GCP file

Returns:

  • world (arr) – GCPs in xyz coordinates

  • image (arr) – GCPs in image coordinates

FileHandler.readImg(path, band='L', equal=True)

Function to prepare an image by opening, equalising, converting to either grayscale or a specified band, then returning a copy

Parameters:

  • path (str) – Image file path directory

  • band (str) – Desired band output - ‘R’: red band; ‘B’: blue band; ‘G’: green band; ‘L’: grayscale (default=’L’)

  • equal (bool) – Flag to denote if histogram equalisation should be applied (default=True)

Returns:

bw – Image array

Return type:

arr

FileHandler.readMask(img, writeMask=None)

Function to create a mask for point seeding using PIL to rasterize polygon. The mask is manually defined by the user using the pyplot ginput function. This subsequently returns the manually defined area as a .jpg mask. The writeMask file path is used to either open the existing mask at that path or to write the generated mask to this path

Parameters:

  • img (arr) – Image to define mask in

  • writeMask (str, optional) – File destination that mask output is written to, default to None

Returns:

myMask – Array defining the image mask

Return type:

arr

FileHandler.readMatrixDistortion(path)

Function to support the calibrate function. Returns the intrinsic matrix and distortion parameters required for calibration from a given file

Parameters:

path (str) – Directory of calibration file

Returns:

  • intrMat (arr) – Intrinsic matrix as a 3x3 array, including focal length, principal point, and skew

  • tanDis (arr) – Tangential distortion values (p1, p2)

  • radDis (arr) – Radial distortion values (k1, k2… k6)

FileHandler.returnData(lines, data)

Function to supplement the importCalibration function. Given the line numbers of the parameter data (the ouput of the lineSearch function), this will return the data

Parameters:

  • lines (list) – Given line numbers to extract data from

  • data (list) – Raw line data

Returns:

D – Extracted data

Return type:

arr

FileHandler.writeAreaCoords(pxpts, xyzpts, imn, pxdestination, xyzdestination)

Write UV and XYZ area coordinates to text files. These file types are compatible with the importing tools (importAreaPX, importAreaXYZ)

Parameters:

  • xyzarea (list) – XYZ areas

  • xyzpts (list) – XYZ coordinates

  • imn (list) – Image names

  • pxdestination (str) – File directory where UV coordinates will be written to

  • xyzdestination (str) – File directory where XYZ coordinates will be written to

FileHandler.writeAreaFile(pxareas, xyzareas, imn, destination)

Write UV and XYZ areas to csv file

Parameters:

  • pxarea (list) – Pixel extents

  • xyzarea (list) – XYZ areas

  • imn (list) – Image names

  • destination (str) – File directory where csv file will be written to

FileHandler.writeAreaSHP(xyzpts, imn, fileDirectory, projection=None)

Write OGR real polygon areas (from ALL images) to file in a .shp file type that is compatible with ESRI mapping software

Parameters:

  • xyzpts (list) – XYZ coordinates for polygons

  • imn (list) – Image name

  • fileDirectory (str) – Destination that shapefiles will be written to

  • projection (int/str, optional) – Coordinate projection that the shapefile will exist in. This can either be an ESPG number (expressed as an integer) or a well-known geographical coordinate system (expressed as a string). Well-known geographical coordinate systems are: ‘WGS84’, ‘WGS72’, NAD83’ or ‘EPSG:n’

FileHandler.writeCalibFile(intrMat, tanDis, radDis, fname)

Write camera calibration data to .txt file, including camera matrix, and radial and tangential distortion parameters

Parameters:

  • intrMat (arr) – Intrinsic camera matrix

  • tanDis (arr) – Tangential distortion parameters

  • radDis (arr) – Radial distortion parameters

  • fname (str) – Directory to write file to

FileHandler.writeHomogFile(homog, imn, fname)

Function to write all homography data from a given timeLapse sequence to .csv file. Data is formatted as sequential columns containing the following information: Image pair 1 name, Image pair 2 name, Homography matrix (i.e. all values in the 3x3 matrix), Number of features tracked, X mean displacement, Y mean displacement, X standard deviation, Y standard deviation, Mean error magnitude, Mean homographic displacement, and Signal-to-noise ratio

Parameters:

  • homog (list) – Homography [mtx, im0pts, im1pts, ptserr, homogerr]

  • imn (list) – List of image names

  • fname (str) – Directory for file to be written to

FileHandler.writeLineCoords(uvpts, xyzpts, imn, pxdestination, xyzdestination)

Write UV and XYZ line coordinates to text file. These file types are compatible with the importing tools (importLinePX, importLineXYZ)

Parameters:

  • uvpts (list) – Pixel coordinates

  • xyzpts (list) – XYZ coordinates

  • imn (list) – Image names

  • pxdestination (str) – File directory where UV coordinates will be written to

  • xyzdestination (str) – File directory where XYZ coordinates will be written to

FileHandler.writeLineFile(pxline, xyzline, imn, destination)

Write UV and XYZ line lengths to csv file

Parameters:

  • pxline (list) – Pixel line lengths

  • xyzline (list) – XYZ line lengths

  • imn (list) – Image names

  • destination (str) – File directory where output will be written to

FileHandler.writeLineSHP(xyzpts, imn, fileDirectory, projection=None)

Write OGR real line features (from ALL images) to file in a .shp file type that is compatible with ESRI mapping software

Parameters:

  • xyzpts (list) – XYZ coordinates for polygons

  • imn (list) – Image name

  • fileDirectory (str) – Destination that shapefiles will be written to

  • projection (int/str, optional) – Coordinate projection that the shapefile will exist in. This can either be an ESPG number (expressed as an integer) or a well-known geographical coordinate system (expressed as a string). Well-known geographical coordinate systems are: ‘WGS84’, ‘WGS72’, NAD83’ or ‘EPSG:n’

FileHandler.writeVeloFile(xyzvel, uvvel, homog, imn, fname)

Function to write all velocity data from a given timeLapse sequence to .csv file. Data is formatted as sequential columns containing the following information: Image pair 1 name, Image pair 2 name, Average xyz velocity, Number of features tracked, Average pixel velocity, Homography residual mean error (RMS), and Signal-to-noise ratio

Parameters:

  • xyzvel (list) – XYZ velocities

  • uvvel (list) – Pixel velocities

  • homog (list) – Homography [mtx, im0pts, im1pts, ptserr, homogerr]

  • imn (list) – List of image names

  • fname (str) – Filename for output file. File destination can also specified

FileHandler.writeVeloSHP(xyzvel, xyzerr, xyz0, imn, fileDirectory, projection=None)

Write OGR real velocity points (from ALL images) to file in a .shp file type that is compatible with ESRI mapping software

Parameters:

  • xyzvel (list) – XYZ velocities

  • xyz0 (list) – XYZ pt0

  • imn (list) – Image name

  • fileDirectory (str) – Destination that shapefiles will be written to

  • projection (int/str, optional) – Coordinate projection that the shapefile will exist in. This can either be an ESPG number (expressed as an integer) or a well-known geographical coordinate system (expressed as a string). Well-known geographical coordinate systems are: ‘WGS84’, ‘WGS72’, NAD83’ or ‘EPSG:n’

Images module

Line module

Utilities module

Velocity module