ecohydroworkflowlib.spatialdata.utils Namespace Reference

Generic utilities for manipulating spatial data sets. More...

Functions
def	getEPSGStringForUTMZone
	Get EPSG string, e.g.
def	getUTMZoneFromCoordinates
	Determine the UTM zone for coordinate pair.
def	transformCoordinates
	Transform a pair of X,Y coordinates from one reference system to another.
def	extractTileFromRaster
	Extract a tile from a raster.
def	resampleRaster
	Resample raster from one spatial reference system and resolution to another.
def	convertGMLToShapefile
	Convert a GML file to a shapefile.
def	deleteShapefile
	Delete shapefile and its related files (.dbf, .prj, .shx)
def	getCoordinatesOfPointsFromShapefile
	Get WGS84 coordinates of point features in shapefile.
def	deleteGeoTiff
	Delete GeoTIFF and its related files (.aux.xml)
def	isCoordinatePairInBoundingBox
	Determine whether coordinate pair lies within bounding box.
def	calculateBoundingBoxCenter
	Calculate the central point of the bounding box.
def	calculateBoundingBoxAreaSqMeters
	Calculate bbox area in square meters.
def	tileBoundingBox
	Break up bounding box into tiles if bounding box is larger than threshold.
def	getBoundingBoxForShapefile
	Return the bounding box, in WGS84 (EPSG:4326) coordinates, for the ESRI shapefile.
def	bufferBoundingBox
	Buffer the bounding by a given percentage.
def	getMeterConversionFactorForLinearUnitOfGMLfile
	Get conversion factor for converting a GML file's linear unit into meters.
def	getMeterConversionFactorForLinearUnitOfShapefile
	Get conversion factor for converting a shapefile's linear unit into meters.
def	getSpatialReferenceForRaster
	Get pixel size and unit for DEM.
def	getDimensionsForRaster
	Get number of columns and rows for raster.
def	getBoundingBoxForRaster
	Return the bounding box, in WGS84 (EPSG:4326) coordinates, for the raster dateset.
def	writeBboxPolygonToShapefile
	Write bbox to a shapfile.
def	writeCoordinatePairsToPointShapefile
	Write coordinates as a point shapefile.
def	copyRasterToGeoTIFF
	Copy input raster from a location outside of outputDir to a GeoTIFF format raster stored in outputDir.

Variables
int	SHP_MINX 0
int	SHP_MAXX 1
int	SHP_MINY 2
int	SHP_MAXY 3
list	RASTER_RESAMPLE_METHOD ['near', 'bilinear', 'cubic', 'cubicspline', 'lanczos']
int	WGS84_EPSG 4326
string	WGS84_EPSG_STR "EPSG:4326"

Detailed Description

Generic utilities for manipulating spatial data sets.

Builds a task-oriented API, for select operations, on top of GDAL/OGR utilities, GDAL/OGR API, Proj API.

This software is provided free of charge under the New BSD License. Please see the following license information:

Copyright (c) 2013, University of North Carolina at Chapel Hill All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the University of North Carolina at Chapel Hill nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author

Brian Miles brian.nosp@m._mil.nosp@m.es@un.nosp@m.c.ed.nosp@m.u

Todo:

Refactor raster and vector functions into their own sub-packages Refactor bounding box as class

Builds a task-oriented API, for select operations, on top of GDAL/OGR utilities, GDAL/OGR API, Proj API.

This software is provided free of charge under the New BSD License. Please see the following license information:

Copyright (c) 2013, University of North Carolina at Chapel Hill All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the University of North Carolina at Chapel Hill nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author

Brian Miles brian.nosp@m._mil.nosp@m.es@un.nosp@m.c.ed.nosp@m.u

Todo:

Refactor raster and vector functions into their own sub-packages Refactor bounding box as class

Function Documentation

def ecohydroworkflowlib.spatialdata.utils.bufferBoundingBox	(		bbox,
			buffer
	)

Buffer the bounding by a given percentage.

Parameters

bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'
buffer	Float >= 0.0 representing number of degrees by which to buffer the bounding box; 0.0 = no buffer, 0.01 = 0.01 degree buffer

