geopandas.GeoSeries.snap#

GeoSeries.snap(other, tolerance, align=None)[source]#

Snaps an input geometry to reference geometry’s vertices.

Vertices of the first geometry are snapped to vertices of the second. geometry, returning a new geometry; the input geometries are not modified. The result geometry is the input geometry with the vertices snapped. If no snapping occurs then the input geometry is returned unchanged. The tolerance is used to control where snapping is performed.

Where possible, this operation tries to avoid creating invalid geometries; however, it does not guarantee that output geometries will be valid. It is the responsibility of the caller to check for and handle invalid geometries.

Because too much snapping can result in invalid geometries being created, heuristics are used to determine the number and location of snapped vertices that are likely safe to snap. These heuristics may omit some potential snaps that are otherwise within the tolerance.

The operation works in a 1-to-1 row-wise manner:

Parameters:

otherGeoSeries or geometric object: The Geoseries (elementwise) or geometric object to snap to.
tolerancefloat or array like: Maximum distance between vertices that shall be snapped
alignbool | None (default None): If True, automatically aligns GeoSeries based on their indices. If False, the order of elements is preserved. None defaults to True.

Returns:

GeoSeries

Examples

>>> from shapely import Polygon, LineString, Point
>>> s = geopandas.GeoSeries(
...     [
...         Point(0.5, 2.5),
...         LineString([(0.1, 0.1), (0.49, 0.51), (1.01, 0.89)]),
...         Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)]),
...     ],
... )
>>> s
0                               POINT (0.5 2.5)
1    LINESTRING (0.1 0.1, 0.49 0.51, 1.01 0.89)
2       POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))
dtype: geometry

>>> s2 = geopandas.GeoSeries(
...     [
...         Point(0, 2),
...         LineString([(0, 0), (0.5, 0.5), (1.0, 1.0)]),
...         Point(8, 10),
...     ],
...     index=range(1, 4),
... )
>>> s2
1                       POINT (0 2)
2    LINESTRING (0 0, 0.5 0.5, 1 1)
3                      POINT (8 10)
dtype: geometry

We can snap each geometry to a single shapely geometry:

>>> s.snap(Point(0, 2), tolerance=1)
0                                     POINT (0 2)
1      LINESTRING (0.1 0.1, 0.49 0.51, 1.01 0.89)
2    POLYGON ((0 0, 0 2, 0 10, 10 10, 10 0, 0 0))
dtype: geometry

We can also snap two GeoSeries to each other, row by row. The GeoSeries above have different indices. We can either align both GeoSeries based on index values and snap elements with the same index using align=True or ignore index and snap elements based on their matching order using align=False:

>>> s.snap(s2, tolerance=1, align=True)
0                                                 None
1           LINESTRING (0.1 0.1, 0.49 0.51, 1.01 0.89)
2    POLYGON ((0.5 0.5, 1 1, 0 10, 10 10, 10 0, 0.5...
3                                                 None
dtype: geometry

>>> s.snap(s2, tolerance=1, align=False)
0                                      POINT (0 2)
1                   LINESTRING (0 0, 0.5 0.5, 1 1)
2    POLYGON ((0 0, 0 10, 8 10, 10 10, 10 0, 0 0))
dtype: geometry