Modules | C++

Remesh

Decimation, isotropic remeshing, edge collapse, and custom handlers.

The Remesh module provides tools for modifying triangle mesh resolution: reducing face count through decimation and edge collapse, or redistributing vertices through isotropic remeshing. All functions operate on triangle meshes and return a new mesh along with the resulting half-edge structure.

Include the module with:

#include <trueform/remesh.hpp>

All remesh functions require triangle meshes (static face size of 3). Polygonal meshes must be triangulated first using tf::triangulated from the Geometry module.

All remesh operations use parallel execution by default. Set config.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 tagged transformations. When the input polygons have a tagged frame, 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

decimated.cpp

auto mesh = tf::read_stl("model.stl");
auto polys = mesh.polygons();

// Decimate to 10% of original faces
auto [result, he] = tf::decimated(polys, 0.1f);

// result is a tf::polygons_buffer, he is a tf::half_edges
for (auto tri : result.polygons()) {
    auto [pt0, pt1, pt2] = tri;
}

With Configuration

decimated_config.cpp

tf::decimate_config<float> config;
config.preserve_boundary = true;
config.max_aspect_ratio = 20;
config.parallel = false; // sequential execution

auto [result, he] = tf::decimated(polys, 0.1f, config);

decimate_config parameters:

Parameter	Default	Description
`max_aspect_ratio`	40	Maximum triangle aspect ratio after collapse. Set negative to disable
`preserve_boundary`	true	If true, boundary edges are never collapsed
`stabilizer`	1e-3	Tikhonov stabilizer for quadric solve
`parallel`	true	If true, use parallel partitioned collapse
`feature_angle`	-1 (disabled)	Dihedral angle threshold for feature edge detection. Edges sharper than this are preserved
`feature_weight`	100	Penalty weight for feature edge quadrics. Higher = stronger preservation

Feature Edge Preservation

Preserve sharp creases and corners during decimation by setting feature_angle to the minimum dihedral angle (in degrees or radians) that defines a feature edge:

decimated_features.cpp

tf::decimate_config<float> config;
config.feature_angle = tf::deg(30.f); // preserve edges sharper than 30 degrees
config.feature_weight = 100.f;

auto [result, he] = tf::decimated(polys, 0.1f, config);

Feature edges receive penalty quadrics that keep the optimal collapse point on the feature line. Corner vertices (where 3+ feature edges meet) are automatically protected.

With Index Maps

Pass tf::return_index_map to also receive face and vertex index maps that track which elements survived the decimation:

decimated_index_map.cpp

auto [result, he, face_map, vertex_map] =
    tf::decimated(polys, 0.1f, tf::return_index_map);

// Or with config:
auto [result, he, face_map, vertex_map] =
    tf::decimated(polys, 0.1f, config, tf::return_index_map);

With Pre-Computed Half-Edges

When half-edges are already available (e.g. from a previous operation), tag them onto the polygons to skip rebuilding:

decimated_precompute.cpp

tf::half_edges<int> he(polys);

// Tag half-edges onto polygons - decimated reuses them
auto [result, he_out] = tf::decimated(polys | tf::tag(he), 0.1f);

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

isotropic_remeshed.cpp

auto mesh = tf::read_stl("model.stl");
auto polys = mesh.polygons();

// Remesh to target edge length
float mel = tf::mean_edge_length(polys);
auto [result, he] = tf::isotropic_remeshed(polys, 2.0f * mel);

With Configuration

isotropic_remeshed_config.cpp

tf::remesh_config<float> config{2.0f * mel};
config.iterations = 5;
config.relaxation_iters = 5;
config.preserve_boundary = true;

auto [result, he] = tf::isotropic_remeshed(polys, config);

remesh_config parameters:

Parameter	Default	Description
`target_length`	(required)	Target edge length. Edges longer are split, shorter are collapsed
`iterations`	3	Number of outer iterations (split + collapse + flip + relax)
`relaxation_iters`	3	Number of tangential relaxation iterations per outer iteration
`max_aspect_ratio`	-1	Maximum triangle aspect ratio after collapse. Set negative to disable
`lambda`	0.5	Damping factor for tangential relaxation in (0, 1]
`preserve_boundary`	true	If true, boundary edges are never split or collapsed
`use_quadric`	false	If true, use quadric error metric for collapse vertex placement
`parallel`	true	If true, use parallel collapse during the collapse step
`feature_angle`	-1 (disabled)	Dihedral angle threshold for feature edge detection. Edges sharper than this are preserved
`feature_weight`	100	Penalty weight for feature edge quadrics. Higher = stronger preservation

With Pre-Computed Half-Edges

isotropic_remeshed_precompute.cpp

tf::half_edges<int> he(polys);
auto [result, he_out] = tf::isotropic_remeshed(polys | tf::tag(he), 2.0f * mel);

Edge Collapse

Collapse edges shorter than a threshold. Unlike decimation which uses quadric error ordering, this collapses by edge length — shortest first.

Basic Usage

collapsed_short_edges.cpp

auto mesh = tf::read_stl("model.stl");
auto polys = mesh.polygons();

float mel = tf::mean_edge_length(polys);

// Collapse edges shorter than 3/4 mel
auto [result, he] = tf::collapsed_short_edges(polys, 0.75f * mel);

With Configuration

collapsed_short_edges_config.cpp

tf::length_collapse_config<float> config;
config.max_length = 1.25f * mel;
config.preserve_boundary = true;
config.use_quadric = true;

