pygplates.reconstruct

pygplates.reconstruct(reconstructable_features, rotation_model, reconstructed_geometries, reconstruction_time[, anchor_plate_id][, **output_parameters])

Reconstruct regular geological features, motion paths or flowlines to a specific geological time.

Parameters

reconstructable_features (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – the features to reconstruct 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 or sequence of FeatureCollection instances and/or strings) – A rotation model or a rotation feature collection or a rotation filename or a sequence of rotation feature collections and/or rotation filenames
reconstructed_geometries (string or list) – the reconstructed feature geometries (default) or reconstructed motion paths or reconstructed flowlines (depending on the optional keyword argument reconstruct_type - see output_parameters table) are either exported to a file (with specified filename) or appended to a Python list (note that the list is not cleared first and note that the list contents are affected by group_with_feature - see output_parameters table)
reconstruction_time (float or GeoTimeInstant) – the specific geological time to reconstruct to
anchor_plate_id (int) – The anchored plate id used during reconstruction. Defaults to the default anchor plate of rotation_model.
output_parameters – variable number of keyword arguments specifying output parameters (see table below)

Raises

OpenFileForReadingError if any input file is not readable (when filenames specified)

Raises

OpenFileForWritingError if reconstructed_geometries is a filename and it is not writeable

Raises

FileFormatNotSupportedError if any input file format (identified by any reconstructable and rotation filename extensions) does not support reading (when filenames specified), or if reconstructed_geometries is a filename and it is not supported for writing

Raises

ValueError if reconstruction_time is distant past or distant future

The following optional keyword arguments are supported by output_parameters:

Name	Type	Default	Description
reconstruct_type	ReconstructType	ReconstructType.feature_geometry	ReconstructType.feature_geometry: only reconstruct regular features (not motion paths or flowlines), this generates `reconstructed feature geometries` ReconstructType.motion_path: only reconstruct motion path features, this generates `reconstructed motion paths` ReconstructType.flowline: only reconstruct flowline features, this generates `reconstructed flowlines`
group_with_feature	bool	False	Group reconstructed geometries with their feature. This can be useful when a feature has more than one geometry and hence more than one reconstructed geometry. reconstructed_geometries then becomes a list of tuples where each tuple contains a `feature` and a `list` of reconstructed geometries. Note Only applies when reconstructed_geometries is a `list` because exported files are always grouped with feature. Note Any ReconstructType can be grouped.
export_wrap_to_dateline	bool	True	Wrap/clip reconstructed geometries to the dateline (currently ignored unless exporting to an ESRI Shapefile format file). Only applies when exporting to a file (ESRI Shapefile).

Only the features, in reconstructable_features, that match the optional keyword argument reconstruct_type (see output_parameters table) are reconstructed. This also determines the type of reconstructed geometries output in reconstructed_geometries which are either reconstructed feature geometries (default) or reconstructed motion paths or reconstructed flowlines.

Note

reconstructed_geometries can be either an export filename or a Python list.
In the latter case the reconstructed geometries (generated by the reconstruction) are appended to the Python list (instead of exported to a file).
And if group_with_feature (see output_parameters table) is True then the list contains tuples that group each feature with a list of its reconstructed geometries.

The reconstructed_geometries are output in the same order as that of their respective features in reconstructable_features (the order across feature collections is also retained). This happens regardless of whether reconstructable_features and reconstructed_geometries include files or not.

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

When exporting to a file, the filename extension of reconstructed_geometries determines the export file format.

If the export format is ESRI Shapefile then the shapefile attributes from reconstructable_features will only be retained in the exported shapefile if there is a single reconstructable feature collection (where reconstructable_features is a single feature collection or file, or sequence containing a single feature collection or file). This is because shapefile attributes from multiple input feature collections are not easily combined into a single output shapefile (due to different attribute field names).

Note

reconstructable_features can be a FeatureCollection or a filename or a Feature or a sequence of features, or a sequence (eg, list or tuple) of any combination of those four types.

Note

rotation_model can be either a RotationModel or a rotation FeatureCollection or a rotation filename or a sequence (eg, list or tuple) containing rotation FeatureCollection instances or filenames (or a mixture of both). When a RotationModel is not specified then a temporary one is created internally (and hence is less efficient if this function is called multiple times with the same rotation data).

If any filenames are specified then FeatureCollection is used internally to read feature collections from those files.

Reconstructing a file containing regular reconstructable features to a shapefile at 10Ma:

pygplates.reconstruct('volcanoes.gpml', 'rotations.rot', 'reconstructed_volcanoes_10Ma.shp', 10)

Reconstructing multiple files containing regular reconstructable features to a list of reconstructed feature geometries at 10Ma:

reconstructed_feature_geometries = []
pygplates.reconstruct(['continent_ocean_boundaries.gpml', 'isochrons.gpml'], rotation_model, reconstructed_feature_geometries, 10)

…and the same but also grouping the reconstructed feature geometries with their feature:

reconstructed_features = []
pygplates.reconstruct(['continent_ocean_boundaries.gpml', 'isochrons.gpml'], rotation_model, reconstructed_features, 10, group_with_feature=True)
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:
        ...

Reconstructing a file containing flowline features to a shapefile at 10Ma:

pygplates.reconstruct('flowlines.gpml', rotation_model, 'reconstructed_flowlines_10Ma.shp', 10, reconstruct_type=pygplates.ReconstructType.flowline)

Reconstructing a file containing flowline features to a list of reconstructed flowlines at 10Ma:

reconstructed_flowlines = []
pygplates.reconstruct('flowlines.gpml', rotation_model, reconstructed_flowlines, 10, reconstruct_type=pygplates.ReconstructType.flowline)

Reconstructing regular reconstructable features to a shapefile at 10Ma:

pygplates.reconstruct(pygplates.FeatureCollection([feature1, feature2]), rotation_model, 'reconstructed_features_10Ma.shp', 10)

Reconstructing a list of regular reconstructable features to a shapefile at 10Ma:

pygplates.reconstruct([feature1, feature2], rotation_model, 'reconstructed_features_10Ma.shp', 10)

Reconstructing a single regular reconstructable feature to a list of reconstructed feature geometries at 10Ma:

reconstructed_feature_geometries = []
pygplates.reconstruct(feature, rotation_model, reconstructed_feature_geometries, 10)
# assert(reconstructed_feature_geometries[0].get_feature().get_feature_id() == feature.get_feature_id())