pygeoutils.geotools#

Some utilities for manipulating GeoSpatial data.

Module Contents#

class pygeoutils.geotools.Coordinates#

Generate validated and normalized coordinates in WGS84.

Parameters:

  • lon (float or list of floats) – Longitude(s) in decimal degrees.

  • lat (float or list of floats) – Latitude(s) in decimal degrees.

  • bounds (tuple of length 4, optional) – The bounding box to check of the input coordinates fall within. Defaults to WGS84 bounds.

Examples

>>> c = Coordinates([460, 20, -30], [80, 200, 10])
>>> c.points.x.tolist()
[100.0, -30.0]
property points: geopandas.GeoSeries#

Get validate coordinate as a geopandas.GeoSeries.

class pygeoutils.geotools.GeoBSpline(points, n_pts, degree=3)#

Create B-spline from a GeoDataFrame of points.

Parameters:

  • points (geopandas.GeoDataFrame or geopandas.GeoSeries) – Input points as a GeoDataFrame or GeoSeries. The results will be more accurate if the CRS is projected.

  • npts_sp (int) – Number of points in the output spline curve.

  • degree (int, optional) – Degree of the spline. Should be less than the number of points and greater than 1. Default is 3.

Examples

>>> import geopandas as gpd
>>> xl, yl = zip(
...     *[
...         (-97.06138, 32.837),
...         (-97.06133, 32.836),
...         (-97.06124, 32.834),
...         (-97.06127, 32.832),
...     ]
... )
>>> pts = gpd.GeoSeries(gpd.points_from_xy(xl, yl, crs=4326))
>>> sp = GeoBSpline(pts.to_crs(3857), 5).spline
>>> pts_sp = gpd.GeoSeries(gpd.points_from_xy(sp.x, sp.y, crs=3857))
>>> pts_sp = pts_sp.to_crs(4326)
>>> list(zip(pts_sp.x, pts_sp.y))
[(-97.06138, 32.837),
(-97.06132, 32.83575),
(-97.06126, 32.83450),
(-97.06123, 32.83325),
(-97.06127, 32.83200)]
property spline: Spline#

Get the spline as a Spline object.

pygeoutils.geotools.break_lines(lines, points, tol=0.0)#

Break lines at specified points at given direction.

Parameters:

  • lines (geopandas.GeoDataFrame) – Lines to break at intersection points.

  • points (geopandas.GeoDataFrame) – Points to break lines at. It must contain a column named direction with values up or down. This column is used to determine which part of the lines to keep, i.e., upstream or downstream of points.

  • tol (float, optional) – Tolerance for snapping points to the nearest lines in meters. The default is 0.0.

Returns:

geopandas.GeoDataFrame – Original lines except for the parts that have been broken at the specified points.

Return type:

GDFTYPE

pygeoutils.geotools.bspline_curvature(bspline, konts)#

Compute the curvature of a B-spline curve.

Notes

The formula for the curvature of a B-spline curve is:

\[\kappa = \frac{\dot{x}\ddot{y} - \ddot{x}\dot{y}}{(\dot{x}^2 + \dot{y}^2)^{3/2}}\]

where \(\dot{x}\) and \(\dot{y}\) are the first derivatives of the B-spline curve and \(\ddot{x}\) and \(\ddot{y}\) are the second derivatives of the B-spline curve. Also, the radius of curvature is:

\[\rho = \frac{1}{|\kappa|}\]
Parameters:
Returns:

  • phi (numpy.ndarray) – Angle of the tangent of the B-spline curve.

  • curvature (numpy.ndarray) – Curvature of the B-spline curve.

  • radius (numpy.ndarray) – Radius of curvature of the B-spline curve.

Return type:

tuple[FloatArray, FloatArray, FloatArray]

pygeoutils.geotools.coords_list(coords)#

Convert a single coordinate or list of coordinates to a list of coordinates.

Parameters:

coords (tuple of list of tuple) – Input coordinates

Returns:

list of tuple – List of coordinates as [(x1, y1), ...].

Return type:

list[tuple[float, float]]

pygeoutils.geotools.geo2polygon(geometry, geo_crs=None, crs=None)#

Convert a geometry to a Shapely’s Polygon and transform to any CRS.

Parameters:

  • geometry (Polygon or tuple of length 4) – Polygon or bounding box (west, south, east, north).

  • geo_crs (int, str, or pyproj.CRS, optional) – Spatial reference of the input geometry, defaults to None.

  • crs (int, str, or pyproj.CRS) – Target spatial reference, defaults to None.

Returns:

shapely.Polygon or shapely.MultiPolygon – A (Multi)Polygon in the target CRS, if different from the input CRS.

Return type:

shapely.geometry.Polygon | shapely.geometry.MultiPolygon

pygeoutils.geotools.geometry_list(geometry)#

Convert input geometry to a list of polygons, points, or lines.

pygeoutils.geotools.geometry_reproject(geom, in_crs, out_crs)#

Reproject a geometry to another CRS.

