You are viewing the documentation for Deformable v0.8.0, an older version. Read the latest, v0.9.0

Python API Reference

Tools

Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.

On this page

The tools turn polygon meshes, triangle meshes and images into closed cages and tetrahedral meshes, the meshes a Scene 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 CancelFlag that another thread can set to stop them. Each tool comes right after the values it takes and returns.

Anisotropy

Named tuple · deformable.Anisotropy

python
class Anisotropy(NamedTuple):
    scale: float
    direction: Sequence[float]

A stretch of the mesher space by scale along direction, which triangulate and 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. Anisotropy.default() is scale 1 along (1, 1, 1): no stretch. Pass the same pair to both tools. They differ on values out of range: triangulate refuses a NaN or infinite scale or component, while tetrahedralize refuses only NaN and clamps an infinite one.

Fields

  • scale (float)The stretch factor along direction: above 1 makes longer elements, below 1 shorter ones. default() gives 1.0, clamped to [0.02, 50].
  • direction (Sequence[float])The stretch direction, three numbers for a vector of any length; a zero direction makes the scale count as 1. default() gives (1.0, 1.0, 1.0), each component clamped to [-100, 100].

Example

python
# Tetrahedrons about three times longer along y.
grain = deformable.Anisotropy(3.0, (0.0, 1.0, 0.0))
parameters = deformable.TetrahedralizeParameters(
    0.3, anisotropy=(grain, deformable.Anisotropy.default())
)
result = deformable.tetrahedralize(cage, parameters)

See also Guide: Stretch the tetrahedrons · C DeformableAnisotropy · Rust Anisotropy

Anisotropy.default

Class method · deformable.Anisotropy.default

python
@classmethod
def default(cls) -> Anisotropy

The anisotropy defaults: scale 1 along (1, 1, 1), no stretch.

Raises

Only the errors every call can raise, which the conventions describe.

See also C deformable_anisotropy_default

DensityRegion

Named tuple · deformable.DensityRegion

python
class DensityRegion(NamedTuple):
    points: Vector3Array
    scale: float

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

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 (Vector3Array)The region’s 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.
  • scale (float)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

python
# Tetrahedrons half the size near one corner of the cube.
corner = [(0, 0, 0), (1, 0, 0), (0, 1, 0), (0, 0, 1)]
region = deformable.DensityRegion(corner, 8.0)
parameters = deformable.TetrahedralizeParameters(
    0.3, density_regions=[region]
)
deformable.tetrahedralize(cage, parameters).skipped_density_regions
# []

See also Guide: Mesh some parts finer · C DeformableDensityRegion · Rust DensityRegion

TetrahedralizeParameters

Data class · deformable.TetrahedralizeParameters

python
@dataclasses.dataclass(frozen=True)
class TetrahedralizeParameters:
    maximum_edge_length: float
    anisotropy: tuple[Anisotropy, Anisotropy] | None = None
    density_regions: Sequence[DensityRegion] = ()

The settings of tetrahedralize: the size limit, the two stretches of the mesher space and the density regions. The size limit has no default: it is always the caller’s choice.

Fields

  • maximum_edge_length (float)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 the status MESHING_FAILED; NaN or infinite meshes the cage with no size limit.
  • anisotropy (tuple[Anisotropy, Anisotropy] or None)The two stretches of the mesher space, each clamped as Anisotropy says; None stretches nothing. Default None.
  • density_regions (Sequence[DensityRegion])The regions meshed finer or coarser than the rest; empty for none. Default ().

Example

python
# Tetrahedrons of at most 0.25 inside the cube, with no stretch.
parameters = deformable.TetrahedralizeParameters(
    maximum_edge_length=0.25
)
fine = deformable.tetrahedralize(cage, parameters).mesh

See also Guide: Fill a cage with tetrahedrons · C DeformableTetrahedralizeParameters · Rust TetrahedralizeParameters

Tetrahedralization

Data class · deformable.Tetrahedralization

python
@dataclasses.dataclass(frozen=True)
class Tetrahedralization:
    mesh: TetrahedralMesh
    skipped_density_regions: list[int]

The result of tetrahedralize: the mesh, and the density regions the call skipped.

Fields

  • mesh (TetrahedralMesh)The tetrahedral mesh: every tetrahedron positively oriented, the cage vertices at their input positions, and every node in a tetrahedron.
  • skipped_density_regions (list[int])The 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.

See also Guide: Fill a cage with tetrahedrons · C DeformableTetrahedralization · C DeformableTetrahedralizationView · Rust Tetrahedralization

