DataObjectFilters.cell_validator

DataObjectFilters.cell_validator(

*,

tolerance: float | None = None,

planarity_tolerance: float | None = None,

size_tolerance: float | None = None,

)

Check the validity of each cell in this dataset.

The status of each cell is encoded as a bit field cell data array 'validity_state'. The possible cell status values are:

• VALID: Cell is valid and has no issues.

• COINCIDENT_POINTS: Cell has duplicate coordinates or repeated use of the same connectivity entry.

• DEGENERATE_FACES: Face(s) collapse to a line or a point through repeated collocated vertices.

• INTERSECTING_EDGES: 2D cell has two edges that intersect.

• INTERSECTING_FACES: 3D cell has two faces that intersect.

• INVALID_POINT_REFERENCES: Cell references points outside the mesh’s points array.

• INVERTED_FACES: Cell face(s) do not point in the direction required by its CellType.

• NEGATIVE_SIZE: 1D, 2D, or 3D cell has negative length, area, or volume, respectively.

• NON_CONTIGUOUS_EDGES: 2D cell’s perimeter edges are not contiguous.

• NON_CONVEX: 2D or 3D cell is not convex.

• NON_PLANAR_FACES: Vertices for a face do not all lie in the same plane.

• WRONG_NUMBER_OF_POINTS: Cell does not have the minimum number of points needed to describe it.

• ZERO_SIZE: 1D, 2D, or 3D cell has zero length, area, or volume, respectively.

Internally, vtkCellValidator is first used to determine the initial status of each cell, then additional PyVista-exclusive checks are made and encoded in the validity state.

For convenience, a field data array for each status is also appended:

• Each field data array contains the indices of cells with the specified status.

• The array names are lower-case versions of the status names above.

• The VALID status is excluded from the field data, and an array named 'invalid' is included instead with cell ids for all invalid cells.

Added in version 0.47.

Changed in version 0.48: Include cell status checks for INVALID_POINT_REFERENCES, ZERO_SIZE, NEGATIVE_SIZE.

Changed in version 0.48: The 'validity_state' array is now a 64-bit integer array. Previously, it was a 16-bit array.

Added in version 0.48: Add tolerance keywords.

Parameters:

tolerancefloat, default: 1.1920929e-07

Value used for most floating point equality checks throughout the cell checking process, e.g. for checking coincident points or intersecting edges. The default value is the epsilon (eps) of float32 dtype using numpy.finfo.

Note

This tolerance is independent of other tolerances.

planarity_tolerancefloat, default: 0.1

Allowed relative distance a planar polyhedral cell face may protrude out of its plane compared to the largest distance between a face center and any of its corner points. Defaults to 0.1, meaning any polygonal cell whose face protrudes more than 10% of their radius out of the plane will be marked as invalid with status NON_PLANAR_FACES.

Set this value to 0 to disable planarity checks for polyhedron cells.

Note

This tolerance only applies to POLYHEDRON cells, and is independent of other tolerances.

size_tolerancefloat, optional

Value used for evaluating the size of a cell. Cells with an absolute size less than or equal to this value are flagged as having ZERO_SIZE, and cells with a size less than this value are flagged as having NEGATIVE_SIZE. The default value is the epsilon (eps) of the mesh’s points dtype using numpy.finfo.

Setting this tolerance explicitly may be useful for marking small cells as invalid.

Note

This tolerance is independent of any other tolerances.

Returns:

DataSet

Dataset with field data of cell validity.

See also

validate_mesh()

cell_quality()

Mesh Validation

Examples

Load a mesh with invalid cells.

>>> import numpy as np
>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.download_cow()

Validate the cells and show the included arrays.

>>> validated = mesh.cell_validator()
>>> validated.array_names
['validity_state',
 'invalid',
 'coincident_points',
 'degenerate_faces',
 'intersecting_edges',
 'intersecting_faces',
 'invalid_point_references',
 'inverted_faces',
 'negative_size',
 'non_contiguous_edges',
 'non_convex',
 'non_planar_faces',
 'wrong_number_of_points',
 'zero_size']

There are many arrays, but most are empty. Show unique scalar values.

>>> validity_state = validated.cell_data['validity_state']
>>> np.unique(validity_state)
pyvista_ndarray([ 0, 16])

The 0 cells are valid, and the cells with value 16 (i.e. hex 0x10) have a nonconvex state. We confirm this by printing the 'non_convex' array, which shows there are three invalid cells.

>>> validated.field_data['non_convex']
pyvista_ndarray([1013, 1532, 3250])

Check the status of cells explicitly using CellStatus. For checking if is a cell is valid, use equality ==.

>>> validity_state[0] == pv.CellStatus.VALID
np.True_

>>> validity_state[1013] == pv.CellStatus.VALID
np.False_

Equality can also be used for checking specific status bits, but will only be True if the cell has exactly one status bit set.

>>> validity_state[1013] == pv.CellStatus.NON_CONVEX
np.True_

In general, checking the status with bit operators should be preferred.

>>> (
...     validity_state[1013] & pv.CellStatus.NON_CONVEX
... ) == pv.CellStatus.NON_CONVEX
np.True_

We can also show all invalid cells. This matches the nonconvex ids, which confirms these are the only invalid cells.

>>> validated.field_data['invalid']
pyvista_ndarray([1013, 1532, 3250])

Plot the cell states using color_labels(). Orient the camera to show the underside of the cow where two of the invalid cells are located.

>>> colored, color_map = validated.color_labels(
...     scalars='validity_state', return_dict=True
... )
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(colored)
>>> _ = pl.add_legend(color_map)
>>> pl.view_xz()
>>> pl.camera.zoom(2.5)
>>> pl.show()

Static Scene

Interactive Scene

Extract the invalid cells and plot them along with the original mesh as wireframe for context. Orient the camera to focus on the cow’s left eye where the third invalid cell is located.

>>> invalid_cells = mesh.extract_cells(validated['invalid'])

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(mesh, style='wireframe', color='light gray')
>>> _ = pl.add_mesh(invalid_cells, color='lime')
>>> pl.camera_position = pv.CameraPosition(
...     position=(5.1, 1.8, -4.9),
...     focal_point=(4.7, 1.8, 0.38),
...     viewup=(0.0, 1.0, 0.0),
... )
>>> pl.show()

Static Scene

Interactive Scene