resqpy.surface.TriMesh

class resqpy.surface.TriMesh(parent_model, uuid=None, t_side=None, nj=None, ni=None, origin=None, z_values=None, z_uom=None, surface_role='map', crs_uuid=None, title=None, originator=None, extra_metadata=None)

Bases: Mesh

Class of mesh using equilateral triangles in the xy plane.

Public Data Attributes:

Inherited from Mesh

resqml_type

Inherited from BaseResqpy

resqml_type	Definition of which RESQML object the class represents.
part	Standard part name corresponding to self.uuid.
root	XML node corresponding to self.uuid.
citation_title	Citation block title equivalent to self.title.

Commonly Used Methods:

Inherited from Mesh

__init__(parent_model[, uuid, mesh_file, ...])

Initialises a Mesh object from xml, or a regular mesh from arguments.

Methods:

__init__(parent_model[, uuid, t_side, nj, ...])	Initialises a TriMesh object from xml, or from arguments.
from_tri_mesh_and_z_values(tri_mesh, z_values)	Create a new tri mesh with the same xy pattern as an existing one, updating z.
tji_for_xy(xy)	Return (tj, ti) indices of triangle containing point xy (x, y).
tji_for_xy_array(xy_array)	Return array of (tj, ti) indices of triangles containing points xy_array (..., 2 or 3).
tji_tc_for_xy(xy)	Return indices of triangle containing point xy (x, y), and trilinear coordinates within triangle.
tji_tc_for_xy_array(xy_array)	Return indices of triangles containing array of points xy, and trilinear coordinates within triangles.
ji_and_weights_for_xy(xy)	Returns triplet of point ji indices and triplet of weights for interpolation at point xy.
ji_and_weights_for_xy_array(xy_array)	Returns arrays of triplet of point ji indices and triplet of weights for interpolation at points xy_array.
interpolated_z(xy)	Returns z value interpolated trilinearly at point xy.
interpolated_z_array(xy_array)	Returns z values interpolated trilinearly at points xy_array.
tri_nodes_for_tji(tji)	Return mesh node indices, shape (3, 2), for triangle tji (tj, ti).
tri_nodes_for_tji_array(tji_array)	Return mesh node indices, shape (..., 3, 2), for triangles tji_array (..., 2) being (tj, ti).
all_tri_nodes()	Returns array of mesh node indices for all triangles, shape (nj - 1, 2 * (ni - 1), 3, 2).
triangles_and_points()	Returns node indices and xyz points in form suitable for a Surface (triangulated set).
tji_for_triangle_index(ti)	Return triangle tji (tj, ti) for triangle index in Surface (triangulated set) protocol.
triangle_index_for_tji(tji)	Return triangle index in Surface (triangulated set) protocol for triangle tji (tj, ti).
tri_nodes_in_triangles(triangles)	Return indices of nodes of this tri mesh which are within other triangles, in xy space.
edge_zero_crossings([z_values])	Returns numpy list of points from edges where z values cross zero (or given value).
axial_edge_crossings(axis[, value])	Returns list-like array of points interpolated from edges that cross value in axis.
area([required_uom])	Returns approximate area of tri mesh based on proportion of non-NaN z values.
is_compatible_with(other_tri_mesh)	Returns True if this tri mesh has the same xy points as the other.

Inherited from Mesh

from_regular_grid_column_property(...)	Creates a reg&z flavoured Mesh from an aligned regular grid column property.
is_big()	Returns True if the number of nodes exceeds 2^31 - 1, False otherwise.
set_represented_interpretation_root(interp_root)	Makes a note of the xml root of the represented interpretation.
full_array_ref()	Populates a full 2D(+1) numpy array of shape (nj, ni, 3) with xyz values, caches and returns.
surface([quad_triangles])	Returns a surface object generated from this mesh.
write_hdf5([file_name, mode, use_xy_only])	Create or append to an hdf5 file, writing datasets for the mesh depending on flavour.
create_xml([ext_uuid, use_xy_only, ...])	Creates a grid 2d representation xml node from this mesh object and optionally adds as part of model.

Inherited from BaseSurface

create_interpretation_and_feature([kind, ...])

Creates xml and objects for a represented interpretaion and interpreted feature, if not already present.

Inherited from BaseResqpy

__init__(model[, uuid, title, originator, ...])	Load an existing resqml object, or create new.
try_reuse()	Look for an equivalent existing RESQML object and modify the uuid of this object if found.
create_xml([title, originator, ...])	Write citation block to XML.
append_extra_metadata(meta_dict)	Append a given dictionary of metadata to the existing metadata.
__eq__(other)	Implements equals operator; uses is_equivalent() otherwise compares class type and uuid.
__ne__(other)	Implements not equal operator.
__repr__()	String representation.

__init__(parent_model, uuid=None, t_side=None, nj=None, ni=None, origin=None, z_values=None, z_uom=None, surface_role='map', crs_uuid=None, title=None, originator=None, extra_metadata=None)

