API documentation#

Fix antimeridian crossings in GeoJSON objects and shapely geometries.

exception antimeridian.FixWindingWarning#: The input shape is wound clockwise (instead of counter-clockwise), so this package is reversing the winding order before fixing the shape.

class antimeridian.GeoInterface(*args, **kwargs)#

A simple protocol for things that have a __geo_interface__ method.

The __geo_interface__ protocol is described here, and is used within shapely to extract geometries from objects.

antimeridian.bbox(shape: Dict[str, Any] | GeoInterface) → List[float]#

Calculates a GeoJSON-spec conforming bounding box for a shape.

Per the GeoJSON spec, an antimeridian-spanning bounding box should have its larger longitude as its first bounding box coordinate.

Parameters:: shape – The polygon or multipolygon for which to calculate the bounding box.
Returns:: The bounding box.
Return type:: List[float]

antimeridian.centroid(shape: Dict[str, Any] | GeoInterface) → Point#

Calculates the centroid for a polygon or multipolygon.

Polygons are easy, we just use shapely.centroid(). For multi-polygons, the antimeridian is taken into account by calculating the centroid from an identical multi-polygon with coordinates in [0, 360).

Parameters:: shape – The polygon or multipolygon for which to calculate the centroid.
Returns:: The centroid.
Return type:: Point

antimeridian.fix_geojson(geojson: Dict[str, Any], *, force_north_pole: bool = False, force_south_pole: bool = False, fix_winding: bool = True) → Dict[str, Any]#

Fixes a GeoJSON object that crosses the antimeridian.

If the object does not cross the antimeridian, it is returned unchanged.

See fix_polygon() for a description of the force_north_pole, force_south_pole, and fix_winding arguments.

Parameters:

geojson – A GeoJSON object as a dictionary
force_north_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the north pole.
force_south_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the south pole.
fix_winding – If the polygon is wound clockwise, reverse its coordinates before applying the algorithm.

Returns:

The same GeoJSON with a fixed geometry or geometries

antimeridian.fix_line_string(line_string: LineString) → LineString | MultiLineString#

Fixes a shapely.geometry.LineString.

Parameters:: line_string – The input line string
Returns:: The fixed line string, either as a single line string or a multi-line string (if it was split)

antimeridian.fix_multi_line_string(multi_line_string: MultiLineString) → MultiLineString#

Fixes a shapely.geometry.MultiLineString.

Parameters:: multi_line_string – The input multi line string
Returns:: The fixed multi line string

antimeridian.fix_multi_polygon(multi_polygon: MultiPolygon, *, force_north_pole: bool = False, force_south_pole: bool = False, fix_winding: bool = True) → MultiPolygon#

Fixes a shapely.geometry.MultiPolygon.

See fix_polygon() for a description of the force_north_pole, force_south_pole, and fix_winding arguments.

Parameters:

multi_polygon – The multi-polygon
force_north_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the north pole.
force_south_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the south pole.
fix_winding – If the polygon is wound clockwise, reverse its coordinates before applying the algorithm.

Returns:

The fixed multi-polygon

antimeridian.fix_polygon(polygon: Polygon, *, force_north_pole: bool = False, force_south_pole: bool = False, fix_winding: bool = True) → Polygon | MultiPolygon#

Fixes a shapely.geometry.Polygon.

If the input polygon is wound clockwise, it will be fixed to be wound counterclockwise _unless_ fix_winding is False, in which case it will be corrected by adding a counterclockwise polygon from (-180, -90) to (180, 90) as its exterior.

In rare cases, the underlying algorithm might need a little help to fix the polygon. For example, a polygon that just barely crosses over a pole might have very few points at high latitudes, leading to ambiguous antimeridian crossing points and invalid geometries. We provide two flags, force_north_pole and force_south_pole, for those cases. Most users can ignore these flags.

If either force_north_pole or force_south_pole is True, fix_winding is set to False.

Parameters:

polygon – The input polygon
force_north_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the north pole.
force_south_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the south pole.
fix_winding – If the polygon is wound clockwise, reverse its coordinates before applying the algorithm.

Returns:

The fixed polygon, either as a single polygon or a multi-polygon (if it was split)

antimeridian.fix_shape(shape: Dict[str, Any] | GeoInterface, *, force_north_pole: bool = False, force_south_pole: bool = False, fix_winding: bool = True) → Dict[str, Any]#

Fixes a shape that crosses the antimeridian.

See fix_polygon() for a description of the force_north_pole, force_south_pole, and fix_winding arguments.

Parameters:

shape – A polygon, multi-polygon, line string, or multi-line string, either as a dictionary or as a GeoInterface. Uses shapely.geometry.shape() under the hood.
force_north_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the north pole.
force_south_pole – If the polygon crosses the antimeridian, force the joined segments to enclose the south pole.
fix_winding – If the polygon is wound clockwise, reverse its coordinates before applying the algorithm.

Returns:

The fixed shape as a dictionary

antimeridian.segment_geojson(geojson: Dict[str, Any]) → MultiLineString#

Segments a GeoJSON object into a MultiLineString.

If the object does not cross the antimeridian, its exterior and interior line strings are returned unchanged.

Parameters:: geojson – A GeoJSON object as a dictionary
Returns:: A MutliLineString of segments.