pygplates.ResolvedTopologicalNetwork

class pygplates.ResolvedTopologicalNetwork

Bases: ReconstructionGeometry

The geometry of a topological network feature resolved to a geological time.

TopologicalModel, TopologicalSnapshot or resolve_topologies() can be used to generate ResolvedTopologicalNetwork instances.

__init__(): Raises an exception This class cannot be instantiated from Python

Methods

`__init__`	Raises an exception This class cannot be instantiated from Python
`get_boundary_sub_segments`()	Returns the `sub-segments` that make up the boundary of this resolved topological network.
`get_feature`()	Returns the feature associated with this `ResolvedTopologicalNetwork`.
`get_network_triangulation`()	Returns the triangulation of this resolved topological network.
`get_point_location`(point)	Determines whether the specified point lies within this resolved topological network.
`get_point_strain_rate`(point)	Returns the strain rate of the specified point (if it lies within this resolved topological network).
`get_point_velocity`(point, ...)	Returns the velocity of the specified point (if it lies within this resolved topological network).
`get_property`()	Returns the feature property containing the topological network property associated with this `ResolvedTopologicalNetwork`.
`get_reconstruction_time`()	Returns the reconstruction time that this instance was created at.
`get_resolved_boundary`(...)	Returns the resolved boundary of this network.
`get_resolved_feature`()	Returns a feature containing the resolved boundary geometry.
`get_resolved_geometry`(...)	Same as `get_resolved_boundary()`.
`get_resolved_geometry_point_velocities`(...)	Returns the velocities of the `resolved geometry points`.
`get_resolved_geometry_points`(...)	Returns the points of the `resolved geometry`.
`get_rigid_blocks`()	Returns the interior rigid blocks (if any) inside this resolved topological network.
`reconstruct_point`(point, ...)	Incrementally reconstruct the specified point (if it lies within this resolved topological network) to the specified reconstruction time.

get_boundary_sub_segments()

Returns the sub-segments that make up the boundary of this resolved topological network.

Return type:: list of ResolvedTopologicalSubSegment

To get a list of the unreversed boundary sub-segment geometries:

sub_segment_geometries = []
for sub_segment in resolved_topological_network.get_boundary_sub_segments():
    sub_segment_geometries.append(sub_segment.get_resolved_geometry())

To get a list of sub-segment geometries with points in the same order as this topological network boundary:

sub_segment_geometries = []
for sub_segment in resolved_topological_network.get_boundary_sub_segments():
    sub_segment_geometry = sub_segment.get_resolved_geometry()
    if sub_segment.was_geometry_reversed_in_topology():
        # Create a new sub-segment polyline with points in reverse order.
        sub_segment_geometry = pygplates.PolylineOnSphere(sub_segment_geometry[::-1])
    sub_segment_geometries.append(sub_segment_geometry)

The following is essentially equivalent to get_resolved_boundary() (except rubber banding points, if any, between adjacent sub-segments are included below but not in get_resolved_boundary()):

def get_resolved_boundary(resolved_topological_network):

    resolved_boundary_points = []
    for sub_segment in resolved_topological_network.get_boundary_sub_segments():
        sub_segment_points = sub_segment.get_resolved_geometry().get_points()
        if sub_segment.was_geometry_reversed_in_topology():
            # Reverse the sub-segment points.
            sub_segment_points = sub_segment_points[::-1]
        resolved_boundary_points.extend(sub_segment_points)

    return pygplates.PolygonOnSphere(resolved_boundary_points)

get_feature()

Returns the feature associated with this ResolvedTopologicalNetwork.

Return type:: Feature

Note

The returned feature is what was used to generate this ResolvedTopologicalNetwork via TopologicalModel, TopologicalSnapshot or resolve_topologies().

See also

get_resolved_feature()

get_network_triangulation()

Returns the triangulation of this resolved topological network.

Return type:: NetworkTriangulation

See also

Network triangulation in the Primer documentation.

Added in version 0.50.

get_point_location(point)

Determines whether the specified point lies within this resolved topological network.