Initialises a TriMesh object from xml, or from arguments.

Parameters:

• parent_model (model.Model object) – the model to which this Mesh object will be associated

• uuid (uuid.UUID, optional) – the uuid of an existing RESQML obj_Grid2dRepresentation object from which this resqpy Mesh object is populated

• t_side (float, optional) – the length of a side of each triangle; units are xy units of crs; required if uuid is None

• nj (int, optional) – the number of nodes (NB. not ‘cells’) in the j axis of the mesh; required if uuid is None

• ni (int, optional) – the number of nodes in the i axis of the mesh; required if uuid is None

• origin (triple float, optional) – the xyz origin of the regular mesh; z usually zero; defaults to triple zero

• z_values (numpy int array of shape (nj, ni), optional) – z values; recommended if uuid is None or will default to zero

• z_uom (str, optional) – recommended if uuid is None and z values are not in the crs z space

• surface_role (string, default 'map') – ‘map’ or ‘pick’; ignored if uuid is not None

• crs_uuid (uuid.Uuid or string, optional) – required if generating a regular mesh, the uuid of the crs

• title (str, optional) – the citation title to use for a new mesh; ignored if uuid is not None

• originator (str, optional) – the name of the person creating the mesh, defaults to login id; ignored if uuid is not None

• extra_metadata (dict, optional) – string key, value pairs to add as extra metadata for the mesh; ignored if uuid is not None

Returns:

the newly created TriMesh object

Note

using the z_uom argument will result in the tri mesh’s full_array_ref() method returning data with x and y values in the object’s crs, whilst z values will be in the given uom

all_tri_nodes()

Returns array of mesh node indices for all triangles, shape (nj - 1, 2 * (ni - 1), 3, 2).

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

area(required_uom=None)

Returns approximate area of tri mesh based on proportion of non-NaN z values.

Parameters:

required_uom (-) – RESQML area unit of measure string for result

Returns:

• float being the approximate area of the tri mesh in its xy projection

Note

• default uom is crs xy_units squared

axial_edge_crossings(axis, value=0.0)

Returns list-like array of points interpolated from edges that cross value in axis.

Parameters:

• axis (int) – xyz axis for crossings; 0: x, 1: y, 2: z

• value (float, default 0.0) – the value to detect crossings for

Returns:

numpy float array of shape (N, 3) being the points on tri mesh edges at which the axial crossing occurs

property citation_title

Citation block title equivalent to self.title.

create_interpretation_and_feature(kind='horizon', name=None, interp_title_suffix=None, is_normal=True)

Creates xml and objects for a represented interpretaion and interpreted feature, if not already present.

create_xml(ext_uuid=None, use_xy_only=False, add_as_part=True, add_relationships=True, title=None, originator=None)

Creates a grid 2d representation xml node from this mesh object and optionally adds as part of model.

Parameters:

• ext_uuid (uuid.UUID, optional) – the uuid of the hdf5 external part holding the mesh array

• use_xy_only (boolean, default False) – if True and the flavour of this mesh is explicit, only the xy coordinates are stored in the hdf5 dataset, otherwise xyz are stored

• add_as_part (boolean, default True) – if True, the newly created xml node is added as a part in the model

• add_relationships (boolean, default True) – if True, a relationship xml part is created relating the new grid 2d part to the crs part (and optional interpretation part), and to the represented interpretation if present

• title (string, optional) – used as the citation Title text; should be meaningful to a human

• originator (string, optional) – the name of the human being who created the grid 2d representation part; default is to use the login name

Returns:

the newly created grid 2d representation (mesh) xml node

edge_zero_crossings(z_values=None)

Returns numpy list of points from edges where z values cross zero (or given value).

Parameters:

z_values (numpy float array of shape (nj, ni), optional) – if present, these values are used to determine the crossing points, though returned xyz values are from the tri mesh’s array

Returns:

numpy float array of shape (N, 3) being points on tri mesh triangle edges where z values cross zero

classmethod from_regular_grid_column_property(parent_model, grid_uuid, property_uuid)

Creates a reg&z flavoured Mesh from an aligned regular grid column property.

Parameters:

• parent_model (Model) – the model that the property is part of and the new Mesh will be part of

• grid_uuid (uuid) – the uuid of the RegularGrid object

• property_uuid (uuid) – the uuid of a property whose supporting representation is a RegularGrid and where the indexable elements are columns

Returns:

a new Mesh object with flavour reg&z, the xy regular points are the column centres and the z values are the property values

Notes

the grid’s (constant) dx, dy & dz properties must be avaiable in the model; the property must not be a points property and must have a count of 1; discrete property data will be converted to continuous (float) data; if the property uom is of quantity class length, a suitable crs will be used for the mesh, otherwise the grid’s crs will be used and a uom extra metadata item will be added; calling code will need to call the write_hdf5() and create_xml() methods for the mesh

classmethod from_tri_mesh_and_z_values(tri_mesh, z_values, z_uom=None, title=None, surface_role='map', extra_metadata=None)

