pygplates.PolylineOnSphere

class pygplates.PolylineOnSphere(...)

Bases: pygplates.GeometryOnSphere

Represents a polyline on the surface of the unit length sphere. Polylines 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 polyline instance is both:

In addition a polyline instance is directly iterable over its points (without having to use get_points()):

polyline = pygplates.PolylineOnSphere(points)
for point in polyline:
    ...

...and so the following operations for accessing the points are supported:

Operation Result
len(polyline) number of vertices in polyline
for p in polyline iterates over the vertices p of polyline
p in polyline True if p is equal to a vertex of polyline
p not in polyline False if p is equal to a vertex of polyline
polyline[i] the vertex of polyline at index i
polyline[i:j] slice of polyline from i to j
polyline[i:j:k] slice of polyline from i to j with step k
Since a PolylineOnSphere is immutable it contains no operations or methods that modify its state (such as adding or removing points). This is similar to other immutable types in python such as str.
So instead of modifying an existing polyline you will need to create a new PolylineOnSphere instance as the following example demonstrates:
# Get a list of points from an existing PolylineOnSphere 'polyline'.
points = list(polyline)

# Modify the points list somehow.
points[0] = pygplates.PointOnSphere(...)
points.append(pygplates.PointOnSphere(...))

# 'polyline' now references a new PolylineOnSphere instance.
polyline = pygplates.PolylineOnSphere(points)
__init__(...)

A PolylineOnSphere object can be constructed in more than one way...

__init__(points)

Create a polyline 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:InvalidPointsForPolylineConstructionError if sequence has less than two points or if any two points (adjacent in the points sequence) are antipodal to each other (on opposite sides of the globe)

Note

The sequence must contain at least two points in order to be a valid polyline, otherwise InvalidPointsForPolylineConstructionError will be raised.

During creation, a GreatCircleArc is created between each adjacent pair of points in points - see get_segments().

It is not an error for adjacent points in the sequence to be coincident. In this case each GreatCircleArc between two such adjacent points will have zero length (GreatCircleArc.is_zero_length() will return True) and will have no rotation axis (GreatCircleArc.get_rotation_axis() will raise an error). However if two such adjacent points are antipodal (on opposite sides of the globe) then InvalidPointsForPolylineConstructionError will be raised.

The following example shows a few different ways to create a polyline:

points = []
points.append(pygplates.PointOnSphere(...))
points.append(pygplates.PointOnSphere(...))
points.append(pygplates.PointOnSphere(...))
polyline = pygplates.PolylineOnSphere(points)

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

points = []
points.append([x1,y1,z1])
points.append([x2,y2,z2])
points.append([x3,y3,z3])
polyline = pygplates.PolylineOnSphere(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])
polyline = pygplates.PolylineOnSphere(zip(points[::2],points[1::2]))

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

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

# Lon/lat list of tuples (ie, different latitude/longitude order).
points = [(lon1, lat1), (lon2, lat2), (lon3, lat3)]
polyline = pygplates.PolylineOnSphere([(lat,lon) for lon, lat in points])
__init__(geometry, [allow_one_point=True])

Create a polyline from a GeometryOnSphere.

param geometry:The point, multi-point, polyline or polygon geometry to convert from.
type geometry:GeometryOnSphere
param allow_one_point:
 Whether geometry is allowed to be a PointOnSphere or a MultiPointOnSphere containing only a single point - if allowed then that single point is duplicated since a PolylineOnSphere requires at least two points - default is True.
type allow_one_point:
 bool
raises:InvalidPointsForPolylineConstructionError if geometry is a PointOnSphere (and allow_one_point is False), or a MultiPointOnSphere with one point (and allow_one_point is False), or if any two consecutive points in a MultiPointOnSphere are antipodal to each other (on opposite sides of the globe)

If allow_one_point is True then geometry can be PointOnSphere, MultiPointOnSphere, PolylineOnSphere or PolygonOnSphere. However if allow_one_point is False then geometry must be a PolylineOnSphere, or a PolygonOnSphere, or a MultiPointOnSphere containing at least two points to avoid raising InvalidPointsForPolylineConstructionError.

During creation, a GreatCircleArc is created between each adjacent pair of geometry points - see get_segments().

It is not an error for adjacent points in a geometry sequence to be coincident. In this case each GreatCircleArc between two such adjacent points will have zero length (GreatCircleArc.is_zero_length() will return True) and will have no rotation axis (GreatCircleArc.get_rotation_axis() will raise an error). However if two such adjacent points are antipodal (on opposite sides of the globe) then InvalidPointsForPolylineConstructionError will be raised

