You are viewing the documentation for Deformable v0.2.1, 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

rust
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

rust
// 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

rust
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 after their license check; 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

TriangleMesh

Struct · deformable::tools::TriangleMesh

rust
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

rust
// 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

rust
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

rust
// 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

rust
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

PolygonMesh::polygons

Method · deformable::mesh::PolygonMesh::polygons

rust
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

rust
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

rust
// 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, &parameters, None)?;

See also Guide: A polygon with a hole · C DeformableFaceHole · Python FaceHole

SurfaceMesh

Struct · deformable::tools::SurfaceMesh

rust
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

rust
// 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

rust
pub fn corner_count(&self) -> usize

The number of corners, the length of every channel that is not empty.

SurfaceMesh::validate

Method · deformable::tools::SurfaceMesh::validate

rust
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 than i32::MAX polygons.
  • 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

rust
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

rust
// 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

rust
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

Example

rust
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