﻿---
title: Math
description: The points, vectors, transforms, planes and convex regions the other pages take and return.
url: https://help.tangerina.io/deformable/v0.8.0/api-references/python/math/
---

# Math – Python API Reference – Deformable v0.8.0

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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/types-and-errors/#points-vectors-and-transforms) · [C `DeformableVector2`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformablevector2) · [Rust `Vector2`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#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`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/#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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/types-and-errors/#points-vectors-and-transforms) · [C `DeformableVector3`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformablevector3) · [Rust `Vector3`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#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`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/#surfaceembedding-deform) takes the world transform of the host's shape as one, and a [`MaterialRegion`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/#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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/types-and-errors/#points-vectors-and-transforms) · [C `DeformableAffineTransform`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformableaffinetransform) · [Rust `AffineTransform`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#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`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/#surfaceembedding-deform) when the surface is already in world space.

**See also** [Guide: Points, vectors and transforms](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/types-and-errors/#points-vectors-and-transforms) · [Rust `AffineTransform::IDENTITY`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/scene/#glue) · [C `DeformablePlane`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformableplane) · [Rust `Plane`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#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`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/#scene-add_glue_region) takes one, in world space and host units, to choose the tetrahedrons it glues.

**Fields**

- `planes` ([`Sequence[Plane]`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/math/#plane)): The bounding planes, each a [`Plane`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/math/#plane) or a (normal, offset) pair.

**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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/scene/#glue) · [C `DeformableConvexRegion`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformableconvexregion) · [Rust `ConvexRegion`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/scene/#glue) · [C `deformable_convex_region_contains`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformable_convex_region_contains) · [Rust `ConvexRegion::contains`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/math/#convexregion-contains)
