matplotlib.tri
¶
Unstructured triangular grid functions.

class
matplotlib.tri.
Triangulation
(x, y, triangles=None, mask=None)[source]¶ An unstructured triangular grid consisting of npoints points and ntri triangles. The triangles can either be specified by the user or automatically generated using a Delaunay triangulation.
Parameters:  x, yarraylike of shape (npoints)
Coordinates of grid points.
 trianglesint arraylike of shape (ntri, 3), optional
For each triangle, the indices of the three points that make up the triangle, ordered in an anticlockwise manner. If not specified, the Delaunay triangulation is calculated.
 maskbool arraylike of shape (ntri), optional
Which triangles are masked out.
Notes
For a Triangulation to be valid it must not have duplicate points, triangles formed from colinear points, or overlapping triangles.
Attributes: edges
int array of shape (nedges, 2)Return integer array of shape (nedges, 2) containing all edges of nonmasked triangles.
neighbors
int array of shape (ntri, 3)Return integer array of shape (ntri, 3) containing neighbor triangles.
 maskbool array of shape (ntri, 3)
Masked out triangles.
 is_delaunaybool
Whether the Triangulation is a calculated Delaunay triangulation (where triangles was not specified) or not.

calculate_plane_coefficients
(self, z)[source]¶ Calculate plane equation coefficients for all unmasked triangles from the point (x, y) coordinates and specified zarray of shape (npoints). The returned array has shape (npoints, 3) and allows zvalue at (x, y) position in triangle tri to be calculated using
z = array[tri, 0] * x + array[tri, 1] * y + array[tri, 2]
.

property
edges
¶ Return integer array of shape (nedges, 2) containing all edges of nonmasked triangles.
Each row defines an edge by it's start point index and end point index. Each edge appears only once, i.e. for an edge between points i and j, there will only be either (i, j) or (j, i).

get_cpp_triangulation
(self)[source]¶ Return the underlying C++ Triangulation object, creating it if necessary.

static
get_from_args_and_kwargs
(*args, **kwargs)[source]¶ Return a Triangulation object from the args and kwargs, and the remaining args and kwargs with the consumed values removed.
There are two alternatives: either the first argument is a Triangulation object, in which case it is returned, or the args and kwargs are sufficient to create a new Triangulation to return. In the latter case, see Triangulation.__init__ for the possible args and kwargs.

get_trifinder
(self)[source]¶ Return the default
matplotlib.tri.TriFinder
of this triangulation, creating it if necessary. This allows the same TriFinder object to be easily shared.

property
neighbors
¶ Return integer array of shape (ntri, 3) containing neighbor triangles.
For each triangle, the indices of the three triangles that share the same edges, or 1 if there is no such neighboring triangle.
neighbors[i, j]
is the triangle that is the neighbor to the edge from point indextriangles[i, j]
to point indextriangles[i, (j+1)%3]
.

class
matplotlib.tri.
TriContourSet
(ax, *args, **kwargs)[source]¶ Bases:
matplotlib.contour.ContourSet
Create and store a set of contour lines or filled regions for a triangular grid.
Usercallable method: clabel
Attributes:  ax
The axes object in which the contours are drawn.
 collections
A silent_list of LineCollections or PolyCollections.
 levels
Contour levels.
 layers
Same as levels for line contours; halfway between levels for filled contours. See
_process_colors()
.
Draw triangular grid contour lines or filled regions, depending on whether keyword arg 'filled' is False (default) or True.
The first argument of the initializer must be an axes object. The remaining arguments and keyword arguments are described in the docstring of
tricontour
.

class
matplotlib.tri.
TriFinder
(triangulation)[source]¶ Abstract base class for classes used to find the triangles of a Triangulation in which (x, y) points lie.
Rather than instantiate an object of a class derived from TriFinder, it is usually better to use the function
Triangulation.get_trifinder
.Derived classes implement __call__(x, y) where x and y are arraylike point coordinates of the same shape.

