Module gplately.geometry

This sub-module contains tools for converting PyGPlates or GPlately geometries to Shapely geometries for mapping (and vice versa).

Supported PyGPlates geometries inherit from the following classes:

• pygplates.GeometryOnSphere: This class has the following derived GeometryOnSphere classes:

  • pygplates.PointOnSphere
  • pygplates.MultiPointOnSphere
  • pygplates.PolylineOnSphere
  • pygplates.PolygonOnSphere

• pygplates.LatLonPoint

• pygplates.ReconstructedFeatureGeometry
• pygplates.ResolvedTopologicalLine
• pygplates.ResolvedTopologicalBoundary
• pygplates.ResolvedTopologicalNetwork

Note: GPlately geometries derive from the GeometryOnSphere and pygplates.GeometryOnSphere base classes.

Supported Shapely geometric objects include:

• Point: a single point in 2D space with coordinate tuple (x,y) or 3D space with coordinate tuple (x,y,z).
• LineString: a sequence of points joined together to form a line (a list of point coordinate tuples).
• Polygon: a sequence of points joined together to form the outer ring of a filled area, or a hole (a list of at least three point coordinate tuples).

Also supported are collections of geometric objects, such as:

• MultiPoint: a list of Point objects (a list of point coordinate tuples).
• MultiLineString: a list of LineString objects (a list containing lists of point coordinate tuples).
• MultiPolygon: a list of Polygon objects (a list containing lists of point coordinate tuples that define exterior rings and/or holes).

Converting PyGPlates geometries into Shapely geometries involves:

• wrapping geometries at the dateline: this involves splitting a polygon, MultiPolygon, line segment or MultiLine segment between connecting points at the dateline. This is to ensure the geometry's points are joined along the short path rather than the long path horizontally across the 2D map projection display.
• ordering geometries counter-clockwise

Input PyGPlates geometries are converted to the following Shapely geometries:

• PointOnSphere or LatLonPoint: Point
• MultiPointOnSphere: MultiPoint
• PolylineOnSphere: LineString or MultiLineString
• PolygonOnSphere: Polygon or MultiPolygon

Converting Shapely geometries into PyGPlates geometries: Input Shapely geometries are converted to the following PyGPlates geometries:

• Point: PointOnSphere
• MultiPoint: MultiPointOnSphere
• LineString: PolylineOnSphere
• LinearRing or Polygon: PolygonOnSphere

Functions

def pygplates_to_shapely(geometry, central_meridian=0.0, tessellate_degrees=None, validate=False, force_ccw=False, explode=False)

Convert one or more PyGPlates or GPlately geometries to Shapely format.

Parameters

geometry : pygplates.GeometryOnSphere or pygplates.LatLonPoint or list

The geometry or geometries to convert.

central_meridian : float, default: 0.0

The central meridian around which to wrap geometries; geometries will be split at the antimeridian.

tessellate_degrees : float, optional

If provided, the geometry will be tessellated to this resolution prior to conversion.

validate : bool, default: False

Attempt to ensure output geometry is valid by applying a buffer of 0.

force_ccw : bool, default: False

Ensure the coordinates of the output geometry are counter-clockwise(only applies to polygons).

explode : bool, default: False

Convert multi-part output geometries to multiple single-part geometries.

Returns

output_geometry : shapely.geometry.base.BaseGeometry or list

Converted Shapely geometry or geometries.

Notes

If a single input geometry was passed, output_geometry will be a subclass of shapely.geometry.base.BaseGeometry. Otherwise, output_geometry will be a list of the same length as the input.

Input geometries that were split while wrapping around central_meridian will produce multi-part output geometries, unless explode=True is specified.

Input geometry types are converted as follows: - PointOnSphere or LatLonPoint: Point - MultiPointOnSphere: MultiPoint - PolylineOnSphere: LineString or MultiLineString - PolygonOnSphere: Polygon or MultiPolygon

def shapely_to_pygplates(geometry)

Convert one or more Shapely geometries to gplately format.

Parameters

geometry : shapely.geometry.base.BaseGeometry or list

The geometry or geometries to convert.

Returns

output_geometry : GeometryOnSphere or list

Converted gplately geometry or geometries.

Notes

If a single input geometry was passed, output_geometry will be a subclass of GeometryOnSphere. Otherwise, output_geometry will be a list of GeometryOnSphere, of the same length as the input.

Input geometry types are converted as follows: - Point: PointOnSphere - MultiPoint: MultiPointOnSphere - LineString: PolylineOnSphere - LinearRing or Polygon: PolygonOnSphere

Multi-part input geometry types other than MultiPoint will be treated as an iterable of their component single-part geometries.

def wrap_geometries(geometries, central_meridian=0.0, tessellate_degrees=None, validate=False, force_ccw=False, explode=False)

Wrap one or more Shapely geometries around a central meridian.

Wrapped geometries will be split at the antimeridian.

Parameters

geometry : shapely.geometry.base.BaseGeometry or list

The geometry or geometries to wrap.

central_meridian : float, default: 0.0

The central meridian around which to wrap geometries; geometries will be split at the antimeridian.

tessellate_degrees : float, optional

If provided, the geometry will be tessellated to this resolution prior to wrapping.

validate : bool, default: False

Attempt to ensure output geometry is valid by applying a buffer of 0.

