Skip to content

Topological offset

topological_offset adds a region at a given distance around a selection of a tagged tet mesh: a shell around a body, inside it or both, or a band around an expression of tags (an overlap, the curve where three regions meet) or around a surface group. It grows a band of cells from the selection, gives them new tags, and then optimizes the mesh until the band's outer boundary, the front, lies at the target distance. The band's topology is fixed when it is built and kept throughout (Topological Offsets, ACM TOG 2025).

Use it to make a coating, a gap, or a contact layer of a given thickness around regions that already exist in a tagged mesh, such as one from simwild. To separate or join regions that touch only along an edge or at a vertex, use manifold extraction, which carves the same kind of band without the optimization.

What runs in this version

The component runs on tet meshes only: a triangle mesh stops with 2D input refused: the 2D offset is not up to date. The optimization is under active development; many of its options are marked EXPERIMENTAL_ in the reference and change often. This page covers the stable options.

A first run

127891.msh is a bar (127891, 342 tets) in a box of background, 1,556 tets in all. A band of distance 0.4 around it, outside, built but not optimized (optimize_offset false), which takes a fraction of a second:

{
  "application": "topological_offset",
  "input": "127891.msh",
  "output": "127891_offset",
  "offsets": [{"selection": "127891", "output_tags": ["offset"], "target_distance": 0.4}],
  "envelope_size_rel": 4e-4,
  "optimize_offset": false,
  "report": "127891_offset.json"
}
wmtk_app -j topological_offset.json

The input must be a .msh. The result is 127891_offset.msh, with the band tagged offset.

bar = wm.read_mesh(str(DATA / "127891.msh"))
outputs, report = wm.topological_offset(
    {"input": "bar",
     "offsets": [{"selection": "127891", "output_tags": ["offset"], "target_distance": 0.4}],
     "envelope_size_rel": 4e-4, "optimize_offset": False},
    {"bar": bar},
)
offset = outputs["mesh"]
print(report["before #t"], "->", report["after #t"], "tets,", count(offset, "offset"), "in the band")

On files instead, with the same options as the JSON file:

wm.topological_offset({
    "input": str(DATA / "127891.msh"),
    "output": "127891_offset",
    "offsets": [{"selection": "127891", "output_tags": ["offset"], "target_distance": 0.4}],
    "envelope_size_rel": 4e-4,
    "optimize_offset": False,
})
wmtk::MeshMap meshes{{"bar", wmtk::io::read_mesh(data / "127891.msh")}};
auto [outputs, report] = wmtk::components::topological_offset::topological_offset(
    {{"input", "bar"},
     {"offsets",
      nlohmann::json::array(
          {{{"selection", "127891"},
            {"output_tags", nlohmann::json::array({"offset"})},
            {"target_distance", 0.4}}})},
     {"envelope_size_rel", 4e-4},
     {"optimize_offset", false}},
    meshes);
std::cout << report["before #t"] << " -> " << report["after #t"] << " tets\n";
wmtk::io::write_mesh("127891_offset.msh", outputs.at("mesh"));

Link wmtk::topological_offset.

It prints 1556 -> 4802 tets, 2094 in the band. The log says how the band was placed and that it passed its checks:

