Modules | TS

Cut

Mesh booleans and scalar field cutting operations.

The Cut module provides scalar field cutting operations (isobands) and boolean operations on meshes.

Overview

Cut operations embed curves into mesh topology, splitting faces so the curves become edges:

Isobands: Cut along scalar field thresholds, label regions by band
Booleans: Cut along mesh intersection curves, combine by set operation
Embedded intersection curves: Embed intersection curves from mesh B into mesh A
Embedded self-intersections: Cut where mesh intersects itself

Boolean operations and isobands return face labels for classification.

Isobands

Extract regions (bands) between consecutive threshold values from scalar fields:

import * as tf from "@polydera/trueform";

const mesh = tf.readStl("terrain.stl");

// Create scalar field (one value per vertex)
const plane = tf.plane([0, 0, 1], 0.0);
const scalars = tf.distance(tf.point(mesh.points), plane);

// Extract isobands
const cutValues = new Float32Array([-1.0, 0.0, 1.0]);
const { mesh: result, labels } = tf.isobands(mesh, scalars, cutValues);

The labels array contains one integer per face, indicating which isoband the face belongs to. Faces are labeled 0, 1, 2, ... corresponding to regions (-∞, cutValues[0]), [cutValues[0], cutValues[1]), etc.

Select specific bands:

const { mesh: result, labels } = tf.isobands(mesh, scalars, cutValues, {
  selectedBands: [1, 3],
});

Get boundary curves:

const { mesh: result, labels, curves } = tf.isobands(mesh, scalars, cutValues, {
  returnCurves: true,
});

for (let i = 0; i < curves.length; i++) {
  const pathIds = curves.paths.at(i);
  // process contour points...
}

Boolean Operations

Boolean operations combine two meshes using set operations.

Input Mesh Requirements

Boolean operations accept PWN (piecewise winding number) meshes — plus the non-manifold flaps and geometric inconsistencies that real-world pipelines accumulate. These defects are modeled as independent noise: locally across polygon regions, globally across manifold edge-connected components.

See our Research for the conceptual model and formal definitions.

Operations

import * as tf from "@polydera/trueform";

const mesh0 = tf.readStl("mesh0.stl");
const mesh1 = tf.readStl("mesh1.stl");

// Union: A ∪ B
const { mesh: union, labels } = tf.booleanUnion(mesh0, mesh1);

// Intersection: A ∩ B
const { mesh: inter, labels: interLabels } = tf.booleanIntersection(mesh0, mesh1);

// Difference: A - B
const { mesh: diff, labels: diffLabels } = tf.booleanDifference(mesh0, mesh1);

The labels array contains one integer per face, indicating which input mesh (0 or 1) the face originated from.

Get intersection curves:

const { mesh: result, labels, curves } = tf.booleanUnion(mesh0, mesh1, {
  returnCurves: true,
});

for (let i = 0; i < curves.length; i++) {
  const pathIds = curves.paths.at(i);
  // process intersection curve points...
}

With transformations:

// Attach transformation to mesh
mesh1.transformation = tf.translation([5, 0, 0]);

// Boolean operations use transformed poses
const { mesh: result } = tf.booleanUnion(mesh0, mesh1);

// Update transformation — no topology rebuild needed
mesh1.transformation = tf.rotation(tf.deg(45), [0, 1, 0]);
const { mesh: result2 } = tf.booleanUnion(mesh0, mesh1);

Required topology structures (tree, faceMembership, manifoldEdgeLink) are built automatically on first use and cached on the Mesh. For performance-critical applications with repeated booleans, the first call pays the build cost and subsequent calls reuse the cached structures.

Embedded Intersection Curves

Embed intersection curves between mesh A and mesh B into mesh A, without performing boolean selection. All faces from mesh A are preserved (split where intersecting), with no faces from mesh B:

import * as tf from "@polydera/trueform";

const mesh0 = tf.readStl("mesh0.stl");
const mesh1 = tf.readStl("mesh1.stl");

// Embed intersection curves into mesh0
const result = tf.embeddedIntersectionCurves(mesh0, mesh1);

// Get curves as well
const { mesh: cut, curves } = tf.embeddedIntersectionCurves(mesh0, mesh1, {
  returnCurves: true,
});
console.log(`Found ${curves.length} intersection curve(s)`);

This is useful when you need to mark where meshes intersect without carving — for example, projecting cutting guides onto a surface or visualizing contact regions.

Unlike boolean operations, this function does not remove any faces from mesh0. The output mesh has the same volume and surface area as mesh0, with additional edges along the intersection curves.

Embedded Self-Intersection Curves

Embed self-intersection curves into mesh topology, splitting faces so intersections become edges:

import * as tf from "@polydera/trueform";

const mesh = tf.readStl("self_intersecting.stl");

// Embed self-intersection curves
const result = tf.embeddedSelfIntersectionCurves(mesh);

// Get curves as well
const { mesh: cut, curves } = tf.embeddedSelfIntersectionCurves(mesh, {
  returnCurves: true,
});
console.log(`Found ${curves.length} self-intersection curve(s)`);

This is useful for:

Mesh repair pipelines
Preparing meshes for boolean operations
Visualization of self-intersection regions

Async

All cut functions are available as async variants via tf.async for off-main-thread execution:

const { mesh, labels } = await tf.async.booleanUnion(mesh0, mesh1);
const { mesh: iso, labels: isoLabels } = await tf.async.isobands(mesh, scalars, cutValues);
const embedded = await tf.async.embeddedIntersectionCurves(mesh0, mesh1);
const selfEmb = await tf.async.embeddedSelfIntersectionCurves(mesh);

For extracting intersection or isocontour curves without cutting, see Intersect. For implementation details, see C++ Cut.

Intersect

Compute intersection curves between meshes and scalar field isocontours.

Clean

Remove duplicates, degenerates, and unreferenced elements.