pygplates.MultiPointOnSphere

class pygplates.MultiPointOnSphere

Bases: pygplates.GeometryOnSphere

Represents a multi-point (collection of points) on the surface of the unit length sphere. Multi-points are equality (==, !=) comparable (but not hashable - cannot be used as a key in a dict). See PointOnSphere for an overview of equality in the presence of limited floating-point precision.

A multi-point instance is iterable over its points:

multi_point = pygplates.MultiPointOnSphere(points)
for point in multi_point:
    ...

The following operations for accessing the points are supported:

Operation	Result
`len(mp)`	number of points in mp
`for p in mp`	iterates over the points p of multi-point mp
`p in mp`	`True` if p is equal to a point in mp
`p not in mp`	`False` if p is equal to a point in mp
`mp[i]`	the point of mp at index i
`mp[i:j]`	slice of mp from i to j
`mp[i:j:k]`	slice of mp from i to j with step k

Note

Since a MultiPointOnSphere is immutable it contains no operations or methods that modify its state (such as adding or removing points).

There are also methods that return the sequence of points as (latitude,longitude) values and (x,y,z) values contained in lists and numpy arrays (GeometryOnSphere.to_lat_lon_list(), GeometryOnSphere.to_lat_lon_array(), GeometryOnSphere.to_xyz_list() and GeometryOnSphere.to_xyz_array()).

__init__(...)

A MultiPointOnSphere object can be constructed in more than one way…

__init__(points)

Create a multi-point from a sequence of (x,y,z) or (latitude,longitude) points.

param points: A sequence of (x,y,z) points, or (latitude,longitude) points (in degrees).
type points: Any sequence of PointOnSphere or LatLonPoint or tuple (float,float,float) or tuple (float,float)
raises: InvalidLatLonError if any latitude or longitude is invalid
raises: ViolatedUnitVectorInvariantError if any (x,y,z) is not unit magnitude
raises: InsufficientPointsForMultiPointConstructionError if point sequence is empty

Note

The sequence must contain at least one point, otherwise InsufficientPointsForMultiPointConstructionError will be raised.

The following example shows a few different ways to create a multi-point:

points = []
points.append(pygplates.PointOnSphere(...))
points.append(pygplates.PointOnSphere(...))
points.append(pygplates.PointOnSphere(...))
multi_point = pygplates.MultiPointOnSphere(points)

points = []
points.append((lat1,lon1))
points.append((lat2,lon2))
points.append((lat3,lon3))
multi_point = pygplates.MultiPointOnSphere(points)

points = []
points.append([x1,y1,z1])
points.append([x2,y2,z2])
points.append([x3,y3,z3])
multi_point = pygplates.MultiPointOnSphere(points)

If you have latitude/longitude values but they are not a sequence of tuples or if the latitude/longitude order is swapped then the following examples demonstrate how you could restructure them:

# Flat lat/lon array.
points = numpy.array([lat1, lon1, lat2, lon2, lat3, lon3])
multi_point = pygplates.MultiPointOnSphere(zip(points[::2],points[1::2]))

# Flat lon/lat list (ie, different latitude/longitude order).
points = [lon1, lat1, lon2, lat2, lon3, lat3]
multi_point = pygplates.MultiPointOnSphere(zip(points[1::2],points[::2]))

# Separate lat/lon arrays.
lats = numpy.array([lat1, lat2, lat3])
lons = numpy.array([lon1, lon2, lon3])
multi_point = pygplates.MultiPointOnSphere(zip(lats,lons))

# Lon/lat list of tuples (ie, different latitude/longitude order).
points = [(lon1, lat1), (lon2, lat2), (lon3, lat3)]
multi_point = pygplates.MultiPointOnSphere([(lat,lon) for lon, lat in points])

__init__(geometry)

Create a multipoint from a GeometryOnSphere.

param geometry: The point, multi-point, polyline or polygon geometry to convert from.
type geometry: GeometryOnSphere

To create a MultiPointOnSphere from any geometry type:

multipoint = pygplates.MultiPointOnSphere(geometry)

Note

If geometry is a polygon then points from both its exterior and interior rings are added to the multipoint.

Methods

`__init__`(...)	A MultiPointOnSphere object can be constructed in more than one way...
`clone`()	Create a duplicate of this geometry (derived) instance.
`distance`(geometry1, geometry2, ...)	[staticmethod] Returns the (minimum) distance between two geometries (in radians).
`get_centroid`()	Returns the centroid of this multi-point.
`get_points`()	Returns a read-only sequence of `points` in this geometry.
`to_lat_lon_array`()	Returns the sequence of points, in this geometry, as a numpy array of (latitude,longitude) pairs (in degrees).
`to_lat_lon_list`()	Returns the sequence of points, in this geometry, as (latitude,longitude) tuples (in degrees).
`to_lat_lon_point_list`()	Returns the sequence of points, in this geometry, as `lat lon points`.
`to_xyz_array`()	Returns the sequence of points, in this geometry, as a numpy array of (x,y,z) triplets.
`to_xyz_list`()	Returns the sequence of points, in this geometry, as (x,y,z) cartesian coordinate tuples.

get_centroid()

Returns the centroid of this multi-point.

Return type: PointOnSphere

The centroid is calculated as the sum of the points of the multi-point with the result normalized to a vector of unit length.