force_ccw : bool, default: False

Ensure the coordinates of the output geometry are counter-clockwise(only applies to polygons).

explode : bool, default: False

Convert multi-part output geometries to multiple single-part geometries.

Returns

output_geometries : shapely.geometry.base.BaseGeometry or list

Wrapped Shapely geometry or geometries.

Notes

If a single input geometry was passed, output_geometry will be a subclass of shapely.geometry.base.BaseGeometry. Otherwise, output_geometry will be a list of the same length as the input, unless explode=True is specified.

Input geometries that were split while wrapping around central_meridian will produce multi-part output geometries, unless explode=True is specified.

Classes

class GeometryOnSphere (...)

Class to mix in to_shapely method to all GPlately geometry classes.

All GPlately geometry classes inherit from this class, in addition to their PyGPlates base class.

Raises an exception This class cannot be instantiated from Python

Expand source code

class GeometryOnSphere(pygplates.GeometryOnSphere):
    """Class to mix in `to_shapely` method to all GPlately geometry classes.

    All GPlately geometry classes inherit from this class, in addition
    to their PyGPlates base class.
    """

    def to_shapely(
        self,
        central_meridian=0.0,
        tessellate_degrees=None,
        validate=False,
        force_ccw=False,
        explode=False,
    ):
        """Convert to Shapely geometry.

        See Also
        --------
        pygplates_to_shapely : Equivalent function.
        """
        return pygplates_to_shapely(
            self,
            central_meridian=central_meridian,
            tessellate_degrees=tessellate_degrees,
            validate=validate,
            force_ccw=force_ccw,
            explode=explode,
        )

    @classmethod
    def from_shapely(cls, geom):
        converted = shapely_to_pygplates(geom)
        return cls(converted)

Ancestors

• pygplates.pygplates.GeometryOnSphere
• Boost.Python.instance

Subclasses

• MultiPointOnSphere
• PointOnSphere
• PolygonOnSphere
• PolylineOnSphere

Static methods

def from_shapely(geom)

Methods

def to_shapely(self, central_meridian=0.0, tessellate_degrees=None, validate=False, force_ccw=False, explode=False)

Convert to Shapely geometry.

See Also

pygplates_to_shapely()

Equivalent function.

class LatLonPoint (...)

GPlately equivalent of pygplates.LatLonPoint, incorporating to_shapely method

Expand source code

class LatLonPoint(pygplates.LatLonPoint):
    """GPlately equivalent of `pygplates.LatLonPoint`, incorporating
    `to_shapely` method
    """

    def to_shapely(self, central_meridian=0.0, tessellate_degrees=None):
        return pygplates_to_shapely(
            self,
            central_meridian=central_meridian,
            tessellate_degrees=tessellate_degrees,
        )

Ancestors

• pygplates.pygplates.LatLonPoint
• Boost.Python.instance

Methods

def to_shapely(self, central_meridian=0.0, tessellate_degrees=None)

class MultiPointOnSphere (...)

GPlately equivalent of pygplates.MultiPointOnSphere, incorporating to_shapely method

Expand source code

class MultiPointOnSphere(pygplates.MultiPointOnSphere, GeometryOnSphere):
    """GPlately equivalent of `pygplates.MultiPointOnSphere`, incorporating
    `to_shapely` method
    """

    pass

Ancestors

• pygplates.pygplates.MultiPointOnSphere
• GeometryOnSphere
• pygplates.pygplates.GeometryOnSphere
• Boost.Python.instance

Inherited members

• GeometryOnSphere:
  • to_shapely

class PointOnSphere (...)

GPlately equivalent of pygplates.PointOnSphere, incorporating to_shapely method

Expand source code

class PointOnSphere(pygplates.PointOnSphere, GeometryOnSphere):
    """GPlately equivalent of `pygplates.PointOnSphere`, incorporating
    `to_shapely` method
    """

    pass

Ancestors

• pygplates.pygplates.PointOnSphere
• GeometryOnSphere
• pygplates.pygplates.GeometryOnSphere
• Boost.Python.instance

Inherited members

• GeometryOnSphere:
  • to_shapely

class PolygonOnSphere (...)

GPlately equivalent of pygplates.PolygonOnSphere, incorporating to_shapely method

Expand source code

class PolygonOnSphere(pygplates.PolygonOnSphere, GeometryOnSphere):
    """GPlately equivalent of `pygplates.PolygonOnSphere`, incorporating
    `to_shapely` method
    """

    pass

Ancestors

• pygplates.pygplates.PolygonOnSphere
• GeometryOnSphere
• pygplates.pygplates.GeometryOnSphere
• Boost.Python.instance

Inherited members

• GeometryOnSphere:
  • to_shapely

class PolylineOnSphere (...)

GPlately equivalent of pygplates.PolylineOnSphere, incorporating to_shapely method

Expand source code

class PolylineOnSphere(pygplates.PolylineOnSphere, GeometryOnSphere):
    """GPlately equivalent of `pygplates.PolylineOnSphere`, incorporating
    `to_shapely` method
    """

    pass

Ancestors

• pygplates.pygplates.PolylineOnSphere
• GeometryOnSphere
• pygplates.pygplates.GeometryOnSphere
• Boost.Python.instance

Inherited members

• GeometryOnSphere:
  • to_shapely