﻿---
title: Tools
description: Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.
url: https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/
---

# Tools – C API Reference – Deformable v0.8.0

The tools turn polygon meshes, triangle meshes and images into closed cages and tetrahedral meshes, the meshes a [`DeformableScene`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/scene/#deformablescene) takes. They keep no state between calls, so separate calls may run on different threads at the same time. Each runs on the calling thread, and the long ones take a [`DeformableCancelFlag`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablecancelflag) that another thread can set to stop them. Each tool comes right after the values it takes and returns.

## DeformableAnisotropy

**Struct** · `deformable.h`

```c
typedef struct DeformableAnisotropy {
    double scale;
    DeformableVector3 direction;
} DeformableAnisotropy;
```

A stretch of the mesher space by `scale` along `direction`, which [`deformable_triangulate`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulate) and
[`deformable_tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralize) take two of: the elements they make come out about `scale` times longer along `direction`.

The stretch is `S = I + (scale - 1) n n^T`, with `n` the unit direction, after the clamps the fields give.
[`deformable_anisotropy_default`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_anisotropy_default) writes scale 1 along (1, 1, 1): no stretch. Pass the same pair to both tools. They
differ on values out of range: `deformable_triangulate` refuses a NaN or infinite scale or component, while
`deformable_tetrahedralize` refuses only NaN and clamps an infinite one.

**Fields**

- `scale` (`double`): The stretch factor along `direction`: above 1 makes longer elements, below 1 shorter ones.
  Default `1`, clamped to `[0.02, 50]`.
- `direction` ([`DeformableVector3`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformablevector3)): The stretch direction, of any length; a zero direction makes the scale count as 1.
  Default `(1, 1, 1)`, each component clamped to `[-100, 100]`.

**Example**

```c
DeformableTetrahedralizeParameters parameters = {0};
parameters.maximum_edge_length = 0.3;
// Tetrahedrons about three times longer along y.
parameters.anisotropy[0] = (DeformableAnisotropy){3.0, {0, 1, 0}};
DeformableTetrahedralization *result = NULL;
CHECK(deformable_tetrahedralize(&cage, &parameters, NULL, &result));
deformable_tetrahedralization_destroy(result);
```

**See also** [Guide: Stretch the elements](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#stretch-the-elements) · [Rust `Anisotropy`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#anisotropy) · [Python `Anisotropy`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#anisotropy)

### deformable_anisotropy_default

**Function** · `deformable.h`

```c
DeformableStatus deformable_anisotropy_default(
    DeformableAnisotropy *anisotropy);
```

Writes the anisotropy defaults to `anisotropy`: scale 1 along (1, 1, 1), no stretch.

**Parameters**

- `anisotropy` ([`DeformableAnisotropy *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableanisotropy)): Out. Receives the defaults.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/#conventions) describe.

**See also** [Python `Anisotropy.default`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#anisotropy-default)

## DeformableDensityRegion

**Struct** · `deformable.h`

```c
typedef struct DeformableDensityRegion {
    const DeformableVector3 *points;
    size_t point_count;
    double scale;
} DeformableDensityRegion;
```

A convex region of the cage meshed finer (scale above 1) or coarser (scale below 1) than the rest, one of the density
regions of [`DeformableTetrahedralizeParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletetrahedralizeparameters).

Regions whose hulls meet form one group, meshed at the size of its largest scale: the tetrahedrons that meet a region
of the group are carved out, and the hole is meshed again at that size. Where the hole reaches the cage, the cage
faces it reaches are triangulated again at that size too: the mesh boundary there gets new points and smaller
triangles, and the cage vertices keep their positions. A group whose largest scale is 1 changes nothing. A region
that cannot be used is skipped, not an error, and the tetrahedralization lists it.

**Fields**

- `points` ([`const DeformableVector3 *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformablevector3)): `point_count` points, in the cage's space; the region is their convex hull. Fewer than 4 points, or a NaN or
  infinite one, skip the region.
- `point_count` (`size_t`): The number of points.
- `scale` (`double`): The density factor: inside the region the tetrahedron size is the maximum edge length over the cube root of the
  scale, so 8 halves it. A scale of 0 or less counts as 1; a NaN scale skips the region.

**Example**

```c
DeformableVector3 corner[] = {{0}, {1, 0, 0}, {0, 1, 0}, {0, 0, 1}};
DeformableDensityRegion finer = {corner, 4, 8.0};
DeformableTetrahedralizeParameters parameters = {
    .maximum_edge_length = 0.3, .density_regions = &finer,
    .density_region_count = 1}; // a zero anisotropy stretches nothing
DeformableTetrahedralization *result = NULL;
CHECK(deformable_tetrahedralize(&cage, &parameters, NULL, &result));
deformable_tetrahedralization_destroy(result);
```

