matplotlib.tri

Unstructured triangular grid functions.

Submodules

Functions

  • tricontourf(): Draw contour regions on an unstructured triangular grid.

matplotlib.tri.tricontourf(ax, *args, **kwargs)

Draw contour regions on an unstructured triangular grid.

Call signatures:

tricontourf(triangulation, z, [levels], ...)
tricontourf(x, y, z, [levels], *, [triangles=triangles], [mask=mask], ...)

The triangular grid can be specified either by passing a .Triangulation object as the first parameter, or by passing the points x, y and optionally the triangles and a mask. See .Triangulation for an explanation of these parameters. If neither of triangulation or triangles are given, the triangulation is calculated on the fly.

It is possible to pass triangles positionally, i.e. tricontourf(x, y, triangles, z, ...). However, this is discouraged. For more clarity, pass triangles via keyword argument.

Parameters:

  • triangulation (.Triangulation, optional) – An already created triangular grid.

  • x – Parameters defining the triangular grid. See .Triangulation. This is mutually exclusive with specifying triangulation.

  • y – Parameters defining the triangular grid. See .Triangulation. This is mutually exclusive with specifying triangulation.

  • triangles – Parameters defining the triangular grid. See .Triangulation. This is mutually exclusive with specifying triangulation.

  • mask – Parameters defining the triangular grid. See .Triangulation. This is mutually exclusive with specifying triangulation.

  • z (array-like) –

    The height values over which the contour is drawn. Color-mapping is controlled by cmap, norm, vmin, and vmax.

    Note

    All values in z must be finite. Hence, nan and inf values must either be removed or ~.Triangulation.set_mask be used.

  • levels (int or array-like, optional) –

    Determines the number and positions of the contour lines / regions.

    If an int n, use ~matplotlib.ticker.MaxNLocator, which tries to automatically choose no more than n+1 “nice” contour levels between between minimum and maximum numeric values of Z.

    If array-like, draw contour lines at the specified levels. The values must be in increasing order.

  • colors (color string or sequence of colors, optional) –

    The colors of the levels, i.e., the contour regions.

    The sequence is cycled for the levels in ascending order. If the sequence is shorter than the number of levels, it is repeated.

    As a shortcut, single color strings may be used in place of one-element lists, i.e. 'red' instead of ['red'] to color all levels with the same color. This shortcut does only work for color strings, not for other ways of specifying colors.

    By default (value None), the colormap specified by cmap will be used.

  • alpha (float, default: 1) – The alpha blending value, between 0 (transparent) and 1 (opaque).

  • cmap (str or ~matplotlib.colors.Colormap, default: :rc:`image.cmap`) –

    The Colormap instance or registered colormap name used to map scalar data to colors.

    This parameter is ignored if colors is set.

  • norm (str or ~matplotlib.colors.Normalize, optional) –

    The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1.

    If given, this can be one of the following:

    • An instance of .Normalize or one of its subclasses (see /tutorials/colors/colormapnorms).

    • A scale name, i.e. one of “linear”, “log”, “symlog”, “logit”, etc. For a list of available scales, call matplotlib.scale.get_scale_names(). In that case, a suitable .Normalize subclass is dynamically generated and instantiated.

    This parameter is ignored if colors is set.

  • vmin (float, optional) –

    When using scalar data and no explicit norm, vmin and vmax define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data. It is an error to use vmin/vmax when a norm instance is given (but using a str norm name together with vmin/vmax is acceptable).

    If vmin or vmax are not given, the default color scaling is based on levels.

    This parameter is ignored if colors is set.

  • vmax (float, optional) –

    When using scalar data and no explicit norm, vmin and vmax define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data. It is an error to use vmin/vmax when a norm instance is given (but using a str norm name together with vmin/vmax is acceptable).

    If vmin or vmax are not given, the default color scaling is based on levels.

    This parameter is ignored if colors is set.

  • origin ({None, ‘upper’, ‘lower’, ‘image’}, default: None) –

    Determines the orientation and exact position of z by specifying the position of z[0, 0]. This is only relevant, if X, Y are not given.

    • None: z[0, 0] is at X=0, Y=0 in the lower left corner.

    • ’lower’: z[0, 0] is at X=0.5, Y=0.5 in the lower left corner.

    • ’upper’: z[0, 0] is at X=N+0.5, Y=0.5 in the upper left corner.

    • ’image’: Use the value from :rc:`image.origin`.

  • extent ((x0, x1, y0, y1), optional) –

    If origin is not None, then extent is interpreted as in .imshow: it gives the outer pixel boundaries. In this case, the position of z[0, 0] is the center of the pixel, not a corner. If origin is None, then (x0, y0) is the position of z[0, 0], and (x1, y1) is the position of z[-1, -1].

    This argument is ignored if X and Y are specified in the call to contour.

  • locator (ticker.Locator subclass, optional) – The locator is used to determine the contour levels if they are not given explicitly via levels. Defaults to ~.ticker.MaxNLocator.

  • extend ({'neither', 'both', 'min', 'max'}, default: 'neither') –

    Determines the tricontourf-coloring of values that are outside the levels range.

    If ‘neither’, values outside the levels range are not colored. If ‘min’, ‘max’ or ‘both’, color the values below, above or below and above the levels range.

    Values below min(levels) and above max(levels) are mapped to the under/over values of the .Colormap. Note that most colormaps do not have dedicated colors for these by default, so that the over and under values are the edge values of the colormap. You may want to set these values explicitly using .Colormap.set_under and .Colormap.set_over.

    Note

    An existing .TriContourSet does not get notified if properties of its colormap are changed. Therefore, an explicit call to .ContourSet.changed() is needed after modifying the colormap. The explicit call can be left out, if a colorbar is assigned to the .TriContourSet because it internally calls .ContourSet.changed().

  • xunits (registered units, optional) – Override axis units by specifying an instance of a matplotlib.units.ConversionInterface.

  • yunits (registered units, optional) – Override axis units by specifying an instance of a matplotlib.units.ConversionInterface.

  • antialiased (bool, optional) – Enable antialiasing, overriding the defaults. For filled contours, the default is True. For line contours, it is taken from :rc:`lines.antialiased`.

  • hatches (list[str], optional) – A list of crosshatch patterns to use on the filled areas. If None, no hatching will be added to the contour. Hatching is supported in the PostScript, PDF, SVG and Agg backends only.