auto [result, he] = tf::collapsed_short_edges(polys, 0.75f * mel, config);

length_collapse_config parameters:

Parameter	Default	Description
`max_length`	max	Maximum edge length allowed after a collapse
`max_aspect_ratio`	40	Maximum triangle aspect ratio after collapse. Set negative to disable
`preserve_boundary`	true	If true, boundary edges are never collapsed
`use_quadric`	true	If true, use quadric error metric for vertex placement
`parallel`	true	If true, use parallel partitioned collapse
`feature_angle`	-1 (disabled)	Dihedral angle threshold for feature edge detection
`feature_weight`	100	Penalty weight for feature edge quadrics
`stabilizer`	1e-6	Tikhonov stabilizer for quadric solve

With Index Maps

Pass tf::return_index_map to also receive face and vertex index maps:

collapsed_short_edges_index_map.cpp

auto [result, he, face_map, vertex_map] =
    tf::collapsed_short_edges(polys, 0.75f * mel, tf::return_index_map);

// Or with config:
auto [result, he, face_map, vertex_map] =
    tf::collapsed_short_edges(polys, 0.75f * mel, config, tf::return_index_map);

With Pre-Computed Half-Edges

collapsed_short_edges_precompute.cpp

tf::half_edges<int> he(polys);
auto [result, he_out] = tf::collapsed_short_edges(polys | tf::tag(he), 0.75f * mel);

Custom Handlers

For advanced use cases — adaptive remeshing, per-region target lengths, narrow triangle removal — the module exposes the underlying handler types. These give full control over edge scoring and acceptance while reusing the collapse machinery (quadrics, feature masks, parallel partitioning).

Split Handler

A tf::split_handler wraps a scoring lambda. Edges with score > 1 are split.

split_handler.cpp

float max2 = max_length * max_length;

auto handler = tf::make_split_handler<float>(
    [max2](const auto &he, const auto &points, auto heh) -> float {
        auto v0 = he.start_vertex_handle(tf::unsafe, heh).id();
        auto v1 = he.end_vertex_handle(tf::unsafe, heh).id();
        auto len2 = (points[v1] - points[v0]).length2();
        return len2 / max2; // > 1 triggers split
    },
    true,  // preserve_boundary
    3);    // max_iterations

tf::split_edges(he, points, handler);

Collapse Handler

A tf::collapse_handler wraps a scoring lambda and an acceptance checker. Edges with score < 1 are eligible for collapse, ordered by score (0 = highest priority). The score lambda receives a reference to the handler, providing access to quadrics and config.

collapse_handler.cpp

float min2 = min_length * min_length;

auto checker = tf::make_collapse_checker<float>(
    40.0f,   // max_aspect_ratio (scalar)
    max2);   // max_edge_length² (scalar)

tf::collapse_config<float> config;
config.use_quadric = true;
config.feature_angle = tf::deg(30.f);

auto handler = tf::make_collapse_handler<float>(
    [min2](const auto &he, const auto &points, auto heh,
           const auto &) -> float {
        auto v0 = he.start_vertex_handle(tf::unsafe, heh).id();
        auto v1 = he.end_vertex_handle(tf::unsafe, heh).id();
        auto len2 = (points[v1] - points[v0]).length2();
        return len2 / min2; // < 1 triggers collapse
    },
    checker, config);

tf::collapse_edges(he, points, handler);

Collapse Checker

The tf::collapse_checker wraps the dihedral geometric check. Each parameter can be a scalar, a callable (half_edges, points, edge_handle) → Real, or tf::none to disable:

collapse_checker.cpp

// Scalar thresholds
auto checker = tf::make_collapse_checker<float>(40.0f, max_len_sq);

// Per-edge max length via callable, no aspect ratio check
auto checker = tf::make_collapse_checker<float>(
    tf::none,
    [&](const auto &he, const auto &points, auto eh) -> float {
        // look up per-face target from adjacent faces
        auto heh = he.half_edge_handle(tf::unsafe, eh, false);
        auto f = he.face_handle(tf::unsafe, heh).id();
        return face_targets[f] * face_targets[f];
    });

// No geometric checks at all
auto checker = tf::make_collapse_checker<float>();

Quadric Scoring

For decimation-style scoring using quadric error metrics, the score lambda can access the handler's quadrics (built during init):

quadric_scoring.cpp

auto score = [](const auto &he, const auto &points, auto heh,
                const auto &handler) -> float {
    return tf::remesh::collapse_error_quadric<float>(
        handler._quadrics, points, he, heh, handler._config.stabilizer);
};

auto checker = tf::make_collapse_checker<float>(40.0f);
auto handler = tf::make_collapse_handler<float>(score, checker, config);

// Collapse to target face count
tf::collapse_edges(he, points, handler, target_faces);

Configuration Hierarchy

All configs share a common base:

Config	Inherits	Adds
`collapse_config`	—	`preserve_boundary`, `use_quadric`, `parallel`, `feature_angle`, `feature_weight`, `stabilizer`
`decimate_config`	`collapse_config`	`max_aspect_ratio`
`length_collapse_config`	`collapse_config`	`max_length`, `max_aspect_ratio`
`remesh_config`	`collapse_config`	`target_length`, `iterations`, `relaxation_iters`, `max_aspect_ratio`, `lambda`

Geometry

Geometric analysis, surface properties, and point cloud alignment.

Intersect

Exact mesh intersections, self-intersections, and scalar field isocontours.