**See also** [Guide: Fill a cage with tetrahedrons](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#fill-a-cage-with-tetrahedrons) · [Rust `DensityRegion`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#densityregion) · [Python `DensityRegion`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#densityregion)

## DeformableTetrahedralizeParameters

**Struct** · `deformable.h`

```c
typedef struct DeformableTetrahedralizeParameters {
    double maximum_edge_length;
    DeformableAnisotropy anisotropy[2];
    const DeformableDensityRegion *density_regions;
    size_t density_region_count;
} DeformableTetrahedralizeParameters;
```

The settings of [`deformable_tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralize): the size limit, the two stretches of the mesher space and the density
regions. It has no `_default` function: the size limit is always the caller's choice. A zeroed struct stretches
nothing and has no density regions, since a zero anisotropy direction makes its scale count as 1.

**Fields**

- `maximum_edge_length` (`double`): The cap on the tetrahedron size inside the volume, in the cage's unit, measured in the stretched mesher space;
  near the cage the size follows the cage triangles. 0 or less gives [`DEFORMABLE_STATUS_MESHING_FAILED`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_meshing_failed); NaN or
  infinite meshes the cage with no size limit.
- `anisotropy` ([`DeformableAnisotropy[2]`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableanisotropy)): The two stretches of the mesher space, each clamped as [`DeformableAnisotropy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableanisotropy) says; two from
  [`deformable_anisotropy_default`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_anisotropy_default) stretch nothing.
- `density_regions` ([`const DeformableDensityRegion *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabledensityregion)): `density_region_count` regions meshed finer or coarser than the rest; may be `NULL` when there are none.
- `density_region_count` (`size_t`): The number of density regions.

**Example**

```c
// Tetrahedrons of at most 0.25 inside the cube, with no stretch.
DeformableTetrahedralizeParameters parameters = {0};
parameters.maximum_edge_length = 0.25;
DeformableTetrahedralization *fine = NULL;
CHECK(deformable_tetrahedralize(&cage, &parameters, NULL, &fine));
deformable_tetrahedralization_destroy(fine);
```

**See also** [Guide: Fill a cage with tetrahedrons](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#fill-a-cage-with-tetrahedrons) · [Rust `TetrahedralizeParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#tetrahedralizeparameters) · [Python `TetrahedralizeParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#tetrahedralizeparameters)

## DeformableTetrahedralization

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableTetrahedralization
    DeformableTetrahedralization;
```

The result of [`deformable_tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralize): the mesh, and the density regions the call skipped. Read it with
[`deformable_tetrahedralization_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralization_view) and free it with [`deformable_tetrahedralization_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralization_destroy).

**See also** [Guide: Fill a cage with tetrahedrons](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#fill-a-cage-with-tetrahedrons) · [Rust `Tetrahedralization`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#tetrahedralization) · [Python `Tetrahedralization`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#tetrahedralization)

### deformable_tetrahedralization_view

**Function** · `deformable.h`

```c
DeformableStatus deformable_tetrahedralization_view(
    const DeformableTetrahedralization *tetrahedralization,
    DeformableTetrahedralizationView *view);
```

Lends the arrays of a tetrahedralization: the mesh, and the indices of the density regions the call skipped.

**Parameters**

- `tetrahedralization` ([`const DeformableTetrahedralization *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletetrahedralization)): The tetrahedralization to read.
- `view` ([`DeformableTetrahedralizationView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletetrahedralizationview)): Out. Receives the arrays, owned by `tetrahedralization` and valid until it is destroyed.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/#conventions) describe.

### deformable_tetrahedralization_destroy

**Function** · `deformable.h`

```c
void deformable_tetrahedralization_destroy(
    DeformableTetrahedralization *tetrahedralization);
```

Destroys a tetrahedralization; `NULL` is ignored. Views of it become invalid.

**Parameters**

- `tetrahedralization` ([`DeformableTetrahedralization *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletetrahedralization)): The tetrahedralization to destroy, or `NULL`.

## DeformableTetrahedralizationView

**Struct** · `deformable.h`

```c
typedef struct DeformableTetrahedralizationView {
    DeformableTetrahedralMeshView mesh;
    const size_t *skipped_density_regions;
    size_t skipped_density_region_count;
} DeformableTetrahedralizationView;
```

The arrays of a tetrahedralization, owned by it and valid until it is destroyed.

**Fields**

- `mesh` ([`DeformableTetrahedralMeshView`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletetrahedralmeshview)): The tetrahedral mesh: every tetrahedron positively oriented, the cage vertices at their input positions, and
  every node in a tetrahedron.
- `skipped_density_regions` (`const size_t *`): `skipped_density_region_count` indices of the density regions the call skipped, in ascending order: those with
  fewer than 4 points, a NaN or infinite point, or a NaN scale.
- `skipped_density_region_count` (`size_t`): The number of skipped density regions.

**See also** [Rust `Tetrahedralization`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#tetrahedralization) · [Python `Tetrahedralization`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#tetrahedralization)

## deformable_tetrahedralize

**Function** · `deformable.h`

```c
DeformableStatus deformable_tetrahedralize(
    const DeformableTriangleMeshView *cage,
    const DeformableTetrahedralizeParameters *parameters,
    const DeformableCancelFlag *cancel,
    DeformableTetrahedralization **tetrahedralization);
```

Fills a closed triangle cage with tetrahedrons, on the calling thread. The cage triangles become the boundary of the
mesh, except where a density region reaches the cage: there the cage faces are triangulated again at the region's
size, with new boundary points. The cage vertices keep their positions, and a vertex no triangle uses is dropped.
Every tetrahedron is positively oriented, as [`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/scene/#deformable_scene_add_object) requires, and every node belongs to a
tetrahedron.

**Parameters**

- `cage` ([`const DeformableTriangleMeshView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletrianglemeshview)): A closed cage with outward normals and no self-intersections.
- `parameters` ([`const DeformableTetrahedralizeParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletetrahedralizeparameters)): The size limit, the two stretches and the density regions.
- `cancel` ([`const DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablecancelflag)): Stops the call when another thread sets it. May be `NULL`.
- `tetrahedralization` ([`DeformableTetrahedralization **`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletetrahedralization)): Out. Receives a new handle; free it with [`deformable_tetrahedralization_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralization_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `tetrahedralization`: read the mesh, and the indices of the density regions the call skipped, with [`deformable_tetrahedralization_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralization_view). A density region that cannot be used is skipped, not an error.

**Errors**

- [`DEFORMABLE_STATUS_INVALID_CAGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_invalid_cage): The cage has no triangle, a NaN or infinite position, or a triangle with a corner past the positions or a repeated corner; or it is not closed and consistently outward, or it crosses itself.
- [`DEFORMABLE_STATUS_MESHING_FAILED`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_meshing_failed): `maximum_edge_length` is 0 or less, or the mesher stopped without a mesh.
- [`DEFORMABLE_STATUS_NO_TETRAHEDRONS`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_no_tetrahedrons): The mesh has no tetrahedron.
- [`DEFORMABLE_STATUS_BAD_SCALES`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_bad_scales): An anisotropy scale or direction component is NaN; an infinite one is clamped.
- [`DEFORMABLE_STATUS_OUTPUT_TOO_LARGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_output_too_large): At `maximum_edge_length`, the cage would hold more regular tetrahedrons than 32-bit indices address, or so would the part a group of density regions carves out, at the group's size, or the cage faces that part reaches would hold more triangles. These are estimates, checked before the run they limit for a mesh that reaches the size everywhere, so a cage much coarser than the size is refused too. The nodes the groups add are counted as they are added, and may not pass that limit either.
- [`DEFORMABLE_STATUS_CANCELLED`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_cancelled): Another thread set `cancel`.

**Example**

```c
DeformableTetrahedralizeParameters parameters = {0};
parameters.maximum_edge_length = 0.3;
DeformableTetrahedralization *result = NULL;
CHECK(deformable_tetrahedralize(&cage, &parameters, NULL, &result));
deformable_tetrahedralization_destroy(result);
```

**See also** [Guide: Fill a cage with tetrahedrons](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#fill-a-cage-with-tetrahedrons) · [Rust `tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#tetrahedralize) · [Python `tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#tetrahedralize)

## DeformableTriangulateParameters

**Struct** · `deformable.h`

```c
typedef struct DeformableTriangulateParameters {
    double maximum_area;
    double quality;
    DeformableAnisotropy anisotropy[2];
    uint8_t closed_boundary;
} DeformableTriangulateParameters;
```

The settings of [`deformable_triangulate`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulate): the area limit, the minimum angle, the two stretches of the mesher space and
the closed boundary check. [`deformable_triangulate_parameters_default`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulate_parameters_default) writes area 1, a minimum angle of 20 degrees, no
stretch and the closed boundary check on.

**Fields**

- `maximum_area` (`double`): The largest triangle area, measured in the stretched mesher space; 0 or less sets no limit.
  Default `1`.
- `quality` (`double`): The minimum triangle angle, in degrees: 0 or less runs as 2, and the rest is clamped to `[1, 20]`.
  Default `20`.
- `anisotropy` ([`DeformableAnisotropy[2]`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableanisotropy)): The two stretches of the mesher space, each clamped as [`DeformableAnisotropy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableanisotropy) says.
  Default: each as [`deformable_anisotropy_default`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_anisotropy_default) writes it, no stretch.
- `closed_boundary` (`uint8_t`): Not 0: refuses an edge that borders only one polygon, with [`DEFORMABLE_STATUS_NON_CLOSED_BOUNDARY`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_closed_boundary); 0 for a
  non-closed mesh. Default `1`.

**Example**

```c
DeformableTriangulateParameters parameters;
CHECK(deformable_triangulate_parameters_default(&parameters));
parameters.maximum_area = 0.05;
parameters.quality = 15.0;
DeformableTriangulation *fine = NULL;
CHECK(deformable_triangulate(&polygons, NULL, 0, &parameters, NULL,
                             &fine));
deformable_triangulation_destroy(fine);
```

**See also** [Guide: Triangulate a polygon mesh](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#triangulate-a-polygon-mesh) · [Rust `TriangulateParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#triangulateparameters) · [Python `TriangulateParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#triangulateparameters)

### deformable_triangulate_parameters_default

**Function** · `deformable.h`

```c
DeformableStatus deformable_triangulate_parameters_default(
    DeformableTriangulateParameters *parameters);
```

Writes the triangulate defaults to `parameters`: area 1, a minimum angle of 20 degrees, no stretch and the closed
boundary check on.

**Parameters**

- `parameters` ([`DeformableTriangulateParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletriangulateparameters)): Out. Receives the defaults.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/#conventions) describe.

**See also** [Python `TriangulateParameters.default`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#triangulateparameters-default)

## DeformableTriangulation

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableTriangulation DeformableTriangulation;
```

The result of [`deformable_triangulate`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulate): the triangle mesh, and the input polygon of each triangle. Read it with
[`deformable_triangulation_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulation_view) and free it with [`deformable_triangulation_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulation_destroy).

**See also** [Guide: Triangulate a polygon mesh](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#triangulate-a-polygon-mesh) · [Rust `Triangulation`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#triangulation) · [Python `Triangulation`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#triangulation)

### deformable_triangulation_view

**Function** · `deformable.h`

```c
DeformableStatus deformable_triangulation_view(
    const DeformableTriangulation *triangulation,
    DeformableTriangulationView *view);
```

Lends the arrays of a triangulation of a polygon mesh: the triangle mesh, and the input polygon of each triangle.

**Parameters**

- `triangulation` ([`const DeformableTriangulation *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletriangulation)): The triangulation to read.
- `view` ([`DeformableTriangulationView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletriangulationview)): Out. Receives the arrays, owned by `triangulation` and valid until it is destroyed.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/#conventions) describe.

### deformable_triangulation_destroy

**Function** · `deformable.h`

```c
void deformable_triangulation_destroy(
    DeformableTriangulation *triangulation);
```

Destroys a triangulation of a polygon mesh; `NULL` is ignored. Views of it become invalid.

**Parameters**

- `triangulation` ([`DeformableTriangulation *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletriangulation)): The triangulation to destroy, or `NULL`.

## DeformableTriangulationView

**Struct** · `deformable.h`

```c
typedef struct DeformableTriangulationView {
    DeformableTriangleMeshView mesh;
    const uint32_t *source_polygons;
    size_t source_polygon_count;
} DeformableTriangulationView;
```

The arrays of a triangulation of a polygon mesh, owned by it and valid until it is destroyed.

**Fields**

- `mesh` ([`DeformableTriangleMeshView`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletrianglemeshview)): The points, in order of first appearance with unused input vertices dropped, and the triangles. Triangles
  come grouped by polygon in input order, and each follows its polygon's winding.
- `source_polygons` (`const uint32_t *`): `source_polygon_count` polygon indices, one per triangle: the input polygon each triangle was made from, so
  per-polygon data such as materials can carry over to the triangles.
- `source_polygon_count` (`size_t`): The number of triangles.

**See also** [Rust `Triangulation`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#triangulation) · [Python `Triangulation`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#triangulation)

## deformable_triangulate

**Function** · `deformable.h`

```c
DeformableStatus deformable_triangulate(
    const DeformablePolygonMeshView *cage,
    const DeformableFaceHole *holes,
    size_t hole_count,
    const DeformableTriangulateParameters *parameters,
    const DeformableCancelFlag *cancel,
    DeformableTriangulation **triangulation);
```

Re-triangulates each polygon of a polygon mesh, holes included, under an area limit and a minimum angle, on the
calling thread.

Each polygon is triangulated in its own plane, in the stretched mesher space. Where two polygons share an edge, the
points added on it are shared too, so a closed mesh stays closed; the inner points of a non-planar polygon get a
height interpolated from its boundary. Triangles follow the winding of their polygon. When the polygons cannot
reach the minimum angle, the call retries at 0.9 times the angle while it stays at least 1 degree.

**Parameters**

- `cage` ([`const DeformablePolygonMeshView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformablepolygonmeshview)): The polygons: their positions, and the corners of each one, its hole runs included.
- `holes` ([`const DeformableFaceHole *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformablefacehole)): `hole_count` runs of polygon corners that form hole loops. May be `NULL` when `hole_count` is 0.
- `hole_count` (`size_t`): The number of `holes`; 0 when no polygon has a hole.
- `parameters` ([`const DeformableTriangulateParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletriangulateparameters)): The area limit, the minimum angle, the two stretches and the closed boundary check.
- `cancel` ([`const DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablecancelflag)): Stops the call when another thread sets it. May be `NULL`.
- `triangulation` ([`DeformableTriangulation **`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformabletriangulation)): Out. Receives a new handle; free it with [`deformable_triangulation_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulation_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `triangulation`: read the triangle mesh, and the input polygon of each triangle, with [`deformable_triangulation_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_triangulation_view).

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A position of `cage`, the area limit, the minimum angle, or an anisotropy scale or direction component is NaN or infinite.
- [`DEFORMABLE_STATUS_EMPTY_MESH`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_empty_mesh): `cage` has no vertices or no polygons.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): A corner names a vertex past the positions, a polygon's corners or a hole run go past the end of their list, a hole names a polygon past the last, or corners are left over after the last polygon. The first index of the last error names the polygon, or the polygon count for corners left over.
- [`DEFORMABLE_STATUS_DEGENERATE_POLYGON`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_degenerate_polygon): A polygon has a loop of fewer than 3 vertices or a zero normal, no outer loop, or an edge it uses twice, or the triangulator cannot mesh its loops, as when they cross in its plane. The first index of the last error names the polygon.
- [`DEFORMABLE_STATUS_NON_MANIFOLD_EDGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_manifold_edge): An edge borders three or more polygons. The two indices of the last error name its vertices.
- [`DEFORMABLE_STATUS_NON_CLOSED_BOUNDARY`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_closed_boundary): `closed_boundary` is not 0 and an edge borders only one polygon. The two indices of the last error name its vertices.
- [`DEFORMABLE_STATUS_OUTPUT_TOO_LARGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_output_too_large): The polygons' area, in the stretched mesher space, would hold more triangles of the area limit than 32-bit indices address. It is checked before triangulating.
- [`DEFORMABLE_STATUS_COULD_NOT_CONVERGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_could_not_converge): The polygons did not settle at any minimum angle down to 1 degree.
- [`DEFORMABLE_STATUS_CANCELLED`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_cancelled): Another thread set `cancel`.

**Example**

```c
DeformableTriangulateParameters parameters;
CHECK(deformable_triangulate_parameters_default(&parameters));
DeformableTriangulation *result = NULL;
CHECK(deformable_triangulate(&polygons, NULL, 0, &parameters, NULL,
                             &result));
DeformableTriangulationView view;
CHECK(deformable_triangulation_view(result, &view));
deformable_triangulation_destroy(result);
```

**See also** [Guide: Triangulate a polygon mesh](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#triangulate-a-polygon-mesh) · [Rust `triangulate`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#triangulate) · [Python `triangulate`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#triangulate)

## DeformableExtrudeDirection

**Enum** · `deformable.h`

```c
typedef int32_t DeformableExtrudeDirection;
```

Where [`deformable_extrude`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_extrude) puts the two layers of its shell, along each vertex's unit normal. The normal points to the
side from which the faces' corners run counter-clockwise.

**Values**

- `DEFORMABLE_EXTRUDE_DIRECTION_UP` (`0`): The mesh, and a copy `thickness` along the normal.
- `DEFORMABLE_EXTRUDE_DIRECTION_DOWN` (`1`): The mesh, and a copy `thickness` against the normal.
- `DEFORMABLE_EXTRUDE_DIRECTION_BOTH` (`2`): Two copies, half of `thickness` on each side of the mesh.

**See also** [Guide: Make a thin shell](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#make-a-thin-shell) · [Rust `ExtrudeDirection`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#extrudedirection) · [Python `ExtrudeDirection`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#extrudedirection)

## deformable_extrude

**Function** · `deformable.h`

```c
DeformableStatus deformable_extrude(
    const DeformableTriangleMeshView *triangle_mesh,
    double thickness,
    DeformableExtrudeDirection direction,
    DeformableTetrahedralMesh **mesh);
```

Turns a triangle mesh into a shell `thickness` thick, on the calling thread: each vertex moves along its unit
angle-weighted normal, which gives 2 points per vertex and 3 tetrahedrons per triangle, with no added points.

The triangle mesh can be non-closed, for sheets, plates and other thin objects. A face wound against its neighbours
counts with its normal flipped. A vertex on no face keeps both of its points at its position and is in no
tetrahedron. A triangle mesh with no vertices or no triangles gives an empty tetrahedral mesh.

Nothing checks the tetrahedrons: they come out positively oriented, but on sharp curvature a thick shell can invert
some, and [`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/scene/#deformable_scene_add_object) then refuses the mesh. Use a thinner shell or a smoother mesh there.
Nor are the positions checked: a NaN or infinite position, or an infinite `thickness`, gives NaN or infinite points.

**Parameters**

- `triangle_mesh` ([`const DeformableTriangleMeshView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletrianglemeshview)): The triangle mesh to thicken, open or closed.
- `thickness` (`double`): The shell's thickness, in the mesh's unit; it must be above 0.
- `direction` ([`DeformableExtrudeDirection`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableextrudedirection)): Where the two layers go: on the normal side, on the other side, or half on each.
- `mesh` ([`DeformableTetrahedralMesh **`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletetrahedralmesh)): Out. Receives a new handle; free it with [`deformable_tetrahedral_mesh_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_tetrahedral_mesh_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `mesh`: read the shell with [`deformable_tetrahedral_mesh_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_tetrahedral_mesh_view). Its points are those of the layer on the normal side, one per vertex, then those of the other layer, and it has 3 tetrahedrons per triangle, in triangle order.

**Errors**

- [`DEFORMABLE_STATUS_NON_POSITIVE_THICKNESS`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_positive_thickness): `thickness` is 0 or less, or NaN, even for an empty mesh.
- [`DEFORMABLE_STATUS_UNKNOWN_VERTEX`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_unknown_vertex): A triangle names a vertex past the end of the positions. The first index of the last error names the triangle.
- [`DEFORMABLE_STATUS_DUPLICATE_VERTEX`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_duplicate_vertex): A triangle uses one vertex at two corners. The first index of the last error names the triangle.
- [`DEFORMABLE_STATUS_DEGENERATE_FACE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_degenerate_face): A triangle has a zero normal: its corners lie on one line. The first index of the last error names the triangle.
- [`DEFORMABLE_STATUS_MULTIPLE_BOUNDARIES`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_multiple_boundaries): The triangles around a vertex form more than one fan, as where two parts of the mesh touch at that vertex only. The first index of the last error names the vertex.
- [`DEFORMABLE_STATUS_NULL_NORMAL`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_null_normal): The angle-weighted normals of the triangles around a vertex cancel out. The first index of the last error names the vertex.

**Example**

```c
// A hollow cube: walls 0.1 thick, centred on the cage's faces.
DeformableTetrahedralMesh *shell = NULL;
DeformableExtrudeDirection both = DEFORMABLE_EXTRUDE_DIRECTION_BOTH;
CHECK(deformable_extrude(&cage, 0.1, both, &shell));
DeformableTetrahedralMeshView view;
CHECK(deformable_tetrahedral_mesh_view(shell, &view));
printf("%zu tetrahedrons\n", view.tetrahedron_count); // 36
deformable_tetrahedral_mesh_destroy(shell);
```

**See also** [Guide: Make a thin shell](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#make-a-thin-shell) · [Rust `extrude`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#extrude) · [Python `extrude`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#extrude)

## deformable_span_layers

**Function** · `deformable.h`

```c
DeformableStatus deformable_span_layers(
    const DeformableTriangleMeshView *first_layer,
    const DeformableTriangleMeshView *second_layer,
    DeformableTetrahedralMesh **mesh);
```

Fills the space between two triangle meshes with the same vertices and faces, such as a mesh and a moved copy
of it, on the calling thread: each triangle and its partner make a prism of 3 tetrahedrons.

Only the first layer's triangles are used; each must match exactly one triangle of the second layer, with the same
vertices and winding, up to a rotation of its corners. The tetrahedrons come out positively oriented whichever
layer is on top. Layers that touch give flat tetrahedrons, which are kept, and which
[`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/scene/#deformable_scene_add_object) then refuses. Layers with no vertices or no triangles give an empty mesh. The
positions are not checked: a NaN or infinite one passes into the mesh.

**Parameters**

- `first_layer` ([`const DeformableTriangleMeshView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletrianglemeshview)): One side of the space, whose triangles the tetrahedrons follow.
- `second_layer` ([`const DeformableTriangleMeshView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletrianglemeshview)): The other side: the same number of vertices, and the same triangles up to a rotation of each one's corners.
- `mesh` ([`DeformableTetrahedralMesh **`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletetrahedralmesh)): Out. Receives a new handle; free it with [`deformable_tetrahedral_mesh_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_tetrahedral_mesh_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `mesh`: read the mesh with [`deformable_tetrahedral_mesh_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_tetrahedral_mesh_view). Its points are the first layer's positions, then the second layer's, and it has 3 tetrahedrons per triangle, in triangle order.

**Errors**

- [`DEFORMABLE_STATUS_NOT_ISOMORPHIC`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_not_isomorphic): The layers differ in vertex or triangle count, or a triangle of the first layer does not match exactly one triangle of the second.
- [`DEFORMABLE_STATUS_UNKNOWN_VERTEX`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_unknown_vertex): A triangle names a vertex past the end of the positions. The first index of the last error names the triangle.
- [`DEFORMABLE_STATUS_DUPLICATE_VERTEX`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_duplicate_vertex): A triangle uses one vertex at two corners. The first index of the last error names the triangle.
- [`DEFORMABLE_STATUS_MULTIPLE_BOUNDARIES`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_multiple_boundaries): The triangles around a vertex form more than one fan, as where two parts of the mesh touch at that vertex only. The first index of the last error names the vertex.

**Example**

```c
// A hollow box: the cage, and a copy three times its size around it.
const DeformableVector3 corners[8] = {
    {-1, -1, -1}, {2, -1, -1}, {-1, 2, -1}, {2, 2, -1},
    {-1, -1, 2}, {2, -1, 2}, {-1, 2, 2}, {2, 2, 2}};
DeformableTriangleMeshView outer = {corners, 8, cage.triangles, 12};
DeformableTetrahedralMesh *walls = NULL;
CHECK(deformable_span_layers(&cage, &outer, &walls));
deformable_tetrahedral_mesh_destroy(walls);
```

**See also** [Guide: Fill the space between two layers](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#fill-the-space-between-two-layers) · [Rust `span_layers`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#span_layers) · [Python `span_layers`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#span_layers)

## DeformableAutocageParameters

**Struct** · `deformable.h`

```c
typedef struct DeformableAutocageParameters {
    double scale_gap;
    int32_t target_face_count;
    int32_t target_tetrahedron_count;
} DeformableAutocageParameters;
```

The settings of [`deformable_autocage`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_autocage): the gap between the cage and the mesh, and the size of the cage's triangles,
set by a face target or else a tetrahedron target. [`deformable_autocage_parameters_default`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_autocage_parameters_default) writes scale gap 1, a
target of 300 faces and no tetrahedron target.

The counts are targets, not exact results. With neither target, the triangles are sized from the mesh's bounding
box alone.

**Fields**

- `scale_gap` (`double`): Multiplies the gap the cage keeps from the mesh, which follows the size of the cage's triangles; NaN or
  infinite gives [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value). Default `1.0`, clamped to `[0.1, 10]`.
- `target_face_count` (`int32_t`): The number of triangles the cage aims for; 0 or less leaves the size to `target_tetrahedron_count`. Default
  `300`.
- `target_tetrahedron_count` (`int32_t`): When there is no face target, the number of tetrahedrons the cage's volume aims for, which sizes its
  triangles; 0 or less sets none. Default `0`.

**Example**

```c
// A coarser cage than the default, kept twice as far out.
DeformableAutocageParameters parameters;
CHECK(deformable_autocage_parameters_default(&parameters));
parameters.scale_gap = 2.0;
parameters.target_face_count = 100;
DeformableTriangleMesh *wrapped = NULL;
CHECK(deformable_autocage(&polygons, &parameters, NULL, &wrapped));
deformable_triangle_mesh_destroy(wrapped);
```

**See also** [Guide: Build a cage around any mesh](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#build-a-cage-around-any-mesh) · [Rust `AutocageParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#autocageparameters) · [Python `AutocageParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#autocageparameters)

### deformable_autocage_parameters_default

**Function** · `deformable.h`

```c
DeformableStatus deformable_autocage_parameters_default(
    DeformableAutocageParameters *parameters);
```

Writes the autocage defaults to `parameters`: scale gap 1, a target of 300 faces and no tetrahedron target.

**Parameters**

- `parameters` ([`DeformableAutocageParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableautocageparameters)): Out. Receives the defaults.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/#conventions) describe.

**See also** [Python `AutocageParameters.default`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#autocageparameters-default)

## deformable_autocage

**Function** · `deformable.h`

```c
DeformableStatus deformable_autocage(
    const DeformablePolygonMeshView *mesh,
    const DeformableAutocageParameters *parameters,
    const DeformableCancelFlag *cancel,
    DeformableTriangleMesh **cage);
```

Wraps any polygon mesh, open or closed, in a closed, outward cage of near-equilateral triangles at a small gap
outside it, on the calling thread, for [`deformable_tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_tetrahedralize) to fill. It makes no tetrahedrons itself.

The cage grows as a front of triangles around the mesh. A front that fails starts again with a target triangle area
one percent larger each time, up to 7 times. The face and tetrahedron counts of `parameters` are targets, not exact
results.

**Parameters**

- `mesh` ([`const DeformablePolygonMeshView *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformablepolygonmeshview)): The polygon mesh to wrap, open or closed.
- `parameters` ([`const DeformableAutocageParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformableautocageparameters)): The gap, and the face or tetrahedron target that sizes the cage's triangles.
- `cancel` ([`const DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablecancelflag)): Stops the call when another thread sets it. May be `NULL`.
- `cage` ([`DeformableTriangleMesh **`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformabletrianglemesh)): Out. Receives a new handle; free it with [`deformable_triangle_mesh_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_triangle_mesh_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `cage`: read the cage, a closed triangle mesh with outward normals around `mesh`, ready for `deformable_tetrahedralize`, with [`deformable_triangle_mesh_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_triangle_mesh_view).

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): `scale_gap` or a position of `mesh` is NaN or infinite, or the mesh is so large that its size overflows.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): A polygon's corners run past the end of the corner list or name a vertex past the positions, or corners are left over after the last polygon. The first index of the last error names the polygon, or the polygon count for corners left over.
- [`DEFORMABLE_STATUS_EMPTY_INPUT`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_empty_input): No polygon has 3 or more corners, or all the vertices the polygons use coincide.
- [`DEFORMABLE_STATUS_OUTPUT_TOO_LARGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_output_too_large): The targets ask for triangles with an edge under `4.28e-3` times half the largest side of the mesh's bounding box, finer than the tool resolves. It is checked before the cage grows.
- [`DEFORMABLE_STATUS_STEP_LIMIT_REACHED`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_step_limit_reached): The cage did not close within its step limit, 1,000 steps per expected triangle and at least 100,000, restarts included.
- [`DEFORMABLE_STATUS_CANCELLED`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_cancelled): Another thread set `cancel`.

**Example**

```c
DeformableAutocageParameters parameters;
CHECK(deformable_autocage_parameters_default(&parameters));
DeformableTriangleMesh *wrapped = NULL;
CHECK(deformable_autocage(&polygons, &parameters, NULL, &wrapped));
DeformableTriangleMeshView wrapped_cage;
CHECK(deformable_triangle_mesh_view(wrapped, &wrapped_cage));
// Fill wrapped_cage with deformable_tetrahedralize, then:
deformable_triangle_mesh_destroy(wrapped);
```

**See also** [Guide: Build a cage around any mesh](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#build-a-cage-around-any-mesh) · [Rust `autocage`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#autocage) · [Python `autocage`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#autocage)

## DeformablePixelGrid

**Struct** · `deformable.h`

```c
typedef struct DeformablePixelGrid {
    uint32_t width;
    uint32_t height;
    const uint8_t (*pixels)[3];
    size_t pixel_count;
} DeformablePixelGrid;
```

An image decoded by the host, for [`deformable_splinters_from_image`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_splinters_from_image): 8-bit red, green and blue pixels, row 0 at the
bottom (y up, as a BMP stores it). The library never reads image files.

**Fields**

- `width` (`uint32_t`): Pixels per row; 0 gives [`DEFORMABLE_STATUS_EMPTY_IMAGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_empty_image).
- `height` (`uint32_t`): Number of rows; 0 gives `DEFORMABLE_STATUS_EMPTY_IMAGE`.
- `pixels` (`const uint8_t (*)[3]`): `pixel_count` pixels as red, green and blue bytes, row after row, bottom row first. May be `NULL` when
  `pixel_count` is 0.
- `pixel_count` (`size_t`): The number of pixels: `width` times `height`, or the call gives [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch).

**Example**

```c
// A 9 by 9 square outline: black sides, red corners, white inside.
const uint8_t colours[3][3] = {{255, 255, 255}, {0, 0, 0}, {255, 0, 0}};
uint8_t pixels[81][3];
for (int pixel = 0; pixel < 81; pixel++) {
    int ends = (pixel % 9 % 8 == 0) + (pixel / 9 % 8 == 0);
    memcpy(pixels[pixel], colours[ends], 3);
}
DeformablePixelGrid image = {9, 9, (const uint8_t (*)[3])pixels, 81};
DeformableSplinterImageParameters parameters;
CHECK(deformable_splinter_image_parameters_default(&parameters));
DeformablePolygonMesh *splinters = NULL;
CHECK(deformable_splinters_from_image(&image, &parameters, &splinters));
deformable_polygon_mesh_destroy(splinters);
```

**See also** [Guide: Make splinters from a drawing](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#make-splinters-from-a-drawing) · [Rust `PixelGrid`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#pixelgrid) · [Python `PixelGrid`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#pixelgrid)

## DeformableSplinterImageParameters

**Struct** · `deformable.h`

```c
typedef struct DeformableSplinterImageParameters {
    DeformableVector3 size;
    DeformableVector3 origin;
    uint8_t allow_nonconvex;
} DeformableSplinterImageParameters;
```

The settings of [`deformable_splinters_from_image`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_splinters_from_image): where the cage lies, how deep it is, and whether the traced cell
outlines are kept. [`deformable_splinter_image_parameters_default`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformable_splinter_image_parameters_default) writes size (1, 1, 1), origin (0, 0, 0) and
non-convex cells allowed.

**Fields**

- `size` ([`DeformableVector3`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformablevector3)): The size the image covers in x and y, and the cage's depth; a NaN or infinite component gives
  [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value). Default `{1.0, 1.0, 1.0}`.
- `origin` ([`DeformableVector3`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/math/#deformablevector3)): The image's lower-left corner in x and y, and the z of the cage's top face; the bottom face sits one depth
  lower. A NaN or infinite component gives `DEFORMABLE_STATUS_NON_FINITE_VALUE`. Default `{0.0, 0.0, 0.0}`.
- `allow_nonconvex` (`uint8_t`): Not 0 keeps the traced cell outlines; 0 dissolves the bends in each wall between two cells, so that it runs
  straight between junctions. Default `1`.

**Example**

```c
// The image over 2 by 2 units around the origin, a cage 0.1 deep
// with its top face at z = 0.5 and straight cell sides.
DeformableSplinterImageParameters parameters;
CHECK(deformable_splinter_image_parameters_default(&parameters));
parameters.size = (DeformableVector3){2.0, 2.0, 0.1};
parameters.origin = (DeformableVector3){-1.0, -1.0, 0.5};
parameters.allow_nonconvex = 0;
```

**See also** [Guide: Make splinters from a drawing](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#make-splinters-from-a-drawing) · [Rust `SplinterImageParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#splinterimageparameters) · [Python `SplinterImageParameters`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#splinterimageparameters)

### deformable_splinter_image_parameters_default

**Function** · `deformable.h`

```c
DeformableStatus deformable_splinter_image_parameters_default(
    DeformableSplinterImageParameters *parameters);
```

Writes the splinter image defaults to `parameters`: size (1, 1, 1), origin (0, 0, 0) and non-convex cells allowed.

**Parameters**

- `parameters` ([`DeformableSplinterImageParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformablesplinterimageparameters)): Out. Receives the defaults.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/#conventions) describe.

**See also** [Python `SplinterImageParameters.default`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#splinterimageparameters-default)

## deformable_splinters_from_image

**Function** · `deformable.h`

```c
DeformableStatus deformable_splinters_from_image(
    const DeformablePixelGrid *image,
    const DeformableSplinterImageParameters *parameters,
    DeformablePolygonMesh **cage);
```

Turns a line drawing into a splinter cage, one closed prism per cell, on the calling thread. Pass the cage to
[`deformable_embed_surface`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/render-surfaces/#deformable_embed_surface), and the render surface breaks into those splinters.

The drawing is black lines on white. A pixel is black when its red is below 128 and its green plus blue is 15 or
less. The lines must close every cell and join into one connected drawing. A red pixel, whose red is 128 or more and
at least 8 times its green plus blue, marks a corner where a line bends without meeting another line. Every other
pixel is background. Neighbouring prisms share their corner points. The tracing warnings, such as a line that ends
nowhere, do not stop the call and are not returned.

**Parameters**

- `image` ([`const DeformablePixelGrid *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformablepixelgrid)): The drawing: black lines between the cells, red marks at the corners where a line bends.
- `parameters` ([`const DeformableSplinterImageParameters *`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/tools/#deformablesplinterimageparameters)): Where the cage lies, how deep it is, and whether the traced cell outlines are kept.
- `cage` ([`DeformablePolygonMesh **`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformablepolygonmesh)): Out. Receives a new handle; free it with [`deformable_polygon_mesh_destroy`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_polygon_mesh_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `cage`: read the cage with [`deformable_polygon_mesh_view`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/meshes/#deformable_polygon_mesh_view). It holds the top points, then the bottom points; the top faces, then the bottom faces, then a side quad for each side of a wall that borders a cell.

**Errors**

- [`DEFORMABLE_STATUS_EMPTY_IMAGE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_empty_image): `width` or `height` is 0.
- [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch): `pixel_count` is not `width` times `height`.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A component of `size` or `origin` is NaN or infinite.
- [`DEFORMABLE_STATUS_NO_VERTICES`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_no_vertices): The drawing has no red mark and no place where lines meet, or none is left once the loose line ends are cleaned up: it is blank, or holds only an open line or a closed line without a red mark.
- [`DEFORMABLE_STATUS_NO_CELLS`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_no_cells): The drawing has vertices, but its lines close no cell.
- [`DEFORMABLE_STATUS_ENDLESS_CYCLE`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_endless_cycle): Tracing a cell took more steps than there are vertices.
- [`DEFORMABLE_STATUS_FACE_ALREADY_SET`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus-deformable_status_face_already_set): Tracing a cell met a wall side that another cell already holds. Loose line ends with red marks can cause it, such as a T on its own with red marks at its three ends.

**Example**

```c
const uint8_t colours[3][3] = {{255, 255, 255}, {0, 0, 0}, {255, 0, 0}};
uint8_t pixels[81][3];
for (int pixel = 0; pixel < 81; pixel++) {
    int ends = (pixel % 9 % 8 == 0) + (pixel / 9 % 8 == 0);
    memcpy(pixels[pixel], colours[ends], 3);
}
DeformablePixelGrid image = {9, 9, (const uint8_t (*)[3])pixels, 81};
DeformableSplinterImageParameters parameters;
CHECK(deformable_splinter_image_parameters_default(&parameters));
DeformablePolygonMesh *splinters = NULL;
CHECK(deformable_splinters_from_image(&image, &parameters, &splinters));
DeformablePolygonMeshView view;
CHECK(deformable_polygon_mesh_view(splinters, &view));
printf("%zu faces\n", view.polygon_count); // A top, a bottom, 4 sides.
deformable_polygon_mesh_destroy(splinters);
```

**See also** [Guide: Make splinters from a drawing](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/#make-splinters-from-a-drawing) · [Rust `splinters_from_image`](https://help.tangerina.io/deformable/v0.8.0/api-references/rust/tools/#splinters_from_image) · [Python `splinters_from_image`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#splinters_from_image)
