You are viewing the documentation for Deformable v0.1.1, an older version. Read the latest, v0.9.0

Rust API Reference

Overview

The reference of the deformable Rust crate: its conventions, and the pages that list every public item.

On this page

The Rust SDK is the deformable crate. These pages list every public item of the crate with its signature and documentation, generated from its source. They group the items by topic rather than by module: the kind line under each heading gives the item’s path in the crate.

For tasks and worked examples, start with the getting-started guide.

Pages

  • Scene: The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs.
  • Tools: Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.
  • Mesh checks: Check a surface for problems before you use it, and find tetrahedral meshes that overlap.
  • Meshes: The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
  • Render surfaces: Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
  • Math: The points, vectors, transforms, planes and convex regions the other pages take and return.
  • Errors: Errors and status codes, the library version, and the cancel flag that stops a long call.
  • License: The license state of this device, and the calls that refresh, activate and deactivate it.

Conventions

  • Errors. Every fallible call returns Error; arguments the C interface cannot carry (a UV set of the wrong length) are refused by the crate itself with the same type.
  • Units. Lengths cross in host units; time, forces, gravity, masses and material values in simulation units. The scene’s scale converts host lengths to simulation lengths.
  • Threads. A scene::Scene is Send and takes one call at a time; tools, scene::SurfaceEmbedding and CancelFlag may be used from several threads at once.
  • License. The library checks the license of this device and user before every engine call; license reads it and activates a license key. A call the trial or license does not allow fails with an Error whose ErrorKind::is_license is true, and whose message is written to show the user as it is.
  • Examples. The examples share a few values set up out of view, in hidden lines: cage, the unit cube as a closed tools::TriangleMesh with outward normals; polygons, the same cube as a mesh::PolygonMesh of six quads; mesh, the cage filled with tetrahedrons; scene, a scene::Scene holding one object made of mesh with one default material; and material and object, the handles of that material and object.

The crate

Finite element deformation and fracture of tetrahedral meshes, with the mesh tools that prepare them.

This is the Rust SDK of Tangerina Deformable: a safe API over libdeformable, the shared library of the C SDK. The crate holds no engine code; it calls the library. The first build downloads the library of the crate’s version for the target platform from https://downloads.tangerina.io with curl, checks it against the SHA-256 checksums the crate carries, and keeps it in the build folder, where cargo run and cargo test find it. To build without a download, set the DEFORMABLE_LIB_DIR environment variable to the absolute path of the lib folder of the C SDK for your platform (from https://tangerina.io/deformable#download-c). A program built with the crate needs the shared library at run time, so ship libdeformable.dylib, libdeformable.so or deformable.dll next to it.

The public surface:

  • sceneone scene a host drives frame by frame — materials, objects, glue, driven vertices, forces, the frame step and its outputs — and the render surfaces embedded in its objects and skinned each frame.
  • toolsmesh functions, with no scene state, that prepare a scene’s inputs — polygon mesh triangulation, tetrahedralize, layer extrusion, autocage, splinters from an image, surface verification and mesh intersection.
  • meshthe tetrahedral and polygon meshes their signatures share, and the faces of a tetrahedron.
  • maththe vectors, matrices and transforms their signatures share.
  • Errorthe error of every fallible call, with the ErrorKind of the failure, the library’s message and the element indices it names.
  • CancelFlagstops a long tool or step from another thread.
  • licensethe trial and license of this device and user, which the library checks before every engine call, and activating or deactivating a license key.

The typical host flow builds an object from a closed cage, embeds the render surface in it, steps the scene each frame and skins the surface:

rust
use deformable::math::{AffineTransform, Vector3};
use deformable::mesh::PolygonMesh;
use deformable::scene::{
    DeformedSurface, MaterialParameters, ObjectOptions, Scene,
    SkinningOptions, StepOutcome, TetrahedronMaterials, embed_surface,
};
use deformable::tools::{
    Anisotropy, ClipMode, PreparationParameters, SurfaceMesh,
    TetrahedralizeParameters, TriangleMesh, tetrahedralize,
};

// A closed unit cube with outward triangles: the tetrahedralization
// cage and the render surface at once.
let positions: Vec<Vector3> = (0..8)
    .map(|corner: u32| {
        let bit = |shift: u32| f64::from(corner >> shift & 1);
        Vector3::new(bit(0), bit(1), bit(2))
    })
    .collect();
let triangles = vec![
    [0, 2, 3], [0, 3, 1], [4, 5, 7], [4, 7, 6], [0, 1, 5], [0, 5, 4],
    [2, 6, 7], [2, 7, 3], [0, 4, 6], [0, 6, 2], [1, 3, 7], [1, 7, 5],
];
let cage = TriangleMesh {
    positions: positions.clone(),
    triangles: triangles.clone(),
};

// The cage, filled with tetrahedrons.
let parameters = TetrahedralizeParameters {
    maximum_edge_length: 0.5,
    anisotropy: [Anisotropy::default(); 2],
    density_regions: Vec::new(),
};
let rest = tetrahedralize(&cage, &parameters, None)?.mesh;

// The tetrahedral mesh, made an object of a scene.
let mut scene = Scene::new();
let material = scene.add_material(&MaterialParameters::default())?;
let object = scene.add_object(
    &rest,
    TetrahedronMaterials::Uniform(material),
    ObjectOptions::default(),
)?;

// The render surface, embedded in the rest mesh.
let surface = SurfaceMesh {
    mesh: PolygonMesh {
        positions,
        polygon_sizes: vec![3; triangles.len()],
        polygon_vertices: triangles.concat(),
    },
    ..SurfaceMesh::default()
};
let preparation = PreparationParameters {
    clip_mode: ClipMode::AssignOnly,
    uv_scale: 1.0,
    splinter_cage: None,
};
let embedding = embed_surface(&rest, &surface, &preparation)?;

// Frames at 24 per second, 10 substeps each; the first call only
// records the time.
let first = scene.step(0.0, 10, None)?;
assert_eq!(first.outcome, StepOutcome::FirstCall);
for frame in 1..=6 {
    let report = scene.step(f64::from(frame) / 24.0, 10, None)?;
    assert_eq!(report.outcome, StepOutcome::Stepped);
}

// The tetrahedron states skin the render surface, in the object space
// of a shape whose world transform is the identity: the whole cube has
// fallen under gravity, top (rest y = 1) and bottom (rest y = 0).
let mut states = Vec::new();
scene.tetrahedron_states(object, &mut states)?;
let mut deformed = DeformedSurface::default();
let world = AffineTransform::IDENTITY;
let options = SkinningOptions::default();
embedding.deform(&states, &world, options, &mut deformed)?;
let heights = || deformed.positions.iter().map(|position| position[1]);
assert!(heights().all(|height| height < 0.9));
assert!(heights().any(|height| height < -0.1));