Return type:

~matplotlib.tri.TriContourSet

Notes

.tricontourf fills intervals that are closed at the top; that is, for boundaries z1 and z2, the filled region is:

z1 < Z <= z2

except for the lowest interval, which is closed on both sides (i.e. it includes the lowest value).

Classes

  • Triangulation: An unstructured triangular grid consisting of npoints points and

  • TriContourSet: Create and store a set of contour lines or filled regions for

  • TriFinder: Abstract base class for classes used to find the triangles of a

  • TrapezoidMapTriFinder: ~matplotlib.tri.TriFinder class implemented using the trapezoid

  • TriInterpolator: Abstract base class for classes used to interpolate on a triangular grid.

  • LinearTriInterpolator: Linear interpolator on a triangular grid.

  • CubicTriInterpolator: Cubic interpolator on a triangular grid.

  • TriRefiner: Abstract base class for classes implementing mesh refinement.

  • UniformTriRefiner: Uniform mesh refinement by recursive subdivisions.

  • TriAnalyzer: Define basic tools for triangular mesh analysis and improvement.

class matplotlib.tri.Triangulation(x, y, triangles=None, mask=None)

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 ((npoints,) array-like) – Coordinates of grid points.

  • y ((npoints,) array-like) – Coordinates of grid points.

  • triangles ((ntri, 3) array-like of int, 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.

  • mask ((ntri,) array-like of bool, optional) – Which triangles are masked out.

triangles

For each triangle, the indices of the three points that make up the triangle, ordered in an anticlockwise manner. If you want to take the mask into account, use get_masked_triangles instead.

Type:

(ntri, 3) array of int

mask

Masked out triangles.

Type:

(ntri, 3) array of bool

is_delaunay

Whether the Triangulation is a calculated Delaunay triangulation (where triangles was not specified) or not.

Type:

bool

Notes

For a Triangulation to be valid it must not have duplicate points, triangles formed from colinear points, or overlapping triangles.

Inheritance

digraph inheritancea4e8d1d6ea { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Triangulation" [URL="#matplotlib.tri.Triangulation",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="An unstructured triangular grid consisting of npoints points and"]; }
calculate_plane_coefficients(z)

Calculate plane equation coefficients for all unmasked triangles from the point (x, y) coordinates and specified z-array of shape (npoints). The returned array has shape (npoints, 3) and allows z-value 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 non-masked triangles.

Each row defines an edge by its 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()

Return the underlying C++ Triangulation object, creating it if necessary.

static get_from_args_and_kwargs(*args, **kwargs)

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_masked_triangles()

Return an array of triangles taking the mask into account.

get_trifinder()

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 index triangles[i, j] to point index triangles[i, (j+1)%3].

set_mask(mask)

Set or clear the mask array.

Parameters:

mask (None or bool array of length ntri) –

class matplotlib.tri.TriContourSet(ax, *args, **kwargs)

Create and store a set of contour lines or filled regions for a triangular grid.

This class is typically not instantiated directly by the user but by ~.Axes.tricontour and ~.Axes.tricontourf.

ax

The Axes object in which the contours are drawn.

Type:

~matplotlib.axes.Axes

collections

The .Artists representing the contour. This is a list of .PathCollections for both line and filled contours.

Type:

.silent_list of .PathCollections

levels

The values of the contour levels.

Type:

array

layers

Same as levels for line contours; half-way between levels for filled contours. See ContourSet._process_colors.

Type:

array

Inheritance

digraph inheritance33c3773f78 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ContourLabeler" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Mixin to provide labelling capability to `.ContourSet`."]; "ContourSet" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Store a set of contour lines or filled regions."]; "ScalarMappable" -> "ContourSet" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ContourLabeler" -> "ContourSet" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ScalarMappable" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A mixin class to map scalar data to RGBA."]; "TriContourSet" [URL="#matplotlib.tri.TriContourSet",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Create and store a set of contour lines or filled regions for"]; "ContourSet" -> "TriContourSet" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
class matplotlib.tri.TriFinder(triangulation)

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 array-like point coordinates of the same shape.

Inheritance

digraph inheritancedc66af8344 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TriFinder" [URL="#matplotlib.tri.TriFinder",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes used to find the triangles of a"]; }
class matplotlib.tri.TrapezoidMapTriFinder(triangulation)

~matplotlib.tri.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.

Inheritance

digraph inheritance103b0a22d8 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TrapezoidMapTriFinder" [URL="#matplotlib.tri.TrapezoidMapTriFinder",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="`~matplotlib.tri.TriFinder` class implemented using the trapezoid"]; "TriFinder" -> "TrapezoidMapTriFinder" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TriFinder" [URL="#matplotlib.tri.TriFinder",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes used to find the triangles of a"]; }
class matplotlib.tri.TriInterpolator(triangulation, z, trifinder=None)

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 array-like point coordinates of the same shape, and that returns a masked array of the same shape containing the interpolated z-values.

  • gradient(x, y), where x, y are array-like 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).

