You are viewing the documentation for Deformable v0.2.1, an older version. Read the latest, v0.9.0
Rust API Reference
Math
The points, vectors, transforms, planes and convex regions the other pages take and return.
The points, vectors and transforms the other pages take and return, and the planes and convex regions that bound a part of space.
The vectors, the matrix and the transform have the layout of their C structs, so arrays of them cross to the library without a copy.
Vector2
Struct · deformable::math::Vector2
pub struct Vector2 {
pub x: f64,
pub y: f64,
}A point or vector in the plane, such as the UV coordinates of a corner: two f64 components.
Fields
x(f64)The first component; u for a UV coordinate pair.y(f64)The second component; v for a UV coordinate pair.
Implements Add · Clone · Copy · Debug · Default · Mul<f64> · PartialEq · Sub · Send · Sync
Example
// The UV coordinates of a corner, halfway along the top edge.
let uv = Vector2::new(0.5, 1.0);
assert_eq!(uv.length_squared(), 1.25);
// Positive: the second vector lies counter-clockwise from the first.
assert_eq!(Vector2::new(1.0, 0.0).cross(uv), 1.0);See also Guide: The crate · C DeformableVector2 · Python Vector2
Vector2::new
Associated function · deformable::math::Vector2::new
pub const fn new(x: f64, y: f64) -> SelfA vector from its two components.
Parameters
x(f64)The first component; u for a UV coordinate pair.y(f64)The second component; v for a UV coordinate pair.
Vector2::dot
Method · deformable::math::Vector2::dot
pub fn dot(self, other: Self) -> f64The dot product: the sum of the products of matching components.
Parameters
other(Vector2)The second vector.
Vector2::cross
Method · deformable::math::Vector2::cross
pub fn cross(self, other: Self) -> f64The z component of the cross product of the two vectors taken in 3D: twice the signed area of the triangle
they span. It is positive when other lies counter-clockwise from self.
Parameters
other(Vector2)The second vector.
Vector2::length_squared
Method · deformable::math::Vector2::length_squared
pub fn length_squared(self) -> f64The squared Euclidean length: length without its square root.
Vector2::length
Method · deformable::math::Vector2::length
pub fn length(self) -> f64The Euclidean length.
Vector2::is_finite
Method · deformable::math::Vector2::is_finite
pub fn is_finite(self) -> boolWhether both components are finite: neither NaN nor infinite.
Vector3
Struct · deformable::math::Vector3
pub struct Vector3 {
pub x: f64,
pub y: f64,
pub z: f64,
}A point or vector in space: three f64 components.
A Matrix3 times a vector (matrix * vector) takes it as a column, and
AffineTransform::apply maps it as a row.
Fields
x(f64)The first component.y(f64)The second component.z(f64)The third component.
Implements Add · AddAssign · Clone · Copy · Debug · Default · Div<f64> · Mul<f64> · Mul<Vector3> for f64 · Mul<Vector3> for Matrix3 · MulAssign<f64> · Neg · PartialEq · Sub · SubAssign · Send · Sync
Example
// Gravity along -z, for a scene whose z axis points up.
let gravity = Vector3::new(0.0, 0.0, -9.81);
scene.set_gravity(gravity)?;
// The cross product is right-handed.
assert_eq!(Vector3::X.cross(Vector3::Y), Vector3::Z);See also Guide: The crate · C DeformableVector3 · Python Vector3
Vector3::ZERO
Associated constant · deformable::math::Vector3::ZERO
pub const ZERO: Vector3 = Self::new(0.0, 0.0, 0.0);The zero vector.
Vector3::X
Associated constant · deformable::math::Vector3::X
pub const X: Vector3 = Self::new(1.0, 0.0, 0.0);The unit vector along the first axis, x.
Vector3::Y
Associated constant · deformable::math::Vector3::Y
pub const Y: Vector3 = Self::new(0.0, 1.0, 0.0);The unit vector along the second axis, y.
Vector3::Z
Associated constant · deformable::math::Vector3::Z
pub const Z: Vector3 = Self::new(0.0, 0.0, 1.0);The unit vector along the third axis, z.
Vector3::new
Associated function · deformable::math::Vector3::new
pub const fn new(x: f64, y: f64, z: f64) -> SelfA vector from its three components.
Parameters
x(f64)The first component.y(f64)The second component.z(f64)The third component.
Vector3::dot
Method · deformable::math::Vector3::dot
pub fn dot(self, other: Self) -> f64The dot product: the sum of the products of matching components.
Parameters
other(Vector3)The second vector.
Vector3::cross
Method · deformable::math::Vector3::cross
pub fn cross(self, other: Self) -> SelfThe cross product of self and other, right-handed: X cross Y is
Z.
Parameters
other(Vector3)The second vector.
Vector3::length_squared
Method · deformable::math::Vector3::length_squared
pub fn length_squared(self) -> f64The squared Euclidean length: length without its square root.
Vector3::length
Method · deformable::math::Vector3::length
pub fn length(self) -> f64The Euclidean length.
Vector3::is_finite
Method · deformable::math::Vector3::is_finite
pub fn is_finite(self) -> boolWhether every component is finite: neither NaN nor infinite.
Vector3::to_array
Method · deformable::math::Vector3::to_array
pub fn to_array(self) -> [f64; 3]The components as an array, [x, y, z].
Matrix3
Struct · deformable::math::Matrix3
pub struct Matrix3 {
pub rows: [Vector3; 3],
}A 3 by 3 matrix of f64, stored by rows.
A matrix times a Vector3 (matrix * vector) takes the vector as a column: component i of the result is the dot
product of row i and the vector. Two matrices multiply as usual, and +, - and * by an f64 work entry by
entry. The default is ZERO, not the identity.
Fields
rows([Vector3; 3])The three rows, from top to bottom.
Implements Add · Clone · Copy · Debug · Default · Mul · Mul<f64> · Mul<Vector3> · PartialEq · Sub · Send · Sync
Example
let scale = Matrix3::from_diagonal(Vector3::new(2.0, 4.0, 0.5));
assert_eq!(scale.determinant(), 4.0);
let inverse = scale.inverse().expect("the determinant is not 0");
assert_eq!(inverse.diagonal(), Vector3::new(0.5, 0.25, 2.0));
assert_eq!(scale * inverse, Matrix3::IDENTITY);See also Guide: The crate · C DeformableMatrix3
Matrix3::ZERO
Associated constant · deformable::math::Matrix3::ZERO
pub const ZERO: Matrix3 =
Self::from_rows(Vector3::ZERO, Vector3::ZERO, Vector3::ZERO);The zero matrix.
Matrix3::IDENTITY
Associated constant · deformable::math::Matrix3::IDENTITY
pub const IDENTITY: Matrix3 =
Self::from_rows(Vector3::X, Vector3::Y, Vector3::Z);The identity matrix: 1 on the diagonal, 0 elsewhere.
Matrix3::from_rows
Associated function · deformable::math::Matrix3::from_rows
pub const fn from_rows(
first: Vector3,
second: Vector3,
third: Vector3,
) -> SelfA matrix from its three rows.
Parameters
Matrix3::from_columns
Associated function · deformable::math::Matrix3::from_columns
pub fn from_columns(
first: Vector3,
second: Vector3,
third: Vector3,
) -> SelfA matrix from its three columns: the transpose of from_rows with the same vectors.
Parameters
Matrix3::outer_product
Associated function · deformable::math::Matrix3::outer_product
pub fn outer_product(a: Vector3, b: Vector3) -> SelfThe outer product of a and b, a taken as a column and b as a row: row i is b times component i of
a.
Parameters
a(Vector3)The column vector, whose component i scales row i.b(Vector3)The row vector that every row is a multiple of.
Matrix3::from_diagonal
Associated function · deformable::math::Matrix3::from_diagonal
pub fn from_diagonal(diagonal: Vector3) -> SelfThe diagonal matrix with diagonal on its diagonal and 0 elsewhere.
Parameters
diagonal(Vector3)The three diagonal entries, from the top left.
Matrix3::transpose
Method · deformable::math::Matrix3::transpose
pub fn transpose(&self) -> SelfThe transpose: row i becomes column i.
Matrix3::determinant
Method · deformable::math::Matrix3::determinant
pub fn determinant(&self) -> f64The determinant, expanded along the top row.
Matrix3::cofactor
Method · deformable::math::Matrix3::cofactor
pub fn cofactor(&self) -> SelfThe cofactor matrix: divided by the determinant, it is the transpose of the inverse.
Matrix3::diagonal
Method · deformable::math::Matrix3::diagonal
pub fn diagonal(&self) -> Vector3The three diagonal entries, from the top left.
Matrix3::transpose_multiply
Method · deformable::math::Matrix3::transpose_multiply
pub fn transpose_multiply(&self, vector: Vector3) -> Vector3The transpose of the matrix times vector, without forming the transpose: the rows added up, each times its
component of vector. It is vector taken as a row times the matrix, as
AffineTransform::apply maps a point.
Parameters
vector(Vector3)The vector to multiply.
Matrix3::is_finite
Method · deformable::math::Matrix3::is_finite
pub fn is_finite(&self) -> boolWhether every entry is finite: neither NaN nor infinite.
Matrix3::inverse
Method · deformable::math::Matrix3::inverse
pub fn inverse(&self) -> Option<Self>The inverse, from the cofactors, or None when the determinant is exactly 0.
The determinant it tests is summed as six products in the engine’s order, so it can round differently from
determinant: a nearly singular matrix whose determinant is 0 can still have an
inverse, or the other way round.
Matrix3::solve
Method · deformable::math::Matrix3::solve
pub fn solve(&self, right_hand_side: Vector3) -> Option<Vector3>The vector x for which the matrix times x is right_hand_side, by Gaussian elimination with partial pivoting.
Parameters
right_hand_side(Vector3)The vector the matrix times the solution must give.
Returns
Option<Vector3>: The solution, or None when a pivot is NaN or 1e-40 or less in magnitude: the matrix is singular, nearly
so, or holds a NaN. The last pivot may be exactly 1e-40.
AffineTransform
Struct · deformable::math::AffineTransform
pub struct AffineTransform {
pub linear: Matrix3,
pub translation: Vector3,
}An affine map of row vectors: a point p maps to p times linear, plus translation.
So row i of linear is where axis i goes. A matrix M that maps column vectors (M times p, as in most engines)
gives linear = M.transpose(), or Matrix3::from_columns with the rows of M.
SurfaceEmbedding::deform takes the world transform of the host’s
shape as one, and a MaterialRegion its map into the mesh’s object space.
Fields
linear(Matrix3)The linear part. A point is multiplied from the left as a row vector, so row i is where axis i goes.translation(Vector3)The translation added after the linear part.
Implements Clone · Copy · Debug · PartialEq · Send · Sync
Example
// Turns the x axis into the y axis, then moves 5 along z.
let turn = AffineTransform {
linear: Matrix3::from_rows(Vector3::Y, -Vector3::X, Vector3::Z),
translation: Vector3::new(0.0, 0.0, 5.0),
};
assert_eq!(turn.apply(Vector3::X), Vector3::new(0.0, 1.0, 5.0));See also Guide: Object space and the world transform · C DeformableAffineTransform · Python AffineTransform
AffineTransform::IDENTITY
Associated constant · deformable::math::AffineTransform::IDENTITY
pub const IDENTITY: AffineTransform = Self {
linear: Matrix3::IDENTITY,
translation: Vector3::ZERO,
};The map that leaves every point where it is: the identity matrix and no translation. Pass it to
SurfaceEmbedding::deform when the surface is already in world
space.
See also Python IDENTITY
AffineTransform::apply
Method · deformable::math::AffineTransform::apply
pub fn apply(&self, point: Vector3) -> Vector3Maps a point: point taken as a row vector times linear, plus translation.
Parameters
point(Vector3)The point to map.
AffineTransform::is_finite
Method · deformable::math::AffineTransform::is_finite
pub fn is_finite(&self) -> boolWhether every entry of the linear part and the translation is finite: neither NaN nor infinite.
BarycentricCoordinates
Struct · deformable::scene::BarycentricCoordinates
pub struct BarycentricCoordinates {
pub weights: [f64; 4],
}The barycentric weights of a point in a tetrahedron: one weight per corner.
The point is the sum of the corners, each times its weight. The weights are all 0 or more for a point inside the
tetrahedron, and some are negative for a point outside it.
SurfaceEmbedding::vertex_weights and
SurfaceEmbedding::normal_weights give them.
Fields
weights([f64; 4])One weight per corner, in corner order; they sum to 1.
Implements Clone · Copy · Debug · PartialEq · Send · Sync
Example
let corners = [Vector3::ZERO, Vector3::X, Vector3::Y, Vector3::Z];
// Equal weights give the centroid.
let centroid = BarycentricCoordinates::UNIFORM.interpolate(&corners);
assert_eq!(centroid, Vector3::new(0.25, 0.25, 0.25));BarycentricCoordinates::UNIFORM
Associated constant · deformable::scene::BarycentricCoordinates::UNIFORM
pub const UNIFORM: BarycentricCoordinates = Self { weights: [0.25; 4] };Equal weights, a quarter each: the centroid. The library falls back to them for a degenerate tetrahedron.
BarycentricCoordinates::from_shape_gradients
Associated function · deformable::scene::BarycentricCoordinates::from_shape_gradients
pub fn from_shape_gradients(
gradients: &[Vector3; 4],
offset: Vector3,
) -> SelfThe weights from the shape gradients of a tetrahedron and the offset of the point from its first corner.
The weight of corner k, for corners 1 to 3, is the dot product of gradient k and offset; the weight of
corner 0 is 1 minus the other three.
Parameters
gradients(&[Vector3; 4])The gradient of each corner’s weight with respect to the point, in corner order; the first is not read.offset(Vector3)The point minus the first corner of the tetrahedron.
BarycentricCoordinates::interpolate
Method · deformable::scene::BarycentricCoordinates::interpolate
pub fn interpolate(&self, corners: &[Vector3; 4]) -> Vector3The point with these weights: the sum of the corners, each times its weight.
Parameters
corners(&[Vector3; 4])The four corners of the tetrahedron, in the order of the weights.
Plane
Struct · deformable::scene::Plane
pub struct Plane {
pub normal: Vector3,
pub offset: f64,
}A bounding plane of a convex region: a point p is inside it when the dot product of normal and p, plus offset,
is 0 or less.
The normal points out of the region and can have any length: scaling the normal and the offset by one factor gives
the same plane. With a unit normal, minus offset is how far the plane lies from the origin along the normal. For
the plane through a point q, the offset is minus the dot product of the normal and q.
Fields
normal(Vector3)The outward normal, of any length.offset(f64)The offset, in the units of the points it bounds.
Implements Clone · Copy · Debug · PartialEq · Send · Sync
Example
// Keeps the points with y at most 0.1: the normal points out.
let plane = Plane { normal: Vector3::Y, offset: -0.1 };
let region = ConvexRegion { planes: vec![plane] };
assert!(region.contains(Vector3::new(3.0, -0.25, 0.0)));
assert!(!region.contains(Vector3::new(0.0, 0.5, 0.0)));See also Guide: Glue objects together · C DeformablePlane · Python Plane
ConvexRegion
Struct · deformable::scene::ConvexRegion
pub struct ConvexRegion {
pub planes: Vec<Plane>,
}A convex region: the points inside every one of its planes. With no plane it holds every point, as does the default region.
Scene::add_glue_region takes one, in world space and host units, to
choose the tetrahedrons it glues.
Fields
planes(Vec<Plane>)The bounding planes.
Implements Clone · Debug · Default · PartialEq · Send · Sync
Example
// The slab of points with x from 0 to 1.
let slab = ConvexRegion {
planes: vec![
Plane { normal: Vector3::X, offset: -1.0 },
Plane { normal: -Vector3::X, offset: 0.0 },
],
};
assert!(slab.contains(Vector3::new(0.5, 7.0, -2.0)));
assert!(!slab.contains(Vector3::new(1.5, 0.0, 0.0)));See also Guide: Glue objects together · C DeformableConvexRegion · Python ConvexRegion
ConvexRegion::contains
Method · deformable::scene::ConvexRegion::contains
pub fn contains(&self, point: Vector3) -> boolWhether point is inside every plane of the region: the dot product of the plane’s normal and point, plus
its offset, is 0 or less.
It is the test the library runs for glue regions; a host runs it for regions of its own, such as passive regions that hold the vertices inside them. Every point is inside a region with no plane; otherwise a NaN, in the point or in a plane, puts the point outside.
Parameters
point(Vector3)The point to test, in the units of the plane offsets.
See also Guide: Glue objects together · C deformable_convex_region_contains · Python ConvexRegion.contains