[construction] construction_mode max_marchable_fallback: maximum marchable distance 0.49254 over 592 marched edges; target_distance 0.4 is below it, so the march traces to the target
Offset region manifold check passed.
connected components check passed. (# components=1)

The front is a closed surface of 1,180 triangles. Its 592 vertices lie at the target: their distance to the bar is between 0.990 and 1.000 times 0.4. Its triangles do not: they are chords between those vertices, and their centroids are between 0.54 and 1.02 times the target (0.93 on average). The band's cells are thin (max AMIPS 179, against 19.2 in the input). Moving the whole front onto the target and restoring the quality is the job of the optimization.

How the band is built

  1. The complex. An offset's selection picks the input complex: cells, and the faces, edges and vertices between them.
  2. The embedding. Cells are split so that no edge, face or tet outside the complex has all its vertices on it (the log says Input complex/offset simplicially embedded: TRUE).
  3. The march. Every edge with one end on the complex is split at the target distance from the complex, found by sphere tracing. That needs the edge's far end to be farther than the target. The smallest such distance over all the edges is the maximum marchable distance; when the target is not below it, every edge is split at half of it instead, and the front starts short of the target.
  4. The band. The cells around the new vertices are the band, one cell thick, and get the output tags.
  5. The optimization (unless optimize_offset is false): turns of splits, collapses, swaps and smoothing that move the front onto the target distance and refine where it is not, with TetWild passes for quality before and after them.

The band's topology is the one the march gives it, and every later operation keeps it.

The input on the left, the result on the right: drag to rotate, scroll to zoom; on the tet mesh, move the cut with the slider. Every example is in the gallery.

Key settings

One entry per offset: offsets

offsets is a list with one entry per offset, {"selection": ..., "output_tags": [...], "target_distance": ...}; only selection is required. The runs on this page have one entry. Several entries are independent offsets, each with its own band, output tags and distance, built in one march; two selections may share no cell, and touch only if both grow inward, each band into its own selection. The other options are set once for the run.

Which side: selection, direction

An entry's selection names what to offset: a region, as in the first run, a sheet, a curve, or an expression of them (below). The band grows from its boundary, on the side the entry's direction says: out (the default) away from the region's cells, in into them, both on either side. Until 2026-11 the run-wide offset_in and offset_out said this, for a single tag only.

# Outward (the default), inward, and both: the band is the cells tagged "offset".
for direction in ["out", "in", "both"]:
    out, _ = wm.topological_offset(
        {"input": "bar",
         "offsets": [{"selection": "127891", "direction": direction,
                      "output_tags": ["offset"], "target_distance": 0.4}],
         "envelope_size_rel": 4e-4, "optimize_offset": False},
        {"bar": bar})
    print(direction, count(out["mesh"], "offset"), "band tets")
side band tets the march traces to
out 2,094 0.4, the target
in 2,876 0.0973, half of the inside's maximum marchable distance, 0.195
both 4,970 0.0973

Inside the bar the maximum marchable distance is 0.195, below the target, so the inward band starts at a quarter of the target and the optimization has to carry it the rest of the way.

Expressions

Any other selection is an expression over tag names, with &, |, ! and parentheses, as in simwild (ambient is the background). Each face, edge and vertex carries the tags of the tets around it, and the selection is every tet, face, edge and vertex whose tags satisfy it, with all their faces: !tag_0 takes the faces of the other tets on tag_0 too. The band grows from the selection's boundary on the side direction says; an expression that selects no tet, like the circle below, has no inside, so out and both are the same for it and in drops the offset, with a warning. On double_sphere.msh, two overlapping spheres tag_0 and tag_1, with a target of 0.05:

# Two overlapping spheres, tag_0 and tag_1. An expression selects the complex to offset.
spheres = wm.read_mesh(str(DATA / "double_sphere.msh"))
for selection in ["tag_0 & tag_1",             # the overlap, a lens
                  "ambient & tag_0 & tag_1"]:  # the circle where the two surfaces cross
    out, _ = wm.topological_offset(
        {"input": "spheres",
         "offsets": [{"selection": selection, "output_tags": ["offset"], "target_distance": 0.05}],
         "optimize_offset": False},
        {"spheres": spheres})
    print(f"{selection!r}: {count(out['mesh'], 'offset')} band tets")
selection the complex band tets
tag_0 & tag_1 the overlap, a lens of tets 2,716
ambient & tag_0 & tag_1 the circle where the two surfaces cross: 28 edges 886

A complex of edges alone, like the circle, is built but not optimized: with the optimization the run stops with the energy's band term needs an input complex of triangles only. Set optimize_offset false for it.

Surfaces: EnvelopeSurface and face tags

A .msh with an EnvelopeSurface triangle group (simwild writes one) has that group as a tag of its own name, and an entry's selection can name it alone: the complex is the faces of the mesh that lie within envelope_size_rel of the group, and the band grows on both sides of them. This is how to offset an open sheet. The log says how many faces carry it:

Surface group 'EnvelopeSurface' (tag 3): 330 triangles; 310 of the mesh's faces lie inside its envelope (eps 0.0836779) and carry the tag

In 127891.msh the group is the bar's own surface, so "selection": "EnvelopeSurface" gives the same 4,970 band tets as direction both. A face tag (simwild's input_type surface) is selected by its name in the same way, with optimize_offset false only.

