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
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, t_side, nj, ...])

Initialises a TriMesh object from xml, or 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.
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__(parent_model[, uuid, t_side, nj, ...])	Initialises a TriMesh object from xml, or from arguments.
try_reuse()	Look for an equivalent existing RESQML object and modify the uuid of this object if found.
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.
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.

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