class
matplotlib.tri.
TrapezoidMapTriFinder
(triangulation)[source]¶ Bases:
matplotlib.tri.trifinder.TriFinder
TriFinder
class implemented using the trapezoid map algorithm from the book "Computational Geometry, Algorithms and Applications", second edition, by M. de Berg, M. van Kreveld, M. Overmars and O. Schwarzkopf.The triangulation must be valid, i.e. it must not have duplicate points, triangles formed from colinear points, or overlapping triangles. The algorithm has some tolerance to triangles formed from colinear points, but this should not be relied upon.

class
matplotlib.tri.
TriInterpolator
(triangulation, z, trifinder=None)[source]¶ Abstract base class for classes used to interpolate on a triangular grid.
Derived classes implement the following methods:
__call__(x, y)
, where x, y are arraylike point coordinates of the same shape, and that returns a masked array of the same shape containing the interpolated zvalues.gradient(x, y)
, where x, y are arraylike point coordinates of the same shape, and that returns a list of 2 masked arrays of the same shape containing the 2 derivatives of the interpolator (derivatives of interpolated z values with respect to x and y).

class
matplotlib.tri.
LinearTriInterpolator
(triangulation, z, trifinder=None)[source]¶ Bases:
matplotlib.tri.triinterpolate.TriInterpolator
Linear interpolator on a triangular grid.
Each triangle is represented by a plane so that an interpolated value at point (x, y) lies on the plane of the triangle containing (x, y). Interpolated values are therefore continuous across the triangulation, but their first derivatives are discontinuous at edges between triangles.
Parameters:  triangulation
Triangulation
The triangulation to interpolate over.
 zarraylike of shape (npoints,)
Array of values, defined at grid points, to interpolate between.
 trifinder
TriFinder
, optional If this is not specified, the Triangulation's default TriFinder will be used by calling
Triangulation.get_trifinder
.
Methods
`__call__` (x, y) (Returns interpolated values at (x, y) points.) `gradient` (x, y) (Returns interpolated derivatives at (x, y) points.) 
gradient
(self, x, y)[source]¶ Returns a list of 2 masked arrays containing interpolated derivatives at the specified (x, y) points.
Parameters:  x, yarraylike
x and y coordinates of the same shape and any number of dimensions.
Returns:  dzdx, dzdynp.ma.array
2 masked arrays of the same shape as x and y; values corresponding to (x, y) points outside of the triangulation are masked out. The first returned array contains the values of \(\frac{\partial z}{\partial x}\) and the second those of \(\frac{\partial z}{\partial y}\).
 triangulation

class
matplotlib.tri.
CubicTriInterpolator
(triangulation, z, kind='min_E', trifinder=None, dz=None)[source]¶ Bases:
matplotlib.tri.triinterpolate.TriInterpolator
Cubic interpolator on a triangular grid.
In onedimension  on a segment  a cubic interpolating function is defined by the values of the function and its derivative at both ends. This is almost the same in 2d inside a triangle, except that the values of the function and its 2 derivatives have to be defined at each triangle node.
The CubicTriInterpolator takes the value of the function at each node  provided by the user  and internally computes the value of the derivatives, resulting in a smooth interpolation. (As a special feature, the user can also impose the value of the derivatives at each node, but this is not supposed to be the common usage.)
Parameters:  triangulation
Triangulation
The triangulation to interpolate over.
 zarraylike of shape (npoints,)
Array of values, defined at grid points, to interpolate between.
 kind{'min_E', 'geom', 'user'}, optional
Choice of the smoothing algorithm, in order to compute the interpolant derivatives (defaults to 'min_E'):
 if 'min_E': (default) The derivatives at each node is computed to minimize a bending energy.
 if 'geom': The derivatives at each node is computed as a weighted average of relevant triangle normals. To be used for speed optimization (large grids).
 if 'user': The user provides the argument dz, no computation is hence needed.
 trifinder
