pygplates.GeometryOnSphere
- class pygplates.GeometryOnSphere
Bases:
Boost.Python.instance
The base class inherited by all derived classes representing geometries on the sphere.
The list of derived geometry on sphere classes is:
- __init__()
Raises an exception This class cannot be instantiated from Python
Methods
Raises an exception This class cannot be instantiated from Python
clone
()Create a duplicate of this geometry (derived) instance.
distance
(geometry1, geometry2, ...)[staticmethod] Returns the (minimum) distance between two geometries (in radians).
Returns a read-only sequence of
points
in this geometry.Returns the sequence of points, in this geometry, as a numpy array of (latitude,longitude) pairs (in degrees).
Returns the sequence of points, in this geometry, as (latitude,longitude) tuples (in degrees).
Returns the sequence of points, in this geometry, as
lat lon points
.Returns the sequence of points, in this geometry, as a numpy array of (x,y,z) triplets.
Returns the sequence of points, in this geometry, as (x,y,z) cartesian coordinate tuples.
- clone()
Create a duplicate of this geometry (derived) instance.
- Return type
Deprecated since version 0.30: Geometry is immutable so there’s no need to clone (instead you can just share the geometry).
- static distance(geometry1, geometry2[, distance_threshold_radians][, return_closest_positions=False][, return_closest_indices=False][, geometry1_is_solid=False][, geometry2_is_solid=False])
[staticmethod] Returns the (minimum) distance between two geometries (in radians).
- Parameters
geometry1 (
GeometryOnSphere
) – the first geometrygeometry2 (
GeometryOnSphere
) – the second geometrydistance_threshold_radians (float or None) – optional distance threshold in radians - threshold should be in the range [0,PI] if specified
return_closest_positions (bool) – whether to also return the closest point on each geometry - default is
False
return_closest_indices (bool) – whether to also return the index of the closest
point
(for multi-points) or the index of the closestsegment
(for polylines and polygons) - default isFalse
geometry1_is_solid (bool) – whether the interior of geometry1 is solid or not - this parameter is ignored if geometry1 is not a
PolygonOnSphere
- default isFalse
geometry2_is_solid (bool) – whether the interior of geometry2 is solid or not - this parameter is ignored if geometry2 is not a
PolygonOnSphere
- default isFalse
- Returns
distance (in radians), or a tuple containing distance and the closest point on each geometry if return_closest_positions is
True
, or a tuple containing distance and the indices of the closestpoint
(for multi-points) orsegment
(for polylines and polygons) on each geometry if return_closest_indices isTrue
, or a tuple containing distance and the closest point on each geometry and the indices of the closestpoint
(for multi-points) orsegment
(for polylines and polygons) on each geometry if both return_closest_positions and return_closest_indices areTrue
, orNone
if distance_threshold_radians is specified and exceeded- Return type
float, or tuple (float,
PointOnSphere
,PointOnSphere
) if return_closest_positions is True, or tuple (float, int, int) if return_closest_indices is True, or tuple (float,PointOnSphere
,PointOnSphere
, int, int) if both return_closest_positions and return_closest_indices are True, or None
The returned distance is the shortest path between geometry1 and geometry2 along the surface of the sphere (great circle arc path). To convert the distance from radians (distance on a unit radius sphere) to real distance you will need to multiply it by the Earth’s radius (see
Earth
).Each geometry (geometry1 and geometry2) can be any of the four geometry types (
PointOnSphere
,MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) allowing all combinations of distance calculations:distance_radians = pygplates.GeometryOnSphere.distance(point1, point2) distance_radians = pygplates.GeometryOnSphere.distance(point1, multi_point2) distance_radians = pygplates.GeometryOnSphere.distance(point1, polyline2) distance_radians = pygplates.GeometryOnSphere.distance(point1, polygon2) distance_radians = pygplates.GeometryOnSphere.distance(multi_point1, point2) distance_radians = pygplates.GeometryOnSphere.distance(multi_point1, multi_point2) distance_radians = pygplates.GeometryOnSphere.distance(multi_point1, polyline2) distance_radians = pygplates.GeometryOnSphere.distance(multi_point1, polygon2) distance_radians = pygplates.GeometryOnSphere.distance(polyline1, point2) distance_radians = pygplates.GeometryOnSphere.distance(polyline1, multi_point2) distance_radians = pygplates.GeometryOnSphere.distance(polyline1, polyline2) distance_radians = pygplates.GeometryOnSphere.distance(polyline1, polygon2) distance_radians = pygplates.GeometryOnSphere.distance(polygon1, point2) distance_radians = pygplates.GeometryOnSphere.distance(polygon1, multi_point2) distance_radians = pygplates.GeometryOnSphere.distance(polygon1, polyline2) distance_radians = pygplates.GeometryOnSphere.distance(polygon1, polygon2)
If distance_threshold_radians is specified and the (minimum) distance between the two geometries exceeds this threshold then
None
is returned.# Perform a region-of-interest query between two geometries to see if # they are within 1 degree of each other. # # Note that we explicitly test against None because a distance of zero is equilavent to False. if pygplates.GeometryOnSphere.distance(geometry1, geometry2, math.radians(1)) is not None: ...
Note that it is more efficient to specify a distance threshold parameter (as shown in the above example) than it is to explicitly compare the returned distance to a threshold yourself. This is because internally each polyline/polygon geometry has an inbuilt spatial tree that optimises distance queries.
The minimum distance between two geometries is zero (and hence does not exceed any distance threshold) if:
both geometries are a polyline/polygon and they intersect each other, or
geometry1_is_solid is
True
and geometry1 is aPolygonOnSphere
and geometry2 overlaps the interior of the polygon (even if it doesn’t intersect the polygon boundary) - similarly for geometry2_is_solid. However note that geometry1_is_solid is ignored if geometry1 is not aPolygonOnSphere
- similarly for geometry2_is_solid.
If return_closest_positions is
True
then the closest point on each geometry is returned (unless the distance threshold is exceeded, if specified). Note that for polygons the closest point is always on the polygon boundary regardless of whether the polygon is solid or not (see geometry1_is_solid and geometry2_is_solid). Also note that the closest position on a polyline/polygon can be anywhere along any of itssegments
. In other words it’s not the nearest vertex of the polyline/polygon - it’s the nearest point on the polyline/polygon itself. If both geometries are polyline/polygon and they intersect then the intersection point is returned (same point for both geometries). If both geometries are polyline/polygon and they intersect more than once then any intersection point can be returned (but the same point is returned for both geometries). If one geometry is a solidPolygonOnSphere
and the other geometry is aMultiPointOnSphere
with more than one of its points inside the interior of the polygon then the closest point in the multi-point could be any of those inside points.distance_radians, closest_point_on_geometry1, closest_point_on_geometry2 = \ pygplates.GeometryOnSphere.distance(geometry1, geometry2, return_closest_positions=True)
If return_closest_indices is
True
then the index of the closestpoint
(for multi-points) or the index of the closestsegment
(for polylines and polygons) is returned (unless the threshold is exceeded, if specified). Note that forpoint
geometries the index will always be zero. The point indices can be used to index directly intoMultiPointOnSphere
and the segment indices can be used withPolylineOnSphere.get_segments()
orPolygonOnSphere.get_segments()
as shown in the following example:distance_radians, closest_point_index_on_multipoint, closest_segment_index_on_polyline = \ pygplates.GeometryOnSphere.distance(multipoint, polyline, return_closest_indices=True) closest_point_on_multipoint = multipoint[closest_point_index_on_multipoint] closest_segment_on_polyline = polyline.get_segments()[closest_segment_index_on_polyline] closest_segment_normal_vector = closest_segment_on_polyline.get_great_circle_normal()
If both return_closest_positions and return_closest_indices are
True
:# Distance between a polyline and a solid polygon. distance_radians, polyline_point, polygon_point, polyline_segment_index, polygon_segment_index = \ pygplates.GeometryOnSphere.distance( polyline, polygon, return_closest_positions=True, return_closest_indices=True, geometry2_is_solid=True)
- get_points()
Returns a read-only sequence of
points
in this geometry.- Return type
a read-only sequence of
PointOnSphere
The following operations for accessing the points in the returned read-only sequence are supported:
Operation
Result
len(seq)
length of seq
for p in seq
iterates over the points p of seq
p in seq
True
if p is equal to a point in seqp not in seq
False
if p is equal to a point in seqseq[i]
the point of seq at index i
seq[i:j]
slice of seq from i to j
seq[i:j:k]
slice of seq from i to j with step k
Note
The returned sequence is read-only and cannot be modified.
If this geometry is a
PointOnSphere
then the returned sequence has length one. For other geometry types (MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) the length will equal the number ofpoints
contained within. For aPolygonOnSphere
the points include its exterior ring followed by its interior rings (if any).The following example demonstrates some uses of the above operations:
points = geometry.get_points() for point in points: print(point)
However if you know you have aMultiPointOnSphere
,PolylineOnSphere
orPolygonOnSphere
(ie, not aPointOnSphere
) it’s actually easier to iterate directly over the geometry itself.For example with aPolylineOnSphere
:for point in polyline: print(point) first_polyline_point = polyline[0] last_polyline_point = polyline[-1]
Note
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 (
to_lat_lon_list()
,to_lat_lon_array()
,to_xyz_list()
andto_xyz_array()
).Changed in version 0.36: For
PolygonOnSphere
the returned points now include interior rings (if any).
- to_lat_lon_array()
Returns the sequence of points, in this geometry, as a numpy array of (latitude,longitude) pairs (in degrees).
- Returns
an array of (latitude,longitude) pairs (in degrees)
- Return type
2D numpy array with number of points as outer dimension and an inner dimension of two
Warning
This method should only be called if the
numpy
module is available.If this geometry is a
PointOnSphere
then the returned sequence has length one. For other geometry types (MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) the length will equal the number ofpoints
contained within. For aPolygonOnSphere
the points include its exterior ring followed by its interior rings (if any).If you want the latitude/longitude order swapped in the returned tuples then the following is one way to achieve this:
# Convert (latitude,longitude) to (longitude,latitude). geometry.to_lat_lon_array()[:, (1,0)]
If you need a flat 1D numpy array then you can do something like:
geometry.to_lat_lon_array().flatten()
- to_lat_lon_list()
Returns the sequence of points, in this geometry, as (latitude,longitude) tuples (in degrees).
- Returns
a list of (latitude,longitude) tuples (in degrees)
- Return type
list of (float,float) tuples
If this geometry is a
PointOnSphere
then the returned sequence has length one. For other geometry types (MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) the length will equal the number ofpoints
contained within. For aPolygonOnSphere
the points include its exterior ring followed by its interior rings (if any).If you want the latitude/longitude order swapped in the returned tuples then the following is one way to achieve this:
# Convert (latitude,longitude) to (longitude,latitude). [(lon,lat) for lat, lon in geometry.to_lat_lon_list()]
- to_lat_lon_point_list()
Returns the sequence of points, in this geometry, as
lat lon points
.- Return type
list of
LatLonPoint
If this geometry is a
PointOnSphere
then the returned sequence has length one. For other geometry types (MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) the length will equal the number ofpoints
contained within. For aPolygonOnSphere
the points include its exterior ring followed by its interior rings (if any).
- to_xyz_array()
Returns the sequence of points, in this geometry, as a numpy array of (x,y,z) triplets.
- Returns
an array of (x,y,z) triplets
- Return type
2D numpy array with number of points as outer dimension and an inner dimension of three
Warning
This method should only be called if the
numpy
module is available.If you need a flat 1D numpy array then you can do something like:
geometry.to_xyz_array().flatten()
If this geometry is a
PointOnSphere
then the returned sequence has length one. For other geometry types (MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) the length will equal the number ofpoints
contained within. For aPolygonOnSphere
the points include its exterior ring followed by its interior rings (if any).
- to_xyz_list()
Returns the sequence of points, in this geometry, as (x,y,z) cartesian coordinate tuples.
- Returns
a list of (x,y,z) tuples
- Return type
list of (float,float,float) tuples
If this geometry is a
PointOnSphere
then the returned sequence has length one. For other geometry types (MultiPointOnSphere
,PolylineOnSphere
andPolygonOnSphere
) the length will equal the number ofpoints
contained within. For aPolygonOnSphere
the points include its exterior ring followed by its interior rings (if any).