You are viewing the documentation for Deformable v0.4.0, an older version. Read the latest, v0.9.0
Rust API Reference
Meshes
The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
On this page
The meshes the tools and the scene take and return: a TetrahedralMesh for each simulated object, a TriangleMesh or a PolygonMesh for cages, and a SurfaceMesh for the surface a host renders. The faces of a tetrahedron come last.
TetrahedralMesh
Struct · deformable::mesh::TetrahedralMesh
pub struct TetrahedralMesh {
pub positions: Vec<Vector3>,
pub tetrahedrons: Vec<[u32; 4]>,
}A tetrahedral mesh: shared node positions and four node indices per tetrahedron, positively oriented (left-handed).
With corners X0 to X3 and ei = Xi - X0, a tetrahedron is positive when -e1 · (e2 × e3) is above 0, and
swapping two corners turns a right-handed tetrahedron positive.
Scene::add_object asks for more: it refuses a mesh with a
tetrahedron whose value, in simulation units, is not above 1e-9, and DegenerateKind
says how such a tetrahedron fails. The tools make positive tetrahedrons, though a thick
extrude shell can invert some on sharp curvature, and
span_layers keeps the flat tetrahedrons of layers that touch.
Fields
positions(Vec<Vector3>)The node positions.tetrahedrons(Vec<[u32; 4]>)The four node indices of each tetrahedron.
Implements Clone · Debug · Default · PartialEq · Send · Sync
Example
// One positive tetrahedron: its corners are left-handed.
let single = TetrahedralMesh {
positions: vec![Vector3::ZERO, Vector3::X, Vector3::Z, Vector3::Y],
tetrahedrons: vec![[0, 1, 2, 3]],
};
let materials = TetrahedronMaterials::Uniform(material);
scene.add_object(&single, materials, ObjectOptions::default())?;See also Guide: The crate · C DeformableTetrahedralMesh · C DeformableTetrahedralMeshView · Python TetrahedralMesh
TetrahedralMesh::validate
Method · deformable::mesh::TetrahedralMesh::validate
pub fn validate(&self) -> Result<(), Error>Checks that the mesh has tetrahedrons, that every node index is in range and that every position is finite, and returns the first failure in that order.
Scene::add_object, boundary_faces
and meshes_intersect run the same checks;
add_object checks the material count before them, and runs them on the positions in simulation units. The
orientation of the tetrahedrons is not checked. The checks run in the crate, without calling the library.
Errors
EmptyMeshThe mesh has no tetrahedron.IndexOutOfRangeA tetrahedron uses a node index past the end of the positions.NonFiniteValueA position is NaN or infinite.
TriangleMesh
Struct · deformable::tools::TriangleMesh
pub struct TriangleMesh {
pub positions: Vec<Vector3>,
pub triangles: Vec<[u32; 3]>,
}A triangle mesh: shared vertex positions and three vertex indices per triangle.
A closed cage, as tetrahedralize takes, lists the corners of each triangle
counter-clockwise as seen from outside, so its normals point outward.
Fields
positions(Vec<Vector3>)The vertex positions.triangles(Vec<[u32; 3]>)The three vertex indices of each triangle.
Implements Clone · Debug · Default · PartialEq · Send · Sync
Example
// One triangle, counter-clockwise seen from +z, its normal side.
let triangle = TriangleMesh {
positions: vec![Vector3::ZERO, Vector3::X, Vector3::Y],
triangles: vec![[0, 1, 2]],
};
let prism = extrude(&triangle, 0.1, ExtrudeDirection::Up)?;
assert_eq!(prism.tetrahedrons.len(), 3);See also Guide: The crate · C DeformableTriangleMesh · C DeformableTriangleMeshView · Python TriangleMesh
PolygonMesh
Struct · deformable::mesh::PolygonMesh
pub struct PolygonMesh {
pub positions: Vec<Vector3>,
pub polygon_sizes: Vec<u32>,
pub polygon_vertices: Vec<u32>,
}A polygon mesh as a host stores it: shared positions, the corner count of each polygon, and the vertex of every corner, polygon after polygon.
A closed mesh lists the corners of each polygon counter-clockwise as seen from outside, so its normals point
outward. A polygon with holes lists its outer loop first, then each hole loop, and a
FaceHole names each hole run.
Fields
positions(Vec<Vector3>)The vertex positions.polygon_sizes(Vec<u32>)The number of corners of each polygon.polygon_vertices(Vec<u32>)The vertex index of each corner, polygon after polygon.
Implements Clone · Debug · Default · PartialEq · Send · Sync
Example
// The cube's bottom and top faces: the corners of one quad, then
// those of the other.
let faces = PolygonMesh {
positions: polygons.positions.clone(),
polygon_sizes: vec![4, 4],
polygon_vertices: vec![0, 2, 3, 1, 4, 5, 7, 6],
};
assert_eq!(faces.polygons().nth(1), Some(&[4, 5, 7, 6][..]));See also Guide: The crate · C DeformablePolygonMesh · C DeformablePolygonMeshView · Python PolygonMesh
PolygonMesh::validate
Method · deformable::mesh::PolygonMesh::validate
pub fn validate(&self) -> Result<(), Error>Checks that the polygon sizes add up to the corner count, that every vertex index is in range and that every position is finite, and returns the first failure in that order.
A mesh with no polygons passes. The polygons’ shapes are not checked: a polygon of fewer than 3 corners passes too. The checks run in the crate, without calling the library.
Errors
LengthMismatchThe polygon sizes do not add up to the length ofpolygon_vertices.IndexOutOfRangeA corner names a vertex past the end of the positions.NonFiniteValueA position is NaN or infinite.
PolygonMesh::polygons
Method · deformable::mesh::PolygonMesh::polygons
pub fn polygons(&self) -> impl Iterator<Item = &[u32]>The corners of each polygon, in polygon order. On a mesh whose sizes add up to more corners than it has, the polygons end before the first one that runs past the last corner.
FaceHole
Struct · deformable::tools::FaceHole
pub struct FaceHole {
pub face: u32,
pub first_corner: u32,
pub corner_count: u32,
}A run of a polygon’s corners that forms one hole loop; the corners before the polygon’s first hole form its outer loop.
triangulate and verify_surface take a list of them, and a
polygon that none of them names has no hole.
Fields
face(u32)The index of the polygon that holds the hole.first_corner(u32)The run’s first corner, counted from the polygon’s first corner.corner_count(u32)The number of corners in the run.
Implements Clone · Copy · Debug · Eq · PartialEq · Send · Sync
Example
// A 3 by 3 square around a 1 by 1 hole: corners 0 to 3 of polygon 0
// are its outer loop, and corners 4 to 7 its hole loop.
let holes = [FaceHole { face: 0, first_corner: 4, corner_count: 4 }];
let parameters = TriangulateParameters {
closed_boundary: false,
..TriangulateParameters::default()
};
let result = triangulate(&frame, &holes, ¶meters, None)?;See also Guide: A polygon with a hole · C DeformableFaceHole · Python FaceHole
SurfaceMesh
Struct · deformable::tools::SurfaceMesh
pub struct SurfaceMesh {
pub mesh: PolygonMesh,
pub normals: Vec<Vector3>,
pub uv_sets: Vec<Vec<Vector2>>,
pub colours: Vec<[f64; 4]>,
}A render surface: a polygon mesh with per-corner channels, the normals, UV sets and colours that
embed_surface carries through its clip.
Each channel is empty or holds one entry per corner, in the order of the mesh’s polygon_vertices. Every UV set
holds one pair per corner: the library reads the sets one after the other, so the crate refuses a set of another
length with ErrorKind::LengthMismatch before it calls the library. SurfaceMesh::default() has no polygons
and no channels.
Fields
mesh(PolygonMesh)The positions and polygons.normals(Vec<Vector3>)The normal of each corner, or none.uv_sets(Vec<Vec<Vector2>>)The UV sets, each with one coordinate pair per corner.colours(Vec<[f64; 4]>)The red, green, blue and alpha of each corner, or none.
Implements Clone · Debug · Default · PartialEq · Send · Sync
Example
// Each quad of the cube mapped onto the unit square in one UV set.
let square = [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]];
let surface = SurfaceMesh {
mesh: polygons,
uv_sets: vec![square.map(|[u, v]| Vector2::new(u, v)).repeat(6)],
..SurfaceMesh::default()
};
surface.validate()?;See also Guide: Describe the render surface · C DeformableSurfaceMeshView · Python SurfaceMesh
SurfaceMesh::corner_count
Method · deformable::tools::SurfaceMesh::corner_count
pub fn corner_count(&self) -> usizeThe number of corners, the length of every channel that is not empty.
SurfaceMesh::validate
Method · deformable::tools::SurfaceMesh::validate
pub fn validate(&self) -> Result<(), Error>Checks the polygon sizes against the corners and the channel lengths, then the vertex indices, then that every value is finite, and returns the first failure in that order. The checks run in the crate, without calling the library.
Errors
LengthMismatchThe polygon sizes do not add up to the corner count, the normals or colours are neither empty nor one per corner, a UV set does not hold one pair per corner, or the mesh has more thani32::MAXpolygons.IndexOutOfRangeA corner names a vertex past the end of the positions.NonFiniteValueA position, normal, UV or colour value is NaN or infinite.
FACES
Constant · deformable::mesh::FACES
pub const FACES: [[usize; 3]; 4] =
[[1, 2, 3], [0, 3, 2], [0, 1, 3], [0, 2, 1]];The three local corners (0 to 3) of each face of a tetrahedron: FACES[k] holds those of face k, the face
opposite corner k.
Seen from outside a positively oriented (left-handed) tetrahedron, the corners of each face run clockwise: with
corners a, b and c in that order, (b - a) × (c - a) points into the tetrahedron, toward corner k. The face bits of
FaceEvent and of boundary_faces number the faces this
way.
Example
// Face 1 is the face opposite corner 1.
assert_eq!(FACES[1], [0, 3, 2]);See also Guide: Tetrahedron faces · C deformable_face_corners · Python face_corners
boundary_faces
Function · deformable::mesh::boundary_faces
pub fn boundary_faces(mesh: &TetrahedralMesh) -> Result<Vec<u8>, Error>The outer faces of each tetrahedron of a mesh, as one mask per tetrahedron: bit k is set when no other tetrahedron shares face k, the face opposite corner k.
The masks depend only on which tetrahedrons share faces, not on the positions, so a host computes them once from
an object’s rest mesh and can set them in its own per-tetrahedron output flags. The exposed faces of a
FaceEvent include them: clear them from it to keep only the faces a fracture
opened. The orientation of the tetrahedrons is not checked.
Parameters
mesh(&TetrahedralMesh)The tetrahedral mesh, such as the rest mesh of an object.
Returns
Vec<u8>: One mask per tetrahedron, in mesh order: bit k stands for face k, as FACES numbers the faces.
Errors
EmptyMeshThe mesh has no tetrahedron.IndexOutOfRangeA tetrahedron uses a node index past the end of the positions.NonFiniteValueA position is NaN or infinite.NonManifoldFaceThree or more tetrahedrons share one face.
Example
let masks = boundary_faces(&mesh)?;
// The 12 triangles of the cage are the outer faces of its mesh.
let outer: u32 = masks.iter().map(|mask| mask.count_ones()).sum();
assert_eq!(outer, 12);See also Guide: Tetrahedron faces · C deformable_boundary_faces · Python boundary_faces