Inheritance

digraph inheritanceb71282bcf6 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TriInterpolator" [URL="matplotlib.tri._triinterpolate.html#matplotlib.tri._triinterpolate.TriInterpolator",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes used to interpolate on a triangular grid."]; }
class matplotlib.tri.LinearTriInterpolator(triangulation, z, trifinder=None)

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 (~matplotlib.tri.Triangulation) – The triangulation to interpolate over.

  • z ((npoints,) array-like) – Array of values, defined at grid points, to interpolate between.

  • trifinder (~matplotlib.tri.TriFinder, optional) – If this is not specified, the Triangulation’s default TriFinder will be used by calling .Triangulation.get_trifinder.

`__call__` (x, y) : Returns interpolated values at (x, y) points.
`gradient` (x, y) : Returns interpolated derivatives at (x, y) points.

Inheritance

digraph inheritancead09dc6577 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "LinearTriInterpolator" [URL="matplotlib.tri._triinterpolate.html#matplotlib.tri._triinterpolate.LinearTriInterpolator",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Linear interpolator on a triangular grid."]; "TriInterpolator" -> "LinearTriInterpolator" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TriInterpolator" [URL="matplotlib.tri._triinterpolate.html#matplotlib.tri._triinterpolate.TriInterpolator",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes used to interpolate on a triangular grid."]; }
gradient(x, y)

Returns a list of 2 masked arrays containing interpolated derivatives at the specified (x, y) points.

Parameters:

  • x (array-like) – x and y coordinates of the same shape and any number of dimensions.

  • y (array-like) – x and y coordinates of the same shape and any number of dimensions.

Returns:

dzdx, dzdy – 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}\).