Parameters:

  • geom (list or tuple or any shapely.geometry) – Input geometry could be a list of coordinates such as [(x1, y1), ...], a bounding box like so (xmin, ymin, xmax, ymax), or any valid shapely’s geometry such as Polygon, MultiPolygon, etc..

  • in_crs (str, int, or pyproj.CRS) – Spatial reference of the input geometry

  • out_crs (str, int, or pyproj.CRS) – Target spatial reference

Returns:

same type as the input geometry – Transformed geometry in the target CRS.

Return type:

GEOM

Examples

>>> from shapely.geometry import Point
>>> point = Point(-7766049.665, 5691929.739)
>>> geometry_reproject(point, 3857, 4326).xy
(array('d', [-69.7636111130079]), array('d', [45.44549114818127]))
>>> bbox = (-7766049.665, 5691929.739, -7763049.665, 5696929.739)
>>> geometry_reproject(bbox, 3857, 4326)
(-69.7636111130079, 45.44549114818127, -69.73666165448431, 45.47699468552394)
>>> coords = [(-7766049.665, 5691929.739)]
>>> geometry_reproject(coords, 3857, 4326)
[(-69.7636111130079, 45.44549114818127)]
pygeoutils.geotools.make_bspline(x, y, n_pts, k=3)#

Create a B-spline curve from a set of points.

Parameters:

  • x (numpy.ndarray) – x-coordinates of the points.

  • y (numpy.ndarray) – y-coordinates of the points.

  • n_pts (int) – Number of points in the output spline curve.

  • k (int, optional) – Degree of the spline. Should be an odd number less than the number of points and greater than 1. Default is 3.

Returns:

Spline – A Spline object with x, y, phi, radius, distance, and line attributes. The line attribute returns the B-spline as a shapely.LineString.

Return type:

Spline

pygeoutils.geotools.multi2poly(gdf)#

Convert multipolygons to polygon and fill holes, if any.

Notes

This function tries to convert multipolygons to polygons by first checking if multiploygons can be directly converted using their exterior boundaries. If not, will try to remove very small sub-polygons that their area is less than 1% of the total area of the multipolygon. If this fails, the original multipolygon will be returned.

Parameters:

gdf (geopandas.GeoDataFrame or geopandas.GeoSeries) – A GeoDataFrame or GeoSeries with (multi)polygons. This will be more accurate if the CRS is projected.

Returns:

geopandas.GeoDataFrame or geopandas.GeoSeries – A GeoDataFrame or GeoSeries with polygons (and multipolygons).

Return type:

GDFTYPE

pygeoutils.geotools.nested_polygons(gdf)#

Get nested polygons in a GeoDataFrame.

Parameters:

gdf (geopandas.GeoDataFrame or geopandas.GeoSeries) – A GeoDataFrame or GeoSeries with (multi)polygons.

Returns:

dict – A dictionary where keys are indices of larger ploygons and values are a list of indices of smaller polygons that are contained within the larger polygons.

Return type:

dict[int | str, list[int | str]]

pygeoutils.geotools.query_indices(tree_gdf, input_gdf, predicate='intersects')#

Find the indices of the input_geo that intersect with the tree_geo.

Parameters:
Returns:

dict – A dictionary of the indices of the input_gdf that intersect with the tree_gdf. Keys are the index of input_gdf and values are a list of indices of the intersecting tree_gdf.

Return type:

dict[Any, list[Any]]

pygeoutils.geotools.smooth_linestring(line, crs, n_pts, degree=3)#

Smooth a line using B-spline interpolation.

Parameters:

  • line (shapely.LineString) – Line to smooth. Note that MultiLineString is not supported.

  • crs (int, str, or pyproj.CRS) – CRS of the input line. It must be a projected CRS.

  • n_pts (int) – Number of points in the output spline curve.

  • degree (int, optional) – Degree of the spline. Should be less than the number of points and greater than 1. Default is 3.

Returns:

Spline – A Spline object with x, y, phi, radius, distance, and line attributes. The line attribute returns the B-spline as a shapely.LineString.

Return type:

Spline

Examples

>>> import pygeoutils as pgu
>>> import geopandas as gpd
>>> import shapely
>>> line = shapely.geometry.LineString(
...     [
...         (-97.06138, 32.837),
...         (-97.06133, 32.836),
...         (-97.06124, 32.834),
...         (-97.06127, 32.832),
...     ]
... )
>>> line = pgu.geometry_reproject(line, 4326, 5070)
>>> sp = pgu.smooth_linestring(line, 5070, 5)
>>> line_sp = pgu.geometry_reproject(sp.line, 5070, 4326)
>>> list(zip(*line_sp.xy))
[(-97.06138, 32.837),
(-97.06132, 32.83575),
(-97.06126, 32.83450),
(-97.06123, 32.83325),
(-97.06127, 32.83200)]
pygeoutils.geotools.snap2nearest(lines, points, tol)#

Find the nearest points on a line to a set of points.

Parameters:
Returns:

geopandas.GeoDataFrame or geopandas.GeoSeries – Points snapped to lines.

Return type:

GDFTYPE