def ecohydroworkflowlib.spatialdata.utils.calculateBoundingBoxAreaSqMeters

(

bbox

)

Calculate bbox area in square meters.

Parameters

bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'

Returns

Float representing the bounding box area in square meters

def ecohydroworkflowlib.spatialdata.utils.calculateBoundingBoxCenter

(

bbox

)

Calculate the central point of the bounding box.

Parameters

bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'

Returns

Tuple of floats of the form (longitude, latitude)

def ecohydroworkflowlib.spatialdata.utils.convertGMLToShapefile	(		config,
			outputDir,
			gmlFilepath,
			layerName,
			t_srs
	)

Convert a GML file to a shapefile.

Will silently exit if shapefile already exists

Parameters

config	A Python ConfigParser containing the section 'GDAL/OGR' and option 'PATH_OF_OGR2OGR'
outputDir	String representing the absolute/relative path of the directory into which shapefile should be written
gmlFilepath	String representing the absolute path of the GML file to convert
layerName	String representing the name of the layer contained in the GML file to write to a shapefile
t_srs	String representing the spatial reference system of the output shapefile, of the form 'EPSG:XXXX'

Returns

String representing the name of the shapefile written

     @exception Exception if the conversion failed.

def ecohydroworkflowlib.spatialdata.utils.copyRasterToGeoTIFF	(		config,
			outputDir,
			inRasterPath,
			outRasterName
	)

Copy input raster from a location outside of outputDir to a GeoTIFF format raster stored in outputDir.

Parameters

config	A Python ConfigParser containing the section 'GDAL/OGR' and option 'PATH_OF_GDAL_TRANSLATE'
outputDir	String representing the absolute/relative path of the directory into which shapefile should be written
inRasterPath	String representing path of input raster
outRasterName	String representing name of output raster to be stored in outputDir @raise IOError if gdal_translate binary is not found/executable @raise IOError if output directory does not exist or not writable @raise IOError if input raster is not readable

def ecohydroworkflowlib.spatialdata.utils.deleteGeoTiff

(

geoTiffPath

)

Delete GeoTIFF and its related files (.aux.xml)

Parameters

geoTiffPath

– Path, including filename, of the GeoTIFF to be deleted

def ecohydroworkflowlib.spatialdata.utils.deleteShapefile

(

shpfilePath

)

Delete shapefile and its related files (.dbf, .prj, .shx)

Parameters

shpfilePath

– Path, including filename, of the shapefile to be deleted

def ecohydroworkflowlib.spatialdata.utils.extractTileFromRaster	(		config,
			outputDir,
			inRasterFilename,
			outRasterFilename,
			bbox
	)

Extract a tile from a raster.

Tile extent is defined by supplied bounding box with coordinates defined in WGS84 (EPSG:4326).

Note

Output raster will be in LZW-compressed GeoTIFF file.

Will silently return if output raster already exists.

Parameters

config	Python ConfigParser containing the section 'GDAL/OGR' and option 'PATH_OF_GDAL_TRANSLATE'
outputDir	String representing the absolute/relative path of the directory into which output raster should be written
inRasterFilename	String representing the name of the input raster
outRasterFilename	String representing the name of the output raster
bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326' (WGS84)

def ecohydroworkflowlib.spatialdata.utils.getBoundingBoxForRaster

(

filename

)

Return the bounding box, in WGS84 (EPSG:4326) coordinates, for the raster dateset.

     Assumes raster exists and is readable.
     Code adapted from: http://svn.osgeo.org/gdal/trunk/gdal/swig/python/samples/gdalinfo.py

Parameters

filename

String representing the DEM file to read pixel size and units

Returns

A tuple of the form: (columns, rows) or None if raster could not be opened

Exceptions

IOError	if filename is not readable
Exception	if raster dataset failed to open

def ecohydroworkflowlib.spatialdata.utils.getBoundingBoxForShapefile	(		shapefileName,
			buffer = 0.0
	)

Return the bounding box, in WGS84 (EPSG:4326) coordinates, for the ESRI shapefile.

     Assumes shapefile exists and is readable.
     Based on http://svn.osgeo.org/gdal/trunk/gdal/swig/python/samples/ogrinfo.py

