<h1>triangular grids<aclass="headerlink" href="#triangular-grids" title="Permalink to this headline">¶</a></h1>
<divclass="section" id="module-matplotlib.tri">
<spanid="matplotlib-tri"></span><h2><aclass="reference internal" href="#module-matplotlib.tri" title="matplotlib.tri"><ttclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib.tri</span></tt></a><aclass="headerlink" href="#module-matplotlib.tri" title="Permalink to this headline">¶</a></h2>
<p>Unstructured triangular grid functions.</p>
<dlclass="class">
<dtid="matplotlib.tri.Triangulation">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">Triangulation</tt><spanclass="sig-paren">(</span><em>x</em>, <em>y</em>, <em>triangles=None</em>, <em>mask=None</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.Triangulation" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<ttclass="descname">calculate_plane_coefficients</tt><spanclass="sig-paren">(</span><em>z</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.Triangulation.calculate_plane_coefficients" title="Permalink to this definition">¶</a></dt>
<dd><p>Calculate plane equation coefficients for all unmasked triangles from
the point (x,y) coordinates and specified z-array of shape (npoints).
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].</p>
</dd></dl>
<dlclass="attribute">
<dtid="matplotlib.tri.Triangulation.edges">
<ttclass="descname">edges</tt><aclass="headerlink" href="#matplotlib.tri.Triangulation.edges" title="Permalink to this definition">¶</a></dt>
<dd><p>Return integer array of shape (nedges,2) containing all edges of
non-masked triangles.</p>
<p>Each edge is the start point index and end point index. Each
edge (start,end and end,start) appears only once.</p>
<emclass="property">static </em><ttclass="descname">get_from_args_and_kwargs</tt><spanclass="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.Triangulation.get_from_args_and_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Triangulation object from the args and kwargs, and
the remaining args and kwargs with the consumed values removed.</p>
<p>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
<ttclass="descname">get_masked_triangles</tt><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.Triangulation.get_masked_triangles" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an array of triangles that are not masked.</p>
<ttclass="descname">get_trifinder</tt><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.Triangulation.get_trifinder" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the default <aclass="reference internal" href="#matplotlib.tri.TriFinder" title="matplotlib.tri.TriFinder"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.tri.TriFinder</span></tt></a> of this
triangulation, creating it if necessary. This allows the same
TriFinder object to be easily shared.</p>
</dd></dl>
<dlclass="attribute">
<dtid="matplotlib.tri.Triangulation.neighbors">
<ttclass="descname">neighbors</tt><aclass="headerlink" href="#matplotlib.tri.Triangulation.neighbors" title="Permalink to this definition">¶</a></dt>
<dd><p>Return integer array of shape (ntri,3) containing neighbor
triangles.</p>
<p>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].</p>
</dd></dl>
<dlclass="method">
<dtid="matplotlib.tri.Triangulation.set_mask">
<ttclass="descname">set_mask</tt><spanclass="sig-paren">(</span><em>mask</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.Triangulation.set_mask" title="Permalink to this definition">¶</a></dt>
<dd><p>Set or clear the mask array. This is either None, or a boolean
array of shape (ntri).</p>
</dd></dl>
</dd></dl>
<dlclass="class">
<dtid="matplotlib.tri.TriFinder">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">TriFinder</tt><spanclass="sig-paren">(</span><em>triangulation</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TriFinder" title="Permalink to this definition">¶</a></dt>
<dd><p>Abstract base class for classes used to find the triangles of a
Triangulation in which (x,y) points lie.</p>
<p>Rather than instantiate an object of a class derived from TriFinder, it is
<p>Derived classes implement __call__(x,y) where x,y are array_like point
coordinates of the same shape.</p>
</dd></dl>
<dlclass="class">
<dtid="matplotlib.tri.TrapezoidMapTriFinder">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">TrapezoidMapTriFinder</tt><spanclass="sig-paren">(</span><em>triangulation</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TrapezoidMapTriFinder" title="Permalink to this definition">¶</a></dt>
<p><aclass="reference internal" href="#matplotlib.tri.TriFinder" title="matplotlib.tri.TriFinder"><ttclass="xref py py-class docutils literal"><spanclass="pre">TriFinder</span></tt></a> 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.</p>
<p>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
<ttclass="descname">__call__</tt><spanclass="sig-paren">(</span><em>x</em>, <em>y</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TrapezoidMapTriFinder.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an array containing the indices of the triangles in which the
specified x,y points lie, or -1 for points that do not lie within a
triangle.</p>
<p><em>x</em>, <em>y</em> are array_like x and y coordinates of the same shape and any
number of dimensions.</p>
<p>Returns integer array with the same shape and <em>x</em> and <em>y</em>.</p>
</dd></dl>
</dd></dl>
<dlclass="class">
<dtid="matplotlib.tri.TriInterpolator">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">TriInterpolator</tt><spanclass="sig-paren">(</span><em>triangulation</em>, <em>z</em>, <em>trifinder=None</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TriInterpolator" title="Permalink to this definition">¶</a></dt>
<dd><p>Abstract base class for classes used to perform interpolation on
triangular grids.</p>
<p>Derived classes implement the following methods:</p>
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).</li>
</ul>
</div></blockquote>
</dd></dl>
<dlclass="class">
<dtid="matplotlib.tri.LinearTriInterpolator">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">LinearTriInterpolator</tt><spanclass="sig-paren">(</span><em>triangulation</em>, <em>z</em>, <em>trifinder=None</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.LinearTriInterpolator" title="Permalink to this definition">¶</a></dt>
<ttclass="descname">__call__</tt><spanclass="sig-paren">(</span><em>x</em>, <em>y</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.LinearTriInterpolator.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a masked array containing interpolated values at the specified
<ttclass="descname">gradient</tt><spanclass="sig-paren">(</span><em>x</em>, <em>y</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.LinearTriInterpolator.gradient" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a list of 2 masked arrays containing interpolated derivatives
<tr><tdclass="label">[R1]</td><td><em>(<aclass="fn-backref" href="#id1">1</a>, <aclass="fn-backref" href="#id3">2</a>)</em> Michel Bernadou, Kamal Hassan, “Basis functions for general
Hsieh-Clough-Tocher triangles, complete or reduced.”,
International Journal for Numerical Methods in Engineering,
<ttclass="descname">__call__</tt><spanclass="sig-paren">(</span><em>x</em>, <em>y</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.CubicTriInterpolator.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a masked array containing interpolated values at the specified
<ttclass="descname">gradient</tt><spanclass="sig-paren">(</span><em>x</em>, <em>y</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.CubicTriInterpolator.gradient" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a list of 2 masked arrays containing interpolated derivatives
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">TriRefiner</tt><spanclass="sig-paren">(</span><em>triangulation</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TriRefiner" title="Permalink to this definition">¶</a></dt>
<dd><p>Abstract base class for classes implementing mesh refinement.</p>
<p>A TriRefiner encapsulates a Triangulation object and provides tools for
mesh refinement and interpolation.</p>
<p>Derived classes must implements:</p>
<blockquote>
<div><ul>
<li><pclass="first"><ttclass="docutils literal"><spanclass="pre">refine_triangulation(return_tri_index=False,</span><spanclass="pre">**kwargs)</span></tt> , where
the optional keyword arguments <em>kwargs</em> are defined in each
TriRefiner concrete implementation, and which returns :</p>
<blockquote>
<div><ulclass="simple">
<li>a refined triangulation</li>
<li>optionally (depending on <em>return_tri_index</em>), for each
point of the refined triangulation: the index of
the initial triangulation triangle to which it belongs.</li>
<li>the other optional keyword arguments <em>kwargs</em> are defined in
each TriRefiner concrete implementation</li>
</ul>
</div></blockquote>
<p>and which returns (as a tuple) a refined triangular mesh and the
interpolated values of the field at the refined triangulation nodes.</p>
</li>
</ul>
</div></blockquote>
</dd></dl>
<dlclass="class">
<dtid="matplotlib.tri.UniformTriRefiner">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">UniformTriRefiner</tt><spanclass="sig-paren">(</span><em>triangulation</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.UniformTriRefiner" title="Permalink to this definition">¶</a></dt>
<ttclass="descname">refine_field</tt><spanclass="sig-paren">(</span><em>z</em>, <em>triinterpolator=None</em>, <em>subdiv=3</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.UniformTriRefiner.refine_field" title="Permalink to this definition">¶</a></dt>
<dd><p>Refines a field defined on the encapsulated triangulation.</p>
<div><p>Interpolator used for field interpolation. If not specified,
a <aclass="reference internal" href="#matplotlib.tri.CubicTriInterpolator" title="matplotlib.tri.CubicTriInterpolator"><ttclass="xref py py-class docutils literal"><spanclass="pre">CubicTriInterpolator</span></tt></a> will
<ttclass="descname">refine_triangulation</tt><spanclass="sig-paren">(</span><em>return_tri_index=False</em>, <em>subdiv=3</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.UniformTriRefiner.refine_triangulation" title="Permalink to this definition">¶</a></dt>
<dd><p>Computes an uniformly refined triangulation <em>refi_triangulation</em> of
the encapsulated <ttclass="xref py py-attr docutils literal"><spanclass="pre">triangulation</span></tt>.</p>
<p>This function refines the encapsulated triangulation by splitting each
father triangle into 4 child sub-triangles built on the edges midside
nodes, recursively (level of recursion <em>subdiv</em>).
In the end, each triangle is hence divided into <ttclass="docutils literal"><spanclass="pre">4**subdiv</span></tt>
child triangles.
The default value for <em>subdiv</em> is 3 resulting in 64 refined
subtriangles for each triangle of the initial triangulation.</p>
<p><strong>found_index</strong> : array-like of integers</p>
<blockquoteclass="last">
<div><p>Index of the initial triangulation containing triangle, for each
point of <em>refi_triangulation</em>.
Returned only if <em>return_tri_index</em> is set to True.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<dlclass="class">
<dtid="matplotlib.tri.TriAnalyzer">
<emclass="property">class </em><ttclass="descclassname">matplotlib.tri.</tt><ttclass="descname">TriAnalyzer</tt><spanclass="sig-paren">(</span><em>triangulation</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TriAnalyzer" title="Permalink to this definition">¶</a></dt>
<dd><p>Define basic tools for triangular mesh analysis and improvement.</p>
<td>Factors to rescale the triangulation into a unit square.</td>
</tr>
</tbody>
</table>
<dlclass="method">
<dtid="matplotlib.tri.TriAnalyzer.circle_ratios">
<ttclass="descname">circle_ratios</tt><spanclass="sig-paren">(</span><em>rescale=True</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TriAnalyzer.circle_ratios" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a measure of the triangulation triangles flatness.</p>
<p>The ratio of the incircle radius over the circumcircle radius is a
widely used indicator of a triangle flatness.
It is always <ttclass="docutils literal"><spanclass="pre"><=</span><spanclass="pre">0.5</span></tt> and <ttclass="docutils literal"><spanclass="pre">==</span><spanclass="pre">0.5</span></tt> only for equilateral
triangles. Circle ratios below 0.01 denote very flat triangles.</p>
<p>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 <aclass="reference internal" href="#matplotlib.tri.TriAnalyzer.scale_factors" title="matplotlib.tri.TriAnalyzer.scale_factors"><ttclass="xref py py-attr docutils literal"><spanclass="pre">scale_factors</span></tt></a> (Only if <em>rescale</em> is True, which is
<div><p>If True, a rescaling will be internally performed (based on
<aclass="reference internal" href="#matplotlib.tri.TriAnalyzer.scale_factors" title="matplotlib.tri.TriAnalyzer.scale_factors"><ttclass="xref py py-attr docutils literal"><spanclass="pre">scale_factors</span></tt></a>, so that the (unmasked) triangles fit
exactly inside a unit square mesh. Default is True.</p>
<ttclass="descname">get_flat_tri_mask</tt><spanclass="sig-paren">(</span><em>min_circle_ratio=0.01</em>, <em>rescale=True</em><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.tri.TriAnalyzer.get_flat_tri_mask" title="Permalink to this definition">¶</a></dt>
<dd><p>Eliminates excessively flat border triangles from the triangulation.</p>
<p>Returns a mask <em>new_mask</em> which allows to clean the encapsulated
triangulation from its border-located flat triangles
(according to their <aclass="reference internal" href="#matplotlib.tri.TriAnalyzer.circle_ratios" title="matplotlib.tri.TriAnalyzer.circle_ratios"><ttclass="xref py py-meth docutils literal"><spanclass="pre">circle_ratios()</span></tt></a>).
This mask is meant to be subsequently applied to the triangulation
using <aclass="reference internal" href="#matplotlib.tri.Triangulation.set_mask" title="matplotlib.tri.Triangulation.set_mask"><ttclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.tri.Triangulation.set_mask()</span></tt></a> .
<em>new_mask</em> is an extension of the initial triangulation mask
in the sense that an initially masked triangle will remain masked.</p>
<p>The <em>new_mask</em> 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
<div><p>If True, a rescaling will first be internally performed (based on
<aclass="reference internal" href="#matplotlib.tri.TriAnalyzer.scale_factors" title="matplotlib.tri.TriAnalyzer.scale_factors"><ttclass="xref py py-attr docutils literal"><spanclass="pre">scale_factors</span></tt></a> ), 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. Default
(and recommended) value is True.</p>
</div></blockquote>
</td>
</tr>
<trclass="field-even field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first"><strong>new_mask</strong> : array-like of booleans</p>
<blockquoteclass="last">
<div><p>Mask to apply to encapsulated triangulation.
All the initially masked triangles remain masked in the
<em>new_mask</em>.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>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 <em>new_mask</em>, the encapsulated
triangulation would contain no more unmasked border triangles
with a circle ratio below <em>min_circle_ratio</em>, thus improving the
mesh quality for subsequent plots or interpolation.</p>
<pclass="rubric">Examples</p>
<p>Please refer to the following illustrating example:</p>
<ttclass="descname">scale_factors</tt><aclass="headerlink" href="#matplotlib.tri.TriAnalyzer.scale_factors" title="Permalink to this definition">¶</a></dt>
<dd><p>Factors to rescale the triangulation into a unit square.</p>
<p>Returns <em>k</em>, tuple of 2 scale factors.</p>