TriFinder
, optional If not specified, the Triangulation's default TriFinder will be used by calling
Triangulation.get_trifinder
. dztuple of arraylikes (dzdx, dzdy), optional
Used only if kind ='user'. In this case dz must be provided as (dzdx, dzdy) where dzdx, dzdy are arrays of the same shape as z and are the interpolant first derivatives at the triangulation points.
Notes
This note is a bit technical and details how the cubic interpolation is computed.
The interpolation is based on a CloughTocher subdivision scheme of the triangulation mesh (to make it clearer, each triangle of the grid will be divided in 3 childtriangles, and on each child triangle the interpolated function is a cubic polynomial of the 2 coordinates). This technique originates from FEM (Finite Element Method) analysis; the element used is a reduced HsiehCloughTocher (HCT) element. Its shape functions are described in [R0be0c58fd53f1]. The assembled function is guaranteed to be C1smooth, i.e. it is continuous and its first derivatives are also continuous (this is easy to show inside the triangles but is also true when crossing the edges).
In the default case (kind ='min_E'), the interpolant minimizes a curvature energy on the functional space generated by the HCT element shape functions  with imposed values but arbitrary derivatives at each node. The minimized functional is the integral of the socalled total curvature (implementation based on an algorithm from [R0be0c58fd53f2]  PCG sparse solver):
\[E(z) = \frac{1}{2} \int_{\Omega} \left( \left( \frac{\partial^2{z}}{\partial{x}^2} \right)^2 + \left( \frac{\partial^2{z}}{\partial{y}^2} \right)^2 + 2\left( \frac{\partial^2{z}}{\partial{y}\partial{x}} \right)^2 \right) dx\,dy\]If the case kind ='geom' is chosen by the user, a simple geometric approximation is used (weighted average of the triangle normal vectors), which could improve speed on very large grids.
References
[R0be0c58fd53f1] Michel Bernadou, Kamal Hassan, "Basis functions for general HsiehCloughTocher triangles, complete or reduced.", International Journal for Numerical Methods in Engineering, 17(5):784  789. 2.01. [R0be0c58fd53f2] C.T. Kelley, "Iterative Methods for Optimization". Methods
`__call__` (x, y) (Returns interpolated values at (x, y) points.) `gradient` (x, y) (Returns interpolated derivatives at (x, y) points.) 
gradient
(self, x, y)[source]¶ Returns a list of 2 masked arrays containing interpolated derivatives at the specified (x, y) points.
Parameters:  x, yarraylike
x and y coordinates of the same shape and any number of dimensions.
Returns:  dzdx, dzdynp.ma.array
2 masked arrays of the same shape as x and y; values corresponding to (x, y) points outside of the triangulation are masked out. The first returned array contains the values of \(\frac{\partial z}{\partial x}\) and the second those of \(\frac{\partial z}{\partial y}\).
 triangulation

class
matplotlib.tri.
TriRefiner
(triangulation)[source]¶ Abstract base class for classes implementing mesh refinement.
A TriRefiner encapsulates a Triangulation object and provides tools for mesh refinement and interpolation.
Derived classes must implement:
refine_triangulation(return_tri_index=False, **kwargs)
, where the optional keyword arguments kwargs are defined in each TriRefiner concrete implementation, and which returns: a refined triangulation,
 optionally (depending on return_tri_index), for each point of the refined triangulation: the index of the initial triangulation triangle to which it belongs.
refine_field(z, triinterpolator=None, **kwargs)
, where: z array of field values (to refine) defined at the base triangulation nodes,
 triinterpolator is an optional
TriInterpolator
,  the other optional keyword arguments kwargs are defined in each TriRefiner concrete implementation;
and which returns (as a tuple) a refined triangular mesh and the interpolated values of the field at the refined triangulation nodes.

class
matplotlib.tri.
UniformTriRefiner
(triangulation)[source]¶ Bases:
matplotlib.tri.trirefine.TriRefiner
Uniform mesh refinement by recursive subdivisions.
Parameters:  triangulation
Triangulation
The encapsulated triangulation (to be refined)

refine_field
(self, z, triinterpolator=None, subdiv=3)[source]¶ Refine a field defined on the encapsulated triangulation.
Parameters:  z1darraylike of length
n_points
Values of the field to refine, defined at the nodes of the encapsulated triangulation. (
n_points
is the number of points in the initial triangulation) triinterpolator
TriInterpolator
, optional Interpolator used for field interpolation. If not specified, a
CubicTriInterpolator
will be used. subdivint, default: 3
Recursion level for the subdivision. Each triangle is divided into
4**subdiv
child triangles.
Returns:  refi_tri
Triangulation
The returned refined triangulation.
 refi_z1d array of length: refi_tri node count.