Parameters:: point (PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – the point to be tested
Return type:: TopologyPointLocation

If the point lies within this resolved topological network then TopologyPointLocation.located_in_resolved_network() will return this resolved topological network, otherwise it will return None (in addition to TopologyPointLocation.not_located_in_resolved_topology() returning True).

To test if a (latitude, longitude) point is inside a resolved topological network:

if resolved_topological_network.get_point_location((latitude, longitude)).located_in_resolved_network():
  ...

Furthermore, if the point lies within this resolved topological network then it will either be in the deforming region or in a rigid block (if any).

To test if a (latitude, longitude) point is inside a resolved topological network’s deforming region or inside a rigid block:

point_location = resolved_topological_network.get_point_location((latitude, longitude))
if point_location.located_in_resolved_network_deforming_region():
  ...
elif point_location.located_in_resolved_network_rigid_block():
  _, rigid_block = point_location.located_in_resolved_network_rigid_block()
  ...
else:  # point is outside resolved topological network
  ...

Note

TopologyPointLocation.located_in_resolved_boundary() will always return None since this is a network (not a rigid plate). TopologyPointLocation is just returned for consistency with ResolvedTopologicalBoundary.get_point_location().

This method is essentially equivalent to:

def get_point_location(resolved_topological_network, point):
    # See if point is located within the resolved topological network boundary.
    if resolved_topological_network.get_resolved_boundary().is_point_in_polygon(point):
        # See if point is located in a rigid block (if any) of the resolved topological network.
        for rigid_block in resolved_topological_network.get_rigid_blocks():
            if rigid_block.get_reconstructed_geometry().is_point_in_polygon(point):
                return resolved_topological_network, rigid_block
        # Point must therefore be located in the deforming region of the resolved topological network.
        return resolved_topological_network

    # Point is *not* located in the resolved topological network.
    return None

Added in version 0.49.

get_point_strain_rate(point)

Returns the strain rate of the specified point (if it lies within this resolved topological network).

Parameters:: point (PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – the point to calculate strain rate at
Return type:: StrainRate or None

If the point lies within this resolved topological network (which can be either its deforming region or one of its rigid blocks) then a strain rate will be returned, otherwise None will be returned.

Note

If point is inside a rigid block (of this resolved topological network) then pygplates.StrainRate.zero will be returned.

To calculate the strain rate of a (latitude, longitude) point (if it is inside a resolved topological network):

point_strain_rate = resolved_topological_network.get_point_strain_rate((latitude, longitude))
if point_strain_rate is not None:
  ...

This method is essentially equivalent to:

def get_point_strain_rate(resolved_topological_network, point):
    # See if point is located within the resolved topological network.
    if resolved_topological_network.get_resolved_boundary().is_point_in_polygon(point):
        # See if point is located in a rigid block (if any) of the resolved topological network.
        for rigid_block in resolved_topological_network.get_rigid_blocks():
            if rigid_block.get_reconstructed_geometry().is_point_in_polygon(point):
                return pygplates.StrainRate.zero
        # Point must therefore be located in the deforming region of the resolved topological network.
        strain_rate = ...  # calculate strain rate using 'point' and the deforming triangulation
        return strain_rate

    # Point is *not* located in the resolved topological network.
    return None

Added in version 0.49.

get_point_velocity(point[, 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])

Returns the velocity of the specified point (if it lies within this resolved topological network).

Parameters:

point (PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – the point to calculate velocity at
velocity_delta_time (float) – The time delta used to calculate velocity (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 velocity 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)

Return type:

Vector3D or None

If the point lies within this resolved topological network (which can be either its deforming region or one of its rigid blocks) then a velocity vector will be returned, otherwise None will be returned.

Note

If point is inside a rigid block (of this resolved topological network) that does not have a reconstruction plate ID then 0 will be used.

To calculate the velocity of a (latitude, longitude) point (if it is inside a resolved topological network):

point_velocity = resolved_topological_network.get_point_velocity((latitude, longitude))
if point_velocity is not None:
  ...

This method is essentially equivalent to:

def get_point_velocity(resolved_topological_network, point):
    # See if point is located within the resolved topological network.
    if resolved_topological_network.get_resolved_boundary().is_point_in_polygon(point):
        # See if point is located in a rigid block (if any) of the resolved topological network.
        for rigid_block in resolved_topological_network.get_rigid_blocks():
            if rigid_block.get_reconstructed_geometry().is_point_in_polygon(point):
                # Get the reconstruction plate ID of the rigid block.
                # If it doesn't have one then zero will be used instead.
                rigid_block_plate_id = rigid_block.get_feature().get_reconstruction_plate_id()
                rigid_block_velocity = ...  # calculate velocity using 'point' and 'rigid_block_plate_id'
                return rigid_block_velocity
        # Point must therefore be located in the deforming region of the resolved topological network.
        deforming_velocity = ...  # calculate velocity using 'point' and the deforming triangulation
        return deforming_velocity

    # Point is *not* located in the resolved topological network.
    return None

Added in version 0.49.

get_property()

Returns the feature property containing the topological network property associated with this ResolvedTopologicalNetwork.

Return type:: Property

This is the Property that the get_resolved_boundary() is obtained from.

get_resolved_boundary([include_rigid_blocks_as_interior_holes=False])

Returns the resolved boundary of this network.

Parameters:: include_rigid_blocks_as_interior_holes (bool) – Whether to include interior rigid blocks (if any) as interior rings in the returned boundary polygon. Defaults to False.
Return type:: PolygonOnSphere

Changed in version 0.49: Added include_rigid_blocks_as_interior_holes argument.

get_resolved_feature()

Returns a feature containing the resolved boundary geometry.

Return type:: Feature

The returned feature contains the static resolved geometry. Unlike get_feature() it cannot be used to generate a ResolvedTopologicalNetwork via TopologicalModel, TopologicalSnapshot or resolve_topologies().

Note

The returned feature does not contain present-day geometry as is typical of most GPlates features.

In this way the returned feature is similar to a GPlates reconstruction export.

Note

The returned feature should not be reverse reconstructed to present day because topologies are resolved (not reconstructed).

See also

get_feature()

get_resolved_geometry([include_rigid_blocks_as_interior_holes=False]): Same as get_resolved_boundary().

Changed in version 0.49: Added include_rigid_blocks_as_interior_holes argument.

get_resolved_geometry_point_velocities([include_rigid_blocks_as_interior_holes=False][, 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])

Returns the velocities of the resolved geometry points.

Parameters:

include_rigid_blocks_as_interior_holes (bool) – Whether to include velocities at vertices of interior rigid block polygons (if any) in the returned velocities. Defaults to False.
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)

Return type:

list of Vector3D

To associate each velocity with its point (in a resolved topological network):

points = resolved_topological_network.get_resolved_geometry_points()
velocities = resolved_topological_network.get_resolved_geometry_point_velocities()

points_and_velocities = zip(points, point_velocities)

for point, velocity in points_and_velocities:
  ...

Added in version 0.50.

get_resolved_geometry_points([include_rigid_blocks_as_interior_holes=False])

Returns the points of the resolved geometry.

Parameters:: include_rigid_blocks_as_interior_holes (bool) – Whether to include vertices of interior rigid block polygons (if any) in the returned points. Defaults to False.
Return type:: list of PointOnSphere

This method is essentially equivalent to:

def get_resolved_geometry_points(
        resolved_topological_network,
        include_rigid_blocks_as_interior_holes):

    return resolved_topological_network.get_resolved_geometry(
            include_rigid_blocks_as_interior_holes).get_points()

See also

GeometryOnSphere.get_points()

Added in version 0.50.

get_rigid_blocks()

Returns the interior rigid blocks (if any) inside this resolved topological network.

Return type:: list of ReconstructedFeatureGeometry

Each rigid block represents a rigid interior island within the deforming region. And as such, each rigid block will have a reconstructed geometry that is a polygon.

Note

The interior rings (if any) of a rigid block polygon are ignored (ie, only the exterior ring applies).

See also

Rigid blocks in the Primer documentation.

Added in version 0.49.

reconstruct_point(point, reconstruction_time[, use_natural_neighbour_interpolation=True])

Incrementally reconstruct the specified point (if it lies within this resolved topological network) to the specified reconstruction time.

Parameters:

point (PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – The point to reconstruct. It is the position at the reconstruction time of this resolved topological network.
reconstruction_time (float or GeoTimeInstant) – The time to reconstruct to. This can be older or younger than the reconstruction time of this resolved topological network.
use_natural_neighbour_interpolation (bool) – If True and point lies within the deforming region, then the reconstructed point is the interpolation of the natural neighbour deformed triangulation vertex positions (otherwise barycentric interpolation is used). Defaults to True.

Return type:

PointOnSphere or None

Raises:

ValueError if reconstruction_time is distant-past (float('inf')) or distant-future (float('-inf')).

If the point lies within this resolved topological network (which can be either its deforming region or one of its rigid blocks) then it is reconstructed from the reconstruction time of this resolved topological network to the specified reconstruction time, and the reconstructed point is returned (otherwise None will be returned).

The specified reconstruction time can be older or younger than the reconstruction time of this resolved topological network. If it’s older then the point is reconstructed backward in time, and if it’s younger then the point is reconstructed forward in time.

Note

The reconstruction involves calculating a stage rotation (for each nearby vertex of the deforming triangulation) from the reconstruction time of this resolved topological network to reconstruction_time. So ideally a small time increment (such as 1 Myr) should be used since the plate boundaries and rotations typically change over small time intervals.

To deform (reconstruct) a point located at (latitude, longitude) to a new position at a time 1 Myr older than the current time (if point is inside a resolved topological network):

reconstructed_point = resolved_topological_network.reconstruct_point(
        (latitude, longitude),
        resolved_topological_network.get_reconstruction_time() + 1.0)
if reconstructed_point is not None:
  ...

This method is essentially equivalent to:

def reconstruct_point(resolved_topological_network, point, reconstruction_time, use_natural_neighbour_interpolation):
    # See if point is located within the resolved topological network.
    if resolved_topological_network.get_resolved_boundary().is_point_in_polygon(point):
        # See if point is located in a rigid block (if any) of the resolved topological network.
        for rigid_block in resolved_topological_network.get_rigid_blocks():
            if rigid_block.get_reconstructed_geometry().is_point_in_polygon(point):
                # Get the reconstruction plate ID of the rigid block.
                # If it doesn't have one then zero will be used instead.
                rigid_block_plate_id = rigid_block.get_feature().get_reconstruction_plate_id()
                # Rigidly rotate 'point' using 'rigid_block_plate_id' and stage rotation
                # from resolved time to 'reconstruction_time'.
                reconstructed_point = ...
                return reconstructed_point
        # Point must therefore be located in the deforming region of the resolved topological network.
        # Deform 'point' using the deforming triangulation and 'use_natural_neighbour_interpolation'
        # from resolved time to 'reconstruction_time'.
        deformed_point = ...
        return deformed_point

    # Point is *not* located in the resolved topological network.
    return None

Note

If point is inside a rigid block (of this resolved topological network) that does not have a reconstruction plate ID then 0 will be used to reconstruct the point.

Added in version 0.50.