To create a PolylineOnSphere from any geometry type:

polyline = pygplates.PolylineOnSphere(geometry)

To create a PolylineOnSphere from any geometry containing at least two points:

try:
    polyline = pygplates.PolylineOnSphere(geometry, allow_one_point=False)
except pygplates.InvalidPointsForPolylineConstructionError:
    ... # Handle failure to convert 'geometry' to a PolylineOnSphere.

Methods

__init__(...) A PolylineOnSphere 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_arc_length() Returns the total arc length of this polyline (in radians).
get_centroid() Returns the centroid of this polyline.
get_points() Returns a read-only sequence of points in this geometry.
get_segments() Returns a read-only sequence of segments in this polyline.
join(geometries, ...) Joins geometries that have end points closer than a distance threshold.
rotation_interpolate(from_polyline, ...) [staticmethod] Interpolates between two polylines about a rotation pole.
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_tessellated(tessellate_radians) Returns a new polyline that is tessellated version of this polyline.
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.
clone()

Create a duplicate of this geometry (derived) instance.

Return type:GeometryOnSphere
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 geometry
  • geometry2 (GeometryOnSphere) – the second geometry
  • distance_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 closest segment (for polylines and polygons) - default is False
  • geometry1_is_solid (bool) – whether the interior of geometry1 is solid or not - this parameter is ignored if geometry1 is not a PolygonOnSphere - default is False
  • geometry2_is_solid (bool) – whether the interior of geometry2 is solid or not - this parameter is ignored if geometry2 is not a PolygonOnSphere - default is False
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 closest point (for multi-points) or segment (for polylines and polygons) on each geometry if return_closest_indices is True, or a tuple containing distance and the closest point on each geometry and the indices of the closest point (for multi-points) or segment (for polylines and polygons) on each geometry if both return_closest_positions and return_closest_indices are True, or None 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 and PolygonOnSphere) 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 a PolygonOnSphere 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 a PolygonOnSphere - 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 its segments. 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 solid PolygonOnSphere and the other geometry is a MultiPointOnSphere 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 closest point (for multi-points) or the index of the closest segment (for polylines and polygons) is returned (unless the threshold is exceeded, if specified). Note that for point geometries the index will always be zero. The point indices can be used to index directly into MultiPointOnSphere and the segment indices can be used with PolylineOnSphere.get_segments() or PolygonOnSphere.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_arc_length()

Returns the total arc length of this polyline (in radians).

Return type:float
This is the sum of the arc lengths of the segments of this polyline.
To convert to distance, multiply the result by the Earth radius (see Earth).
get_centroid()

Returns the centroid of this polyline.

Return type:PointOnSphere

The centroid is calculated as a weighted average of the mid-points of the great circle arcs of this polyline with weighting proportional to the individual arc lengths.

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 seq
p not in seq False if p is equal to a point in seq
seq[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.

Note

If you want a modifiable sequence consider wrapping the returned sequence in a list using something like points = list(geometry.get_points()) but note that modifying the list (eg, inserting a new point) will not modify the original geometry.

If this geometry is a PointOnSphere then the returned sequence has length one. For other geometry types (MultiPointOnSphere, PolylineOnSphere and PolygonOnSphere) the length will equal the number of points contained within.

The following example demonstrates some uses of the above operations:

points = geometry.get_points()
for point in points:
    print point
first_point = points[0]
last_point = points[-1]
However if you know you have a MultiPointOnSphere, PolylineOnSphere or PolygonOnSphere (ie, not a PointOnSphere) it’s actually easier to iterate directly over the geometry itself.
For example with a PolylineOnSphere:
for point in polyline:
    print point
first_point = polyline[0]
last_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() and to_xyz_array()).

get_segments()

Returns a read-only sequence of segments in this polyline.

Return type:a read-only sequence of GreatCircleArc

The following operations for accessing the great circle arcs in the returned read-only sequence are supported:

Operation Result
len(seq) number of segments of the polyline
for s in seq iterates over the segments s of the polyline
s in seq True if s is an segment of the polyline
s not in seq False if s is an segment of the polyline
seq[i] the segment of the polyline at index i
seq[i:j] slice of segments of the polyline from i to j
seq[i:j:k] slice of segments of the polyline from i to j with step k

Note

Between each adjacent pair of points there is an segment such that the number of points exceeds the number of segments by one.