tetrahedralize

Function · deformable.tetrahedralize

python
def tetrahedralize(
    cage: TriangleMesh,
    parameters: TetrahedralizeParameters,
    cancel: CancelFlag | None = None,
) -> 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 Scene.add_object requires, and every node belongs to a tetrahedron.

Parameters

  • cage (TriangleMesh)A closed cage with outward normals and no self-intersections.
  • parameters (TetrahedralizeParameters)The size limit, the two stretches and the density regions.
  • cancel (CancelFlag or None)Stops the call when another thread sets it.

Returns

Tetrahedralization: The mesh, and the indices of the density regions the call skipped. A density region that cannot be used is skipped, not an error.

Raises

DeformableError with one of these statuses:

  • INVALID_CAGEThe 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.
  • MESHING_FAILEDmaximum_edge_length is 0 or less, or the mesher stopped without a mesh.
  • NO_TETRAHEDRONSThe mesh has no tetrahedron.
  • BAD_SCALESAn anisotropy scale or direction component is NaN; an infinite one is clamped.
  • OUTPUT_TOO_LARGEAt 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.
  • CANCELLEDAnother thread set cancel.

ValueError when the positions or triangles of cage, or the points of a density region, do not form whole groups of three numbers, a triangle index is negative or does not fit in 32 bits, an anisotropy direction does not hold three numbers, or cancel is closed.

Example

python
parameters = deformable.TetrahedralizeParameters(
    maximum_edge_length=0.3
)
result = deformable.tetrahedralize(cage, parameters)
result.skipped_density_regions
# []

See also Guide: Fill a cage with tetrahedrons · C deformable_tetrahedralize · Rust tetrahedralize

TriangulateParameters

Data class · deformable.TriangulateParameters

python
@dataclasses.dataclass(frozen=True)
class TriangulateParameters:
    maximum_area: float
    quality: float
    anisotropy: tuple[Anisotropy, Anisotropy]
    closed_boundary: bool

The settings of triangulate: the area limit, the minimum angle, the two stretches of the mesher space and the closed boundary check. TriangulateParameters.default() gives area 1, a minimum angle of 20 degrees, no stretch and the closed boundary check on, with any field changed.

Fields

  • maximum_area (float)The largest triangle area, measured in the stretched mesher space; 0 or less sets no limit. default() gives 1.0.
  • quality (float)The minimum triangle angle, in degrees: 0 or less runs as 2, and the rest is clamped to [1, 20]. default() gives 20.0.
  • anisotropy (tuple[Anisotropy, Anisotropy])The two stretches of the mesher space, each clamped as Anisotropy says. default() gives two Anisotropy.default(), no stretch.
  • closed_boundary (bool)Refuses an edge that borders only one polygon, with the status NON_CLOSED_BOUNDARY; turn it off for a non-closed mesh. default() gives True.

Example

python
parameters = deformable.TriangulateParameters.default(
    maximum_area=0.05, quality=15.0
)
fine = deformable.triangulate(polygons, parameters=parameters).mesh

See also Guide: Triangulate a polygon mesh · C DeformableTriangulateParameters · Rust TriangulateParameters

TriangulateParameters.default

Class method · deformable.TriangulateParameters.default

python
@classmethod
def default(
    cls,
    **changes: float | tuple[Anisotropy, Anisotropy] | bool,
) -> TriangulateParameters

The triangulate defaults, area 1, a minimum angle of 20 degrees, no stretch and the closed boundary check on, with the given fields changed.

Parameters

Raises

TypeError when changes names a field TriangulateParameters does not have.

See also C deformable_triangulate_parameters_default

Triangulation

Data class · deformable.Triangulation

python
@dataclasses.dataclass(frozen=True)
class Triangulation:
    mesh: TriangleMesh
    source_polygons: list[int]

The result of triangulate: the triangle mesh, and the input polygon of each triangle. Triangles come grouped by polygon in input order, and each follows its polygon’s winding.

Fields

  • mesh (TriangleMesh)The points, in order of first appearance with unused input vertices dropped, and the triangles.
  • source_polygons (list[int])The input polygon each triangle was made from, one per triangle, so per-polygon data such as materials can carry over to the triangles.

See also Guide: Triangulate a polygon mesh · C DeformableTriangulation · C DeformableTriangulationView · Rust Triangulation

triangulate

Function · deformable.triangulate