Parameters

shapefileName	String representing the path of the shapefile whose bounding box should be determined.
buffer	Float >= 0.0 representing number of degrees by which to buffer the bounding box; 0.0 = no buffer, 0.01 = 0.01 degree buffer

Returns

A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'

def ecohydroworkflowlib.spatialdata.utils.getCoordinatesOfPointsFromShapefile	(		shpFilepath,
			layerName,
			pointIDAttr,
			pointIDs
	)

Get WGS84 coordinates of point features in shapefile.

Parameters

shpFilepath	String representing the path of the shapefile
layerName	String representing the name of the layer within the shapefile from to read points
pointIDAttr	String representing name of the attribute used to identify points
pointIDs	List of strings representing IDs of coordinate pairs

Returns

Tuple of floats of the form (longitude, latitude)

def ecohydroworkflowlib.spatialdata.utils.getDimensionsForRaster

(

filename

)

Get number of columns and rows for raster.

Uses GDAL library Code adapted from: http://svn.osgeo.org/gdal/trunk/gdal/swig/python/samples/gdalinfo.py

Parameters

filename

String representing the DEM file to read pixel size and units

Returns

A tuple of the form: (columns, rows) or None if raster could not be opened

Exceptions

IOError

if filename is not readable

def ecohydroworkflowlib.spatialdata.utils.getEPSGStringForUTMZone	(		zone,
			isNorth
	)

Get EPSG string, e.g.

"EPSG:32618" for UTM zone (WGS84)

Parameters

zone	Integer representing UTM zone
isNorth	True if north

Returns

String of the pattern "^EPSG:\d+$"

def ecohydroworkflowlib.spatialdata.utils.getMeterConversionFactorForLinearUnitOfGMLfile

(

gmlFilename

)

Get conversion factor for converting a GML file's linear unit into meters.

Parameters

gmlFilename

String representing the GML file

Returns

Float representing the conversion factor

     @exception IOError(errno.EACCES) if the GML file cannot be opened

def ecohydroworkflowlib.spatialdata.utils.getMeterConversionFactorForLinearUnitOfShapefile

(

shpFilename

)

Get conversion factor for converting a shapefile's linear unit into meters.

Parameters

shpFilename

String representing the name of the shapefile

Returns

Float representing the conversion factor

     @exception IOError(errno.EACCES) if the shapefile cannot be opened

def ecohydroworkflowlib.spatialdata.utils.getSpatialReferenceForRaster

(

filename

)

Get pixel size and unit for DEM.

Uses GDAL library Code adapted from: http://svn.osgeo.org/gdal/trunk/gdal/swig/python/samples/gdalinfo.py

Parameters

filename

String representing the DEM file to read pixel size and units

Returns

A tuple of the form: (pixelWidth, pixelHeight, linearUnitsName, linearUnitsConversionFactor, WKT SRS string, EPSG SRS string)

Exceptions

IOError

if filename is not readable

def ecohydroworkflowlib.spatialdata.utils.getUTMZoneFromCoordinates	(		longitude,
			latitude
	)

Determine the UTM zone for coordinate pair.

Parameters

longitude	Float representing WGS84 longitude
latitude	Float representing WGS84 latitude

Returns

Tuple of the form (zone number, true if north)

def ecohydroworkflowlib.spatialdata.utils.isCoordinatePairInBoundingBox	(		bbox,
			coordinates
	)

Determine whether coordinate pair lies within bounding box.

Parameters

bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'
coordinates	List of tuples of floats of the form (longitude, latitude), in WGS84

Returns

True if coordinates pair is within bounding box

def ecohydroworkflowlib.spatialdata.utils.resampleRaster	(		config,
			outputDir,
			inRasterFilepath,
			outRasterFilename,
			s_srs,
			t_srs,
			trX,
			trY,
			resampleMethod = 'bilinear'
	)

Resample raster from one spatial reference system and resolution to another.

Note

Output raster will be in LZW-compressed GeoTIFF file.

Will silently return if output raster already exists.

Parameters

