Python 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.

Vector2

Named tuple · deformable.Vector2

python
class Vector2(NamedTuple):
    x: float
    y: float

A point or vector in the plane, such as the UV coordinates of a corner: two floats.

The package returns UV coordinates as Vector2; anywhere it takes a pair, a plain tuple or list of two numbers works too.

Fields

  • x (float)The first component; u for a UV coordinate pair.
  • y (float)The second component; v for a UV coordinate pair.

Example

python
# The UV coordinates of a corner, halfway along the top edge.
uv = deformable.Vector2(0.5, 1.0)
uv.x, uv.y
# (0.5, 1.0)

See also Guide: Points, vectors and transforms · C DeformableVector2 · Rust Vector2

Vector3

Named tuple · deformable.Vector3

python
class Vector3(NamedTuple):
    x: float
    y: float
    z: float

A point or vector in space: three floats.

The package returns points and vectors as Vector3, apart from the skinned output of SurfaceEmbedding.deform; anywhere it takes one, a plain tuple or list of three numbers works too.

Fields

  • x (float)The first component.
  • y (float)The second component.
  • z (float)The third component.

Example

python
# Gravity along -z, for a scene whose z axis points up.
gravity = deformable.Vector3(0.0, 0.0, -9.81)
scene.set_gravity(gravity)
# A plain tuple works too.
scene.set_gravity((0.0, 0.0, -9.81))

See also Guide: Points, vectors and transforms · C DeformableVector3 · Rust Vector3

AffineTransform

Named tuple · deformable.AffineTransform

python
class AffineTransform(NamedTuple):
    linear: Sequence[Sequence[float]]
    translation: Sequence[float] = (0.0, 0.0, 0.0)

An affine map of row vectors: a point p maps to p times linear, plus translation.

So linear[i] is where axis i goes. A matrix M that maps column vectors (M times p, as in Blender) gives linear[i][j] = M[j][i]. 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 (Sequence[Sequence[float]])The three rows of the linear part, three numbers each. A point is multiplied from the left as a row vector, so linear[i] is where axis i goes.
  • translation (Sequence[float])The translation added after the linear part. Default (0.0, 0.0, 0.0).

Example

python
# Turns the x axis into the y axis, then moves 5 along z.
turn = deformable.AffineTransform(
    ((0.0, 1.0, 0.0), (-1.0, 0.0, 0.0), (0.0, 0.0, 1.0)),
    (0.0, 0.0, 5.0),
)
point = (1.0, 0.0, 0.0)  # the x axis, as a row vector
mapped = [
    sum(
        coordinate * row[axis]
        for coordinate, row in zip(point, turn.linear)
    )
    + turn.translation[axis]
    for axis in range(3)
]
mapped
# [0.0, 1.0, 5.0]

See also Guide: Points, vectors and transforms · C DeformableAffineTransform · Rust AffineTransform

IDENTITY

Constant · deformable.IDENTITY

python
IDENTITY = AffineTransform(
    ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)),
)

The affine map that leaves every point where it is: the identity rows and no translation. Pass it to SurfaceEmbedding.deform when the surface is already in world space.

See also Guide: Points, vectors and transforms · Rust AffineTransform::IDENTITY

Plane

Named tuple · deformable.Plane

python
class Plane(NamedTuple):
    normal: Sequence[float]
    offset: float

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 (Sequence[float])The outward normal, of any length: three numbers.
  • offset (float)The offset, in the units of the points it bounds.

Example

python
# Keeps the points with y at most 0.1: the normal points out.
plane = deformable.Plane((0.0, 1.0, 0.0), -0.1)
region = deformable.ConvexRegion([plane])
region.contains((3.0, -0.25, 0.0)), region.contains((0.0, 0.5, 0.0))
# (True, False)

See also Guide: Glue · C DeformablePlane · Rust Plane

ConvexRegion

Data class · deformable.ConvexRegion

python
@dataclasses.dataclass(frozen=True)
class ConvexRegion:
    planes: Sequence[Plane]

A convex region: the points inside every one of its planes. With no plane it holds every point.

Scene.add_glue_region takes one, in world space and host units, to choose the tetrahedrons it glues.

Fields

Example

python
# The slab of points with x from 0 to 1.
slab = deformable.ConvexRegion([
    deformable.Plane((1.0, 0.0, 0.0), -1.0),
    ((-1.0, 0.0, 0.0), 0.0),  # a (normal, offset) pair works too
])
slab.contains((0.5, 7.0, -2.0)), slab.contains((1.5, 0.0, 0.0))
# (True, False)

See also Guide: Glue · C DeformableConvexRegion · Rust ConvexRegion

ConvexRegion.contains

Method · deformable.ConvexRegion.contains

python
def contains(self, point: Sequence[float]) -> 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 (Sequence[float])The point to test, in the units of the plane offsets: three numbers.

Raises

ValueError when point, or the normal of a plane, does not hold three numbers.

See also Guide: Glue · C deformable_convex_region_contains · Rust ConvexRegion::contains