python
def triangulate(
    cage: PolygonMesh,
    holes: Sequence[FaceHole] = (),
    parameters: TriangulateParameters | None = None,
    cancel: CancelFlag | None = None,
) -> 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

Returns

Triangulation: The triangle mesh, and the input polygon of each triangle.

Raises

DeformableError with one of these statuses:

  • NON_FINITE_VALUEA position of cage, the area limit, the minimum angle, or an anisotropy scale or direction component is NaN or infinite.
  • EMPTY_MESHcage has no vertices or no polygons.
  • INDEX_OUT_OF_RANGEA 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 error’s first index names the polygon, or the polygon count for corners left over.
  • DEGENERATE_POLYGONA 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 error’s first index names the polygon.
  • NON_MANIFOLD_EDGEAn edge borders three or more polygons. The error’s two indices name its vertices.
  • NON_CLOSED_BOUNDARYclosed_boundary is on and an edge borders only one polygon. The error’s two indices name its vertices.
  • OUTPUT_TOO_LARGEThe 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.
  • COULD_NOT_CONVERGEThe polygons did not settle at any minimum angle down to 1 degree.
  • CANCELLEDAnother thread set cancel.

ValueError when the positions of cage do not form whole groups of three numbers, a polygon size, corner or hole value is negative or does not fit in 32 bits, an anisotropy direction does not hold three numbers, or cancel is closed.

Example

python
result = deformable.triangulate(polygons)
# Each triangle names the face of the cube it came from.
sorted(set(result.source_polygons))
# [0, 1, 2, 3, 4, 5]

See also Guide: Triangulate a polygon mesh · C deformable_triangulate · Rust triangulate

ExtrudeDirection

Enum · deformable.ExtrudeDirection

python
class ExtrudeDirection(enum.IntEnum):
    UP = 0
    DOWN = 1
    BOTH = 2

Where 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. extrude defaults to BOTH.

Values

  • UP (0)The mesh, and a copy thickness along the normal.
  • DOWN (1)The mesh, and a copy thickness against the normal.
  • BOTH (2)Two copies, half of thickness on each side of the mesh. The default.

See also Guide: Extrude a triangle mesh into a shell · C DeformableExtrudeDirection · Rust ExtrudeDirection

extrude

Function · deformable.extrude

python
def extrude(
    mesh: TriangleMesh,
    thickness: float,
    direction: ExtrudeDirection | int = ExtrudeDirection.BOTH,
) -> TetrahedralMesh

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

  • mesh (TriangleMesh)The triangle mesh to thicken, open or closed.
  • thickness (float)The shell’s thickness, in the mesh’s unit; it must be above 0.
  • direction (ExtrudeDirection or int)Where the two layers go: on the normal side, on the other side, or half on each. An int that is no member’s value raises DeformableError with the status INVALID_ARGUMENT, and one that does not fit in 32 bits ValueError.

Returns

TetrahedralMesh: The shell: the points of the layer on the normal side, one per vertex, then those of the other layer, and 3 tetrahedrons per triangle, in triangle order.

Raises

DeformableError with one of these statuses:

  • NON_POSITIVE_THICKNESSthickness is 0 or less, or NaN, even for an empty mesh.
  • UNKNOWN_VERTEXA triangle names a vertex past the end of the positions. The error’s first index names the triangle.
  • DUPLICATE_VERTEXA triangle uses one vertex at two corners. The error’s first index names the triangle.
  • DEGENERATE_FACEA triangle has a zero normal: its corners lie on one line. The error’s first index names the triangle.
  • MULTIPLE_BOUNDARIESThe triangles around a vertex form more than one fan, as where two parts of the mesh touch at that vertex only. The error’s first index names the vertex.
  • NULL_NORMALThe angle-weighted normals of the triangles around a vertex cancel out. The error’s first index names the vertex.

ValueError when the positions or triangles of mesh do not form whole groups of three numbers, a triangle index is negative or does not fit in 32 bits, or direction does not fit in 32 bits.

TypeError when direction is not an int.

Example

python
# A hollow cube: walls 0.1 thick, centred on the cage's faces.
shell = deformable.extrude(cage, 0.1, deformable.ExtrudeDirection.BOTH)
len(shell.positions), len(shell.tetrahedrons)
# (16, 36)

See also Guide: Extrude a triangle mesh into a shell · C deformable_extrude · Rust extrude

span_layers

Function · deformable.span_layers

