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

On this page

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

rust
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

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

rust
pub const fn new(x: f64, y: f64) -> Self

A 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

rust
pub fn dot(self, other: Self) -> f64

The dot product: the sum of the products of matching components.

Parameters

  • other (Vector2)The second vector.

Vector2::cross

Method · deformable::math::Vector2::cross

rust
pub fn cross(self, other: Self) -> f64

The 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

rust
pub fn length_squared(self) -> f64

The squared Euclidean length: length without its square root.

Vector2::length

Method · deformable::math::Vector2::length

rust
pub fn length(self) -> f64

The Euclidean length.

Vector2::is_finite

Method · deformable::math::Vector2::is_finite

rust
pub fn is_finite(self) -> bool

Whether both components are finite: neither NaN nor infinite.

Vector3

Struct · deformable::math::Vector3

rust
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

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

rust
pub const ZERO: Vector3 = Self::new(0.0, 0.0, 0.0);

The zero vector.

Vector3::X

Associated constant · deformable::math::Vector3::X

rust
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

rust
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

rust
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

rust
pub const fn new(x: f64, y: f64, z: f64) -> Self

A 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

rust
pub fn dot(self, other: Self) -> f64

The dot product: the sum of the products of matching components.

Parameters

  • other (Vector3)The second vector.

Vector3::cross

Method · deformable::math::Vector3::cross

rust
pub fn cross(self, other: Self) -> Self

The 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

rust
pub fn length_squared(self) -> f64

The squared Euclidean length: length without its square root.

Vector3::length

Method · deformable::math::Vector3::length

rust
pub fn length(self) -> f64

The Euclidean length.

Vector3::is_finite

Method · deformable::math::Vector3::is_finite

rust
pub fn is_finite(self) -> bool

Whether every component is finite: neither NaN nor infinite.

Vector3::to_array

Method · deformable::math::Vector3::to_array

rust
pub fn to_array(self) -> [f64; 3]

The components as an array, [x, y, z].

Matrix3

Struct · deformable::math::Matrix3

rust
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

Implements Add · Clone · Copy · Debug · Default · Mul · Mul<f64> · Mul<Vector3> · PartialEq · Sub · Send · Sync

Example

rust
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

rust
pub const ZERO: Matrix3 =
    Self::from_rows(Vector3::ZERO, Vector3::ZERO, Vector3::ZERO);

The zero matrix.

Matrix3::IDENTITY

Associated constant · deformable::math::Matrix3::IDENTITY

rust
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

rust
pub const fn from_rows(
    first: Vector3,
    second: Vector3,
    third: Vector3,
) -> Self

A matrix from its three rows.

Parameters

Matrix3::from_columns

Associated function · deformable::math::Matrix3::from_columns

rust
pub fn from_columns(
    first: Vector3,
    second: Vector3,
    third: Vector3,
) -> Self

A 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

rust
pub fn outer_product(a: Vector3, b: Vector3) -> Self

The 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

rust
pub fn from_diagonal(diagonal: Vector3) -> Self

The 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

rust
pub fn transpose(&self) -> Self

The transpose: row i becomes column i.

Matrix3::determinant

Method · deformable::math::Matrix3::determinant

rust
pub fn determinant(&self) -> f64

The determinant, expanded along the top row.

Matrix3::cofactor

Method · deformable::math::Matrix3::cofactor

rust
pub fn cofactor(&self) -> Self

The cofactor matrix: divided by the determinant, it is the transpose of the inverse.

Matrix3::diagonal

Method · deformable::math::Matrix3::diagonal

rust
pub fn diagonal(&self) -> Vector3

The three diagonal entries, from the top left.

Matrix3::transpose_multiply

Method · deformable::math::Matrix3::transpose_multiply

rust
pub fn transpose_multiply(&self, vector: Vector3) -> Vector3

The 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

rust
pub fn is_finite(&self) -> bool

Whether every entry is finite: neither NaN nor infinite.

Matrix3::inverse

Method · deformable::math::Matrix3::inverse

rust
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

rust
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

rust
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

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

rust
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

rust
pub fn apply(&self, point: Vector3) -> Vector3

Maps a point: point taken as a row vector times linear, plus translation.

Parameters

AffineTransform::is_finite

Method · deformable::math::AffineTransform::is_finite

rust
pub fn is_finite(&self) -> bool

Whether every entry of the linear part and the translation is finite: neither NaN nor infinite.

BarycentricCoordinates

Struct · deformable::scene::BarycentricCoordinates

rust
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

rust
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

rust
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

rust
pub fn from_shape_gradients(
    gradients: &[Vector3; 4],
    offset: Vector3,
) -> Self

The 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

rust
pub fn interpolate(&self, corners: &[Vector3; 4]) -> Vector3

The 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

rust
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

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

rust
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

Implements Clone · Debug · Default · PartialEq · Send · Sync

Example

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

rust
pub fn contains(&self, point: Vector3) -> bool

Whether 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