pygplates.resolve_topologies

pygplates.resolve_topologies(topological_features, rotation_model, resolved_topologies, reconstruction_time[, resolved_topological_sections][, anchor_plate_id][, default_resolve_topology_parameters][, **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. Note: Each sequence entry can optionally be a 2-tuple (entry, ResolveTopologyParameters) to override default_resolve_topology_parameters for that entry.

  • 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). Default is to do neither.

  • anchor_plate_id (int) – The anchored plate id used during reconstruction. Defaults to the default anchor plate of rotation_model.

  • default_resolve_topology_parameters (ResolveTopologyParameters) – Default parameters used to resolve topologies. Note that these can optionally be overridden in topological_features. Defaults to default-constructed ResolveTopologyParameters).

  • output_parameters – Variable number of keyword arguments specifying output parameters (see table below). Default is no keyword arguments.

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), or if resolved_topologies or resolved_topological_sections is a filename and it is not supported for writing

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

Raises

ValueError if resolve_topological_section_types (if specified) contains a flag that is not one of 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:

  • ResolveTopologyType.line:

  • ResolveTopologyType.boundary:

  • ResolveTopologyType.network:

Determines whether to output ResolvedTopologicalLine, ResolvedTopologicalBoundary and ResolvedTopologicalNetwork.

resolve_topological_section_types

int

Same value as resolve_topology_types (if specified), otherwise its default value ResolveTopologyType.boundary | ResolveTopologyType.network

A bitwise combination of any of the following:

  • ResolveTopologyType.boundary:

  • ResolveTopologyType.network:

Note

ResolveTopologyType.line is excluded since only topologies with boundaries are considered.

Determines whether ResolvedTopologicalBoundary or ResolvedTopologicalNetwork (or both types) are referenced in the resolved topological sections of resolved_topological_sections.

export_topological_line_sub_segments

bool

True
Export the individual sub-segments of each boundary segment that came from a resolved topological line (instead of exporting a single geometry per boundary segment).

Note

Only applies when exporting to a file specified with resolved_topological_sections.

See also

TopologicalSnapshot.export_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

int

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 geodata 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).
Both resolved_topologies and resolved_topological_sections are output in the same order as that of their respective features in topological_features (the order across feature collections is also retained). This happens regardless of whether topological_features, and resolved_topologies and resolved_topological_sections, include files or not.

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 referenced in the shared sub-segments of the resolved_topological_sections.

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’

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 FeatureCollection 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)

Changed in version 0.29: The output order of resolved_topological_sections is now same as that of their respective features in topological_features (the order across feature collections is also retained). Previously the order was only retained for resolved_topologies.

Changed in version 0.31: Added default_resolve_topology_parameters argument.

Changed in version 0.33: Added export_topological_line_sub_segments argument.