GeoTools¶
Geospatial Functions for Hydraulics and Morphodynamics
geotools
provides Python3 functions for many sorts of river-related analyses with geospatial data. The package is intended as support material for the lecture Python programming for Water Resources Engineering and Research, where primarily conda environments are used.
Note
This documentation is also as available as style-adapted PDF (download).
Usage¶
Example (code block)¶
from flusstools import geotools as gt
raster, array, geo_transform = gt.raster2array("/sample-data/froude.tif")
type(raster)
# >>> <class 'osgeo.gdal.Dataset'>
type(array)
# >>> <class 'numpy.ndarray'>
type(geo_transform)
# >>> <class 'tuple'>
print(geo_transform)
# >>> (6748604.7742, 3.0, 0.0, 2207317.1771, 0.0, -3.0)
Example (showcase)¶
A showcase is provided with the ROOT/examples/geotools-showcase/georeference_tifs.py script that illustrates geo-referencing tif images that do not have a projection assigned.
Code structure¶
The following diagram highlights function locations in Python scripts and how those are linked to each other.

Fig. 1 Diagram of the code structure (needs to be updated).¶
Script and function docs¶
geotools
(MASTER)¶
geo_utils
is a package for creating, modifying, and transforming geo-spatial datasets.
A detailed documentation of geo_utils
is available at geo-utils.readthedocs.io.
-
flusstools.geotools.geotools.
float2int
(raster_file_name, band_number=1)[source]¶ Converts a float number raster to an integer raster (required for converting a raster to a polygon shapefile).
-
flusstools.geotools.geotools.
raster2line
(raster_file_name, out_shp_fn, pixel_value)[source]¶ Converts a raster to a line shapefile, where
pixel_value
determines line start and end points.
-
flusstools.geotools.geotools.
raster2polygon
(file_name, out_shp_fn, band_number=1, field_name='values')[source]¶ Converts a raster to a polygon shapefile.
- Parameters
file_name (str) – Target file name, including directory; must end on
".tif"
out_shp_fn (str) – Shapefile name (with directory e.g.,
"C:/temp/poly.shp"
)band_number (int) – Raster band number to open (default:
1
)field_name (str) – Field name where raster pixel values will be stored (default:
"values"
)add_area – If
True
, an “area” field will be added, where the area in the shapefiles unit system is calculated (default:False
)
-
flusstools.geotools.geotools.
rasterize
(in_shp_file_name, out_raster_file_name, pixel_size=10, no_data_value=- 9999, rdtype=gdal.GDT_Float32, overwrite=True, interpolate_gap_pixels=False, **kwargs)[source]¶ Converts any ESRI shapefile to a raster.
- Parameters
in_shp_file_name (str) – A shapefile name (with directory e.g.,
"C:/temp/poly.shp"
)out_raster_file_name (str) – Target file name, including directory; must end on
".tif"
pixel_size (float) – Pixel size as multiple of length units defined in the spatial reference (default:
10
)no_data_value (int OR float) – Numeric value for no-data pixels (default:
-9999
)rdtype (gdal.GDALDataType) – The raster data type (default:
gdal.GDT_Float32
(32 bit floating point)overwrite (bool) – Overwrite existing files (default:
True
)interpolate_gap_pixels (bool) – Fill empty pixels that are not touched by a shapefile element with interpolated values (default:
False
)
- Keyword Arguments
field_name (str) – Name of the shapefile’s field with values to burn to raster pixel values.
radius1 (float) – Define the x-radius for interpolating pixels (default:
-1
, corresponding to infinity). Only applicablewith interpolate_gap_pixels
.radius2 (float) – Define the y-radius for interpolating pixels (default:
-1
, corresponding to infinity). Only applicablewith interpolate_gap_pixels
.power (float) – Power of the function for interpolating pixel values (default:
1.0
, corresponding to linear).smoothing (float) – Smoothing parameter for interpolating pixel values (default:
0.0
).min_points (int) – Minimum number of points to use for interpolation. If the interpolator cannot find at least
min_points
for a pixel, it assigns ano_data
value to that pixel (default:0
).max_points (int) – Maximum number of points to use for interpolation. The interpolator will not use more than
max_points
closest points to interpolate a pixel value (default:0
).
- Hints:
More information on pixel value interpolation: *
interpolate_gap_pixels=True
interpolates values at pixels that are not touched by any las point. * The pixel value interpolation usesgdal_grid
(i.e., its Python bindings throughgdal.Grid()
). * Control the interpolation parameters with the keyword argumentsradius1
,radius2
,power
,max_points
,min_points
, andsmoothing
..
- Returns
Creates the GeoTIFF raster defined with
out_raster_file_name
(success:0
, otherwiseNone
).- Return type
raster_mgmt
raster management¶
-
flusstools.geotools.raster_mgmt.
clip_raster
(polygon, in_raster, out_raster)[source]¶ Clips a raster to a polygon.
- Parameters
- Returns
Creates a new, clipped raster defined with
out_raster
.- Return type
-
flusstools.geotools.raster_mgmt.
create_raster
(file_name, raster_array, bands=1, origin=None, epsg=4326, pixel_width=10.0, pixel_height=10.0, nan_val=- 9999.0, rdtype=gdal.GDT_Float32, geo_info=False, rotation_angle=None, shear_pixels=True, options=['PROFILE=GeoTIFF'])[source]¶ Converts an
ndarray
(numpy.array
) to a GeoTIFF raster.- Parameters
file_name (str) – Target file name, including directory; must end on
".tif"
.raster_array (
ndarray
orlist
) – Array or list of arrays of values to rasterize. If a list of arrays is provided, the length of the list will correspond to the number of bands added to the raster (supersedesbands
).bands (int) – Number of bands to write to the raster (default:
1
).origin (tuple) – Coordinates (x, y) of the origin.
epsg (int) – EPSG:XXXX projection to use (default:
4326
).pixel_height (float OR int) – Pixel height as multiple of the base units defined with the EPSG number (default:
10
meters).pixel_width (float OR int) – Pixel width as multiple of the base units defined with the EPSG number (default:
10
meters).nan_val (
int
orfloat
) – No-data value to be used in the raster. Replaces non-numeric andnp.nan
in thendarray
. (default:geoconfig.nan_value
).rdtype – gdal.GDALDataType raster data type (default: gdal.GDT_Float32 (32 bit floating point).
geo_info (tuple) – Defines a
gdal.DataSet.GetGeoTransform
object and supersedesorigin
,pixel_width
,pixel_height
(default:False
).rotation_angle (float) – Rotate (in degrees) not North-up rasters. The default value (
0
) corresponds to north-up (only modify if you know what you are doing).shear_pixels (bool) – Use with
rotation_angle
to shear pixels as well (default:True
).options (list) – Raster creation options - default is [‘PROFILE=GeoTIFF’]. Add ‘PHOTOMETRIC=RGB’ to create an RGB image raster.
- Returns
0
if successful, otherwise-1
.- Return type
Hint
For processing airborne imagery, the
roation_angle
corresponds to the bearing angle of the aircraft with reference to true, not magnetic North.
-
flusstools.geotools.raster_mgmt.
open_raster
(file_name, band_number=1)[source]¶ Opens a raster file and accesses its bands.
-
flusstools.geotools.raster_mgmt.
raster2array
(file_name, band_number=1)[source]¶ Extracts an
ndarray
from a raster.- Parameters
- Returns
Indicated raster band, where no-data values are replaced with
np.nan
. GeoTransform: The GeoTransformation used in the original raster.- Return type
ndarray
-
flusstools.geotools.raster_mgmt.
remove_tif
(file_name)[source]¶ Removes a GeoTIFF and its dependent files (e.g., xml).
- Parameters
file_name (str) – Directory (path) and name of a GeoTIFF
- Returns
Removes the provided
file_name
and all dependencies.
shp_mgmt
shapefile management¶
-
flusstools.geotools.shp_mgmt.
create_shp
(shp_file_dir, overwrite=True, *args, **kwargs)[source]¶ Creates a new shapefile with an optionally defined geometry type.
- Parameters
shp_file_dir (str) – of the (relative) shapefile directory (ends on
".shp"
).overwrite (bool) – If
True
(default), existing files are overwritten.layer_name (str) – The layer name to be created. If
None
: no layer will be created.layer_type (str) – Either
"point"
,"line"
, or"polygon"
of thelayer_name
. IfNone
: no layer will be created.
- Returns
An
ogr
shapefile- Return type
osgeo.ogr.DataSource
-
flusstools.geotools.shp_mgmt.
get_geom_description
(layer)[source]¶ Gets the WKB Geometry Type as string from a shapefile layer.
- Parameters
layer (osgeo.ogr.Layer) – A shapefile layer.
- Returns
WKB (binary) geometry type
- Return type
-
flusstools.geotools.shp_mgmt.
get_geom_simplified
(layer)[source]¶ - Gets a simplified geometry description (either point, line, or polygon) as a function of
the WKB Geometry Type of a shapefile layer.
- Parameters
layer (osgeo.ogr.Layer) – A shapefile layer.
- Returns
Either WKT-formatted point, line, or polygon (or unknown if invalid layer).
- Return type
-
flusstools.geotools.shp_mgmt.
polygon_from_shapepoints
(shapepoints, polygon, alpha=nan)[source]¶ Creates a polygon around a cloud of
shapepoints
.- Parameters
- Returns
Creates the polygon shapefile defined with
polygon
.- Return type
srs_mgmt
projection management¶
-
flusstools.geotools.srs_mgmt.
get_esriwkt
(epsg)[source]¶ Gets esriwkt-formatted spatial references with epsg code online.
- Parameters
epsg (int) – EPSG Authority Code
- Returns
An esriwkt string (if an error occur, the default epsg=``4326`` is used).
- Return type
Example
get_esriwkt(4326)
-
flusstools.geotools.srs_mgmt.
get_srs
(dataset)[source]¶ Gets the spatial reference of any
gdal.Dataset
.- Parameters
dataset (gdal.Dataset) – A shapefile or raster.
- Returns
A spatial reference object.
- Return type
osr.SpatialReference
-
flusstools.geotools.srs_mgmt.
get_wkt
(epsg, wkt_format='esriwkt')[source]¶ Gets WKT-formatted projection information for an epsg code using the
osr
library.
-
flusstools.geotools.srs_mgmt.
make_prj
(shp_file_name, epsg)[source]¶ Generates a projection file for a shapefile.
-
flusstools.geotools.srs_mgmt.
reproject
(source_dataset, new_projection_dataset)[source]¶ Re-projects a dataset (raster or shapefile) onto the spatial reference system of a (shapefile or raster) layer.
- Parameters
source_dataset (gdal.Dataset) – Shapefile or raster.
new_projection_dataset (gdal.Dataset) – Shapefile or raster with new projection info.
- Returns
If the source is a raster, the function creates a GeoTIFF in same directory as
source_dataset
with a"_reprojected"
suffix in the file name.If the source is a shapefile, the function creates a shapefile in same directory as
source_dataset
with a"_reprojected"
suffix in the file name.
-
flusstools.geotools.srs_mgmt.
reproject_raster
(source_dataset, source_srs, target_srs)[source]¶ Re-projects a raster dataset. This function is called by the
reproject
function.- Parameters
source_dataset (osgeo.ogr.DataSource) – Instantiates with an
ogr.Open(SHP-FILE)
.source_srs (osgeo.osr.SpatialReference) – Instantiates with
get_srs(source_dataset)
target_srs (osgeo.osr.SpatialReference) – Instantiates with
get_srs(DATASET-WITH-TARGET-PROJECTION)
.
- Returns
Creates a new GeoTIFF raster in the same directory where
source_dataset
lives.
-
flusstools.geotools.srs_mgmt.
reproject_shapefile
(source_dataset, source_layer, source_srs, target_srs)[source]¶ Re-projects a shapefile dataset. This function is called by the
reproject
function.- Parameters
source_dataset (osgeo.ogr.DataSource) – Instantiates with
ogr.Open(SHP-FILE)
.source_layer (osgeo.ogr.Layer) – Instantiates with
source_dataset.GetLayer()
.source_srs (osgeo.osr.SpatialReference) – Instantiates with
get_srs(source_dataset)
.target_srs (osgeo.osr.SpatialReference) – Instantiates with
get_srs(DATASET-WITH-TARGET-PROJECTION)
.
- Returns
Creates a new shapefile in the same directory where
source_dataset
lives.
dataset_mgmt
dataset conversion¶
-
flusstools.geotools.dataset_mgmt.
coords2offset
(geo_transform, x_coord, y_coord)[source]¶ Returns x-y pixel offset (inverse of the
offset2coords
function).
-
flusstools.geotools.dataset_mgmt.
get_layer
(dataset, band_number=1)[source]¶ Gets a
layer=band
(RasterDataSet
) orlayer=ogr.Dataset.Layer
of any dataset.
KML/KML file management¶
Modified script (original: Linwood Creekmore III)
Examples
# output to geopandas dataframe (gdf) gdf = kmx2other(“my-places.kmz”, output=”gpd”)
# plot the new gdf (use %matplotlib inline in notebooks) gdf.plot()
# convert a kml-file to a shapefile success = kmx2other(“my-places.kml”, output=”shp”)
-
flusstools.geotools.kml.
kmx2other
(file, output='df')[source]¶ Converts a Keyhole Markup Language Zipped (KMZ) or KML file to a pandas dataframe, geopandas geodataframe, csv, geojson, or ESRI shapefile.
- Parameters
Hint
The core function is taken from http://programmingadvent.blogspot.com/2013/06/kmzkml-file-parsing-with-python.html
- Returns
object
- Return type
self
Original Classes written by Linwood Creekmore III (modified for geo_utils)
With code blocks from:
http://programmingadvent.blogspot.com/2013/06/kmzkml-file-parsing-with-python.html
http://gis.stackexchange.com/questions/159681/geopandas-cant-save-geojson
-
class
flusstools.geotools.kmx_parser.
ModHTMLParser
[source]¶ A child of HTMLParser, tailored (modified) for kml/kmy parsing.