The returned interpolated field (at refi_tri nodes).
 z1darraylike of length

refine_triangulation
(self, return_tri_index=False, subdiv=3)[source]¶ Compute an uniformly refined triangulation refi_triangulation of the encapsulated
triangulation
.This function refines the encapsulated triangulation by splitting each father triangle into 4 child subtriangles built on the edges midside nodes, recursing subdiv times. In the end, each triangle is hence divided into
4**subdiv
child triangles.Parameters:  return_tri_indexbool, default: False
Whether an index table indicating the father triangle index of each point is returned.
 subdivint, default: 3
Recursion level for the subdivision. Each triangle is divided into
4**subdiv
child triangles; hence, the default results in 64 refined subtriangles for each triangle of the initial triangulation.
Returns:  refi_triangulation
Triangulation
The refined triangulation.
 found_indexint array
Index of the initial triangulation containing triangle, for each point of refi_triangulation. Returned only if return_tri_index is set to True.
 triangulation

class
matplotlib.tri.
TriAnalyzer
(triangulation)[source]¶ Define basic tools for triangular mesh analysis and improvement.
A TriAnalyzer encapsulates a
Triangulation
object and provides basic tools for mesh analysis and mesh improvement.Parameters:  triangulation
Triangulation
The encapsulated triangulation to analyze.
Attributes: scale_factors
Factors to rescale the triangulation into a unit square.

circle_ratios
(self, rescale=True)[source]¶ Return a measure of the triangulation triangles flatness.
The ratio of the incircle radius over the circumcircle radius is a widely used indicator of a triangle flatness. It is always
<= 0.5
and== 0.5
only for equilateral triangles. Circle ratios below 0.01 denote very flat triangles.To avoid unduly low values due to a difference of scale between the 2 axis, the triangular mesh can first be rescaled to fit inside a unit square with
scale_factors
(Only if rescale is True, which is its default value).Parameters:  rescalebool, default: True
If True, internally rescale (based on
scale_factors
), so that the (unmasked) triangles fit exactly inside a unit square mesh.
Returns:  masked array
Ratio of the incircle radius over the circumcircle radius, for each 'rescaled' triangle of the encapsulated triangulation. Values corresponding to masked triangles are masked out.

get_flat_tri_mask
(self, min_circle_ratio=0.01, rescale=True)[source]¶ Eliminate excessively flat border triangles from the triangulation.
Returns a mask new_mask which allows to clean the encapsulated triangulation from its borderlocated flat triangles (according to their
circle_ratios()
). This mask is meant to be subsequently applied to the triangulation usingTriangulation.set_mask
. new_mask is an extension of the initial triangulation mask in the sense that an initially masked triangle will remain masked.The new_mask array is computed recursively; at each step flat triangles are removed only if they share a side with the current mesh border. Thus no new holes in the triangulated domain will be created.
Parameters:  min_circle_ratiofloat, default: 0.01
Border triangles with incircle/circumcircle radii ratio r/R will be removed if r/R < min_circle_ratio.
 rescalebool, default: True
If True, first, internally rescale (based on
scale_factors
) so that the (unmasked) triangles fit exactly inside a unit square mesh. This rescaling accounts for the difference of scale which might exist between the 2 axis.
Returns:  bool arraylike
Mask to apply to encapsulated triangulation. All the initially masked triangles remain masked in the new_mask.
Notes
The rationale behind this function is that a Delaunay triangulation  of an unstructured set of points  sometimes contains almost flat triangles at its border, leading to artifacts in plots (especially for highresolution contouring). Masked with computed new_mask, the encapsulated triangulation would contain no more unmasked border triangles with a circle ratio below min_circle_ratio, thus improving the mesh quality for subsequent plots or interpolation.

property
scale_factors
¶ Factors to rescale the triangulation into a unit square.
Returns:  (float, float)
Scaling factors (kx, ky) so that the triangulation
[triangulation.x * kx, triangulation.y * ky]
fits exactly inside a unit square.
 triangulation