Tags of the band: output_tags, protected_tags

An entry's output_tags (default ["newtag"]) are the tags every cell of its band gets, replacing the tags it had; a name the mesh does not have is added as a new region. [] makes the band background, which carves a gap. protected_tags is a tag expression of what the band leaves alone (default "", nothing): the march takes none of the cells whose tags satisfy it, so the band stops at them, and a face the band covers whose face tags satisfy it keeps the ones it names. ambient cannot be protected (refused), nor be an output tag (ignored, with a warning). On the two spheres, the band around tag_0 runs through tag_1:

# The band around tag_0 runs through tag_1. Protected, tag_1 keeps its cells: the band stops there.
for protected in ["", "tag_1"]:
    out, _ = wm.topological_offset(
        {"input": "spheres",
         "offsets": [{"selection": "tag_0", "output_tags": ["offset"], "target_distance": 0.05}],
         "protected_tags": protected, "optimize_offset": False},
        {"spheres": spheres})
    m = out["mesh"]
    print(f"protected {protected!r}: offset {count(m, 'offset')}, tag_1 {count(m, 'tag_1')} tets")

Protected, tag_1 is not taken: none of its cells joins the band, which grows only where it does not meet tag_1.

The distance: target_distance_rel, target_distance

An entry's target_distance_rel (default 0.01) is its target relative to the diagonal of the whole mesh's bounding box, background included; its target_distance, when positive, replaces it with an absolute length. The box of 127891.msh has a diagonal of 83.7, so the default target is 0.837, above the maximum marchable distance, 0.493: the march puts the front at 0.246, 0.29 of the target, and the optimization has to grow it. On this mesh, with the other options at their defaults (and four threads), that optimization had not converged after 22 turns, when the run was stopped.

The envelope that holds the input complex and the other surfaces in place, envelope_size_rel (default 1e-3 of the diagonal), may not be wider than the bar, front_conv_rel times the target (default 0.1): a wider one lets them move farther than the front is measured to, and the run stops at startup with the largest value allowed. At the default target the two are equal; at the target 0.4 used here the bar is 0.04 and the default envelope 0.084, so the examples set envelope_size_rel to 4e-4.

A target below the maximum marchable distance is traced exactly, as in the first run. That distance is the one from the complex to the nearest far end of an edge that leaves it, so it is set by the cells around the selection, and the construction does not change them beforehand: the input's resolution decides what the construction can reach.

The field: offset_field

offset_field is the field the front is placed on. euclidean, the default, is the distance to the complex, and the only one available: smooth stops with offset_field "smooth" is not available in 3D.

The optimization: optimize_offset, front_conv_rel

optimize_offset (default true) runs the optimization after the construction: up to max_rounds (default 40) turns of splits, collapses, swaps and smoothing that place the front, a TetWild pass before them on the constructed mesh, and a final one if the max AMIPS is over stop_energy (100). After each turn, each front vertex is measured on the front triangles around it: the root mean square of (distance − target) / target over sample points on them. The loop stops when every vertex is within the bar, front_conv_rel times the target (default 0.025); around a vertex over the bar, the target edge length is halved. Each turn logs the measure in units of the bar:

======== turn 5 / 5: max AMIPS 117.9 (stop 100) | ring measure max 3.766x the bar (avg 0.3237x) ...

The optimization is most of the cost. The first run's offset, optimized for five turns with a bar of 20% of the target and four threads:

# The optimization, cut short: five turns, a bar of 20% of the target, four threads.
outputs, report = wm.topological_offset(
    {"input": "bar",
     "offsets": [{"selection": "127891", "output_tags": ["offset"], "target_distance": 0.4}],
     "envelope_size_rel": 4e-4, "front_conv_rel": 0.2, "max_rounds": 5, "num_threads": 4},
    {"bar": bar},
)
metrics = report["optimization_metrics"]
print("converged:", report["converged"], "|", report["after #t"], "tets |",
      f"front distance error: avg {metrics['avg_l2_dist_err'][-1]:.3g},"
      f" max {metrics['max_l2_dist_err'][-1]:.3g}")

