You are viewing the documentation for Deformable v0.4.1, an older version. Read the latest, v0.9.0
Python 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.
Vector2
Named tuple · deformable.Vector2
class Vector2(NamedTuple):
x: float
y: floatA 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
# 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
class Vector3(NamedTuple):
x: float
y: float
z: floatA 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
# 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
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, solinear[i]is where axis i goes.translation(Sequence[float])The translation added after the linear part. Default(0.0, 0.0, 0.0).
Example
# 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
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
class Plane(NamedTuple):
normal: Sequence[float]
offset: floatA 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
# 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
@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
planes(Sequence[Plane])The bounding planes, each aPlaneor a (normal, offset) pair.
Example
# 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
def contains(self, point: Sequence[float]) -> 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(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