pygplates.resolve_topologies

pygplates.resolve_topologies(topological_features, rotation_model, resolved_topologies, reconstruction_time[, resolved_topological_sections][, anchor_plate_id=0][, **output_parameters])

Resolve topological features (lines, boundaries and networks) to a specific geological time.

Parameters:
  • topological_features (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – the topological boundary and network features and the topological section features they reference (regular and topological lines) 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
  • resolved_topologies (string or list) – the resolved topological lines, resolved topological boundaries and resolved topological networks (depending on the optional keyword argument resolve_topology_types - 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)
  • reconstruction_time (float or GeoTimeInstant) – the specific geological time to resolve to
  • resolved_topological_sections (string or list) – the resolved topological sections are either exported to a file (with specified filename) or appended to a python list (note that the list is not cleared first)
  • anchor_plate_id (int) – the anchored plate id used during reconstruction
  • 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 resolved_topologies is a filename and it is not writeable
Raises:

FileFormatNotSupportedError if any input file format (identified by any topological and rotation filename extensions) does not support reading (when filenames specified)
Raises:

ValueError if reconstruction_time is distant past or distant future
Raises:

ValueError if resolve_topology_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.line, pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

The following optional keyword arguments are supported by output_parameters:

Name Type Default Description
resolve_topology_types int ResolveTopologyType.boundary | ResolveTopologyType.network

A bitwise combination of any of the following:
resolve_topological_section_types int Same value as resolve_topology_types

Supports the same options as resolve_topology_types.

Note

Although ResolveTopologyType.line is ignored if specified since only boundary topologies are considered.

Determines whether ResolvedTopologicalBoundary or ResolvedTopologicalNetwork (or both types) are listed in the resolved topological sections of resolved_topological_sections.
export_wrap_to_dateline bool True
Wrap/clip resolved topologies to the dateline (currently ignored unless exporting to an ESRI Shapefile format file).

Note

Only applies when exporting to a file (ESRI Shapefile).
export_force_boundary_orientation bool None (don’t force)

Optionally force boundary orientation (clockwise or counter-clockwise):

  • PolygonOnSphere.Orientation.clockwise
  • PolygonOnSphere.Orientation.counter_clockwise

Note

Only applies to resolved topological boundaries and networks.

Note

ESRI Shapefiles always use clockwise orientation.

Warning

Only applies when exporting to a file (except ESRI Shapefile).
The argument topological_features consists of the topological features as well as the topological sections (also features) that are referenced by the topological features.
They can all be mixed in a single feature collection or file, or they can be distributed across multiple feature collections or files.
For example the dynamic polygons in the GPlates sample data have everything in a single file.

Note

Topological sections can be regular features or topological line features. The latter are typically used for sections of a plate polygon (or network) boundary that are deforming.

The argument resolved_topologies can be either an export filename or a python list.
In the latter case the resolved topologies generated by the reconstruction are appended to the python list (instead of exported to a file).
A similar argument resolved_topological_sections can also be either an export filename or a python list.
In the latter case the resolved topological sections generated by the reconstruction are appended to the python list (instead of exported to a file).

Note

Resolved topological sections can be used to find the unique (non-overlapping) set of boundary sub-segments that are shared by the resolved topologies.
Each resolved topology also has a list of its boundary sub-segments but they overlap with the boundary sub-segments of neighbouring topologies.
The optional keyword argument resolve_topology_types (see output_parameters table) determines the type of resolved topologies output to resolved_topologies.
This can consist of resolved topological lines, resolved topological boundaries and resolved topological networks (and any combination of them).
By default only resolved topological boundaries and resolved topological networks are output since resolved topological lines are typically only used as topological sections for resolved topological boundaries and networks.
A similar optional keyword argument is resolve_topological_section_types (see output_parameters table).
This determines which resolved topology types are listed in the shared sub-segments of the resolved_topological_sections.

The following export file formats are currently supported by GPlates:

Export File Format Filename Extension
ESRI Shapefile ‘.shp’
OGR GMT ‘.gmt’
GMT xy ‘.xy’

Warning

Currently, resolved topological networks exported to OGR GMT or ESRI Shapefile will not be loaded if the exported file is subsequently loaded into GPlates.
The resolved topological networks will still be in the exported file though.

Note

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

Note

topological_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 FeatureCollectionFileFormatRegistry is used internally to read feature collections from those files.

Resolving a file containing dynamic plate polygons to a shapefile at 10Ma:

pygplates.resolve_topologies(
    'dynamic_plate_polygons.gpml', 'rotations.rot', 'resolved_plate_polygons_10Ma.shp', 10)
Resolving the same file but also exporting resolved topological sections.
These are the unique (non-duplicated) segments (shared by neighbouring topology boundaries).
pygplates.resolve_topologies(
   'dynamic_plate_polygons.gpml', 'rotations.rot', 'resolved_plate_polygons_10Ma.shp', 10,
   'resolved_plate_segments_10Ma.shp')

Resolving only topological networks in a file containing both dynamic plate polygons and deforming networks:

pygplates.resolve_topologies(
    'plate_polygons_and_networks.gpml', 'rotations.rot', 'resolved_networks_10Ma.shp', 10,
    resolve_topology_types=pygplates.ResolveTopologyType.network)

Writing only resolved networks to resolved_networks_10Ma.shp but writing shared boundary segments between resolved plate polygons and networks to resolved_boundary_segments_10Ma.shp:

pygplates.resolve_topologies(
    'plate_polygons_and_networks.gpml', 'rotations.rot', 'resolved_networks_10Ma.shp', 10,
    'resolved_boundary_segments_10Ma.shp',
    resolve_topology_types=pygplates.ResolveTopologyType.network,
    resolve_topological_section_types=pygplates.ResolveTopologyType.boundary | pygplates.ResolveTopologyType.network)

Resolving to a list of topologies and a list of topological sections:

resolved_topologies = []
resolved_topological_sections = []
pygplates.resolve_topologies(
    'plate_polygons_and_networks.gpml', 'rotations.rot', resolved_topologies, 10,
     resolved_topological_sections)