The following example demonstrates some uses of the above operations:

polyline = pygplates.PolylineOnSphere(points)
...
segments = polyline.get_segments()
for segment in segments:
    if not segment.is_zero_length():
        segment_midpoint_direction = segment.get_arc_direction(0.5)
first_segment = segments[0]
last_segment = segments[-1]

Note

The returned sequence is read-only and cannot be modified.

Note

If you want a modifiable sequence consider wrapping the returned sequence in a list using something like segments = list(polyline.get_segments()) but note that modifying the list (eg, appending a new segment) will not modify the original polyline.

static join(geometries[, distance_threshold_radians][, polyline_conversion=PolylineConversion.ignore_non_polyline])

Joins geometries that have end points closer than a distance threshold.

Parameters:
  • geometries (sequence (eg, list or tuple) of GeometryOnSphere) – the geometries to join
  • distance_threshold_radians (float) – optional closeness distance threshold in radians for joining to occur (if not specified then end point equality is used)
  • polyline_conversion (PolylineConversion.convert_to_polyline, PolylineConversion.ignore_non_polyline or PolylineConversion.raise_if_non_polyline) – whether to raise error, convert to PolylineOnSphere or ignore those geometries in geometries that are not PolylineOnSphere - defaults to PolylineConversion.ignore_non_polyline
Returns:

a list of joined polylines

Return type:

list of PolylineOnSphere

Raises:

GeometryTypeError if polyline_conversion is PolylineConversion.raise_if_non_polyline and any geometry in geometries is not a PolylineOnSphere

All pairs of geometries are tested for joining and only those with end points closer than distance_threshold_radians radians are joined. Each joined polyline is further joined if possible until there are no more possibilities for joining (or there is a single joined polyline that is a concatenation of all geometries in geometries - depending on polyline_conversion).

Note

If distance_threshold_radians is not specified then the end points must be equal (rather than separated by less than a threshold distance).

When determining if two geometries A and B can be joined the closest pair of end points (one from A and one from B) decides which end of each geometry can be joined, provided their distance is less than distance_threshold_radians radians. If a third geometry C also has an end point close enough to A then the closest of B and C is joined to A.

Two geometries A and B are joined by prepending or appending a (possibly reversed) copy of the points in geometry B to a copy of the points in geometry A. Hence the joined polyline will always have points ordered in the same direction as geometry A (only the points from geometry B are reversed if necessary). So geometries earlier in the geometries sequence determine the direction of joined polylines.

Join three polylines if their end points are within 3 degrees of another:

# If all three polylines join then the returned list will have one joined polyline.
# If only two polylines join then the returned list will have two polylines (one original and one joined).
# If no polylines join then the returned list will have the three original polylines.
joined_polylines = pygplates.PolylineOnSphere.join((polyline1, polyline2, polyline3), math.radians(3))

Other geometries besides PolylineOnSphere can be joined if polyline_conversion is PolylineConversion.convert_to_polyline. This is useful for joining nearby points into polylines for example:

# If all points are close enough then the returned list will have one joined polyline,
# otherwise there will be multiple polylines each representing a subset of the points.
# If none of the points are close to each other then the returned list will have degenerate
# polylines that each look like a point (each polyline has two identical points).
joined_polylines = pygplates.PolylineOnSphere.join(
        points, math.radians(3), pygplates.PolylineConversion.convert_to_polyline)
rotation_interpolate(from_polyline, to_polyline, rotation_pole, interpolate[, minimum_latitude_overlap_radians=0][, maximum_latitude_non_overlap_radians=0][, maximum_distance_threshold_radians][, flatten_longitude_overlaps=FlattenLongitudeOverlaps.no][, polyline_conversion=PolylineConversion.ignore_non_polyline])

[staticmethod] Interpolates between two polylines about a rotation pole.

