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/os.PathLike, 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 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/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.
resolved_topologies (string/os.PathLike 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/os.PathLike 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)