config	Python ConfigParser containing the section 'GDAL/OGR' and option 'PATH_OF_GDAL_WARP'
outputDir	String representing the absolute/relative path of the directory into which output raster should be written
inRasterFilepath	String representing the path of the input raster
outRasterFilename	String representing the name of the output raster
s_srs	String representing the spatial reference of the input raster, if s_srs is None, the input raster's spatial reference
t_srs	String representing the spatial reference of the output raster
trX	Float representing the X resolution of the output raster (in target spatial reference units)
trY	Float representing the Y resolution of the output raster (in target spatial reference units)
resampleMethod	String representing resampling method to use. Must be one of spatialdatalib.utils.RASTER_RESAMPLE_METHOD. @exception ConfigParser.NoSectionError @exception ConfigParser.NoOptionError @exception IOError(errno.ENOTDIR) if outputDir is not a directory @exception IOError(errno.EACCESS) if outputDir is not writable @exception ValueError if trX or trY are not floating point numbers greater than 0 @exception Exception if a gdal_warp command fails

def ecohydroworkflowlib.spatialdata.utils.tileBoundingBox	(		bbox,
			threshold
	)

Break up bounding box into tiles if bounding box is larger than threshold.

     Bounding box must be defined by WGS84 lat,lon coordinates

Parameters

bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'
threshold	Float representing threshold area above which bounding box will be tiled. Units: sq. meters

Returns

A list containing tiles defined as a dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'

def ecohydroworkflowlib.spatialdata.utils.transformCoordinates	(		sourceX,
			sourceY,
			t_srs,
			s_srs = "EPSG:4326"
	)

Transform a pair of X,Y coordinates from one reference system to another.

Parameters

sourceX	A float representing the X coordinate
sourceY	A float representing the Y coordinate
t_srs	A string representing the spatial reference system of the output coordinates
s_srs	A string representing the spatial reference system, in EPSG format, of the input coordinates

Returns

A tuple of floats representing the transformed coordinates

def ecohydroworkflowlib.spatialdata.utils.writeBboxPolygonToShapefile	(		bbox,
			outputDir,
			layerName
	)

Write bbox to a shapfile.

Parameters

bbox	A dict containing keys: minX, minY, maxX, maxY, srs, where srs='EPSG:4326'
outputDir	String representing the absolute/relative path of the directory into which shapefile should be written
layerName	String representing the name of the layer. Will be used as root of filename of output shapefile

Returns

String representing the name of shapefile created (not the absolute path)

     @raise IOError is output directory is not a writable directory
     @raise Exception if shapefile already exists
     @raise Exception is failed to create shapefile

def ecohydroworkflowlib.spatialdata.utils.writeCoordinatePairsToPointShapefile	(		outputDir,
			layerName,
			pointIDAttr,
			pointIDs,
			coordinates
	)

Write coordinates as a point shapefile.

Parameters

outputDir	String representing the absolute/relative path of the directory into which shapefile should be written
layerName	String representing the name of the layer. Will be used as root of filename of output shapefile
pointIDAttr	String representing name of the attribute used to identify points
pointIDs	List of strings representing IDs of coordinate pairs
coordinates	List of tuples of floats of the form (longitude, latitude), in WGS84

Returns

String representing the name of shapefile created (not the absolute path)

     @raise IOError is output directory is not a writable directory
     @raise Exception if shapefile already exists
     @raise Exception is failed to create shapefile

Variable Documentation

list ecohydroworkflowlib.spatialdata.utils.RASTER_RESAMPLE_METHOD ['near', 'bilinear', 'cubic', 'cubicspline', 'lanczos']

int ecohydroworkflowlib.spatialdata.utils.SHP_MAXX 1

int ecohydroworkflowlib.spatialdata.utils.SHP_MAXY 3

int ecohydroworkflowlib.spatialdata.utils.SHP_MINX 0

int ecohydroworkflowlib.spatialdata.utils.SHP_MINY 2

int ecohydroworkflowlib.spatialdata.utils.WGS84_EPSG 4326

string ecohydroworkflowlib.spatialdata.utils.WGS84_EPSG_STR "EPSG:4326"