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 adict
). SeePointOnSphere
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 mpp not in mp
False
if p is equal to a point in mpmp[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()
andGeometryOnSphere.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
orLatLonPoint
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
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).
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
The centroid is calculated as the sum of the points of the multi-point with the result normalized to a vector of unit length.