Remesh

The Remesh module provides tools for modifying triangle mesh resolution: reducing face count through decimation (to a target count) or simplification (to an error budget), or redistributing vertices through isotropic remeshing.

Decimation

Reduce face count using quadric error metrics. The algorithm collapses edges in priority order, placing the new vertex at the position that minimizes geometric error.

Basic Usage

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

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

// Decimate to 10% of original faces
const decimated = tf.decimated(mesh, 0.1);

With Configuration

const decimated = tf.decimated(mesh, 0.1, {
  preserveBoundary: true,
  minQuality: 0.3,
  parallel: false,
});

Feature Edge Preservation

Preserve sharp creases and corners during decimation:

const decimated = tf.decimated(mesh, 0.1, { featureAngle: 30 });

Returns a new Mesh, or { mesh, regions } when preserveRegions is given.

Simplification

Like decimation, simplification reduces a triangle mesh by quadric-error edge collapse (Garland–Heckbert). The difference is the stopping criterion: decimation stops at a target face count, while simplification stops at a geometric error budget. Flat regions collapse to almost nothing while curved detail and feature edges survive — the right tool when you care about fidelity rather than a specific size, such as cleaning up the over-sampled output of a boolean or arrangement.

Basic Usage

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

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

// Simplify within the default budget (0.2% of the bounding-box diagonal)
const simplified = tf.simplified(mesh);

With Configuration

const simplified = tf.simplified(mesh, {
  errorRel: 0.005,          // allow more deviation -> fewer faces
  optimizeIterations: 3,
  featureAngle: 30,
});

Quality Cleanup

A pure error-budget collapse leaves whatever triangulation the collapses produce, which can include thin slivers in flattened regions. Set optimizeIterations to run that many rounds of min-angle edge flip plus tangential relaxation after the collapse — feature- and boundary-aware — to even out the result:

const simplified = tf.simplified(mesh, { optimizeIterations: 5 });

Iterated Remesh

A single collapse stops at the edges the quality guard blocked. Set iterations > 1 to re-collapse after each cleanup round: the flip pass repairs the slivers a collapse leaves behind, which unblocks collapses the previous round refused, so more is removed. This turns simplification into an iterated error-budget remesh — the error sibling of isotropic remeshing. It trades fidelity for coarseness, since each round measures error against the already-collapsed surface rather than the original.

const simplified = tf.simplified(mesh, { iterations: 3 });

Region Preservation

To keep the boundaries between labelled regions (e.g. geological domains, material groups) intact, pass preserveRegions with a per-face label array (exactly one int per input face). Edges between differently-labelled faces are treated as features and never crossed, and the call returns the output mesh's per-face labels (int32, one per output face) alongside the mesh. This works the same way for decimated, simplified, and isotropicRemeshed (sync and async).

const { mesh, regions } = tf.simplified(inputMesh, { preserveRegions: regionLabels });
// regions: NDArray of int32, one label per face of `mesh`

A wrong-sized array (including an empty one) throws — omit preserveRegions when there are no regions to carry.

Returns a new Mesh, or { mesh, regions } when preserveRegions is given.

Isotropic Remeshing

Redistribute vertices to achieve uniform edge lengths. Each iteration splits long edges, collapses short edges, flips edges to improve valence, and relaxes vertex positions tangentially.

Basic Usage

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

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

// Remesh to target edge length
const mel = tf.meanEdgeLength(mesh);
const remeshed = tf.isotropicRemeshed(mesh, 2.0 * mel);

With Configuration

const remeshed = tf.isotropicRemeshed(mesh, 0.02, {
  iterations: 5,
  relaxationIters: 5,
  preserveBoundary: true,
  useQuadric: true,
});

Returns a new Mesh, or { mesh, regions } when preserveRegions is given.

Typical Pipeline

A common workflow is to decimate first, then isotropic remesh to improve triangle quality:

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

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

// Decimate to 5%
const dec = tf.decimated(mesh, 0.05);

// Isotropic remesh to mean edge length of decimated result
const mel = tf.meanEdgeLength(dec);
const result = tf.isotropicRemeshed(dec, mel, { useQuadric: true });

Async

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

const dec = await tf.async.decimated(mesh, 0.1);
const sim = await tf.async.simplified(mesh, { errorRel: 0.005 });
const rem = await tf.async.isotropicRemeshed(mesh, 0.02);

// preserveRegions works the same as sync, returning { mesh, regions }:
const { mesh: out, regions } = await tf.async.decimated(mesh, 0.1, {
  preserveRegions: regionLabels,
});