General Spatial Tools

cmap_mpl2gdal	convert a matplotlib color table to a GDAL representation.
coordinate_reproject	reproject a coordinate from one CRS to another
crsConvert	convert between different types of spatial reference representations
gdal_rasterize	a simple wrapper for osgeo.gdal.Rasterize()
gdal_translate	a simple wrapper for osgeo.gdal.Translate()
gdalbuildvrt	a simple wrapper for osgeo.gdal.BuildVRT()
gdalwarp	a simple wrapper for osgeo.gdal.Warp()
haversine	compute the distance in meters between two points in latlon
iter_geometries	Iterate over the simple geometry parts of an OGR geometry.
iter_points	Iterate over all vertices of an OGR geometry.
latlon_clamp	Clamp latitude and longitude values to the range [-180, 180] and [-90, 90] respectively.
latlon_extent_center	Compute the center of a (potentially antimeridian-crossing) extent.
latlon_normalize	Normalize latitude and longitude values to the range [-180, 180] and [-90, 90] respectively.
longitude_shortest_interval	Get the shortest circular interval containing all longitudes.
ogr2ogr	a simple wrapper for osgeo.gdal.VectorTranslate() aka ogr2ogr
utm_autodetect	get the UTM CRS for a spatial object

spatialist.auxil.cmap_mpl2gdal(mplcolor, values)

convert a matplotlib color table to a GDAL representation.

Parameters:

• mplcolor (str) – a color table code

• values (list[int] | range) – the integer data values for which to retrieve colors

Returns:

the color table in GDAL format

Return type:

ColorTable

Note

This function is currently only developed for handling discrete integer data values in an 8 Bit file. Colors are thus scaled between 0 and 255.

Examples

>>> from osgeo import gdal
>>> from spatialist.auxil import cmap_mpl2gdal
>>> values = list(range(0, 100))
>>> cmap = cmap_mpl2gdal(mplcolor='YlGnBu', values=values)
>>> print(isinstance(cmap, gdal.ColorTable))
True

spatialist.auxil.coordinate_reproject(x, y, s_crs, t_crs)

reproject a coordinate from one CRS to another

Parameters:

• x (float) – the X coordinate component

• y (float) – the Y coordinate component

• s_crs (int | str | SpatialReference) – the source CRS. See crsConvert() for options.

• t_crs (int | str | SpatialReference) – the target CRS. See crsConvert() for options.

Return type:

tuple[float, float]

spatialist.auxil.crsConvert(crsIn, crsOut, wkt_format='DEFAULT')

convert between different types of spatial reference representations

Parameters:

• crsIn (int | str | SpatialReference) – the input CRS

• crsOut (Literal['epsg', 'opengis', 'osr', 'prettyWkt', 'proj4', 'wkt']) – the output CRS type

• wkt_format (str) – the format of the wkt string. See here for options: https://gdal.org/api/ogrspatialref.html#_CPPv4NK19OGRSpatialReference11exportToWktEPPcPPCKc

Return type:

int | str | SpatialReference

Returns:

the output CRS

Examples

convert an integer EPSG code to PROJ.4:

>>> crsConvert(4326, 'proj4')
'+proj=longlat +datum=WGS84 +no_defs '

convert the opengis URL back to EPSG:

>>> crsConvert('https://www.opengis.net/def/crs/EPSG/0/4326', 'epsg')
4326

convert an EPSG compound CRS (WGS84 horizontal + EGM96 vertical) to PROJ.4

>>> crsConvert('EPSG:4326+5773', 'proj4')
'+proj=longlat +datum=WGS84 +geoidgrids=us_nga_egm96_15.tif +vunits=m +no_defs'

spatialist.auxil.gdal_rasterize(src, dst, **kwargs)

a simple wrapper for osgeo.gdal.Rasterize()

Parameters:

• src (str | Dataset) – the input data set

• dst (str) – the output data set

• **kwargs (Any) – Additional parameters passed to osgeo.gdal.Rasterize(). See osgeo.gdal.RasterizeOptions().

Return type:

None

spatialist.auxil.gdal_translate(src, dst, void=True, **kwargs)

a simple wrapper for osgeo.gdal.Translate()

Parameters:

• src (str | Dataset) – the input data set

• dst (str) – the output data set

• void (bool) – just write the results and don’t return anything? If not, the spatial object is returned.

• **kwargs (Any) – additional parameters passed to osgeo.gdal.Translate(); see osgeo.gdal.TranslateOptions()

Return type:

Dataset | None

spatialist.auxil.gdalbuildvrt(src, dst, void=True, **kwargs)

a simple wrapper for osgeo.gdal.BuildVRT()

Parameters:

