SimWild (simwild)¶
Builds and edits multi-region meshes. With surfaces (3D) or curve networks (2D) as input, it meshes them all into one tet or triangle mesh with a region per input, overlaps included, and optimizes it like tetwild and triwild. With a tagged .msh as input, operation selects an edit: remeshing improves the mesh; fill_holes_topo, tight_seal_topo, tight_seal_geom, keep_lcc, resolve_overlaps, replace_tags and tag_priority edit its regions.
Spec source · Defaults · JSON Schema
Required¶
application¶
string · required · one of simwild
Application name must be simwild.
input¶
list of string · required · min 1
List of input files. A .msh is an already-tagged mesh and is used as-is. Any other input is read for what it is: triangles a surface, segments a curve (an OBJ of 'v'/'l' polylines), bare vertices points (an OBJ of 'v' records alone); on the memory route by its blocks. In 3D the surfaces are inserted by VolumeRemesher, each a volume or a surface (see /input_type); the curves are forced into the tetrahedralization exactly as feature curves -- every edge a chain of tet edges tiling it, endpoint to endpoint, held in a tube of feature_envelope_ratio x eps, every vertex where they end or three or more meet anchored -- and the points as tet vertices, anchored. In 2D the curves are arranged, each a region or a curve (see /input_type), and the points inserted as vertices of the arrangement, anchored (only x and y are used). A vertex of a curve with no incident edge is a point. The output mesh's point block holds the points, each vertex under the names of the inputs with a point there. Curves and points, with the forcing-triangle apexes the 3D insertion builds for curves (offset by up to 0.1 x the edge length), lie inside the background box, which is grown over them. A surface (2D: a curve) is needed; see /dimension. Read and held by the same code as tetwild's (3D) and triwild's (2D). Until 2026-11 curves and points came in lists of their own, input_edges and input_points, the curves named feature_<i>. A tagged mesh's lower blocks are tags too, on both routes: in 3D its triangles are face tags and its edges feature curves, one feature input per label, held as curve inputs are; in 2D its edges are edge tags, as curve inputs give them (see /input_type); in both its points are input points, one per label, anchored where they are (with an envelope, on its point of their label). Their rows labelled EnvelopeSurface, and in 2D an edge block without tags, are the envelope. simwild writes its tags back the same way, and reads tetwild's and triwild's outputs as such tagged meshes. A tagged mesh is the only input, refused with any other. Its tracked faces (in 2D edges) must lie inside it: a filtered mesh, whose boundary is its tracked faces, is refused, and its surfaces go in as inputs instead.
Each entry: One input file.
Key options¶
input_names¶
list of string · default []
List of names for the inputs, one per entry of /input, at its position there: a volume's region, a surface's face tag (2D: a curve's edge tag), a 3D curve's feature-curve tag. If no names are assigned, the inputs will be named tag_0, tag_1, etc., by their position.
Each entry: Name for one input mesh.
input_type¶
list of string · default []
One entry per input, saying what its tag marks. 'volume': the input encloses a volume (in 2D, a region), and the tets (in 2D, the triangles) inside it get its name as a tag. 'surface' (3D only): the input stays a surface, and the embedded faces on it get its name as a face tag. 'curve': in 2D the input stays a curve, open or closed, and the arrangement's edges on it get its name as an edge tag, written as the edge block of the output mesh; in 3D a curve input is a feature curve, and 'curve' is the only entry it takes. 'point': a point input, the only entry it takes. An entry the input's content contradicts is refused. 'surface' and 'curve' (2D) need tag_from_winding_number, and 'surface' needs split_connected_components off. Empty (the default): every surface (2D: curve) is a volume, every other input what its content makes it. Applies to surface and curve inputs, not to a tagged mesh input.
Each entry: What that input's tag marks: the tets (2D: triangles) it encloses, the faces on it (3D only), the edges on it (2D; in 3D a curve input), or its points.
operation¶
string · default "remeshing" · one of remeshing, fill_holes_topo, tight_seal_topo, tight_seal_geom, keep_lcc, resolve_overlaps, replace_tags, tag_priority
What to do. 'remeshing' meshes the inputs, or improves the quality of a tagged .msh; the others edit the regions of a tagged .msh, each with its own options below. Depending on the operation, more parameters might be required.
dimension¶
string · default "auto" · one of auto, 2, 3
Whether the input is 2D or 3D, as a string. 'auto' looks at the inputs: a first input .msh decides from its own content; a surface among them (an OBJ with 'f' records, or another mesh format) makes the run 3D, else curves (OBJ 'l' records, no 'f') make it 2D. A curve network and a surface are both .obj, so the extension alone cannot separate them. Setting "2" or "3" forces the route and errors if the file disagrees, rather than failing later with a confusing parse error.
output¶
string · default "out"
Output file name (without extension): the mesh is <output>.msh. Next to it <output>_envelope.msh, the memory route's outputs["envelope"]: an envelope given (see /envelope), unchanged; else the reference this run held its tags to, labelled as the mesh labels them (triangles, 2D segments, one column per face tag, edge tag or region; the feature curves; the input points); after an operation that changes the tags, one built around its result, each face between regions (2D: edge) labelled by the regions it bounds and its face tags, with the feature curves. It is the envelope a later run takes. It holds no eps: the receiver builds its own envelopes around it.
input_transform¶
list of list of list of float · default []
Transformation matrices for the inputs, one per entry of /input. Transformations are optional and don't need to be described for all inputs. They apply to the surfaces (2D: curves): one for a 3D curve or for points is refused.
Each entry: Homogeneous transformation matrix for one input: 4x4 for a 3D input, 3x3 for a 2D one. An empty list means identity.
eps_rel¶
float · default 0.002
Envelope thickness relative to the bounding box diagonal. The bounding box is the inputs' own, feature curves and points included, as in tetwild and triwild; a mesh input's is the mesh's. Until 2026-11 it was the embedding's box, padded by a fifteenth of the diagonal on each side: 1.22x the inputs' diagonal on simwild_double_sphere_notop_3d, 1.42x on simwild_curves_2d.
length_rel¶
float · default 0.05
Target edge length relative to the bounding box diagonal. The diagonal is eps_rel's: the inputs' own bounding box.
sizing_field¶
list of objects · default []
Prescribe a length for a specific region defined by tags. The length can be absolute (length) or relative (length_rel). The smallest prescribed length will be used for each vertex. With sizing_mesh, the smaller of the two lengths where both apply (see there). Example: [{"tags": "tag_0 & tag_1", "length": 0.1}, {"tags": "tag_2", "length_rel": 0.05}]
Each entry: A region and its target length.
Each entry is an object with:
tags: string · required. A region of tags.length: float · default-1. Absolute target edge length for the region.length_rel: float · default0.05. Target edge length relative to the bounding box for the region.
quality_field¶
list of objects · default []
Prescribe a target quality for a specific region defined by tags. The last prescribed quality will be used for each element. Example: [{"tags": "tag_0 & tag_1", "quality": 100}, {"tags": "tag_2", "quality": 50}]
Each entry: A region and its target quality.
Each entry is an object with:
tags: string · required. A region of tags.quality: float · required · min0. Target quality for the region.
stop_energy¶
float · default 10
Target energy. If every cell (tet in 3D, triangle in 2D) has an energy below this, the optimization stops.
preserve_topology¶
bool · default true
Preserve topology of input.
simplify¶
bool · default true
If true, the input is simplified: a surface or curve input before insertion when preserve_topology is false; in 3D, the tet mesh after insertion when preserve_topology is true and the operation is remeshing -- a tagged mesh input included, whose envelope is then the mesh's tracked faces as read (see envelope_reference). The 2D route has no simplification after insertion.
num_threads¶
int · default 0
Number of threads. 0 runs sequentially and gives the same result on every run; with more threads the order of the operations depends on the schedule, and the result can change slightly from run to run.
Other options¶
tag_from_winding_number¶
bool · default true
How the cells of the arrangement are tagged. True evaluates the winding number of every input at each cell's centroid. False propagates the tags across the arrangement's own surface provenance instead: combinatorial and exact, starting from a cell of the padded box (which is outside everything) and flipping membership of an input whenever a face belonging to that input is crossed. The provenance route needs every input surface to be closed, and says which crossings disagree rather than returning a tagging that depends on the traversal order. 3D surface input only -- a .msh input arrives already tagged.
split_connected_components¶
bool · default false
Treat each connected component of an input file as an input in its own right, rather than the file as a whole. What counts as an input is what gets its own tag column and its own winding-number evaluation, so a file holding several disjoint closed surfaces is tagged as one region with this off, and as one region per component with it on. Components are vertex-connected. Note that the inputs then outnumber the files, so /input_names -- which is applied by position -- no longer lines up with the filenames, and components past the end of that list fall back to the generic tag_N names. 3D surface input only: a .msh input arrives already tagged, and the 2D curve path has its own reader.
use_sample_envelope¶
bool · default false
Use the sampled envelope instead of the exact one. Governs both the 3D surface envelope and, since the exact envelope gained support for edges, the order-2 (open boundary and non-manifold) curve envelope and the 2D polyline envelope -- all three are containment tests against the same input at the same epsilon, so they follow one flag. The sampled test places points along the query and asks whether each is within eps of the input, so it cannot see what happens between two samples and shrinks its acceptance radius to compensate; the exact one decides coverage by the union of the eps-neighbourhoods without sampling, so it uses the full eps and is strictly sharper.
simplify_use_sample_envelope¶
bool · default false
Use the sampled envelope instead of the exact one for the input simplification only -- in 3D, of the input surface before insertion without preserve_topology, of the tet mesh after insertion with it (operation remeshing); in 2D, of the input curves before insertion without preserve_topology, of the triangle mesh after insertion with it (operation remeshing); in every case only if simplify is true; the optimization keeps whatever use_sample_envelope selects. Off by default, like use_sample_envelope; the opt-in buys speed, since the exact envelope dominates the cost of simplifying a large input. Note the sampled test cannot see what happens between two samples, and on thin lattice geometry the sampled simplification has been observed to over-collapse badly (in tetwild).
max_iterations¶
int · default 80
Maximum iterations before stopping.
eps¶
float · default -1
Absolute envelope thickness. If this value is negative, the relative envelope thickness is used to compute the absolute one.
eps_simplify_rel¶
float · default 0.0002
Envelope thickness relative to the bounding box for the initial simplification. Will be ignored if simplify is false or the input is already a tet mesh. The diagonal is eps_rel's, so both simplifications, before and after the insertion, run at the same eps; until 2026-11 the one before the insertion used the inputs' own and the one after the embedding's padded box.
envelope_reference¶
string · default "input" · one of input, simplified
Which geometry every envelope, tube and anchor is built around: the surface (2D: curve) envelope and the per-label ones, the order-2 and feature tubes, and the curve anchors, one choice for all. "input": the input as read, at eps times each one's ratio, through either simplification; the output is within eps of it. Before the insertion (preserve_topology off), an open boundary, non-manifold edge or curve end the simplification made, and every curve where two inputs meet, is held around itself as the insertion leaves it, since a free one erodes the input along its curve; after it (preserve_topology on, remeshing), the result is held to the envelope around the input again. Needs eps_simplify below eps, else refused: the simplified geometry could start outside its envelope. "simplified": the simplified geometry, which replaces the input, at eps times each one's ratio; the output is within eps of it, so within eps_simplify plus eps of the input, and any eps_simplify is allowed. Refused when no simplification runs (simplify false; under preserve_topology, outside remeshing). After a simplification following the insertion the order-2 curves are tagged again around its result, the simplification holding them within order2_envelope_ratio x eps_simplify, and the curve anchors keep their centres at that radius. In 2D the order-2 features are points, the curve ends and junctions, held by those anchors alone: nothing is tagged again, and they stay within order2_envelope_ratio x eps of the input under either reference. Until 2026-11 "simplified" built at eps minus eps_simplify; until 2026-10 the key optimize_envelope_around_simplified, and SimWild built every envelope around the simplified geometry whatever it said.
per_input_envelopes¶
bool · default true
Hold each input to its own envelopes. With two or more labels: one surface (2D: curve) envelope per label, in 3D one order-2 and one feature tube per input, and the input simplification's envelope per input likewise, so a face or curve of one input cannot end up on another. false: one shared envelope of each kind for all labels, faster where inputs come within eps of each other (the simplification measured 3% to 20% faster shared, 2026-11), but an input may then end up on another within eps. Anchors are per point either way.
eps_simplify¶
float · default -1
Absolute envelope thickness for the initial simplification. If this value is negative, the relative envelope thickness is used to compute the absolute one. Will be ignored if simplify is false or the input is already a tet mesh.
simplify_boundary_envelope¶
bool · default true
Let the input simplification move the open boundary of the surface, as long as every boundary edge stays within order2_envelope_ratio * eps_simplify of the input's boundary edges (the same scaling tetwild uses). When false, every boundary vertex is frozen, which also freezes whatever lies between boundary loops packed too tightly to leave a free vertex. Boundary that the simplification opens away from the input's is not judged by the tube. Only affects the simplification before insertion, which runs only when preserve_topology is false and simplify is true; under preserve_topology the surface is simplified after insertion against the order-2 envelope instead.
remove_duplicate_eps¶
float · default 0
Remove duplicate vertices in the input meshes that are closer than this fraction of the bounding box diagonal. Applied to each input file separately, right after it is read and before it is split into connected components -- unmerged coincident vertices would otherwise leave one surface looking like several. 0 merges only exactly coincident vertices; negative skips the pass entirely.
order2_envelope_ratio¶
float · default 1.0
Thickness of the tube that holds the order-2 edges -- the open boundaries of the surface and its non-manifold edges -- as a fraction of the surface envelope's eps, and the radius of the anchors where they end or three or more meet. Under envelope_reference "input" the tube is built around the input's own order-2 curves where the inserted edges lie in it, so such an edge stays within order2_envelope_ratio x eps of the input's; one the simplification before the insertion made, or one where two inputs meet, is held in a tube around itself as inserted, and the simplification after the insertion (preserve_topology) runs inside the tube. Under "simplified", around the order-2 edges of the simplified geometry. Until 2026-11 the tube was built around the edges as the insertion left them whatever envelope_reference said, and an open boundary could drift order2_envelope_ratio x (eps + eps_simplify) from the input's. In 2D, the radius of the anchors where the region borders end or three or more meet. A 2026-10 sweep (13 tetwild integration configs with open boundaries; ratio 0.25, 0.5, 0.75 and 1.0, each at eps x0.99, x1 and x1.01) found no advantage below 1: 7 configs give identical output at every ratio, Thingi10K 111388 gives the fewest tets at 1.0 (27-28k, against 30-31k at 0.5) and the most at 0.25 (28-44k), and the others differ by less than the 1% eps perturbation does. The earlier case for 0.5 (Thingi10K 36075, 14 against 24 iterations) does not reproduce: that model now gives identical output at every ratio.
feature_envelope_ratio¶
float · default 1.0
Thickness of the feature-curve tube -- the region a tet edge tagged as tiling an input feature edge (a 3D curve input) must stay inside -- and the radius of the feature anchors (the point inputs, and the vertices where feature curves end or three or more meet), as a fraction of the surface envelope's eps. Where an anchor is also on an order-2 edge the smaller order2_envelope_ratio radius holds it. The default 1 holds them to the same eps as the surface: the tube is built around the input feature curves themselves. Unused without curve and point inputs.
length¶
float · default -1
Absolute target edge length. If this value is negative, the relative length is used to compute the absolute one.
sizing_mesh¶
string · default ""
A target edge length that varies over space: a tet mesh in 3D, a triangle mesh in 2D (read in the xy plane), whose vertices carry the absolute target length as the field 'target_length' (one value per vertex), interpolated linearly inside its cells. On the memory route the name of a mesh of the call, on the file route the path of a mesh file with a node field 'target_length', relative to input_dir. It sets the sizing of the vertices it covers, the scalar that scales the target length and that stuck-element refinement lowers, as sizing_field does for its regions: at the start, and after every pass as a ceiling, so the vertices a pass makes follow it and refinement is kept. Outside its cells the global length (length, else length_rel) applies. With sizing_field, a vertex of a region it covers takes the smaller of the region's length and its own; a vertex of no region it covers takes its length, also where it is longer than the global one, which it replaces there; a vertex it does not cover keeps the regions' sizing. The bounded coarsening pass (coarsen_pass with coarsen_unbounded off) stops at 0.8 of its length instead of the global one. Remeshing only: a tag operation does not read it. Empty: none, and the run is the same as without the option. The field is a largest edge length: with it, limit_collapse_length is on unless set to false, and the optimization goes on past stop_energy while more than 1% of the edges are longer than 4/3 of their target and that share still drops.
limit_collapse_length¶
bool · default set by the component (see below)
Default: on with a sizing_mesh (the field is then a bound the collapses keep), off without. Refuse a collapse that leaves an edge longer than the split length: 4/3 of the target edge length, scaled by the sizing at its ends, the length above which an edge is split. As isotropic_remeshing's limit_collapse_length (Botsch and Kobbelt). Without it a collapse is judged by the edge it removes alone, so two collinear edges of an interface merge into one up to 0.8 + 4/3 of the target; and since the optimization ends on collapses (the last iteration's, then the bare pass after the loop), nothing cuts them again. With it the edges stay about 4/3 of the target at most (smoothing can still stretch them a little), so a target of 3/4 of a bound keeps them near or under that bound, for a denser mesh. It holds every collapse of a remeshing, the simplification after the insertion (preserve_topology) included. In the coarsening pass the target is the one asked for (sizing_mesh, else the global length), not the optimizer's refinement of it. The tag operations make no collapse.
stop_at_float¶
bool · default false
Stop when all vertices are in floating point precision, i.e., no more rational numbers are needed. stop_energy will be ignored when this is true.
project_line_search_steps¶
int · default 12
Bisections tried by the projected line search before it gives up on a vertex: the step along the Newton direction is halved this many times, each candidate projected onto the input, and the first that does not invert and lowers the worst incident element is taken.
project_line_search_nested_steps¶
int · default 0
After the projected line search gives up, revisit each candidate and bisect between the interpolated point and its projection this many times, taking the longest step toward the input that still does not invert and still lowers the worst element. Lets a vertex whose one-ring cannot tolerate a full projection still travel toward the input, instead of being refused every pass from the same place. 0 disables the pass.
smoothing_mode¶
string · default "projected" · one of projected, penalty
How smoothing places a surface vertex. 'projected': smooth with AMIPS alone as if interior, then walk back toward the start projecting each candidate onto the input; accept the first projected candidate that does not invert and strictly lowers the worst incident element, else do not move. Lands exactly on the input; no weights. 'penalty': no projection; minimize w_amips * AMIPS + (1-w_amips) * (d/eps)^2, a quadratic penalty on the distance d, with the true region-wise Hessian of the distance to the piecewise-linear input; sliding is free where the input is flat, held at corners, constrained along 3D edges and curve segments. Rests a w_amips-proportional distance off the input.
w_amips¶
float · default 0.0001 · min 0 · max 1
Relative weight of the AMIPS quality term against the envelope term during smoothing; the envelope weight is 1 - w_amips. The small default makes smoothing primarily about staying on the surface, with quality as a secondary preference.
num_smoothing_passes¶
int · default 2 · min 0
Smoothing passes per optimization iteration when interleaved_smoothing is disabled. Matches the Wild driver.
interleaved_smoothing¶
bool · default true
Run smoothing after each topology phase, matching TetWild and TriWild, instead of batching it after all topology operations.
interleaved_smoothing_passes¶
int · default 1 · min 0
Smoothing passes after each topology phase when interleaved_smoothing is enabled.
check_surface_folds¶
bool · default false
Refuse a collapse, swap or smoothing that folds the tracked surface over: one that leaves more tracked faces facing against, or flat to, the surface it replaces (the tracked faces around it, their area vectors summed) or the surface it leaves than there were, or more such faces in the stars of the surface vertices it touches. Exact (orient3d). A fold the input has can be undone, but none is made. Splits are not checked: they move no vertex. Turns colored_smoothing off.
colored_smoothing¶
bool · default true
Parallel smoothing (num_threads > 0) by color class: the vertices are split into classes of pairwise non-adjacent vertices, smoothed one class after another, each class fully in parallel without locks. The result does not depend on the number of threads. false: the locked, partitioned smoothing pass, whose result depends on the thread schedule. Serial runs (num_threads 0) are the same either way.
write_vtu¶
bool · default false
Write not just MSH but also VTU output.
history_output¶
string · default ""
3D only: a 2D run refuses it. Record every change to the tracked surface -- the interfaces between unlike tags -- from the mesh the input initialises to the output, and save the history here (see wmtk/history): the tracking component rebuilds the map between the two from it. The mesh the history starts from is written next to the output as <output>_history_input.msh; on the memory route it is the output mesh history_input. On the memory route no file is written: any non-empty value records the history, and the bytes of the file it would be are returned in the report as history (bytes in Python; history::write_history or wm.write_history saves them). Empty: no recording.
volume_history_output¶
string · default ""
3D only, with history_output. Also record the tets around every operation that changes the tracked surface, and save them here (see wmtk/history/VolumeHistory.hpp): with the surface history, the tracking component rebuilds a map of the volume, region by region (a region: the tets with the same tags), from the mesh the surface history starts from (<output>_history_input.msh; on the memory route the output mesh history_input) to the output. On the memory route no file is written: any non-empty value records the volume history, and the bytes of the file it would be are returned in the report as volume_history (bytes in Python; history::write_history or wm.write_history saves them). It takes many times the room of the surface history. Empty: no recording.
curve_history_output¶
string · default ""
3D surface inputs only: a .msh input, a tagged mesh and a 2D input refuse it. Record every change to the feature curves -- the tet edges tiling the curve inputs, with the feature points: their ends and junctions, and the point inputs -- from the inputs as read to the output, and save the history here (see wmtk/history), as tetwild's curve_history_output: the tracking component rebuilds the map between the two from it. Its own file, with or without history_output. The output names a point on its curves by two vertices of the output mesh. The curves are welded by exact position, as the insertion places them, and not simplified: ends of two curves at the same coordinates are one vertex, which the joined curve passes. On the memory route no file is written: any non-empty value records the history, and the bytes of the file it would be are returned in the report as curve_history (bytes in Python; history::write_history or wm.write_history saves them). Empty: no recording.
allow_surface_swap¶
bool · default true
Allow surface edge swapping.
check_surface_topology¶
bool · default false
Check if the surface topology is preserved after each operation. This can be very slow and should only be used for debugging.
verbose_quality_stats¶
bool · default true
Log the per-tag quality breakdown after every optimization iteration: for each entry of /quality_field, and for the cells no entry matches, the number of cells, their max and average absolute quality, the target applied to them, and the max quality relative to that target. Groups are listed worst-relative-first, so the top line names the region holding the optimization back. Off by default: it adds one log line per quality-field entry per iteration, which is noise unless a particular tagged region is failing to converge. The figures are collected in the sweep that computes the mesh-wide max/avg anyway, so enabling this costs logging, not computation.
stuck_refine_stall_eps¶
float · default 0.1
Refine when the last iteration's improvement was at most this fraction of the distance the max energy still has to cover: (prev_max - max) <= eps * (max - stop_energy). Equivalently, refine unless the mesh is on course to reach the target within about 1/eps more iterations. 0 => only when it does not improve at all.
stuck_refine_cooldown¶
int · default 1
After a refinement, skip this many improvement iterations before refining again (let the operations act on the new sizing field). 1 by default: refining every iteration can outrun the operations entirely -- on triwild20k 189017 at eps_rel 1e-4 the mesh runs away to 5.8M faces and never converges at 0, and converges at 9.9994 in 35 iterations at 1. Costs ~5% iterations across the challenging models at no wall-time cost.
stuck_refine_num_worst¶
int · default 0 · min 0
Number of worst tets whose neighborhoods are refined when stuck. 0 => refine all tets with energy above the filter_energy.
stuck_refine_rings¶
int · default 0 · min 0
Graph rings around each worst tet included in the stuck refinement. 0 => only the worst tet itself, 1 => its neighbors, 2 => neighbors of neighbors, etc.
stuck_refine_factor¶
float · default 0.5
Multiplicative reduction of the sizing scalar per stuck refinement (0.5 => halve).
stuck_refine_min_scalar¶
float · default 0.001
Lower bound on the sizing scalar during stuck refinement.
stuck_refine_gradation¶
float · default 2.0
Gradation cap for the monotone sizing smoothing: adjacent sizings may differ by at most this factor (smoothing only lowers values).
stuck_refine_force_split¶
bool · default true
When the max energy stalls, split each worst tet's longest edge once, bypassing the split length gate, to unstick a sliver without changing the sizing field. Adds at most one split per worst tet per stall.
skip_good_regions¶
bool · default false
Only smooth vertices incident to a tet whose energy is at least skip_good_regions_margin * stop_energy; skip smoothing already-good regions. OFF by default: smoothing is the only phase that improves quality without changing connectivity, and the premise that a vertex surrounded by good elements has nothing to gain is not reliable -- for surface vertices the move is driven by the envelope term rather than by element quality, which is why active_vertices() has to append every surface vertex unconditionally to keep the filter from freezing them outright. With the filter off that special case stops carrying the correctness of the pass. Measured in 2D on 122839 at stop_energy 20, filtering also cost more than it saved: 60 iterations ending at max energy 21.03 with it on, against convergence to 19.9998 in 54 iterations and less wall time (875s vs 947s) with it off. Note the threshold scales with stop_energy, so the filter skips far more at 100 than at 20.
skip_good_regions_margin¶
float · default 0.9
A tet is 'active' (worth smoothing around) when its energy is at least this fraction of stop_energy.
fill_holes_tags¶
list of string · default []
For fill_holes_topo: list of tag values used to fill enclosed connected components (processed in order).
Each entry: An intersection of tag values to fill holes.
fill_holes_threshold¶
float · default -1
For fill_holes_topo: only fill a connected component if its size (area in 2D, volume in 3D, in model units) is less than this threshold. Negative value means no threshold (fill all enclosed components).
tight_seal_tag_sets¶
list of list of string · default []
For tight_seal_topo: list of tag sets. Each inner list defines a group of tags whose enclosed holes are filled; each set is exactly two tag names, e.g. [["tag_0", "tag_1"]].
Each entry: One tag set: a list of tag values that are treated as a group for hole filling.
tight_seal_threshold¶
float · default -1
For tight_seal_topo: only fill a hole cluster if its total size (area in 2D, volume in 3D, in model units) is less than this threshold. Negative value means no threshold.
tight_seal_geom_input_selection¶
string · default ""
For tight_seal_geom, required: a Boolean expression on tags, as in resolve_overlaps_tags (_ is a cell with no tag, ambient), picking the cells (faces in 2D, tets in 3D) of the region R that is closed to find the parts to fill. The operation throws if it is empty.
tight_seal_geom_fill_selections¶
list of string · default []
For tight_seal_geom: the colors of the fill, two or more Boolean expressions on tags, as in resolve_overlaps_tags; a cell outside the parts to fill that satisfies expression k has color k, whether it is in the closed region or not (a cell of a part has no color, whatever its tags). A part borders a color if one of its cells shares a facet (an edge in 2D, a face in 3D) with a cell of that color, and is filled if it borders tight_seal_geom_min_regions colors or more, with those it borders. The expressions may not overlap: the operation throws, before changing anything, if any cell of the mesh satisfies more than one of them, so that each color's distance is defined over cells no other color shares. A part is filled thus (tight seal v2 note, section 4.2). Its functions are the distances to the colors it borders, taken at its vertices and linear in each of its cells. In each cell, a function another is strictly smaller than at all its corners is left out; for each pair of the others in turn, every edge of the cell's pieces whose ends lie on opposite sides of the level set where the two are equal is split there, exactly, the new vertex's values interpolated along the edge and the pair counted as equal at it (as is every pair equal at both ends of its edge). A cell is labelled once the label sets of its corners (the functions smallest at each, a pair counted as equal tying) share a color, the first if several; by linearity that color is the nearest on the whole cell. A cell still without one at the end (possible only after a refused split) takes the color nearest its centroid, with a warning. It gets that color's tags (tight_seal_geom_fill_tags) added to its own. No topology is checked.
Each entry: One color: a Boolean expression on tags.
tight_seal_geom_fill_tags¶
list of list of string · default []
For tight_seal_geom: the tags each color adds to the cells of the fill it labels, one list of tag names per entry of tight_seal_geom_fill_selections, in the same order, e.g. [["tag_0"], ["tag_1", "tag_2"]]. They are added to a cell's own tags, never replacing them; an empty list adds nothing. A name the mesh lacks becomes a new tag, with a warning; ambient (no tag) cannot be one. The operation throws unless there are as many lists as fill selections.
Each entry: The tags one color adds.
tight_seal_geom_distance¶
float · default -1
For tight_seal_geom: the distance d, which must be positive. A disk (a ball in 3D) of diameter d moves through the cells outside the region R (tight_seal_geom_input_selection) without entering it or leaving the mesh; the parts it cannot reach are found (the closing of R, minus R), and each is filled if it borders enough colors (see tight_seal_geom_fill_selections). With tol = tight_seal_geom_trace_rel_tol x the mesh's bounding box diagonal, a vertex within d/2 of R, R's own included, is IN if it is at least d/2 + tol from the dilation surface (where the distance to R is d/2), else OUT; the others are OUT. The cells whose vertices are all IN are marked, R's included; each edge from an IN vertex to an OUT one is split where the distance to the dilation surface falls to d/2 + tol, the labels' level, and of the cells it makes, those touching its IN end are marked and the others not (the new vertex takes no label), so R's cells may be split. The marked cells outside R form the parts. The operation throws if any part, filled or not, touches the mesh boundary, even at a vertex: keep R more than d/2 from it.
tight_seal_geom_trace_rel_tol¶
float · default 0.001
For tight_seal_geom, in (0, 1): the tolerance, this x the mesh's bounding box diagonal (independent of tight_seal_geom_distance). The dilation surface is placed where the distance to the region R is d/2, and the parts' boundary where the distance to the dilation surface is d/2 + this tolerance, each by sphere tracing (steps of at least the tolerance) then bisection. A vertex within d/2 of R, R's own included, is IN at least d/2 + tolerance from the dilation surface, else OUT; hence the level d/2 + tolerance of the parts' boundary.
tight_seal_geom_min_regions¶
int · default 2 · min 2
For tight_seal_geom: a part is filled only if it borders at least this many colors (see tight_seal_geom_fill_selections), 2 or more; parts bordering fewer are left alone.
tight_seal_geom_sanity¶
bool · default false
For tight_seal_geom: check the output and throw if a cell is inverted, a filled cell holds none of the tight_seal_geom_fill_tags sets, or a part of the filled cells (connected through edges in 2D, faces in 3D) borders fewer than two colors, which would be a concave feature of one body, filled. For tests; the integration tests set it.
keep_lcc_tags¶
list of string · default []
For keep_lcc: list of tag values for which only the largest connected component is kept.
Each entry: An intersection of tags whose smaller connected components will be removed.
keep_lcc_num¶
int · default 1
Number of largest connected components that are kept. By default, only the largest one is kept.
resolve_overlaps_tags¶
list of list of string · default []
Resolve intersections between tags by filling the areas with intersections with the nearest of the intersecting tags.
Each entry: Two Boolean expressions that define the two intersecting regions.
replace_tags_in¶
list of string · default []
Replace the tags by the output tags.
Each entry: An intersection of tags that should be replaced.
replace_tags_out¶
list of string · default []
The output tags (written as intersection) that should replace the input tags. For each input tag, an output tag must be provided. The order of the output tags should correspond to the order of the input tags.
Each entry: An intersection of tags that should replace the input tags.
tag_priority¶
list of string · default []
List of tags for the tag_priority operation. Tags earlier in the list have higher priority.
Each entry: A tag value.
coarsen_pass¶
bool · default false
Run a final coarsening pass after the optimization has converged. The ordinary collapse judges a candidate on the raw post-collapse geometry -- the worst moment in the operation's life, before smoothing has absorbed any of the damage -- so a collapse that would be fine once its neighbourhood relaxes is never taken, and the converged mesh keeps vertices it does not need. This pass takes the collapse optimistically, re-smooths coarsen_smooth_ring around the merged vertex, and keeps it only if the worst element in the region it touched is no worse than before; every element outside that region is untouched, so 'no worse locally' is exactly 'no worse globally'. Alternates with ordinary smoothing passes, as the main optimization does.
coarsen_local_smoothing_passes¶
int · default 0
Smoothing sweeps over the ring, inside each candidate collapse, before judging it. 0 by default, which means the pass judges the collapse on its raw post-collapse geometry and never smooths inside the operation. At the level of a single candidate that matters -- the composite's reject rate rises from 25% to 39% without it -- but it does not cost coarsening, because the pass runs to a fixed point: a candidate the smoothing would have rescued is replaced by another the pass finds instead, and the relaxation the mesh actually needs comes from the global smoothing between rounds. What it costs is time. The smoothed ball averaged 98 vertices on tetwild's octocat, so at the old default of 2 sweeps one candidate ran ~200 nonlinear smoothing solves and the pass ran 1.4 million of them to accept 5173 collapses. Over seven tetwild models, dropping this to 0 (with coarsen_max_inner_passes 1) made the pass 9.7x to 31.9x faster for about 1 percentage point of cell reduction.
coarsen_smooth_ring¶
int · default 1
Radius smoothed inside the collapse, and the radius the accept test measures over. The lock claims one more ring than this. With coarsen_local_smoothing_passes at 0 nothing is smoothed, so this only sets how wide a region the accept test compares; a wider region is a more permissive test (it admits untouched cells to both the before and after maxima, which is still sound) so ring 2 coarsens slightly more, but it also makes the pass lock 3 rings per operation where the ordinary collapse locks 2, which is the worst thing for its parallel scaling. 1 by default: on octocat that is 2.3x faster than ring 2 for 1.5 percentage points of cell reduction, and it puts the lock footprint back in line with every other pass.
coarsen_global_smoothing_passes¶
int · default 1
Ordinary whole-mesh smoothing passes run between coarsening rounds. This is what makes a second round worth running at all -- see coarsen_max_rounds -- so setting it to 0 collapses the rounds to one.
coarsen_max_rounds¶
int · default 2
Cap on the coarsen/smooth alternation; the pass also stops as soon as a round accepts no collapse. A round does NOT exist to finish what the previous one started: within a round the collapse pass already runs to a fixed point, so repeating the collapse alone finds nothing. What a round adds is the global smoothing in between, which moves that fixed point -- the dirty-epoch retry only re-offers failures next to a SUCCESSFUL collapse, so a whole-mesh smoothing pass is invisible to it, and a rejected composite is rolled back in full so rejections never accumulate progress within a round. Returns decay fast: measured over the 16 challenging triwild models at five rounds, accepted collapses by round were 68.8% / 21.7% / 7.2% / 1.8% / 0.5%. Every round costs a full pre-check sweep over all edges plus a smoothing pass, so the default is two -- they carry 90.5% of the coarsening, and the three that would follow are worth 9.5% for 60% of the pass's budget.
coarsen_max_inner_passes¶
int · default 1
Cap on the collapse pass's own dirty-epoch retry loop within one coarsening round; 0 is uncapped. Distinct from coarsen_max_rounds, which counts collapse+global-smoothing alternations. This counts the passes the retry loop makes inside a single collapse pass, re-offering failures whose neighbourhood a successful collapse disturbed. That filter asks only whether the neighbourhood MOVED, not whether it moved helpfully, so a productive first pass re-offers most of the mesh. 1 by default, i.e. one pass per round and no retry within it: on octocat the first pass found 5110 collapses in 135.8s and the three that followed found 27 in 38.4s. Rounds still repeat the pass, and those do pay off, because the global smoothing between them moves the fixed point in a way this filter cannot see.
coarsen_unbounded¶
bool · default true
Coarsen as far as the quality guarantee allows, instead of stopping at the target edge length. The pass answers 'how few elements can hold this max energy', and that is a more aggressive question than it sounds -- the answer ignores how big the elements become. Measured on the registered tetwild models it takes them from 348k to 60k cells (-82.7%) at max energy raised on none of them, against -43.2% with this off, because a converged mesh is sized by length_rel and the adaptive sizing field rather than by what the quality target strictly requires. On by default: the element count is the thing worth having. Turned off, the pass leaves alone any edge already at or past the collapse threshold (0.8 * the target length, the same one the ordinary collapse uses), since collapsing it only makes its neighbours longer still. The sizing FIELD is deliberately not applied either way: that is the optimizer's own refinement scratch work, and honouring it here would leave the pass unable to undo refinement that turned out to be unnecessary. With a sizing_mesh, the bound follows the field: 0.8 of its length, the one asked for, not the refinement. Either way, limit_collapse_length, when on (the default with a sizing_mesh), keeps the pass from leaving an edge longer than 4/3 of the length asked for.
envelope¶
string · default ""
The envelope of a tagged mesh input: on the memory route the name of an input mesh, on the file route the path of a mesh file, relative to input_dir as the inputs are -- the envelope tetwild, triwild and simwild return (outputs["envelope"]) and write (<output>_envelope.msh). Labelled, as theirs are, it is the reference the first component held its tags to, its input: every envelope, order-2 and feature tube and anchor is built around it, label by label, at this run's own eps, its labels naming the mesh's face tags (2D: edge tags), regions and feature curves. The output is then within this run's eps of the original input however many components came before; built around the mesh received, the bound would grow by one eps per stage. Each input point's anchor is centred on its nearest point of the point's label within the anchor's radius. A label of a held face, edge or feature curve of the mesh that the envelope lacks throws, and so does an input point with no point of its label within its anchor's radius: no component makes input points, so it is not the envelope's. Until 2026-11 an input point was anchored where it arrived. A remeshing first checks, exactly, that every held face (2D: edge) and feature edge received lies in the envelopes of its labels, and throws otherwise, naming the labels, the number outside and the eps: the sender held them to a wider envelope. Nothing is rebuilt around the mesh. Not with use_sample_envelope, nor with envelope_reference "simplified", which builds the envelopes around this run's simplification. The run returns it unchanged as its envelope (on the file route <output>_envelope.msh), so that a chain keeps passing it. The operations that change the tags hold nothing to it and do not read it: they return one built around their result (see /output). Without labels, as bare geometry, it is held to as a whole, as before the labels, and rebuilt from the mesh when a face starts outside it. Not with a .msh input that has an EnvelopeSurface group, which otherwise plays this role.
Run control¶
input_dir¶
string · default ""
Directory where the input files are located. This is injected by the application and should not be set by the user.
num_threads¶
int · default 0
Number of threads. 0 runs sequentially and gives the same result on every run; with more threads the order of the operations depends on the schedule, and the result can change slightly from run to run.
log_file¶
string · default ""
Logs are not just printed on the terminal but also saved in this file.
report¶
string · default ""
A JSON file that stores information about the result and the method execution, e.g., runtime.
throw_on_fail¶
bool · default false
Throw if the output has vertices that could not be rounded (their exact positions have no float64 representation). Without it, the run logs an error and returns: on the memory route the exact positions are in the mesh's V_rational; a written .msh holds their rounding only.
Debug options¶
Diagnostics: slow checks and extra output files. (2)
DEBUG_output · bool · default false
Write the mesh as debug_{}.vtu after every operation. tight_seal_geom also writes debug_{}_join_regions.vtu once it has found its join region J, before filling: cell fields join_region (1 on J's cells), join_component (the number of the J component, connected through faces in 3D and edges in 2D; -1 outside J) and join_filled (1 on the components that are filled); vertex field join_label, each vertex's label in finding J: 0 OUT, 1 IN, and -1 for a vertex made by a split, which takes no label.
DEBUG_sanity_checks · bool · default false
Perform sanity checks after every operation. This can be very slow and should only be used for debugging.