pyvista.cell_quality_info

cell_quality_info(

cell_type: Literal[CellType.TRIANGLE, CellType.QUAD, CellType.TETRA, CellType.HEXAHEDRON, CellType.PYRAMID, CellType.WEDGE, 'TRIANGLE', 'triangle', 'QUAD', 'quad', 'TETRA', 'tetra', 'HEXAHEDRON', 'hexahedron', 'PYRAMID', 'pyramid', 'WEDGE', 'wedge'],

quality_measure: Literal['area', 'aspect_frobenius', 'aspect_gamma', 'aspect_ratio', 'collapse_ratio', 'condition', 'diagonal', 'dimension', 'distortion', 'jacobian', 'max_angle', 'max_aspect_frobenius', 'max_edge_ratio', 'med_aspect_frobenius', 'min_angle', 'oddy', 'radius_ratio', 'relative_size_squared', 'scaled_jacobian', 'shape', 'shape_and_size', 'shear', 'shear_and_size', 'skew', 'stretch', 'taper', 'volume', 'warpage'],

) → CellQualityInfo

Return information about a cell’s quality measure.

This function returns information about a quality measure computed by cell_quality() for a specified CellType. The following is provided for each measure:

• acceptable_range: Well-behaved cells have values in this range.

• normal_range: All cells except those with degeneracies have values in this range.

• full_range: All cells including degenerate ones have values in this range.

• unit_cell_value: The quality measure value for a reference unit cell (e.g. equilateral triangle with edge length of one for triangles).

This information can help inform if a particular cell is of high or low quality.

See the tables below for a summary of all cell quality info available from this function.

Triangle Cell Info

Info about TRIANGLE cell quality measures. See Triangle() for an example unit cell.

