You are viewing the documentation for Deformable v0.6.0, an older version. Read the latest, v0.9.0
Python API Reference
Mesh checks
Check a surface for problems before you use it, and find tetrahedral meshes that overlap.
On this page
verify_surface checks a surface for problems before you use it and reports one MeshIssue per problem it finds. meshes_intersect tells whether two tetrahedral meshes overlap, so that objects do not start inside each other.
SelfIntersectionCheck
Enum · deformable.SelfIntersectionCheck
class SelfIntersectionCheck(enum.IntEnum):
SKIP = 0
PER_ISLAND = 1
FULL = 2How far the self-intersection stage of verify_surface goes: the stage that reports an edge crossing a face it does not touch.
The stage also splits the surface into islands, the parts whose faces join through shared edges, which the inward-normal and nesting stage of MeshChecks.closed_boundary needs.
Values
SKIP(0)No self-intersection, island, inward-normal or nesting check.PER_ISLAND(1)The default: a face crossed by an edge of another island is not reported; the two islands count as intersecting for the inward-normal and nesting stage.FULL(2)Every face crossed by an edge is reported, whatever the islands.
See also Guide: Check a mesh before you use it · C DeformableSelfIntersectionCheck · Rust SelfIntersectionCheck
MeshChecks
Data class · deformable.MeshChecks
@dataclasses.dataclass(frozen=True)
class MeshChecks:
angle_threshold_degrees: float
gap_threshold: float
planar_threshold: float
uv_threshold: float | None
same_uv: bool
convex: bool
closed_boundary: bool
self_intersection: SelfIntersectionCheck | intWhich checks verify_surface runs, and their thresholds.
MeshChecks.default() gives the defaults the fields list. Some checks run whatever the fields say: lone and co-located vertices, co-located, non-manifold, inverted and degenerate edges, degenerate faces and holes, corners of one face at one position, outer loops that do not wind once, and faces with holes.
The mesh radius is the largest distance of a vertex position from the mean of the distinct positions. A face’s radius is the largest distance of its corners from the mean of its outer loop’s corners.
Fields
angle_threshold_degrees(float)A face whose outer loop has a corner angle below this many degrees is aSMALL_ANGLEissue. The angle is the one between the corner’s two edges, from 0 to 180 degrees, so a reflex corner counts as 360 degrees minus its interior angle.default()gives2.0.gap_threshold(float)Two corners of a face at different positions closer than this fraction of the mesh radius are aNEAR_VERTICESissue; a negative threshold counts as its absolute value. At 0, only corners whose squared distance is 0 are reported: asCO_LOCATED_FACE_VERTICESwhen they sit at one position, which no threshold turns off, and asNEAR_VERTICESwhen they are so close that the square of their distance rounds to 0.default()gives0.001.planar_threshold(float)A face with a corner farther from its outer loop’s plane than this fraction of its radius is aNON_PLANARissue, and skips theINCONSISTENT_UVcheck. A triangle without holes is always planar.default()gives0.05.uv_threshold(floatorNone)A corner farther than this fraction of the face radius from where the UV map of its face puts it is anINCONSISTENT_UVissue; None skips the check.default()givesNone.same_uv(bool)ReportsSAME_UV: two corners of a face at different places with identical UVs.default()givesFalse.convex(bool)ReportsNON_CONVEX: a face with a reflex corner.default()givesFalse.closed_boundary(bool)ReportsNON_CLOSED_BOUNDARY, an edge with one face, and runs the inward-normal and nesting stage last.default()givesFalse.self_intersection(SelfIntersectionCheckorint)How far the self-intersection stage goes. An int that is no member’s value makesverify_surfaceraiseDeformableErrorwith the statusINVALID_ARGUMENT, and one that does not fit in 32 bits ValueError.default()givesSelfIntersectionCheck.PER_ISLAND.
Example
# A cage for tetrahedralize: every edge on two faces, none crossed.
checks = deformable.MeshChecks.default(
closed_boundary=True,
self_intersection=deformable.SelfIntersectionCheck.FULL,
)
surface = deformable.SurfaceMesh(polygons)
deformable.verify_surface(surface, checks=checks)
# []See also Guide: Check a mesh before you use it · C DeformableMeshChecks · Rust MeshChecks
MeshChecks.default
Class method · deformable.MeshChecks.default
@classmethod
def default(
cls,
**changes: float | bool | SelfIntersectionCheck | None,
) -> MeshChecksThe defaults the fields list, with the given fields changed.
Parameters
**changes(float,bool,SelfIntersectionCheckorNone)Field values that replace the defaults, by field name.
Raises
TypeError when changes names a field MeshChecks does not have.
See also C deformable_mesh_checks_default
MeshIssueKind
Enum · deformable.MeshIssueKind
class MeshIssueKind(enum.IntEnum):
LONE_VERTEX = 0
NON_CLOSED_BOUNDARY = 1
NON_MANIFOLD = 2
CO_LOCATED_VERTICES = 3
CO_LOCATED_EDGES = 4
INVERTED_NORMAL = 5
DEGENERATE_EDGE = 6
DEGENERATE_FACE = 7
DEGENERATE_HOLE = 8
CO_LOCATED_FACE_VERTICES = 9
NEAR_VERTICES = 10
SMALL_ANGLE = 11
NON_PLANAR = 12
NON_CONVEX = 13
MULTIPLE_WINDING = 14
SAME_UV = 15
INCONSISTENT_UV = 16
FACE_HAS_HOLES = 17
SELF_INTERSECTION = 18
INWARD_ISLAND_INTERSECTS = 19
NESTED_ISLANDS = 20
INWARD_NORMALS = 21The kind of a MeshIssue: each member says which fields of the issue it fills; the others are 0 or empty.
Values
LONE_VERTEX(0)No face uses the vertexvertex. It is reported for the vertex, then once more for its position, named by the lowest vertex there, when no vertex at that position is used.NON_CLOSED_BOUNDARY(1)The edgeedgehas one face; only withMeshChecks.closed_boundary.NON_MANIFOLD(2)The edgeedgehas more than two faces:use_countis its face count on an edge between vertex indices, its loop-edge count on an edge between positions.CO_LOCATED_VERTICES(3)The verticesvertices, ascending, sit at exactly one position; reported whatever the checks.CO_LOCATED_EDGES(4)The edges between vertex indicesedges, in order of first use, join the same two positions.INVERTED_NORMAL(5)The two faces of the edgeedgedisagree on their orientation.DEGENERATE_EDGE(6)The two ends of the edgeedgeare at one position.DEGENERATE_FACE(7)The outer loop of the facefaceencloses no area, so it has no normal.DEGENERATE_HOLE(8)The loop of the holeholeof the facefaceencloses no area, so it has no normal.CO_LOCATED_FACE_VERTICES(9)The two cornerscornersof the facefacesit at one position, across its outer loop and holes.NEAR_VERTICES(10)The two cornerscornersof the facefacesit at different positions, closer thanMeshChecks.gap_thresholdtimes the mesh radius:distanceapart,relative_distanceof the mesh radius.SMALL_ANGLE(11)The smallest corner angle of the outer loop of the faceface,degrees, is belowMeshChecks.angle_threshold_degrees. The angle is the one between the corner’s two edges, from 0 to 180 degrees.NON_PLANAR(12)A corner of the facefacelies farther from its outer loop’s plane thanMeshChecks.planar_thresholdtimes the face radius:relative_deviationis the largest distance of a corner from the plane, over the face radius.NON_CONVEX(13)The outer loop of the facefacehas a reflex corner; only withMeshChecks.convex.interior_angle_degreesis the interior angle of the most reflex one, in degrees, above 180.MULTIPLE_WINDING(14)The turns of the outer loop of the facefacedo not add up to one turn, within a quarter turn; reported whateverMeshChecks.convexsays.SAME_UV(15)The two cornerscornersof the facefacesit at different places with identical coordinates in the UV setuv_set, 0 or 1; only withMeshChecks.same_uv. The two corners then drop out of theINCONSISTENT_UVcheck of that set.INCONSISTENT_UV(16)The cornercornerof the facefacelies farther thanMeshChecks.uv_thresholdtimes the face radius from where the UV map of the face puts it, in the UV setuv_set:relative_distanceis that distance over the face radius. The map is the affine one that fits the face’s best-shaped triple of outer corners; only a face within the planar threshold, with a hole or more than three outer corners, is checked.FACE_HAS_HOLES(17)The facefacehashole_countholes; reported for every face with holes, whatever the checks.SELF_INTERSECTION(18)The edgeedgecrosses the faceface, which it does not touch. WithSelfIntersectionCheck.PER_ISLAND, only an edge and a face of one island are reported.INWARD_ISLAND_INTERSECTS(19)From the inward-normal and nesting stage: the islandisland, whose face normals point inward, intersects another island. The stage reports nothing else then.NESTED_ISLANDS(20)From the inward-normal and nesting stage: the islandislandlies inside an island of the same orientation, its innermost containercontainer;inwardsays whether both have inward face normals.INWARD_NORMALS(21)From the inward-normal and nesting stage: the islandsuncontained, ascending, have inward face normals and no island contains them;island_countis the number of islands of the surface.
See also Guide: Check a mesh before you use it · C DeformableMeshIssueKind
MeshIssue
Data class · deformable.MeshIssue
@dataclasses.dataclass(frozen=True)
class MeshIssue:
kind: MeshIssueKind
vertex: int
face: int
hole: int
corner: int
uv_set: int
island: int
container: int
use_count: int
hole_count: int
island_count: int
edge: tuple[int, int]
corners: tuple[int, int]
inward: bool
distance: float
relative_distance: float
degrees: float
relative_deviation: float
interior_angle_degrees: float
vertices: list[int]
edges: list[tuple[int, int]]
uncontained: list[int]One problem verify_surface found, with the elements that locate it. Its kind says which fields it fills, as each MeshIssueKind member lists; the others are 0 or empty.
Vertices are input vertex indices. An edge is named by the two vertex indices of the first loop edge on it, smaller first. Corners count within their polygon, outer loop first, then the holes; holes count within their face in corner order; islands, the parts of the surface whose faces join through shared edges, are numbered in order of their lowest face.
NON_CLOSED_BOUNDARY and NON_MANIFOLD are checked twice: on the edges between distinct vertex indices, then on the edges between distinct positions. So an edge of a surface without co-located vertices is reported once by each; remove the duplicates before showing the issues.
Fields
kind(MeshIssueKind)What the issue is, which says the fields it fills.vertex(int)The unused vertex ofLONE_VERTEX.face(int)The face the issue names: the face of a face, corner or UV issue, or the faceSELF_INTERSECTIONcrosses.hole(int)The hole within the face.corner(int)The corner within the face.uv_set(int)The UV set, 0 or 1.island(int)The island an inward-normal or nesting issue names: the inward one, or the contained one.container(int)The innermost container island.use_count(int)The face count of a non-manifold edge between vertex indices, or the loop-edge count of one between positions.hole_count(int)The number of holes of the face.island_count(int)The number of islands of the surface.edge(tuple[int, int])The edge’s two vertices.corners(tuple[int, int])The two corners within the face, smaller first.inward(bool)Whether both nested islands have inward face normals.distance(float)The distance between the two corners.relative_distance(float)The distance between the two corners over the mesh radius, or between a corner and where the UV map puts it over the face radius.degrees(float)The smallest corner angle of the outer loop, in degrees, measured between the corner’s two edges.relative_deviation(float)The largest distance of a corner from the plane, over the face radius.interior_angle_degrees(float)The interior angle of the most reflex corner, in degrees, above 180.vertices(list[int])The co-located vertices, ascending.edges(list[tuple[int, int]])The co-located edges, in order of first use.uncontained(list[int])The uncontained inward islands, ascending.
See also Guide: Check a mesh before you use it · C DeformableMeshIssue · Rust MeshIssue
verify_surface
Function · deformable.verify_surface
def verify_surface(
mesh: SurfaceMesh,
holes: Sequence[FaceHole] = (),
checks: MeshChecks | None = None,
) -> list[MeshIssue]Checks the polygon mesh of a surface mesh for problems before you use it, such as a cage before triangulate, and returns one MeshIssue per problem found.
The checks read the positions, the polygons, the holes and the first two UV sets of mesh, not its normals or colours. Malformed input is an error, not an issue. With MeshChecks.closed_boundary, a last stage looks for islands with inward face normals and for islands nested inside an island of the same orientation; it runs only when every check before it passed. Its containment rays come from a stream with a fixed seed, so equal calls give equal results.
Parameters
mesh(SurfaceMesh)The surface mesh to check.holes(Sequence[FaceHole])The runs of polygon corners that form hole loops; empty when no polygon has a hole.checks(MeshChecksorNone)Which checks run, and their thresholds; None takesMeshChecks.default().
Returns
list[MeshIssue]: The issues in check order; an empty list means the mesh passes.
Raises
DeformableError with one of these statuses:
INDEX_OUT_OF_RANGEA corner names a vertex past the end of the positions, a polygon has no corners, a hole names a polygon past the last, or a polygon’s hole runs do not cover the corners after its outer loop end to end. Each run needs at least one corner, and so does the outer loop.LENGTH_MISMATCHThe polygon sizes do not add up to the number of corners.NON_FINITE_VALUEA position or a UV of the first two sets is NaN or infinite, or so isangle_threshold_degrees,gap_threshold,planar_thresholdor auv_thresholdthat is not None.
ValueError when the positions or normals of mesh do not form whole groups of three numbers, a UV set does not hold one coordinate pair per corner, the colours do not form whole groups of four numbers, or a polygon size, corner or hole value is negative or does not fit in 32 bits, or the self_intersection of checks does not fit in 32 bits; after the checks ran, when the library reports an issue kind this package does not know, which only a newer library does.
TypeError when the self_intersection of checks is not an int.
Example
# The unit cube without its last face.
open_box = deformable.PolygonMesh(
polygons.positions, [4] * 5, polygons.polygon_vertices[:20]
)
checks = deformable.MeshChecks.default(closed_boundary=True)
surface = deformable.SurfaceMesh(open_box)
issues = deformable.verify_surface(surface, checks=checks)
issues[0].kind.name, issues[0].edge
# ('NON_CLOSED_BOUNDARY', (1, 3))See also Guide: Check a mesh before you use it · C deformable_verify_surface · Rust verify_surface
meshes_intersect
Function · deformable.meshes_intersect
def meshes_intersect(
first: TetrahedralMesh,
second: TetrahedralMesh,
) -> boolWhether two tetrahedral meshes in world space overlap, to find objects that start inside each other: True when a tetrahedron of first and one of second have bounding boxes that meet and an overlap volume above 1e-10 with a nonzero normal.
The normal of a pair is the summed area of the second tetrahedron’s faces clipped to the first. It vanishes, and the pair does not count, when either tetrahedron lies inside the other, the two coincide, or their overlap is symmetric about its centre, as some partial overlaps are: two identical meshes do not intersect, and faces on each other’s planes can make the answer depend on the argument order. The clipping tolerance, 1e-12 times the longest edge, also comes from the first tetrahedron alone.
Parameters
first(TetrahedralMesh)One mesh, in world space.second(TetrahedralMesh)The other mesh, in world space.
Raises
DeformableError with one of these statuses:
EMPTY_MESHfirstorsecondhas no tetrahedrons.INDEX_OUT_OF_RANGEA tetrahedron names a node past the end of its mesh’s positions.NON_FINITE_VALUEA position is NaN or infinite.
ValueError when the positions of a mesh do not form whole groups of three numbers, its tetrahedrons do not form whole groups of four indices, or an index is negative or does not fit in 32 bits.
Example
# A copy of mesh moved half a unit along x overlaps it.
positions = [(x + 0.5, y, z) for x, y, z in mesh.positions]
moved = deformable.TetrahedralMesh(positions, mesh.tetrahedrons)
deformable.meshes_intersect(mesh, moved)
# TrueSee also Guide: Find objects that start inside each other · C deformable_meshes_intersect · Rust meshes_intersect