Create a new tri mesh with the same xy pattern as an existing one, updating z.

full_array_ref()

Populates a full 2D(+1) numpy array of shape (nj, ni, 3) with xyz values, caches and returns.

Note

z values may be zero or not applicable when using the mesh as support for properties.

interpolated_z(xy)

Returns z value interpolated trilinearly at point xy.

interpolated_z_array(xy_array)

Returns z values interpolated trilinearly at points xy_array.

is_big()

Returns True if the number of nodes exceeds 2^31 - 1, False otherwise.

is_compatible_with(other_tri_mesh)

Returns True if this tri mesh has the same xy points as the other.

ji_and_weights_for_xy(xy)

Returns triplet of point ji indices and triplet of weights for interpolation at point xy.

Parameters:

xy (pair of floats) – coordinates x, y of a point of interest

Returns:

numpy int array of shape (3, 2) and numpy triple float; int array holds mesh ji indices of three vertices of triangle containing xy; float triplet contains corresponding weights (summing to one) which can be used to interpolate z values at point xy

ji_and_weights_for_xy_array(xy_array)

Returns arrays of triplet of point ji indices and triplet of weights for interpolation at points xy_array.

Parameters:

xy_array (numpy float array of shape(..., 2 or 3)) – coordinates x, y of points of interest

Returns:

numpy int array of shape (…, 3, 2) and numpy float array of shape (…, 3); int array holds mesh ji indices of three vertices of triangles containing xy points; float triplets contain corresponding weights (summing to one per triangle) which can be used to interpolate z values at points xy_array

property part

Standard part name corresponding to self.uuid.

property root

XML node corresponding to self.uuid.

set_represented_interpretation_root(interp_root)

Makes a note of the xml root of the represented interpretation.

surface(quad_triangles=False)

Returns a surface object generated from this mesh.

tji_for_triangle_index(ti)

Return triangle tji (tj, ti) for triangle index in Surface (triangulated set) protocol.

tji_for_xy(xy)

Return (tj, ti) indices of triangle containing point xy (x, y).

Note

tj triangle indices are in the range 0..nj - 2 inclusive ti triangle indices are in the range 0..(ni - 2) * 2 + 1 inclusive

tji_for_xy_array(xy_array)

Return array of (tj, ti) indices of triangles containing points xy_array (…, 2 or 3).

Note

tj triangle indices are in the range 0..nj - 2 inclusive ti triangle indices are in the range 0..(ni - 2) * 2 + 1 inclusive

tji_tc_for_xy(xy)

Return indices of triangle containing point xy (x, y), and trilinear coordinates within triangle.

Parameters:

xy (pair of floats) – coordinates x, y of a point of interest

Returns:

((tj, ti), (f0, f1, f2)) – the indices of the triangle containing the point xy, and the trilinear coordinates of the point within the triangle; f2 is component from base edge towards point 2; f1 is component towards point 1; f0 is component towards point 0; the trilinear coordinates sum to one and can be used as weights to interpolate z values at point xy

tji_tc_for_xy_array(xy_array)

Return indices of triangles containing array of points xy, and trilinear coordinates within triangles.

Parameters:

xy_array (numpy float array of shape (..., 2 or 3)) – coordinates x, y of points of interest

Returns:

pair of numpy arrays of shape (…, 2) and (…, 3); the first has int elements, being (tj, ti) indices of the triangles containing each point xy; the second has float elements, being the trilinear coordinates of the points within the triangles; f2 is component from base edge towards point 2; f1 is component towards point 1; f0 is component towards point 0; the trilinear coordinates sum to one and can be used as weights to interpolate z values at points

tri_nodes_for_tji(tji)

Return mesh node indices, shape (3, 2), for triangle tji (tj, ti).

tri_nodes_for_tji_array(tji_array)

Return mesh node indices, shape (…, 3, 2), for triangles tji_array (…, 2) being (tj, ti).

tri_nodes_in_triangles(triangles)

Return indices of nodes of this tri mesh which are within other triangles, in xy space.

Parameters:

triangles (numpy float array of shape (N, 3, 2)) – other triangles’ vertices in 2D (last axis is x,y)

Returns:

numpy int array (list-like) of shape (M, 3) where last axis is (triangle index, nj, ni)

Note

other triangles must be in the same crs as this tri mesh; they do not need to be equilateral

triangle_index_for_tji(tji)

Return triangle index in Surface (triangulated set) protocol for triangle tji (tj, ti).

triangles_and_points()

Returns node indices and xyz points in form suitable for a Surface (triangulated set).

try_reuse()

Look for an equivalent existing RESQML object and modify the uuid of this object if found.

Returns:

boolean – True if an equivalent object was found, False if not

Note

by design this method may change this object’s uuid as a side effect

write_hdf5(file_name=None, mode='a', use_xy_only=False)

Create or append to an hdf5 file, writing datasets for the mesh depending on flavour.

title

Citation title

originator

Creator of object. By default, user id.

uuid

Unique identifier