pygplates.ReconstructSnapshot

class pygplates.ReconstructSnapshot

Bases: instance

A snapshot of reconstructed regular features (including motion paths and flowlines) at a specific geological time.

A ReconstructSnapshot can also be pickled.

Added in version 0.48.

__init__(reconstructable_features, rotation_model, reconstruction_time[, anchor_plate_id])

Create from reconstructable features and a rotation model at a specific reconstruction time.

Parameters:

reconstructable_features (FeatureCollection, or string/os.PathLike, or Feature, or sequence of Feature, or sequence of any combination of those four types) – The reconstructable features as a feature collection, or filename, or feature, or sequence of features, or a sequence (eg, list or tuple) of any combination of those four types.
rotation_model (RotationModel. Or FeatureCollection, or string/os.PathLike, or Feature, or sequence of Feature, or sequence of any combination of those four types) – A rotation model. Or a rotation feature collection, or a rotation filename, or a rotation feature, or a sequence of rotation features, or a sequence of any combination of those four types.
reconstruction_time (float or GeoTimeInstant) – the specific geological time to reconstruct to
anchor_plate_id (int) – The anchored plate id used for all reconstructions. Defaults to the default anchor plate of rotation_model (or zero if rotation_model is not a RotationModel).

Create a reconstruct snapshot by reconstructing features at a specific reconstruction time:

reconstruction_time = 100
reconstructable_features = pygplates.FeatureCollection('reconstructable_features.gpml')
rotation_model = pygplates.RotationModel('rotations.rot')
reconstruct_snapshot = pygplates.ReconstructSnapshot(reconstructable_features, rotation_model, reconstruction_time)

Methods

`__init__`(reconstructable_features, ...)	Create from reconstructable features and a rotation model at a specific reconstruction time.
`export_reconstructed_geometries`(...)	Exports the reconstructed geometries of the requested type(s) to a file.
`get_anchor_plate_id`()	Return the anchor plate ID (see `constructor`).
`get_point_locations`(points, ...)	Returns the reconstructed static polygons that contain the specified points.
`get_point_velocities`(points, ...)	Returns the velocities of the specified points (as determined by the reconstructed static polygons that contain them).
`get_reconstructed_features`(...)	Returns the reconstructed geometries of the requested type(s) grouped by their feature.
`get_reconstructed_geometries`(...)	Returns the reconstructed geometries of the requested type(s).
`get_reconstruction_time`()	Return the reconstruction time of this snapshot.
`get_rotation_model`()	Return the rotation model used internally.

export_reconstructed_geometries(export_filename[, reconstruct_type=pygplates.ReconstructType.feature_geometry][, wrap_to_dateline=True][, force_polygon_orientation])

Exports the reconstructed geometries of the requested type(s) to a file.

Parameters:

export_filename (string/os.PathLike) – the name of the export file
reconstruct_type (pygplates.ReconstructType.feature_geometry, pygplates.ReconstructType.motion_path or pygplates.ReconstructType.flowline) – specifies which type of features to export - defaults to exporting only regular features (not motion paths or flowlines)
wrap_to_dateline (bool) – Whether to wrap/clip reconstructed geometries to the dateline (currently ignored unless exporting to an ESRI Shapefile format file). Defaults to True.
force_polygon_orientation (int) – Optionally force boundary orientation to clockwise (PolygonOnSphere.Orientation.clockwise) or counter-clockwise (PolygonOnSphere.Orientation.counter_clockwise). Only applies to reconstructed feature geometries (excludes motion paths and flowlines) that are polygons. Note that ESRI Shapefiles always use clockwise orientation (and so ignore this parameter).

Raises:

ValueError if reconstruct_type (if specified) is not one of pygplates.ReconstructType.feature_geometry, pygplates.ReconstructType.motion_path or pygplates.ReconstructType.flowline

Note

reconstruct_type must be a single reconstruct type. This is different than get_reconstructed_geometries() and get_reconstructed_features() which can specify multiple types.

The following export file formats are currently supported:

Export File Format	Filename Extension
ESRI Shapefile	‘.shp’
GeoJSON	‘.geojson’ or ‘.json’
OGR GMT	‘.gmt’
GMT xy	‘.xy’

