Modules | PY
Remesh
Decimation and isotropic remeshing.
The Remesh module provides tools for modifying triangle mesh resolution: reducing face count through decimation, or redistributing vertices through isotropic remeshing.
All remesh functions require triangle meshes (3 vertices per face) and 3D coordinates. Use
tf.triangulated from the Geometry module to convert polygon meshes first.All remesh operations use parallel execution by default. Set
parallel=False for sequential execution (e.g. when processing many meshes in parallel externally).All edge length decisions (split thresholds, collapse thresholds, max edge length checks) respect the
Meshtransformation. When a Mesh has a transformation, lengths are measured in the transformed coordinate space. This allows remeshing a scaled or rotated mesh without modifying vertex data.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,
max_aspect_ratio=20.0,
parallel=False,
)
| Parameter | Type | Default | Description |
|---|---|---|---|
data | Mesh or tuple | Triangle mesh or (faces, points) tuple | |
target_proportion | float | Target face count as fraction of original (0.0–1.0) | |
max_aspect_ratio | float | 40.0 | Maximum triangle aspect ratio after collapse. Negative to disable |
preserve_boundary | bool | False | If True, boundary edges are never collapsed |
stabilizer | float | 1e-3 | Tikhonov stabilizer for quadric solve |
parallel | bool | True | Use parallel partitioned collapse |
| Returns | Type | Description |
|---|---|---|
faces | ndarray | Face indices, shape (N, 3) |
points | ndarray | Vertex positions, shape (M, 3) |
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,
)
| Parameter | Type | Default | Description |
|---|---|---|---|
data | Mesh or tuple | Triangle mesh or (faces, points) tuple | |
target_length | float | Target edge length. Longer edges are split, shorter are collapsed | |
iterations | int | 3 | Number of outer iterations (split + collapse + flip + relax) |
relaxation_iters | int | 3 | Tangential relaxation iterations per outer iteration |
max_aspect_ratio | float | -1.0 | Maximum aspect ratio after collapse. Negative to disable |
lambda_ | float | 0.5 | Damping factor for tangential relaxation in (0, 1] |
preserve_boundary | bool | False | If True, boundary edges are never split or collapsed |
use_quadric | bool | False | Use quadric error metric for collapse vertex placement |
parallel | bool | True | Use parallel execution |
| Returns | Type | Description |
|---|---|---|
faces | ndarray | Face indices, shape (N, 3) |
points | ndarray | Vertex positions, shape (M, 3) |
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)
Use
tf.mean_edge_length to compute a natural target length from the current mesh. This is often the right default for isotropic remeshing after decimation.