python
def span_layers(
    first_layer: TriangleMesh,
    second_layer: TriangleMesh,
) -> TetrahedralMesh

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 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 (TriangleMesh)One side of the space, whose triangles the tetrahedrons follow.
  • second_layer (TriangleMesh)The other side: the same number of vertices, and the same triangles up to a rotation of each one’s corners.

Returns

TetrahedralMesh: The mesh: the first layer’s positions, then the second layer’s, and 3 tetrahedrons per triangle, in triangle order.

Raises

DeformableError with one of these statuses:

  • NOT_ISOMORPHICThe layers differ in vertex or triangle count, or a triangle of the first layer does not match exactly one triangle of the second.
  • UNKNOWN_VERTEXA triangle names a vertex past the end of the positions. The error’s first index names the triangle.
  • DUPLICATE_VERTEXA triangle uses one vertex at two corners. The error’s first index names the triangle.
  • MULTIPLE_BOUNDARIESThe triangles around a vertex form more than one fan, as where two parts of the mesh touch at that vertex only. The error’s first index names the vertex.

ValueError when the positions or triangles of a layer do not form whole groups of three numbers, or a triangle index is negative or does not fit in 32 bits.

Example

python
# A hollow box: the cage, and a copy three times its size around it.
outer = deformable.TriangleMesh(
    [[3 * value - 1 for value in point] for point in cage.positions],
    cage.triangles,
)
walls = deformable.span_layers(cage, outer)
len(walls.positions), len(walls.tetrahedrons)
# (16, 36)

See also Guide: Fill the space between two layers · C deformable_span_layers · Rust span_layers

AutocageParameters

Data class · deformable.AutocageParameters

python
@dataclasses.dataclass(frozen=True)
class AutocageParameters:
    scale_gap: float
    target_face_count: int
    target_tetrahedron_count: int

The settings of 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. AutocageParameters.default() gives scale gap 1, a target of 300 faces and no tetrahedron target, with any field changed.

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

Fields

  • scale_gap (float)Multiplies the gap the cage keeps from the mesh, which follows the size of the cage’s triangles; NaN or infinite gives NON_FINITE_VALUE. default() gives 1.0, clamped to [0.1, 10].
  • target_face_count (int)The number of triangles the cage aims for; 0 or less leaves the size to target_tetrahedron_count. default() gives 300.
  • target_tetrahedron_count (int)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() gives 0.

Example

python
# A coarser cage than the default, kept twice as far out.
parameters = deformable.AutocageParameters.default(
    scale_gap=2.0, target_face_count=100
)
wrapped = deformable.autocage(polygons, parameters)

See also Guide: Wrap any mesh in a cage · C DeformableAutocageParameters · Rust AutocageParameters

AutocageParameters.default

Class method · deformable.AutocageParameters.default

python
@classmethod
def default(cls, **changes: float | int) -> AutocageParameters

The autocage defaults, scale gap 1, a target of 300 faces and no tetrahedron target, with the given fields changed.

Parameters

  • **changes (float or int)Field values that replace the defaults, by field name.

Raises

TypeError when changes names a field AutocageParameters does not have.

See also C deformable_autocage_parameters_default

autocage

Function · deformable.autocage

python
def autocage(
    mesh: PolygonMesh,
    parameters: AutocageParameters | None = None,
    cancel: CancelFlag | None = None,
) -> TriangleMesh

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

Returns

TriangleMesh: The cage: a closed triangle mesh with outward normals around mesh, ready for tetrahedralize.

Raises

DeformableError with one of these statuses:

  • NON_FINITE_VALUEscale_gap or a position of mesh is NaN or infinite, or the mesh is so large that its size overflows.
  • INDEX_OUT_OF_RANGEA 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 error’s first index names the polygon, or the polygon count for corners left over.
  • EMPTY_INPUTNo polygon has 3 or more corners, or all the vertices the polygons use coincide.
  • OUTPUT_TOO_LARGEThe 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.
  • STEP_LIMIT_REACHEDThe cage did not close within its step limit, 1,000 steps per expected triangle and at least 100,000, restarts included.
  • CANCELLEDAnother thread set cancel.

ValueError when the positions of mesh do not form whole groups of three numbers, a polygon size or vertex index is negative or does not fit in 32 bits, a count of parameters does not fit in 32 bits (it may be negative), or cancel is closed.

TypeError when a count of parameters is not an int.

Example

python
wrapped = deformable.autocage(polygons)
parameters = deformable.TetrahedralizeParameters(0.5)
filled = deformable.tetrahedralize(wrapped, parameters).mesh

See also Guide: Wrap any mesh in a cage · C deformable_autocage · Rust autocage