Measure	Acceptable Range	Normal Range	Full Range	Unit Cell Value
area	[0.0, inf]	[0.0, inf]	[0.0, inf]	0.433
aspect_ratio	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
aspect_frobenius	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
condition	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
distortion	[0.5, 1.0]	[0.0, 1.0]	[-inf, inf]	1.0
max_angle	[60.0, 90.0]	[60.0, 180.0]	[0.0, 180.0]	60.0
min_angle	[30.0, 60.0]	[0.0, 60.0]	[0.0, 360.0]	60.0
scaled_jacobian	[0.5, 1.15]	[-1.15, 1.15]	[-inf, inf]	1.0
radius_ratio	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
shape	[0.25, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shape_and_size	[0.25, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0

Quad Cell Info

Info about QUAD cell quality measures. See Quadrilateral() for an example unit cell.

Measure	Acceptable Range	Normal Range	Full Range	Unit Cell Value
area	[0.0, inf]	[0.0, inf]	[-inf, inf]	1.0
aspect_ratio	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
condition	[1.0, 4.0]	[1.0, inf]	[1.0, inf]	1.0
distortion	[0.5, 1.0]	[0.0, 1.0]	[-inf, inf]	1.0
jacobian	[0.0, inf]	[0.0, inf]	[-inf, inf]	1.0
max_aspect_frobenius	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
max_angle	[90.0, 135.0]	[90.0, 360.0]	[0.0, 360.0]	90.0
max_edge_ratio	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
med_aspect_frobenius	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
min_angle	[45.0, 90.0]	[0.0, 90.0]	[0.0, 360.0]	90.0
oddy	[0.0, 0.5]	[0.0, inf]	[0.0, inf]	0.0
radius_ratio	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
relative_size_squared	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
scaled_jacobian	[0.3, 1.0]	[-1.0, 1.0]	[-1.0, 1.0]	1.0
shape	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shape_and_size	[0.2, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shear	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shear_and_size	[0.2, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
skew	[0.0, 0.5]	[0.0, 1.0]	[0.0, 1.0]	0.0
stretch	[0.25, 1.0]	[0.0, 1.0]	[0.0, inf]	1.0
taper	[0.0, 0.7]	[0.0, inf]	[0.0, inf]	0.0
warpage	[0.3, 1.0]	[-1.0, 1.0]	[-inf, inf]	1.0

Hexahedron Cell Info

Info about HEXAHEDRON cell quality measures. See Hexahedron() for an example unit cell.

Measure	Acceptable Range	Normal Range	Full Range	Unit Cell Value
diagonal	[0.65, 1.0]	[0.0, 1.0]	[0.0, inf]	1.0
dimension	[0.0, inf]	[0.0, inf]	[0.0, inf]	0.577
distortion	[0.5, 1.0]	[0.0, 1.0]	[-inf, inf]	1.0
jacobian	[0.0, inf]	[0.0, inf]	[-inf, inf]	1.0
max_edge_ratio	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
max_aspect_frobenius	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
med_aspect_frobenius	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
oddy	[0.0, 0.5]	[0.0, inf]	[0.0, inf]	0.0
relative_size_squared	[0.5, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
scaled_jacobian	[0.5, 1.0]	[-1.0, 1.0]	[-1.0, inf]	1.0
shape	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shape_and_size	[0.2, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shear	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shear_and_size	[0.2, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
skew	[0.0, 0.5]	[0.0, 1.0]	[0.0, inf]	0.0
stretch	[0.25, 1.0]	[0.0, 1.0]	[0.0, inf]	1.0
taper	[0.0, 0.5]	[0.0, inf]	[0.0, inf]	0.0
volume	[0.0, inf]	[0.0, inf]	[-inf, inf]	1.0

Tetra Cell Info

Info about TETRA cell quality measures. See Tetrahedron() for an example unit cell.

Measure	Acceptable Range	Normal Range	Full Range	Unit Cell Value
aspect_frobenius	[1.0, 1.3]	[1.0, inf]	[1.0, inf]	1.0
aspect_gamma	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
aspect_ratio	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
collapse_ratio	[0.1, inf]	[0.0, inf]	[0.0, inf]	0.816
condition	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
distortion	[0.5, 1.0]	[0.0, 1.0]	[-inf, inf]	1.0
jacobian	[0.0, inf]	[0.0, inf]	[-inf, inf]	0.707
min_angle	[40.0, 70.5]	[0.0, 70.5]	[0.0, 360.0]	70.5
radius_ratio	[1.0, 3.0]	[1.0, inf]	[1.0, inf]	1.0
relative_size_squared	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
scaled_jacobian	[0.5, 1.0]	[-1.0, 1.0]	[-inf, inf]	1.0
shape	[0.3, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
shape_and_size	[0.2, 1.0]	[0.0, 1.0]	[0.0, 1.0]	1.0
volume	[0.0, inf]	[-inf, inf]	[-inf, inf]	0.118

Wedge Cell Info

Info about WEDGE cell quality measures. See Wedge() for an example unit cell.

Measure	Acceptable Range	Normal Range	Full Range	Unit Cell Value
volume	[0.0, inf]	[-inf, inf]	[-inf, inf]	0.433

Pyramid Cell Info

Info about PYRAMID cell quality measures. See Pyramid() for an example unit cell.

Measure	Acceptable Range	Normal Range	Full Range	Unit Cell Value
volume	[0.0, inf]	[-inf, inf]	[-inf, inf]	0.236

Note

The information returned by this function is based on the Verdict Library Reference Manual.

Note

Information is not available for all valid quality measures computed by cell_quality(). Only a subset is provided here. If information about a measure is missing and you have knowledge about its acceptable range, normal range, etc., please consider submitting a pull request on GitHub at pyvista/pyvista.

Parameters:

cell_typeCellType | str

Cell type to get information about. May be a CellType or the name of a cell type as a string.

quality_measurestr

Quality measure to get information about. May be any quality measure from Cell Quality Measures.

Returns:

CellQualityInfo

Dataclass with information about the quality measure for a specific cell type.

Raises:

ValueError

If info is not available for the specified cell type or measure.

See also

cell_quality()

Examples

Get cell quality info for TRIANGLE cells and the 'scaled_jacobian' quality measure.

>>> import pyvista as pv
>>> info_tri = pv.cell_quality_info(pv.CellType.TRIANGLE, 'scaled_jacobian')
>>> info_tri
CellQualityInfo(cell_type=<CellType.TRIANGLE: 5>,
                quality_measure='scaled_jacobian',
                acceptable_range=(0.5, 1.1547005383792515),
                normal_range=(-1.1547005383792515, 1.1547005383792515),
                full_range=(-inf, inf),
                unit_cell_value=1.0)

Show the acceptable range for this measure.

>>> info_tri.acceptable_range
(0.5, 1.1547005383792515)

Show the value of this measure for equilateral triangles with edge length of one.

>>> info_tri.unit_cell_value
1.0

Get info for the same measure but for QUAD cells.

>>> info_quad = pv.cell_quality_info(pv.CellType.QUAD, 'scaled_jacobian')
>>> info_quad
CellQualityInfo(cell_type=<CellType.QUAD: 9>,
                quality_measure='scaled_jacobian',
                acceptable_range=(0.3, 1.0),
                normal_range=(-1.0, 1.0),
                full_range=(-1.0, 1.0),
                unit_cell_value=1.0)

Show the acceptable range. Note that it differs for quads compared to triangles.

>>> info_quad.acceptable_range
(0.3, 1.0)

Show the value of this measure for a square cell with edge length of one.

>>> info_quad.unit_cell_value
1.0

See Computing Mesh Quality for more examples using this function.