Parameters:
  • from_polyline (GeometryOnSphere) – the polyline to interpolate from
  • to_polyline (GeometryOnSphere) – the polyline to interpolate to
  • rotation_pole (PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – the rotation axis to interpolate around
  • interpolate (float, or list of float) – if a single number then interpolate is the interval spacing, in radians, between from_polyline and to_polyline at which to generate interpolated polylines - otherwise if a sequence of numbers (eg, list or tuple) then interpolate is the sequence of interpolate ratios, in the range [0,1], at which to generate interpolated polylines (with 0 meaning from_polyline and 1 meaning to_polyline)
  • minimum_latitude_overlap_radians (float - defaults to zero) – required amount of latitude overlap of polylines
  • maximum_latitude_non_overlap_radians (float - defaults to zero) – allowed non-overlapping latitude region
  • maximum_distance_threshold_radians (float - default is no threshold detection) – maximum distance (in radians) between from_polyline and to_polyline - if specified and if exceeded then None is returned
  • flatten_longitude_overlaps (FlattenLongitudeOverlaps.no, FlattenLongitudeOverlaps.use_from or FlattenLongitudeOverlaps.use_to - defaults to FlattenLongitudeOverlaps.no) – whether or not to ensure from_polyline and to_polyline do not overlap in longitude (in North pole reference frame of rotation_pole) and how to correct the overlap
  • polyline_conversion (PolylineConversion.convert_to_polyline, PolylineConversion.ignore_non_polyline or PolylineConversion.raise_if_non_polyline) – whether to raise error, convert to PolylineOnSphere or ignore from_polyline and to_polyline if they are not PolylineOnSphere (ignoring equates to returning None) - defaults to PolylineConversion.ignore_non_polyline
Returns:

list of interpolated polylines - or None if polylines do not have overlapping latitude ranges or if maximum distance threshold exceeded or if either polyline is not a PolylineOnSphere (and polyline_conversion is PolylineConversion.ignore_non_polyline)

Return type:

list of PolylineOnSphere or None

Raises:

GeometryTypeError if from_polyline or to_polyline are not of type PolylineOnSphere (and polyline_conversion is PolylineConversion.raise_if_non_polyline)

If interpolate is a single number then it is the distance interval spacing, in radians, between from_polyline and to_polyline at which to generate interpolated polylines. Also modified versions of from_polyline and to_polyline are returned along with the interpolated polylines.

If interpolate is a sequence of numbers (eg, list or tuple) then it is the sequence of interpolate ratios, in the range [0,1], at which to generate interpolated polylines (with 0 meaning from_polyline and 1 meaning to_polyline and values between meaning interpolated polylines).

The points in the returned polylines are ordered from closest (latitude) to rotation_pole to furthest (which may be different than the order in the original polylines). The modified versions of polylines from_polyline and to_polyline, and hence all interpolated polylines, have monotonically decreasing latitudes (in North pole reference frame of rotation_pole) starting with the northmost polyline end-point and (monotonically) decreasing southward such that subsequent points have latitudes lower than, or equal to, all previous points as shown in the following diagram:

  /|
 / |
/  |                       ___
   |                          |
   | /|                       |
   |/ |                       |__
      |                          |
      |           ===>           |
      | /|                       |
      |/ |                       |__
         |                          |
          \                          \
           \                          \
            |                          |
            | /                        |
            |/                         |__

The modified versions of polylines from_polyline and to_polyline are also clipped to have a common overlapping latitude range (with a certain amount of non-overlapping allowed if max_latitude_non_overlap_radians is non-zero).

minimum_latitude_overlap_radians specifies the amount that from_polyline and to_polyline must overlap in latitude (North pole reference frame of rotation_pole), otherwise None is returned. Note that this also means if the range of latitudes of either polyline is smaller than the minimum overlap then None is returned. The following diagram shows the original latitude overlapping polylines on the left and the resultant interpolated polylines on the right clipped to the latitude overlapping range (in rotation_pole reference frame):

|_
  |
  |         |                         |    |    |
  |_        |_          ===>          |_   |_   |_
    |         |                         |    |    |
    |         |                         |    |    |
              |_
                |

However problems can arise if rotation_pole is placed such that one, or both, the original polylines (from_polyline and to_polyline) strongly overlaps itself (in rotation_pole reference frame) causing the monotonically-decreasing-latitude requirement to severely distort its geometry. The following diagram shows the original polylines in the top of the diagram and the resultant interpolated polylines in the bottom of the diagram:

                             \
                              \
         ______                \
    ____|      |____            \
 __|                |__          \
/                      \          \
                        \          \
                         |          |
                         |          |
                         |          |

             ||
             ||
             \/

______________________________
                        \     \    \
                         |     |    |
                         |     |    |
                         |     |    |

If maximum_latitude_non_overlap_radians is non-zero then an extra range of non-overlapping latitudes at the North and South (in rotation_pole reference frame) of from_polyline and to_polyline is allowed. The following diagram shows the original latitude overlapping polylines on the left and the resultant interpolated polylines on the right with a limited amount of non-overlapping interpolation from the North end of one polyline and from the South end of the other (in rotation_pole reference frame):

|
|
|                                   |
|                                   |    |
|         |                         |    |    |
|_        |_          ===>          |_   |_   |_
  |         |                         |    |    |
  |         |                         |    |    |
            |                              |    |
            |                                   |
            |
            |

If flatten_longitude_overlaps is FlattenLongitudeOverlaps.use_from or FlattenLongitudeOverlaps.use_to then this function ensures the longitudes of each point pair of from_polyline and to_polyline (in North pole reference frame of rotation_pole) at the same latitude don’t overlap. For those point pairs where overlap occurs, the points in from_polyline are copied to the corresponding (same latitude) points in to_polyline if FlattenLongitudeOverlaps.use_from is used (and vice versa if FlattenLongitudeOverlaps.use_to is used). This essentially removes or flattens overlaps in longitude. The following diagram shows the original longitude overlapping polylines on the left and the resultant interpolated polylines on the right (in rotation_pole reference frame) after longitude flattening with FlattenLongitudeOverlaps.use_from:

from     to
  \     /                             \  |  /
   \   /                               \ | /
    \ /                                 \|/
     .                                   .
    / \                                   \
   /   \                                   \
  /     \                                   \
 |       |                                   |
 |       |           ===>                    |
 |       |                                   |
  \     /                                   /
   \   /                                   /
    \ /                                   /
     .                                   .
    / \                                 /|\
   /   \                               / | \
  /     \                             /  |  \
 /       \                           /   |   \

Returns None if:

  • the polylines do not overlap by at least minimum_latitude_overlap_radians radians (where North pole is rotation_axis), or
  • any corresponding pair of points (same latitude) of the polylines are separated by a distance of more than max_distance_threshold_radians (if specified).

Note

All returned polylines have the same number of points.

Note

Corresponding points in returned polylines (points at same indices) have the same latitude (in North pole reference frame of rotation_pole) except those points in the non-overlapping latitude ranges (if maximum_latitude_non_overlap_radians is specified).

To interpolate polylines with a spacing of 2 minutes (with a minimum required latitude overlap of 1 degree and with an allowed latitude non-overlap of up to 3 degrees and with no distance threshold and with no longitude overlaps flattened):

interpolated_polylines = pygplates.PolylineOnSphere.rotation_interpolate(
    from_polyline, to_polyline, rotation_pole, math.radians(2.0/60), math.radians(1), math.radians(3))

To interpolate polylines at interpolate ratios between 0 and 1 at 0.1 intervals (with a minimum required latitude overlap of 1 degree and with an allowed latitude non-overlap of up to 3 degrees and with no distance threshold and with no longitude overlaps flattened):

interpolated_polylines = pygplates.PolylineOnSphere.rotation_interpolate(
    from_polyline, to_polyline, rotation_pole, range(0, 1.01, 0.1), math.radians(1), math.radians(3))

An easy way to test whether two polylines can possibly be interpolated without actually interpolating anything is to specify an empty list of interpolate ratios:

if pygplates.PolylineOnSphere.rotation_interpolate(
        from_polyline, to_polyline, rotation_pole, [], ...) is not None:
    # 'from_polyline' and 'to_polyline' can be interpolated (ie, they overlap
    # and don't exceed the maximum distance threshold)
    ...
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 and PolygonOnSphere) the length will equal the number of points contained within.

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 and PolygonOnSphere) the length will equal the number of points contained within.

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 and PolygonOnSphere) the length will equal the number of points contained within.

to_tessellated(tessellate_radians)

Returns a new polyline that is tessellated version of this polyline.

Parameters:tessellate_radians (float) – maximum tessellation angle (in radians)
Return type:PolylineOnSphere

Adjacent points (in the returned tessellated polyline) are separated by no more than tessellate_radians on the globe.

Create a polyline tessellated to 2 degrees:

tessellated_polyline = polyline.to_tessellated(math.radians(2))

Note

Since a PolylineOnSphere is immutable it cannot be modified. Which is why a new (tessellated) PolylineOnSphere is returned.

Note

The distance between adjacent points (in the tessellated polyline) will not be exactly uniform. This is because each segment in the original polyline is tessellated to the nearest integer number of points (that keeps that segment under the threshold) and hence each original segment will have a slightly different tessellation angle.

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 and PolygonOnSphere) the length will equal the number of points contained within.

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 and PolygonOnSphere) the length will equal the number of points contained within.

Previous topic

pygplates.MultiPointOnSphere

Next topic

pygplates.PolygonOnSphere

This Page