It prints converged: False, 21,683 to 24,423 tets in four runs (the threads change the order of the operations), and a front distance error of 0.016 to 0.024 on average and 0.4 at most. Measured back to back, these five turns take about 400 times as long as the construction, and the time per turn grows with the mesh. On one result (23,148 tets), 84% of the front's vertices are within 2.5% of the target and 83% of its triangles' centroids within 5% (55% after the construction); the max AMIPS is 117.9. A few front vertices are still off by the whole target, and the log warns that some 170 to 200 of the front's 2,300 to 2,500 triangles are folded ([foldover]). Ten turns with the same bar end at 100,131 tets, still not converged (worst vertex 4.9 times the bar). None of the optimized runs made for this page converged.

With optimize_offset false, the run stops after the march: the front's vertices are at the target (or at half the maximum marchable distance), the report has no convergence fields, and the mesh's distance_over_target is NaN.

The checks: check_manifoldness

With check_manifoldness (default true), the region made of the complex and the band must be manifold after the construction, or the run stops with OFFSET REGION IS NOT MANIFOLD; after the optimization it is checked again, and a failure is logged as an error. Whatever this option says, the mesh's connected components are counted before and after the construction, and a change stops the run (connected components check passed in the log).

Outputs

  • The mesh: output on the command line (default out, written as out.msh), outputs["mesh"] in memory. Its tags are the input's, with the output tags on the band (and an empty EnvelopeSurface column when the input has that group). The vertex field labels is 1 on the complex, 2 on the vertices the march added, 0 elsewhere: in the first run, 157, 592 and 195. Besides them, the fields other components read (vid, the tet field offset_tag, 1 on the band) and two annotations: amips, each tet's quality, and distance_over_target, each vertex's distance to the complex over target_distance. The diagnostics of the optimization are in the DEBUG_output frames only.
  • The front is the band's boundary, where offset_tag differs across a face: the mesh holds it, and no output repeats it. outputs["envelope"] is the input's EnvelopeSurface group, passed on, or the envelope given, a labelled reference, which the run holds to and returns with the band's boundary added under the band's tags (on the command line also <output>_envelope.msh): the front, which is new and so its own reference, and, where the band wraps a region, its interface with that region.
  • With report, a JSON file with the vertex, edge, face and tet counts before and after, the threads and the run time; after the optimization also converged and optimization_metrics, whose avg_l2_dist_err and max_l2_dist_err are the front's distance error. In memory, the report is the second return value.
  • With save_vtu, .vtu files for ParaView, with the mesh's fields.

Recipes and pitfalls

  • A misspelled or outdated option is an error. Unlike most components, topological_offset refuses an option its spec does not have: No rule matched for "/front_conv_criterion" (wmtk_app logs topological_offset has no option ... first). Configurations written for earlier versions, with front_conv_criterion, offset_gradient_rel or offset_residual_rel, fail this way. Start from the reference.
  • The run does not converge. The result is written anyway, with a warning Optimization did not converge and converged false in the report; check it before using the offset. throw_on_nonconvergence makes it an error instead.
  • The target is beyond the cells. When the log says the march traces to half of the maximum marchable distance, the constructed front is short of the target, and only the optimization carries it out, which is slow. Pick a target below that distance where the offset allows it; growth_mode sets how the optimization grows the front.
  • A surface group that does not lie on mesh faces. The group's faces are found geometrically. On double_sphere.msh, only 129 of the mesh's faces lie within the group's envelope, in 36 pieces, so the complex is a scatter of patches; the log line above says so.
  • Parallel runs differ. With num_threads above 0 the optimization's result changes slightly from run to run (the tet counts above); 0 runs sequentially.
  • For prismatic meshes, save_offset_correspondence records which input vertex each marched vertex came from; it needs optimize_offset false.

See also