PixelGrid

Data class · deformable.PixelGrid

python
@dataclasses.dataclass(frozen=True)
class PixelGrid:
    width: int
    height: int
    pixels: PixelArray

An image decoded by the host, for 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 (int)Pixels per row; 0 gives EMPTY_IMAGE.
  • height (int)Number of rows; 0 gives EMPTY_IMAGE.
  • pixels (PixelArray)The pixels, row after row, bottom row first, as (red, green, blue) triples or flat bytes: width times height of them, or the call gives LENGTH_MISMATCH.

Example

python
# A 9 by 9 square outline: black sides, red corners, white inside.
def colour(x, y):
    ends = (x in (0, 8)) + (y in (0, 8))
    return [(255, 255, 255), (0, 0, 0), (255, 0, 0)][ends]
pixels = [colour(x, y) for y in range(9) for x in range(9)]
image = deformable.PixelGrid(9, 9, pixels)

See also Guide: Make a splinter cage from a drawing · C DeformablePixelGrid · Rust PixelGrid

SplinterImageParameters

Data class · deformable.SplinterImageParameters

python
@dataclasses.dataclass(frozen=True)
class SplinterImageParameters:
    size: Sequence[float]
    origin: Sequence[float]
    allow_nonconvex: bool

The settings of splinters_from_image: where the cage lies, how deep it is, and whether the traced cell outlines are kept. SplinterImageParameters.default() gives size (1, 1, 1), origin (0, 0, 0) and non-convex cells allowed, with any field changed.

Fields

  • size (Sequence[float])The size the image covers in x and y, and the cage’s depth; a NaN or infinite component gives NON_FINITE_VALUE. default() gives Vector3(1.0, 1.0, 1.0).
  • origin (Sequence[float])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 NON_FINITE_VALUE. default() gives Vector3(0.0, 0.0, 0.0).
  • allow_nonconvex (bool)Keeps the traced cell outlines; False dissolves the bends in each wall between two cells, so that it runs straight between junctions. default() gives True.

Example

python
# 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.
parameters = deformable.SplinterImageParameters(
    size=(2.0, 2.0, 0.1),
    origin=(-1.0, -1.0, 0.5),
    allow_nonconvex=False,
)

See also Guide: Make a splinter cage from a drawing · C DeformableSplinterImageParameters · Rust SplinterImageParameters

SplinterImageParameters.default

Class method · deformable.SplinterImageParameters.default

python
@classmethod
def default(
    cls,
    **changes: Sequence[float] | bool,
) -> SplinterImageParameters

The splinter image defaults, size (1, 1, 1), origin (0, 0, 0) and non-convex cells allowed, with the given fields changed.

Parameters

  • **changes (Sequence[float] or bool)Field values that replace the defaults, by field name.

Raises

TypeError when changes names a field SplinterImageParameters does not have.

See also C deformable_splinter_image_parameters_default

splinters_from_image

Function · deformable.splinters_from_image

python
def splinters_from_image(
    image: PixelGrid,
    parameters: SplinterImageParameters | None = None,
) -> PolygonMesh

Turns a line drawing into a splinter cage, one closed prism per cell, on the calling thread. Pass the cage to 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

Returns

PolygonMesh: The cage: 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.

Raises

DeformableError with one of these statuses:

  • EMPTY_IMAGEwidth or height is 0.
  • LENGTH_MISMATCHThe pixel count is not width times height.
  • NON_FINITE_VALUEA component of size or origin is NaN or infinite.
  • NO_VERTICESThe 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.
  • NO_CELLSThe drawing has vertices, but its lines close no cell.
  • ENDLESS_CYCLETracing a cell took more steps than there are vertices.
  • FACE_ALREADY_SETTracing 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.

ValueError when the pixels do not form whole groups of three bytes, a byte is outside [0, 255], width or height is negative or does not fit in 32 bits, or size or origin does not hold three numbers.

Example

python
def colour(x, y):
    ends = (x in (0, 8)) + (y in (0, 8))
    return [(255, 255, 255), (0, 0, 0), (255, 0, 0)][ends]
pixels = [colour(x, y) for y in range(9) for x in range(9)]
image = deformable.PixelGrid(9, 9, pixels)
# One cell: a top, a bottom and 4 sides.
deformable.splinters_from_image(image).polygon_sizes
# [4, 4, 4, 4, 4, 4]

See also Guide: Make a splinter cage from a drawing · C deformable_splinters_from_image · Rust splinters_from_image