TetWild (tetwild)¶
Tetrahedralizes triangle surfaces as they come -- open, self-intersecting, non-manifold -- following TetWild: the input is simplified within the envelope, embedded exactly into a Delaunay tet mesh of its bounding box, and the tet mesh is then optimized for quality while the embedded surface stays inside an envelope around the input. filter removes the tets outside. The output keeps the embedded surface as tracked faces, and the inputs' winding numbers on the tets.
Tutorial · Spec source · Defaults · JSON Schema
Cite: Hu et al. 2018, Tetrahedral Meshing in the Wild; Hu et al. 2020, Fast Tetrahedral Meshing in the Wild
Required¶
application¶
string · required · one of tetwild
Application name must be tetwild.
input¶
list of string · required · min 1
List of inputs, each read for what it is: triangles a surface (an OBJ with 'f' records, STL, OFF, a .msh of triangles, ...; on the memory route a mesh with a triangle block), segments a curve (an OBJ of 'l' polylines; a mesh with an edge block), bare vertices points (an OBJ of 'v' records alone; a mesh without either block). Or one tagged tet mesh. Surfaces are simplified, inserted into a background mesh and tracked, each its own input, its face tag named by input_names. Curves are forced into the tetrahedralization exactly -- every edge represented by a chain of tet edges tiling it, endpoint to endpoint -- and held as feature curves, each its own input, its edge tag named by input_names; a vertex of a curve with no incident edge is a point. Points are forced in as tet vertices, exactly, and anchored; the output mesh's point block holds them, each vertex under the names of the inputs with a point there (a curve's lone vertices under the curve's). See feature_envelope_ratio for the tube the curves stay in and the anchors' radius. The curves, the points and the forcing-triangle apexes the insertion builds for the curves (offset by up to 0.1 x the edge length) must lie inside the background box; the input bounding box is grown over them. At least one input is a surface. Until 2026-11 curves and points came in lists of their own, input_edges and input_points, the curves named feature_<i>. A tet mesh -- on the memory route a named mesh with a tetrahedron block, on the file route a .msh with tets -- takes the tagged route: tetwild continues from it as it is, its tets kept, so that a chain of components can go on through tetwild (tetwild -> topological_offset -> ... -> tetwild). Its triangle block's tags are the tracked faces, one input per label, each row oriented by its vertex order, named as the mesh names them; its edge block's tags the feature curves, one feature input per label; its point block's tags the input points, one input per label, anchored where they are (with an envelope, on its point of their label) -- as simwild reads a tagged mesh, and as tetwild writes its own output, which can go back in as it is. tetwild holds no volumes: tets tagged other than ambient are refused (a mesh with volume tags is simwild's to remesh). It must fill its bounding box, as the insertion's background box does: its boundary faces are the wall, held by the box rule, each untracked and in a plane of the box. A tracked boundary face -- a filtered mesh's boundary -- is refused (give a filtered mesh's surfaces as inputs), and so is an untracked one in no plane. Skipped on this route: the simplification, the insertion and the input winding numbers (wn_<i>); eps_rel and length_rel are of the mesh's bounding box diagonal. Refused with it: any other input, input_names, use_legacy_code, and filter "input". Until 2026-11 a tet mesh threw on the memory route, and on the file route its triangles became one input surface, its tets and tags dropped.
Each entry: One input: a triangle surface, a curve or points, or one tagged tet mesh (see /input).
Key options¶
input_names¶
list of string · default []
Names for the inputs, one per entry of /input, at its position there: a surface's face tag and winding-number field, a curve's edge tag. The face tag, on both routes, is a column of the tags of the output mesh's triangle block (<output>final.msh, the memory route's mesh): the tracked faces on the input, each under every input it lies on and oriented as its input, which simwild and topological_offset read back as face tags. An input curve's edge tag is a column of the tags of the output mesh's edge block: the tet edges tiling it. An input without a name is tag<i>, i its position in /input, as simwild and triwild name one. The winding-number field is wn_<name> in the VTU output and on the memory route; the .msh output numbers them, wn_0, wn_1, ..., and so does everything without names.
Each entry: Name for one input.
output¶
string · default "out"
Output file name (without extension): the tet mesh is <output>_final.msh. Next to it <output>_envelope.msh, the memory route's outputs["envelope"]: the reference the tags were held to -- the input, or the simplified input under envelope_reference "simplified" -- labelled as the mesh labels them (a triangle block, one column per input; an edge block of the curves, one column per curve input; a point block of the input points, labelled alike), the envelope a later simwild, manifold_extraction or topological_offset takes. It holds no eps: the receiver builds its own envelopes around it, so a chain stays within one eps of this input.
eps_rel¶
float · default 0.001
Envelope thickness relative to the bounding box diagonal.
length_rel¶
float · default 0.05
Target edge length relative to the bounding box diagonal.
stop_energy¶
float · default 100
Target energy. If all tets have an energy below this, tetwild will stop.
filter¶
string · default "none" · one of flood, input, tracked, none
Remove the outside region based on different criteria. 'flood': flood fill. 'input': winding number w.r.t. the input. 'tracked': winding number w.r.t. the tracked surface. 'none': Do not filter. Flood fill only works if the input is closed. Otherwise, it results in an empty mesh. Filtering w.r.t. the input might cause wrinkles along the surface as some tets might be falsely tagged. 'tracked' orients the tracked surface as the input is (coincident surfaces add up, opposite ones cancel -- solids touching face to face merge), repairing triangles flipped against their neighbours, so it needs no consistent global orientation across components but does need each component closed. With filter_inputs, only those inputs bound the domain kept. On a tagged mesh input (see /input), 'tracked' and 'flood' use its tracked faces as on surface inputs, and 'input' is refused: there is no input surface.
max_iterations¶
int · default 80
Maximum iterations before stopping.
preserve_topology¶
bool · default false
Preserve the topology of the input surface where the phases can. This forces remove_duplicate_eps to merge only exactly coincident vertices, keeps the link condition enabled during the input simplification, and enables the substructure link condition during optimization; when unset, all three are relaxed and the topology may change. Even so, the surface simplification before the insertion may change the topology: the link condition checks connectivity only, and the envelope admits a fold of the surface through itself. The insertion keeps the topology of the surface it receives when that surface does not cross itself, and cuts crossing triangles along their intersection otherwise; that surface is checked once, exactly, and a warning names its crossing pairs of triangles and its degenerate triangles (report: inserted_crossing_pairs, inserted_degenerate_triangles). The optimization after the insertion keeps the topology of the inserted surface, and its input points stay points: no collapse merges one with another, or with a curve or the surface it is not on. The run reports the Euler characteristics of the input surface, of the tracked surface right after the insertion and of the output surface, and warns when the input's and the output's differ (an error with throw_on_fail).
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.
history_output¶
string · default ""
Record every change to the tracked surface, from the input as inserted to the output, and save the history here (see wmtk/history): the tracking component rebuilds the map between the two from it. A filter's removal of tracked faces is recorded too, as faces no map can follow. Not with use_legacy_code. 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.
Other options¶
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 must stay inside -- and the radius of the feature-point anchors, as a fraction of the surface envelope's eps. The default 1 holds them to the same eps as the surface: the tube is built around the input feature curves themselves, which the simplification does not move. See order2_envelope_ratio for the sweep behind the default. The anchors are the 0-dimensional features: every point input's point, and every vertex where a feature curve or an open boundary ends or three or more of them meet. Each stays within its radius of where it was when the optimization began -- where the input put it for input points and feature curves, which the simplification does not move, and where the simplification left it for open boundaries (see order2_envelope_ratio) -- with radius feature_envelope_ratio x eps for input points and feature curves, order2_envelope_ratio x eps for open boundaries, the smaller of the two for a point on both: some output vertex stays within that ball of each anchor, collapses that would break this are refused, and smoothing may move an anchor-carrying vertex only inside its ball. Always on, as the tubes and the surface envelope are. Without the anchors an open feature curve erodes from its own tips: every eroding collapse keeps the surviving chain inside the tube, so no containment test can see it.
envelope¶
string · default ""
The envelope of a tagged mesh input (see /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 input is -- the envelope tetwild, triwild and simwild return (outputs["envelope"]) and write (<output>_envelope.msh), labelled by the tags it holds. It is the reference the first component of a chain held its tags to, and the run holds to it as simwild does: the surface envelope, the per-label envelopes, the order-2 and feature tubes and the curve-end anchors are built around it, label by label, at this run's eps, and each input point's anchor is centred on its nearest point of the point's label within the anchor's radius, its labels matched to the mesh's face tags, feature curves and points by name, so that the output is within this run's eps of the first component's input however many components came before. A label of a tagged face or feature curve of the mesh that the envelope lacks throws, and so does a tagged face or feature edge received outside the envelopes of its labels, checked exactly before the optimization: the sender held it to a wider envelope. 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. The run returns it unchanged as its envelope (on the file route <output>_envelope.msh). Not with use_sample_envelope, nor bare geometry without labels. Empty, the default: the envelopes are built around the tagged faces and curves as received, and those are the envelope returned.
write_vtu¶
bool · default true
Write the VTU output next to the MSH.
simplify¶
bool · default true
If true, the input surface is simplified first. False inserts it as it is.
simplify_use_sample_envelope¶
bool · default false
Use the sampled envelope instead of the exact one for the input simplification only; the tetrahedralisation 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. On thin lattice geometry it has been observed to over-collapse badly.
eps_simplify_rel¶
float · default 0.0005
Envelope thickness used for the input simplification, relative to the same bounding box diagonal as eps_rel. Simplifying inside a tighter envelope than the tetrahedralisation's reserves the remainder as headroom: if the simplification is allowed to place vertices at the full limit, the optimizer starts with a mesh where almost every move already lies outside and most operations are vetoed. The default is half of eps at the default eps_rel, and does not follow eps_rel: under envelope_reference "input" the simplification's eps must be below eps, else the run is refused, so an eps_rel at or below eps_simplify_rel needs it lowered too. Ignored if simplify is false or eps_simplify is positive. Until 2026-11 the key simplify_envelope_ratio, the simplification's eps as a fraction of eps (default 0.5).
eps_simplify¶
float · default -1
Absolute envelope thickness used for the input simplification. When positive it is used instead of eps_simplify_rel, as in simwild; otherwise eps_simplify_rel sets it. Ignored if simplify is false.
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 * the simplification's eps of the input's boundary edges. When false, every boundary vertex is frozen, which also freezes whatever lies between boundary loops packed too tightly to leave a free vertex: on Thingi10K 55928 a 0.02-wide knot holding all 130 boundary edges of the model survives the simplification as a non-manifold tangle and ends up as a cluster of tets three orders of magnitude below the target size. With the envelope, holes and slits narrower than the tube close (when the surface envelope admits the triangles that cover them). Boundary that the simplification opens away from the input's is not judged by the tube, as before. Ignored under preserve_topology, which keeps the boundary frozen.
envelope_reference¶
string · default "input" · one of input, simplified
Which geometry every envelope, tube and anchor is built around: the surface envelope, the order-2 (open boundary) and feature tubes, and the curve anchors, one choice for all. "input": the original input, at eps times each one's ratio; the output is within eps of it. An open boundary or curve end the simplification made is held around itself as the insertion leaves it, since a free one erodes the input along its curve (measured 2026-11: left free, 104509 239 -> 317 input samples farther than eps from the output, crown 554 -> 695), and one it removed is lost, as the topology change it may make without preserve_topology; measured on the integration configs (2026-10), 8 of them carried order-2 curves on no curve of the input. Needs the simplification's eps (eps_simplify_rel or eps_simplify) below eps, else refused: the simplified surface could start outside its envelope. "simplified": the SIMPLIFIED surface, which replaces the input, at eps times each one's ratio; the output is within eps of it, so within the simplification's eps plus eps of the input, and any simplification eps is allowed. Refused with simplify false. The geometry starts at the CENTRE of the envelope it is held to rather than somewhere inside it, which matters since the envelope is a hard veto rather than a penalty (starving that headroom, a simplification at 0.95 eps -- simplify_envelope_ratio 0.95, until 2026-11 -- turned a converging run on Thingi10K 1368052 into a diverging one). Until 2026-11 "simplified" built at eps minus the simplification's eps; until 2026-10 the key optimize_envelope_around_simplified, which moved the surface envelope only.
per_input_envelopes¶
bool · default true
Hold each input to its own envelopes. With two or more input files: one surface envelope per input, 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 inputs, 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, and either way each tracked face records the inputs it lies on, the output's face tags (see input_names); until 2026-11 false gave every face input 0's.
order2_envelope_ratio¶
float · default 1.0
Thickness of the tube that holds the order-2 edges -- the open boundaries of the surface -- as a fraction of the surface envelope's eps, and the radius of the anchors where they end or three or more meet (see feature_envelope_ratio). Under envelope_reference "input" the tube is built around the input's own open boundaries where the inserted ones lie in it, so such a boundary stays within order2_envelope_ratio x eps of the input's; one the simplification made is held in a tube around itself as inserted. Under "simplified", around the simplified boundaries. Until 2026-11 it was built around the simplified boundaries whatever envelope_reference said, and an open boundary could drift order2_envelope_ratio x (eps + the simplification's eps) from the input's, 1.5 eps at the defaults. 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.
use_sample_envelope¶
bool · default false
Use sample envelope instead of exact one.
use_legacy_code¶
bool · default false
Use the original TetWild code for the mesh improvement. This only works with 'use_sample_envelope'! Not with sizing_mesh or limit_collapse_length, which its operations would ignore.
filter_inputs¶
list of string · default []
The inputs that bound the domain a filter keeps, by their labels: the names of the surface inputs (input_names, tag_<i> without one), or a tagged mesh's face-tag labels. Empty, the default: every input, as before the key. With 'input' the winding number of those inputs only; with 'tracked' that of the tracked faces carrying one of them only; with 'flood' the fill crosses every tracked face of the other inputs. So an input that is not named -- an open sheet through a solid, a second solid outside it -- does not cut or add to the domain kept, and stays in the output as tracked faces, its face tag, inside the domain or on its boundary. The field the filter reads (winding_number_input, winding_number_tracked or part) is then of those inputs; the others stay of every input. Under 'tracked' a tracked face carrying a named input and another input (two solids touching face to face) is refused before the filter: a face's orientation is one count for all its inputs, not one per input, so the named inputs' winding number cannot be computed there; 'flood' needs no orientation, and is exact for inputs that do not overlap themselves. Built with the CMake option WMTK_PER_INPUT_ORIENTATION, a face keeps one count per input, and 'tracked' takes the named inputs' own there instead. A name that is not an input throws, and so does the key with filter 'none'.
Each entry: The label of one input that bounds the domain.
skip_winding_number¶
bool · default true
Skip the finalize-phase winding numbers of the input: the whole input's (winding_number_input) and each input's (wn_<i>). The filter needs them unless filter is 'none', and computes them regardless of this flag; otherwise they are written only as output annotation fields, and computing them is a large part of finalize on an open or many-input surface. Default true since 2026-11: set false to have the fields written with filter 'none'.
compute_tracked_winding_number¶
bool · default false
Compute the winding number with respect to the tracked surface and write it (winding_number_tracked) even when filter is not 'tracked', which computes it anyway. Left out of the output otherwise.
compute_flood_fill¶
bool · default false
Compute the flood-fill parts -- the regions the tracked surface separates -- and write them (part) even when filter is not 'flood', which computes them anyway. A serial pass over every tet; left out of the output otherwise.
eps¶
float · default -1
Absolute envelope thickness. If this value is negative, the relative envelope thickness (eps_rel) is used to compute the absolute one. As simwild's eps. Under envelope_reference "input" it must be above the simplification's eps (eps_simplify, else eps_simplify_rel of the diagonal), as eps_rel must.
length¶
float · default -1
Absolute target edge length. If this value is negative, the relative length (length_rel) is used to compute the absolute one. As simwild's length.
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 the edges of the vertex it removes, moved to the one it keeps, can reach 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. In the coarsening pass the target is the one asked for (sizing_mesh, else the global length), not the optimizer's refinement of it. Not with use_legacy_code, whose operations would ignore it.
sizing_mesh¶
string · default ""
A target edge length that varies over space: a tet mesh whose vertices carry the absolute target length as the field 'target_length' (one value per vertex), interpolated linearly inside its tets. 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 triwild's sizing_mesh does: at the start of the optimization, and after every pass as a ceiling, so the vertices a pass makes follow it and refinement is kept. Outside its tets the global length (length, else length_rel) applies; the background mesh fills the input's bounding box grown by 1/15 of its diagonal on each side, so a sizing mesh meant to cover all of it must reach that far. The bounded coarsening pass (coarsen_pass with coarsen_unbounded off) stops at 0.8 of the field's length instead of the global one. Not with use_legacy_code, whose operations would ignore 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.
split_high_valence_threshold¶
int · default 0
Incident-tet count above which a vertex accepts only one valence-increasing split per split pass, or 0 to disable. A well-shaped tet mesh has valence around 20-30; a split cascade can drive one vertex into the thousands, at which point every operation touching it is O(valence) and the pass stalls. Splitting an edge leaves its endpoints' counts unchanged and adds one to each vertex in the edge's link, so the gate applies to the link.
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
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
Number of smoothing passes per optimization iteration. Smoothing is the only phase that improves quality without changing connectivity, so when split, collapse and swap have run out of useful moves it is the only thing that can still lower the energy. Was 10; lowered to 2 once surface vertices stopped being skipped by skip_good_regions, which made each pass do real work -- on Thingi10K 240280 a pass costs 41-51s and moves fewer vertices each time (accepted 18606 -> 17077 over five passes, envelope rejections 11316 -> 12237), so the later passes in a run of 10 buy very little for their cost.
interleaved_smoothing¶
bool · default true
Interleave smoothing between the topology passes: split + smoothing, collapse + smoothing, swaps + smoothing, instead of split, collapse, swaps followed by num_smoothing_passes smoothing passes. On by default in both applications: each topology pass then sees a relaxed mesh rather than the raw output of the previous one. Measured in 2D on 122839, where per iteration it reached a given energy sooner than the batched schedule (102 vs 535 at iteration 5, 25 vs 69 at iteration 13), at roughly 3x the work per iteration since each topology pass gets its own smoothing.
interleaved_smoothing_passes¶
int · default 1
Smoothing passes to run after each topology pass when interleaved_smoothing is set. One is enough with interleaving on, since there are three of them per iteration.
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.
remove_duplicate_eps¶
float · default 0
Remove duplicate vertices in the input meshes that are closer than this fraction of the bounding box diagonal. This is applied to each input mesh separately. 0 merges only exactly coincident vertices, which is still needed to build the surface connectivity; negative skips the pass entirely. Ignored when preserve_topology is set: merging vertices that are merely close welds sheets of the surface together and so removes handles, therefore only exactly coincident vertices are merged in that case.
allow_surface_swap¶
bool · default true
Allow the edge swaps (3-2, 4-4, 5-6) to operate on surface edges, as a topology-preserving surface diagonal flip. When false, every surface edge is left alone.
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.
volume_history_output¶
string · default ""
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 whole volume -- one region, the tracked surface kept on itself -- from the tet mesh the optimization starts from, written as <output>_history_input.msh, to the mesh before the filter, written as <output>_history_output.msh. On the memory route no file is written: any non-empty value records the volume history, 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), and the two meshes as the output meshes history_input and history_output, the rows of the files. It takes several times the room of the surface history. Not with use_legacy_code, nor with coarsen_pass and coarsen_local_smoothing_passes above 0: the coarsening composite smooths a ball of vertices inside one collapse, which the volume history does not see. Empty: no recording.
curve_history_output¶
string · default ""
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): the tracking component rebuilds the map between the two from it, as from triwild's history_output. Its own file, with or without history_output. The output names a point on its curves by two vertices of <output>_final.msh. 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. Recording ends after the filter, as the surface's does, and records the tracked edges of the tets the filter drops as segments no map can follow. Not with use_legacy_code. 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.
max_expected_iterations¶
int · default 0
Fail the run if mesh_improvement needed more than this many iterations, even if it did reach stop_energy. 0 disables the check. This is a regression guard rather than a quality target: an input that normally converges in a handful of iterations and suddenly needs the whole budget means the sizing-refinement trigger stopped firing when it should, which is a silent slowdown that no energy or envelope assertion catches.
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.
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.
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 exception if the output does not fulfil the desired criteria. No output will be generated.
Debug options¶
Diagnostics: slow checks and extra output files. (6)
DEBUG_feature_retention · bool · default false
Sanity check: count how many feature anchors still have a mesh vertex within the anchor ball, measured BEFORE any /filter discards regions (a feature preserved through the optimization is never reported lost because extraction dropped its region), and report the worst miss in multiples of the ball radius. The invariant the anchors maintain (see feature_envelope_ratio), measured rather than assumed.
DEBUG_output · bool · default false
Write the mesh as debug_{}.vtu after every operation.
DEBUG_sanity_checks · bool · default false
Perform sanity checks after every operation. This can be very slow and should only be used for debugging.
DEBUG_hausdorff · bool · default false
Sanity Check: Compute and report the Hausdorff distance of the output to the input. Should be always smaller than eps.
DEBUG_euler · bool · default false
Sanity Check: Compute and report the Euler characteristic of the input and output surfaces and warn if they differ. Off by default because on meshes with many components it can take tens of seconds. It is computed regardless when preserve_topology is set (the topology check needs it).
DEBUG_disable_envelope · bool · default false
Diagnostic only. Disables every envelope containment check during the tetrahedralisation, after the input simplification has run. The envelope is the only thing that rejects an operation for geometric rather than combinatorial reasons, so this answers whether a stalled optimization is blocked by the envelope or by the mesh. The output has no containment guarantee and must not be used.