Ctrl+K

pygeoutils.geotools

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.GeoSpline(points, n_pts, degree=3, smoothing=None)#

Create a parametric 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 smoothing spline. Must be 1 <= degree <= 5. Default to 3 which is a cubic spline.

  • smoothing (float or None, optional) – Smoothing factor is used for determining the number of knots. This arg controls the tradeoff between closeness and smoothness of fit. Larger smoothing means more smoothing while smaller values of smoothing indicates less smoothing. If None (default), smoothing is done with all points.

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 = GeoSpline(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.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.Polygon | shapely.MultiPolygon

pygeoutils.geotools.geometry_list(geometry)#

Convert input geometry to a list of Polygons, Points, or LineStrings.

Parameters:

geometry (Polygon or MultiPolygon or tuple of length 4 or list of tuples of length 2 or 3) – Input geometry could be a (Multi)Polygon, (Multi)LineString, (Multi)Point, a tuple/list of length 4 (west, south, east, north), or a list of tuples of length 2 or 3.

Returns:

list – A list of Polygons, Points, or LineStrings.

Return type:

list[shapely.Polygon] | list[shapely.Point] | list[shapely.LineString]

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

Reproject a geometry to another CRS.

Parameters:

  • geom (list or tuple or any shapely.GeometryType) – 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 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.line_curvature(line)#

Compute the curvature of a Spline curve.

Notes

The formula for the curvature of a 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 Spline curve and \(\ddot{x}\) and \(\ddot{y}\) are the second derivatives of the Spline curve. Also, the radius of curvature is:

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

line (shapely.LineString) – Line to compute the curvature at.

Returns:

  • phi (numpy.ndarray) – Angle of the tangent of the Spline curve.

  • curvature (numpy.ndarray) – Curvature of the Spline curve.

  • radius (numpy.ndarray) – Radius of curvature of the Spline curve.

Return type:

tuple[FloatArray, FloatArray, FloatArray]

pygeoutils.geotools.make_spline(x, y, n_pts, k=3, s=None)#

Create a parametric spline 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 smoothing spline. Must be 1 <= k <= 5. Default to 3 which is a cubic spline.

  • s (float or None, optional) – Smoothing factor is used for determining the number of knots. This arg controls the tradeoff between closeness and smoothness of fit. Larger s means more smoothing while smaller values of s indicates less smoothing. If None (default), smoothing is done with all data points.

Returns:

Spline – A Spline object with x, y, phi, radius, distance, and line attributes. The line attribute returns the 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 polygons 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, smoothing=None, npts=None)#

Smooth a LineString using UnivariateSpline from scipy.

Parameters:

  • line (shapely.LineString) – Centerline to be smoothed.

  • smoothing (float or None, optional) – Smoothing factor is used for determining the number of knots. This arg controls the tradeoff between closeness and smoothness of fit. Larger smoothing means more smoothing while smaller values of smoothing indicates less smoothing. If None (default), smoothing is done with all points.

  • npts (int, optional) – Number of points in the output smoothed line. Defaults to 5 times the number of points in the input line.

Returns:

shapely.LineString – Smoothed line with uniform spacing.

Return type:

shapely.LineString

Examples

>>> import geopandas as gpd
>>> import shapely
>>> line = shapely.LineString(
...     [
...         (-97.06138, 32.837),
...         (-97.06133, 32.836),
...         (-97.06124, 32.834),
...         (-97.06127, 32.832),
...     ]
... )
>>> line_smooth = smooth_linestring(line, 4326, 5)
>>> list(zip(*line_smooth.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

pygeoutils.geotools.spline_curvature(spline_x, spline_y, konts)#

Compute the curvature of a Spline curve.

Notes

The formula for the curvature of a 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 Spline curve and \(\ddot{x}\) and \(\ddot{y}\) are the second derivatives of the Spline curve. Also, the radius of curvature is:

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

  • phi (numpy.ndarray) – Angle of the tangent of the Spline curve.

  • curvature (numpy.ndarray) – Curvature of the Spline curve.

  • radius (numpy.ndarray) – Radius of curvature of the Spline curve.

Return type:

tuple[FloatArray, FloatArray, FloatArray]

pygeoutils.geotools.spline_linestring(line, crs, n_pts, degree=3, smoothing=None)#

Generate a parametric spline from a LineString.

Parameters:

  • line (shapely.LineString, shapely.MultiLineString) – Line to smooth. Note that if line is MultiLineString it will be merged into a single LineString. If the merge fails, an exception will be raised.

  • 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 smoothing spline. Must be 1 <= degree <= 5. Default to 3 which is a cubic spline.

  • smoothing (float or None, optional) – Smoothing factor is used for determining the number of knots. This arg controls the tradeoff between closeness and smoothness of fit. Larger smoothing means more smoothing while smaller values of smoothing indicates less smoothing. If None (default), smoothing is done with all points.

Returns:

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

Return type:

Spline

Examples

>>> import geopandas as gpd
>>> import shapely
>>> line = shapely.LineString(
...     [
...         (-97.06138, 32.837),
...         (-97.06133, 32.836),
...         (-97.06124, 32.834),
...         (-97.06127, 32.832),
...     ]
... )
>>> sp = spline_linestring(line, 4326, 5)
>>> list(zip(*sp.line.xy))
[(-97.06138, 32.837),
(-97.06132, 32.83575),
(-97.06126, 32.83450),
(-97.06123, 32.83325),
(-97.06127, 32.83200)]
Contents