Return type:

np.ma.array

class matplotlib.tri.CubicTriInterpolator(triangulation, z, kind='min_E', trifinder=None, dz=None)

Cubic interpolator on a triangular grid.

In one-dimension - 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 (~matplotlib.tri.Triangulation) – The triangulation to interpolate over.

  • z ((npoints,) array-like) – 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 (~matplotlib.tri.TriFinder, optional) – If not specified, the Triangulation’s default TriFinder will be used by calling .Triangulation.get_trifinder.

  • dz (tuple of array-likes (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.

`__call__` (x, y) : Returns interpolated values at (x, y) points.
`gradient` (x, y) : Returns interpolated derivatives at (x, y) points.

Notes

This note is a bit technical and details how the cubic interpolation is computed.

The interpolation is based on a Clough-Tocher subdivision scheme of the triangulation mesh (to make it clearer, each triangle of the grid will be divided in 3 child-triangles, 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 Hsieh-Clough-Tocher (HCT) element. Its shape functions are described in [1]. The assembled function is guaranteed to be C1-smooth, 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 so-called total curvature (implementation based on an algorithm from [2] - 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

Inheritance

digraph inheritance3f0b33ddc8 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "CubicTriInterpolator" [URL="matplotlib.tri._triinterpolate.html#matplotlib.tri._triinterpolate.CubicTriInterpolator",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Cubic interpolator on a triangular grid."]; "TriInterpolator" -> "CubicTriInterpolator" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TriInterpolator" [URL="matplotlib.tri._triinterpolate.html#matplotlib.tri._triinterpolate.TriInterpolator",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes used to interpolate on a triangular grid."]; }
gradient(x, y)

Returns a list of 2 masked arrays containing interpolated derivatives at the specified (x, y) points.

Parameters:

  • x (array-like) – x and y coordinates of the same shape and any number of dimensions.

  • y (array-like) – x and y coordinates of the same shape and any number of dimensions.

Returns:

dzdx, dzdy – 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}\).

Return type:

np.ma.array

class matplotlib.tri.TriRefiner(triangulation)

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 ~matplotlib.tri.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.

Inheritance

digraph inheritance235a6fbc25 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TriRefiner" [URL="#matplotlib.tri.TriRefiner",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes implementing mesh refinement."]; }
class matplotlib.tri.UniformTriRefiner(triangulation)

Uniform mesh refinement by recursive subdivisions.

Parameters:

triangulation (~matplotlib.tri.Triangulation) – The encapsulated triangulation (to be refined)

Inheritance

digraph inheritance1c877898d5 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TriRefiner" [URL="#matplotlib.tri.TriRefiner",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Abstract base class for classes implementing mesh refinement."]; "UniformTriRefiner" [URL="#matplotlib.tri.UniformTriRefiner",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Uniform mesh refinement by recursive subdivisions."]; "TriRefiner" -> "UniformTriRefiner" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
refine_field(z, triinterpolator=None, subdiv=3)

Refine a field defined on the encapsulated triangulation.

Parameters:

  • z ((npoints,) array-like) – 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 (~matplotlib.tri.TriInterpolator, optional) – Interpolator used for field interpolation. If not specified, a ~matplotlib.tri.CubicTriInterpolator will be used.

  • subdiv (int, default: 3) – Recursion level for the subdivision. Each triangle is divided into 4**subdiv child triangles.

Returns:

  • refi_tri (~matplotlib.tri.Triangulation) – The returned refined triangulation.

  • refi_z (1D array of length: *refi_tri node count.*) – The returned interpolated field (at refi_tri nodes).

refine_triangulation(return_tri_index=False, subdiv=3)

Compute a uniformly refined triangulation refi_triangulation of the encapsulated triangulation.

This function refines the encapsulated triangulation by splitting each father triangle into 4 child sub-triangles 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_index (bool, default: False) – Whether an index table indicating the father triangle index of each point is returned.

  • subdiv (int, 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 (~matplotlib.tri.Triangulation) – The refined triangulation.

  • found_index (int array) – Index of the initial triangulation containing triangle, for each point of refi_triangulation. Returned only if return_tri_index is set to True.

class matplotlib.tri.TriAnalyzer(triangulation)

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.

scale_factors
Parameters:

triangulation (~matplotlib.tri.Triangulation) – The encapsulated triangulation to analyze.

Inheritance

digraph inheritance68baa16c35 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TriAnalyzer" [URL="#matplotlib.tri.TriAnalyzer",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Define basic tools for triangular mesh analysis and improvement."]; }
circle_ratios(rescale=True)

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:

rescale (bool, default: True) – If True, internally rescale (based on scale_factors), so that the (unmasked) triangles fit exactly inside a unit square mesh.

Returns:

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.

Return type:

masked array

get_flat_tri_mask(min_circle_ratio=0.01, rescale=True)

Eliminate excessively flat border triangles from the triangulation.

Returns a mask new_mask which allows to clean the encapsulated triangulation from its border-located flat triangles (according to their circle_ratios()). This mask is meant to be subsequently applied to the triangulation using .Triangulation.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_ratio (float, default: 0.01) – Border triangles with incircle/circumcircle radii ratio r/R will be removed if r/R < min_circle_ratio.

  • rescale (bool, 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:

Mask to apply to encapsulated triangulation. All the initially masked triangles remain masked in the new_mask.

Return type:

array of bool

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 high-resolution 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:

Scaling factors (kx, ky) so that the triangulation [triangulation.x * kx, triangulation.y * ky] fits exactly inside a unit square.

Return type:

(float, float)

Variables

matplotlib.tri.tricontour
<module 'matplotlib.tri.tricontour' from '/home/docs/checkouts/readthedocs.org/user_builds/mtdoc/envs/latest/lib/python3.8/site-packages/matplotlib/tri/tricontour.py'>
matplotlib.tri.tripcolor
<module 'matplotlib.tri.tripcolor' from '/home/docs/checkouts/readthedocs.org/user_builds/mtdoc/envs/latest/lib/python3.8/site-packages/matplotlib/tri/tripcolor.py'>
matplotlib.tri.triplot
<module 'matplotlib.tri.triplot' from '/home/docs/checkouts/readthedocs.org/user_builds/mtdoc/envs/latest/lib/python3.8/site-packages/matplotlib/tri/triplot.py'>