pygplates.DateLineWrapper

class pygplates.DateLineWrapper

Bases: Boost.Python.instance

Wraps geometries to the dateline.

The motivation for this class is to remove horizontal lines when polylines and polygons are displayed in 2D map projections. The horizontal lines occur when the longitude of two adjacent points change from approximately -180 degrees to 180 degrees (or vice versa) causing the line segment between the adjacent points to take the long path right across the map display instead of the short path.

Date line wrapping avoids this by splitting a polyline/polygon into multiple polylines/polygons at the dateline.

__init__([central_meridian=0])

Create a dateline wrapper with a central meridian (longitude).

Parameters:central_meridian (float) – Longitude of the central meridian. Defaults to zero.

If central_meridian is non-zero then the dateline is essentially shifted such that the longitudes of the wrapped points lie in the range [central_meridian - 180, central_meridian + 180]. If central_meridian is zero then the output range becomes [-180, 180].

To enable wrapping to the ranges [-180, 180] and [-90, 270]:

date_line_wrapper = pygplates.DateLineWrapper()
date_line_wrapper_90 = pygplates.DateLineWrapper(90)

Note

If central_meridian is outside the range [-180, 180] then it will be wrapped to be within that range (eg, -200 becomes 160). This ensures that the range of longitudes of wrapped points, [central_meridian - 180, central_meridian + 180], will always be within the range [-360, 360] which is the valid range for LatLonPoint.

Methods

__init__([central_meridian=0])	Create a dateline wrapper with a central meridian (longitude).
wrap(geometry, [tessellate_degrees])	Wrap a geometry to the range [central_meridian - 180, central_meridian + 180].

wrap(geometry[, tessellate_degrees])

Wrap a geometry to the range [central_meridian - 180, central_meridian + 180].

Parameters:

• geometry (GeometryOnSphere) – the geometry to wrap
• tessellate_degrees (float or None) – optional tessellation threshold (in degrees)

The following table maps the input geometry type to the return type:

Input Geometry	Returns	Description
PointOnSphere	LatLonPoint	A single wrapped point.
MultiPointOnSphere	DateLineWrapper.LatLonMultiPoint	A single LatLonMultiPoint with the following methods: get_points: returns a list of LatLonPoint representing the wrapped points.
PolylineOnSphere	list of DateLineWrapper.LatLonPolyline	A list of wrapped polylines. Each LatLonPolyline has the following methods: get_points: returns a list of LatLonPoint representing the wrapped points (of one wrapped polyline). get_is_original_point_flags: returns a list of bool indicating whether each point in get_points is an original point in the polyline. Newly added points due to dateline wrapping and tessellation will be False. Note that both lists are the same length.
PolygonOnSphere	list of DateLineWrapper.LatLonPolygon	A list of wrapped polygons. Each LatLonPolygon has the following methods: get_exterior_points: returns a list of LatLonPoint representing the wrapped exterior points (of one wrapped polygon). In future, interior points (holes) will also be supported. get_is_original_exterior_point_flags: returns a list of bool indicating whether each point in get_exterior_points is an original exterior point in the polygon. Newly added points due to dateline wrapping and tessellation will be False. Note that both lists are the same length. Note The start and end points are generally not the same. This is similar to pygplates.PolygonOnSphere.

Note that, unlike points and multi-points, when wrapping an input polyline (or polygon) you can get more than one wrapped output polyline (or polygon) if it crosses the dateline.

date_line_wrapper = pygplates.DateLineWrapper(90.0)

# Wrap a point to the range [-90, 270].
point = pygplates.PointOnSphere(...)
wrapped_point = date_line_wrapper.wrap(point)
wrapped_point_lat_lon = wrapped_point.get_latitude(), wrapped_point.get_longitude()

# Wrap a multi-point to the range [-90, 270].
multi_point = pygplates.MultiPointOnSphere(...)
wrapped_multi_point = date_line_wrapper.wrap(multi_point)
for wrapped_point in wrapped_multi_point.get_points():
  wrapped_point_lat_lon = wrapped_point.get_latitude(), wrapped_point.get_longitude()

# Wrap a polyline to the range [-90, 270].
polyline = pygplates.PolylineOnSphere(...)
wrapped_polylines = date_line_wrapper.wrap(polyline)
for wrapped_polyline in wrapped_polylines:
  for wrapped_point in wrapped_polyline.get_points():
    wrapped_point_lat_lon = wrapped_point.get_latitude(), wrapped_point.get_longitude()

# Wrap a polygon to the range [-90, 270].
polygon = pygplates.PolygonOnSphere(...)
wrapped_polygons = date_line_wrapper.wrap(polygon)
for wrapped_polygon in wrapped_polygons:
  for wrapped_point in wrapped_polygon.get_exterior_points():
    wrapped_point_lat_lon = wrapped_point.get_latitude(), wrapped_point.get_longitude()

If tessellate_degrees is specified then tessellation (of polylines and polygons) is also performed.

Each segment is then tessellated such that adjacent points are separated by no more than tessellate_degrees on the globe.

This is useful both for geometries that cross the dateline and those that don’t. It helps ensure each polyline or polygon does not deviate too much from the true path where each great circle arc segment can be curved in 2D map projection space (rather than a straight line segment).

But it is especially useful for wrapped polygons in 2D map projections where the boundary of the projection is curved (such as Mollweide). Without tessellation the segment of the wrapped polygon along the boundary will be a straight line instead of curved to follow the map boundary.

Wrapping and tessellating a polyline and a polygon to a central meridian of 90 degrees:

date_line_wrapper = pygplates.DateLineWrapper(90.0)

# Wrap a polyline to the range [-90, 270] and tessellate to at least 2 degrees.
polyline = pygplates.PolylineOnSphere(...)
wrapped_and_tessellated_polylines = date_line_wrapper.wrap(polyline, 2.0)
...

# Wrap a polygon to the range [-90, 270] and tessellate to at least 2 degrees.
polygon = pygplates.PolygonOnSphere(...)
wrapped_and_tessellated_polygons = date_line_wrapper.wrap(polygon, 2.0)
...

Note

tessellate_degrees is ignored for points and multi-points.

Wrapping (and tessellating) can introduce new points into the original polyline or polygon.

In some cases it is desirable to know which points are original points and which are not.

For example, if the original points in a polyline are decorated with point symbols in a 2D map rendering. Any newly introduced points (from wrapping/tessellating) should not be decorated.

As such both LatLonPolyline and LatLonPolygon have methods to support this (see the above wrapped geometry table).

Determining whether points in a wrapped polyline are original polyline points:

date_line_wrapper = pygplates.DateLineWrapper()

# Wrap a polyline (and tessellate to at least 2 degrees).
polyline = pygplates.PolylineOnSphere(...)
wrapped_polylines = date_line_wrapper.wrap(polyline, 2.0)
for wrapped_polyline in wrapped_polylines:
  wrapped_points = wrapped_polyline.get_points()
  is_original_point_flags = wrapped_polyline.get_is_original_point_flags()
  for wrapped_point_index in range(len(wrapped_points)):
    if is_original_point_flags[wrapped_point_index]:
      wrapped_point_lat, wrapped_point_lon = wrapped_points[wrapped_point_index].to_lat_lon()