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 trueform as tf

faces, points = tf.read_stl("model.stl")
mesh = tf.Mesh(faces, points)

# Decimate to 10% of original faces
dec_faces, dec_points = tf.decimated(mesh, 0.1)

From Tuple

# Also accepts (faces, points) tuples directly
dec_faces, dec_points = tf.decimated((faces, points), 0.1)

With Configuration

dec_faces, dec_points = tf.decimated(
    mesh, 0.1,
    preserve_boundary=True,
    min_quality=0.3,
    parallel=False,
)

Feature Edge Preservation

Preserve sharp creases and corners during decimation:

dec_faces, dec_points = tf.decimated(mesh, 0.1, feature_angle=30)

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 trueform as tf

mesh = tf.Mesh(*tf.read_stl("model.stl"))

# Simplify within the default budget (0.2% of the bounding-box diagonal)
sim_faces, sim_points = tf.simplified(mesh)

From Tuple

# Also accepts (faces, points) tuples directly
sim_faces, sim_points = tf.simplified((faces, points))

With Configuration

sim_faces, sim_points = tf.simplified(
    mesh,
    error_rel=0.005,         # allow more deviation -> fewer faces
    optimize_iterations=3,
    feature_angle=30,
)

Quality Cleanup

A pure error-budget collapse leaves whatever triangulation the collapses produce, which can include thin slivers in flattened regions. Set optimize_iterations 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:

sim_faces, sim_points = tf.simplified(mesh, optimize_iterations=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.

sim_faces, sim_points = tf.simplified(mesh, iterations=3)

Region Preservation

To keep the boundaries between labelled regions (e.g. geological domains, material groups) intact, pass preserve_regions with a per-face label array (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) alongside the mesh. This works the same way for decimated, simplified, and isotropic_remeshed.

faces, points, labels = tf.simplified(mesh, preserve_regions=region_labels)

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 trueform as tf

mesh = tf.Mesh(*tf.read_stl("model.stl"))

# Remesh to target edge length
mel = tf.mean_edge_length(mesh)
rem_faces, rem_points = tf.isotropic_remeshed(mesh, 2.0 * mel)

From Tuple

rem_faces, rem_points = tf.isotropic_remeshed((faces, points), 0.02)

With Configuration

rem_faces, rem_points = tf.isotropic_remeshed(
    mesh, 0.02,
    iterations=5,
    relaxation_iters=5,
    preserve_boundary=True,
    use_quadric=True,
)

Typical Pipeline

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

import trueform as tf

mesh = tf.Mesh(*tf.read_stl("model.stl"))

# Decimate to 5%
dec_faces, dec_points = tf.decimated(mesh, 0.05)

# Isotropic remesh to mean edge length of decimated result
mel = tf.mean_edge_length((dec_faces, dec_points))
dec_mesh = tf.Mesh(dec_faces, dec_points)
rem_faces, rem_points = tf.isotropic_remeshed(dec_mesh, mel, use_quadric=True)