Note

Reconstructed geometries are exported in the order of their respective reconstructable features (see constructor). This includes the order across any reconstructable feature collections/files.

get_anchor_plate_id()

Return the anchor plate ID (see constructor).

Return type:: int

Note

This is the same as the default anchor plate ID of get_rotation_model().

get_point_locations(points[, sort_reconstructed_static_polygons=pygplates.SortReconstructedStaticPolygons.by_plate_id])

Returns the reconstructed static polygons that contain the specified points.

Parameters:

points (any sequence of PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – sequence of points at which to find containing reconstructed static polygons
sort_reconstructed_static_polygons (pygplates.SortReconstructedStaticPolygons.by_plate_id or pygplates.SortReconstructedStaticPolygons.by_plate_area or None) – optional sort order of reconstructed static polygons (defaults to pygplates.SortReconstructedStaticPolygons.by_plate_id)

Return type:

list of ReconstructedFeatureGeometry

Reconstructed static polygons are reconstructed feature geometries that have polygon geometries (other geometry types are ignored since only polygons can contain points). The reconstructed feature geometries are obtained from get_reconstructed_geometries() with reconstruct_types=pygplates.ReconstructType.feature_geometry and same_order_as_reconstructable_features=True.

Note

Each point that is outside all reconstructed static polygons will have a point location (reconstructed static polygon) of None.

Reconstructed static polygons can overlap each other at reconstruction times in the past (unlike resolved topological plates which typically do not overlap). This means a point could be contained inside more than one reconstructed static polygon, but only the first one will be returned for that point. However, you can change the search order of reconstructed static polygons using sort_reconstructed_static_polygons:

pygplates.SortReconstructedStaticPolygons.by_plate_id: Search by plate ID (from highest to lowest).
pygplates.SortReconstructedStaticPolygons.by_plate_area: Search by plate area (from highest to lowest).
None: Search using the original order. This is the order of reconstructable features (see constructor), and includes the order across any reconstructable feature collections/files.

Note

The default search order is pygplates.SortReconstructedStaticPolygons.by_plate_id to ensure the results are the same regardless of the order of reconstructable features (specified in the constructor).

To associate each point with the reconstructed static polygon containing it:

reconstructed_static_polygons = reconstruct_snapshot.get_point_locations(points)

for point_index in range(len(points)):
    point = points[point_index]
    reconstructed_static_polygon = reconstructed_static_polygons[point_index]

    if reconstructed_static_polygon:  # if point is inside a reconstructed static polygon
        ...

Added in version 0.50.

get_point_velocities(points[, velocity_delta_time=1.0][, velocity_delta_time_type=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t][, velocity_units=pygplates.VelocityUnits.kms_per_my][, earth_radius_in_kms=pygplates.Earth.mean_radius_in_kms][, sort_reconstructed_static_polygons=pygplates.SortReconstructedStaticPolygons.by_plate_id][, return_point_locations=False])

Returns the velocities of the specified points (as determined by the reconstructed static polygons that contain them).

Parameters:

points (any sequence of PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – sequence of points at which to calculate velocities
velocity_delta_time (float) – The time delta used to calculate velocities (defaults to 1 Myr).
velocity_delta_time_type (VelocityDeltaTimeType.t_plus_delta_t_to_t, VelocityDeltaTimeType.t_to_t_minus_delta_t or VelocityDeltaTimeType.t_plus_minus_half_delta_t) – How the two velocity times are calculated relative to the reconstruction time. This includes [t+dt, t], [t, t-dt] and [t+dt/2, t-dt/2]. Defaults to [t+dt, t].
velocity_units (VelocityUnits.kms_per_my or VelocityUnits.cms_per_yr) – whether to return velocities as kilometres per million years or centimetres per year (defaults to kilometres per million years)
earth_radius_in_kms (float) – the radius of the Earth in kilometres (defaults to pygplates.Earth.mean_radius_in_kms)
sort_reconstructed_static_polygons (pygplates.SortReconstructedStaticPolygons.by_plate_id or pygplates.SortReconstructedStaticPolygons.by_plate_area or None) – optional sort order of reconstructed static polygons (defaults to pygplates.SortReconstructedStaticPolygons.by_plate_id)
return_point_locations – whether to also return the reconstructed static polygon that contains each point - defaults to False

Return type:

list of Vector3D, or 2-tuple (list of Vector3D, list of ReconstructedFeatureGeometry) if return_point_locations is True

Reconstructed static polygons are reconstructed feature geometries that have polygon geometries (other geometry types are ignored since only polygons can contain points). The reconstructed feature geometries are obtained from get_reconstructed_geometries() with reconstruct_types=pygplates.ReconstructType.feature_geometry and same_order_as_reconstructable_features=True.

Note

Each point that is outside all reconstructed static polygons will have a velocity of None, and optionally (if return_point_locations is True) have a point location (reconstructed static polygon) of None.

Reconstructed static polygons can overlap each other at reconstruction times in the past (unlike resolved topological plates which typically do not overlap). This means a point could be contained inside more than one reconstructed static polygon, but only the first one will be returned for that point. However, you can change the search order of reconstructed static polygons using sort_reconstructed_static_polygons:

pygplates.SortReconstructedStaticPolygons.by_plate_id: Search by plate ID (from highest to lowest).
pygplates.SortReconstructedStaticPolygons.by_plate_area: Search by plate area (from highest to lowest).
None: Search using the original order. This is the order of reconstructable features (see constructor), and includes the order across any reconstructable feature collections/files.

Note

The default search order is pygplates.SortReconstructedStaticPolygons.by_plate_id to ensure the results are the same regardless of the order of reconstructable features (specified in the constructor).

To associate each point with its velocity and the reconstructed static polygon containing it:

velocities, reconstructed_static_polygons = reconstruct_snapshot.get_point_velocities(
        points,
        return_point_locations=True)

for point_index in range(len(points)):
    point = points[point_index]
    velocity = velocities[point_index]
    reconstructed_static_polygon = reconstructed_static_polygons[point_index]

    if velocity:  # if point is inside a reconstructed static polygon
        ...

Note

It is more efficient to call reconstruct_snapshot.get_point_velocities(points, return_point_locations=True) to get both velocities and point locations than it is to call both reconstruct_snapshot.get_point_velocities(points) and reconstruct_snapshot.get_point_locations(points).

Added in version 0.50.

get_reconstructed_features([reconstruct_types=pygplates.ReconstructType.feature_geometry])

Returns the reconstructed geometries of the requested type(s) grouped by their feature.

Parameters:: reconstruct_types (a bitwise combination of any of pygplates.ReconstructType.feature_geometry, pygplates.ReconstructType.motion_path or pygplates.ReconstructType.flowline) – specifies which types of features to reconstruct - defaults to reconstructing only regular features (not motion paths or flowlines)
Returns:: a list of tuples, where each tuple contains a Feature and a list of reconstructed geometries (each reconstructed geometry is a reconstructed feature geometry, reconstructed motion path or reconstructed flowline - depending on the optional argument reconstruct_types)
Return type:: list
Raises:: ValueError if reconstruct_types (if specified) contains a flag that is not one of pygplates.ReconstructType.feature_geometry, pygplates.ReconstructType.motion_path or pygplates.ReconstructType.flowline

This can be useful (compared to get_reconstructed_geometries()) when a feature has more than one (present day) geometry and hence more than one reconstructed geometry.

Note

The returned features (and associated reconstructed geometries) are sorted in the order of their respective reconstructable features (see constructor). This includes the order across any reconstructable feature collections/files.

Note

The reconstruct_types argument accepts more than one reconstruct type, unlike export_reconstructed_geometries() and reconstruct().

To get the reconstructed feature geometries grouped by their Feature:

reconstructed_features = reconstruct_snapshot.get_reconstructed_features()
for feature, feature_reconstructed_geometries in reconstructed_features:
    # Note that 'feature' is the same as 'feature_reconstructed_geometry.get_feature()'.
    for feature_reconstructed_geometry in feature_reconstructed_geometries:
        ...