• src (str | Dataset | list[str | Dataset]) – the input data set(s)

• dst (str) – the output data set

• void (bool) – just write the results and don’t return anything? If not, the spatial object is returned.

• **kwargs (Any) – additional parameters passed to osgeo.gdal.BuildVRT(); see osgeo.gdal.BuildVRTOptions()

Return type:

Dataset | None

spatialist.auxil.gdalwarp(src, dst, pbar=False, **kwargs)

a simple wrapper for osgeo.gdal.Warp()

Parameters:

• src (str | Dataset | list[str | Dataset]) – the input data set

• dst (str) – the output data set

• pbar (bool) – add a progressbar?

• **kwargs (Any) – additional parameters passed to osgeo.gdal.Warp(); see osgeo.gdal.WarpOptions()

Return type:

None

spatialist.auxil.haversine(lat1, lon1, lat2, lon2)

compute the distance in meters between two points in latlon

Parameters:

• lat1 (float) – the latitude of point 1

• lon1 (float) – the longitude of point 1

• lat2 (float) – the latitude of point 2

• lon2 (float) – the longitude of point 2

Return type:

float

Returns:

the distance between point 1 and point 2 in meters

spatialist.auxil.iter_geometries(geom)

Iterate over the simple geometry parts of an OGR geometry.

Multi-geometries and geometry collections are recursively unpacked. Polygons are treated as atomic geometries, i.e. their exterior and interior rings are not yielded separately.

Parameters:

geom (Geometry | None) – The input geometry.

Yields:

ogr.Geometry – Individual simple geometry parts. The yielded geometries are references to parts of the input geometry and are not cloned.

spatialist.auxil.iter_points(geom)

Iterate over all vertices of an OGR geometry.

Nested geometries such as polygons, multi-geometries, and geometry collections are traversed recursively.

Parameters:

geom (Geometry | None) – The input geometry.

Yields:

tuple[float, …] – Coordinate tuples of the geometry vertices. Depending on the dimensionality of the input geometry, tuples may contain two or more coordinate components, e.g., (x, y) or (x, y, z).

spatialist.auxil.latlon_clamp(lat=None, lon=None)

Clamp latitude and longitude values to the range [-180, 180] and [-90, 90] respectively.

Parameters:

• lat (int | float | None) – the latitude

• lon (int | float | None) – the longitude

Return type:

float

Examples

>>> latlon_clamp(lon=200)
180.0

spatialist.auxil.latlon_extent_center(extent)

Compute the center of a (potentially antimeridian-crossing) extent.

Parameters:

extent (dict[str, int | float]) – the extent object

Return type:

tuple[float, float]

Returns:

(x, y)

spatialist.auxil.latlon_normalize(lat=None, lon=None)

Normalize latitude and longitude values to the range [-180, 180] and [-90, 90] respectively.

Parameters:

• lat (int | float | None) – the latitude

• lon (int | float | None) – the longitude

Return type:

float

Examples

>>> latlon_normalize(lon=200)
-160.0

spatialist.auxil.longitude_shortest_interval(longitudes)

Get the shortest circular interval containing all longitudes.

Longitudes are normalized to the range [-180, 180]. If the shortest interval crosses the antimeridian, the returned minimum is greater than the returned maximum.

Parameters:

longitudes (list[int | float]) – The longitude coordinates.

Returns:

The bounds of the shortest circular longitude interval.

Return type:

tuple[int | float, int | float]

Raises:

ValueError – If longitudes is empty.

Examples

>>> longitude_shortest_interval([170, -170])
(170.0, -170.0)

>>> longitude_shortest_interval([-10, 10])
(-10.0, 10.0)

spatialist.auxil.ogr2ogr(src, dst, void=True, **kwargs)

a simple wrapper for osgeo.gdal.VectorTranslate() aka ogr2ogr

Parameters:

• src (str | Dataset) – the input data set

• dst (str) – the output data set

• void (bool) – just write the results and don’t return anything? If not, the spatial object is returned.

• **kwargs (Any) – additional parameters passed to osgeo.gdal.VectorTranslate(); see osgeo.gdal.VectorTranslateOptions()

Return type:

Dataset | None

spatialist.auxil.utm_autodetect(spatial, crsOut)

get the UTM CRS for a spatial object

The bounding box of the object is extracted, reprojected to EPSG:4326 and its center coordinate used for computing the best UTM zone fit. In case the reprojected geometry crosses the antimeridian, the coordinates are first shifted to a 0-360° space.

Parameters:

• spatial (Raster | Vector) – a spatial object in an arbitrary CRS

• crsOut (str) – the output CRS type; see function crsConvert() for options

Returns:

the output CRS

Return type:

int | str | SpatialReference