Topological Offset
/ (object)
/
Description
Required
/application (string)
/application
Description
Application name must be topological_offset.Options: ['topological_offset']
/input (string)
/input
Description
Tetrahedral input mesh.Optional
/output (string)
/output
Description
Output file name (without extension).Default: 'out'
/input_dir (string)
/input_dir
Description
Directory where the input files are located. This is injected by the application and should not be set by the user.Default: ''
/offset_selection (string)
/offset_selection
Description
Boolean expression for input simplicial complex to offset. If a single tag (ie ‘tag_0’) is given, single body mode is used.Default: '!_'
/offset_output_tags (list)
/offset_output_tags
Description
Tags to add to elements in the resulting offset region./offset_output_tags/* (string)
/offset_output_tags/*
Description
A tag./protected_tags (list)
/protected_tags
Description
Set of tags that will not be overwritten by the offset./protected_tags/* (string)
/protected_tags/*
Description
A tag./respect_all_topologies (bool)
/respect_all_topologies
Description
If true, the topology (after offset initialization) of every tag is respected as if the offset was to replace all tags. If false, only the topology of the offset is respected.Default: False
/offset_in (bool)
/offset_in
Description
Only relevant for single body mode. Whether to create offset inside bodyDefault: False
/offset_out (bool)
/offset_out
Description
Only relevant for single body mode. Whether to create offset outside bodyDefault: True
/target_distance (float)
/target_distance
Description
Target distance for offset. If < 0, the relative target distance is used to compute this one.Default: -1.0
/target_distance_rel (float)
/target_distance_rel
Description
Target offset distance relative to bounding box of mesh.Default: 0.01
/convergence_target (float)
/convergence_target
Description
Absolute max_dist_err threshold for early termination of optimization. If < 0, computed from convergence_target_rel (relative to target_distance, not the bounding box).Default: -1.0
/convergence_target_rel (float)
/convergence_target_rel
Description
Optimization terminates early once max_dist_err drops to or below this fraction of target_distance. Ignored if convergence_target >= 0.Default: 0.1
/convergence_normal_deviation (float)
/convergence_normal_deviation
Description
AVERAGE normal deviation threshold, IN DEGREES, for early termination of optimization. Tested against avg_norm_dev, not max_norm_dev – the paper’s Termination criterion is the same way round (‘the average sigma_max … both the maximum and mean distance error’), because max normal deviation has a floor set by the input’s sharpest reentrant corner, where the distance field’s normal is discontinuous at every scale, and no refinement or smaller target_distance can lower it. max_norm_dev is still reported, as a diagnostic. The offset must reach both this and convergence_target before the run may stop early. An angle has no natural relative form, so unlike convergence_target there is no _rel counterpart. If <= 0 the criterion is disabled and max_dist_err alone decides convergence, which is the 3D behaviour.Default: -1.0
/throw_on_nonconvergence (bool)
/throw_on_nonconvergence
Description
If true, a run that finishes without meeting the convergence criteria raises an error instead of logging a warning. Default false: a non-converged offset is still a usable one, and the warnings already name which criterion failed. Set true in integration tests so a convergence regression fails the run rather than passing with a warning nobody reads. 2D only – the 3D path does not read it.Default: False
/envelope_size (float)
/envelope_size
Description
Absolute half-width of the tag-region boundary envelope. If < 0, computed from envelope_size_rel.Default: -1.0
/envelope_size_rel (float)
/envelope_size_rel
Description
Half-width, relative to the bounding box diagonal, of the envelope containing every tag-region boundary during optimization. Any operation that would push a region boundary outside it is rejected. Ignored if envelope_size >= 0.Default: 0.001
/region_envelope_from_input (bool)
/region_envelope_from_input
Description
Build the region-boundary envelope from the INPUT mesh, before the offset is constructed, rather than from the mesh the offset construction leaves behind. The band’s tags REPLACE a face’s own rather than joining them, so a region the band grows through loses its tag there and its boundary curve is truncated at whatever contour conservative growth stopped on; an envelope built afterwards caps the triple junction where a region boundary meets the offset at a position that is an artefact of relative_ball_threshold. Building it from the input follows the region’s original, untruncated curve, which relaxes the constraint only along the stretch the band later swallows. Set false for the older behaviour. 2D only.Default: True
/relative_ball_threshold (float)
/relative_ball_threshold
Description
Float between 0 and 1, radius relative to target_distance to stop circle/sphere splitting in conservative distance approximation. Smaller means more accurate offset growth but longer run time.Default: 0.1
/edge_search_termination_len (float)
/edge_search_termination_len
Description
Length below which binary search will be terminated for function-guided edge splittingDefault: 0.001
/sorted_marching (bool)
/sorted_marching
Description
Execute marching tets in decreasing order of edge length. Increases run time, may increase output mesh quality.Default: False
/check_manifoldness (bool)
/check_manifoldness
Description
After performing offset, check if offset region is manifoldDefault: True
/optimize (bool)
/optimize
Description
Run optimization on the offset.Default: False
/save_vtu (bool)
/save_vtu
Description
Save .vtu of output meshDefault: False
/DEBUG_output (bool)
/DEBUG_output
Description
Write the tet mesh as out_{}.vtu after every operation.Default: False
/log_file (string)
/log_file
Description
Logs are not just printed on the terminal but also saved in this file.Default: ''
/report (string)
/report
Description
A JSON file that stores information about the result and the method execution, e.g., runtime.Default: ''
/num_threads (int)
/num_threads
Description
Number of threads used for parallel execution (smoothing, edge collapse). 0 means single-threaded.Default: 0
/smoothing_iterations (int)
/smoothing_iterations
Description
Number of smoothing passes run during offset optimization (only used if optimize is true).Default: 3
/optimization_iterations (int)
/optimization_iterations
Description
Number of split/collapse/swap/smooth passes run during offset optimization (only used if optimize is true).Default: 3
/length_rel (float)
/length_rel
Description
Target edge length relative to the bounding box diagonal. Used to bound which edges edge collapse is allowed to touch (only edges shorter than ⅘ of this length are collapsed). Ignored if length >= 0.Default: 0.05
/length (float)
/length
Description
Target edge length (absolute). If < 0, computed from length_rel.Default: -1.0
/stop_energy (float)
/stop_energy
Description
Target AMIPS quality for tets. Edge collapse will not push an already-on-target region’s quality back above this.Default: 10.0
/max_normal_deviation_deg (float)
/max_normal_deviation_deg
Description
sigma_max. Max normal deviation (degrees, 0-90) allowed across one offset-surface element. Collapse and swap reject moves that would push an already-aligned patch of the offset surface further out of alignment than this, and the sizing field refines wherever it is exceeded. Also sets the derived min_edge_length.Default: 15.0
/min_normal_deviation_deg (float)
/min_normal_deviation_deg
Description
sigma_min. Normal deviation (degrees) below which a stretch of offset surface counts as planar, so the sizing field may coarsen it. Paper value is 2 degrees. 2D only.Default: 2.0
/min_edge_length (float)
/min_edge_length
Description
l_min: the shortest edge the sizing field may ask for, in absolute units. If < 0, derived as 2 * target_distance * sin(max_normal_deviation_deg), the paper’s formula – tied to the offset distance rather than the bounding box, because the offset is what has to be resolved. This is a floor on REFINEMENT, so raising it makes the offset coarser (paper Fig. 18). 2D only.Default: -1.0
/smooth_quadrics_weight (float)
/smooth_quadrics_weight
Description
Blend weight (0-1) toward the quadrics-optimal target vertex during offset-surface smoothing. The remaining weight (1 - smooth_quadrics_weight - smooth_laplacian_weight) stays with the vertex’s previous position.Default: 0.5
/smooth_laplacian_weight (float)
/smooth_laplacian_weight
Description
Blend weight (0-1) toward the Laplacian of neighboring offset-surface vertices during offset-surface smoothing. The remaining weight (1 - smooth_quadrics_weight - smooth_laplacian_weight) stays with the vertex’s previous position.Default: 0.01
/quadrics_svd_threshold (float)
/quadrics_svd_threshold
Description
SVD threshold used when solving for the quadrics-optimal target vertex during offset-surface smoothing. Controls sensitivity to feature edges: lower means more sensitive.Default: 0.01
/min_sizing_scalar (float)
/min_sizing_scalar
Description
Lower bound for the per-vertex sizing field (see max_sizing_scalar). Refinement stops once a vertex’s sizing scalar reaches this fraction of the base target length.Default: 0.01
/max_sizing_scalar (float)
/max_sizing_scalar
Description
Upper bound for the per-vertex sizing field, a multiplier on the target edge length (splitting_l2/collapsing_l2) refined/coarsened once per optimize_offset() iteration based on the mean ratio metric of the offset triangulation (see sizing_mrm_threshold). 1.0 means never coarser than the base target length.Default: 1.0
/sizing_mrm_threshold (float)
/sizing_mrm_threshold
Description
Mean ratio metric threshold used to update the sizing field once per optimize_offset() iteration: for each offset-surface vertex, the sizing scalar is halved (refine) if the worst incident offset triangle’s mean ratio metric is below this, or multiplied by 1.5 (coarsen) if above.Default: 0.5
/sizing_gradation (float)
/sizing_gradation
Description
Gradation cap for the sizing field: neighboring vertices’ sizing scalars may differ by at most this factor. After each mean-ratio-metric refinement pass, the refined vertices’ lower sizing scalar is propagated outward (monotone, only ever lowers a neighbor’s scalar) so the mesh doesn’t jump straight from fine to coarse. <= 1 disables gradation.Default: 2.0
/split_high_valence_threshold (int)
/split_high_valence_threshold
Description
Incident-tet count above which a vertex in a split edge’s link accepts only one valence-increasing split per pass, or 0 to disable. Spreads refinement instead of letting it pile onto one vertex (only used if optimize is true).Default: 0
/skip_good_regions (bool)
/skip_good_regions
Description
Only smooth vertices incident to a tet whose energy is still far from stop_energy. Smoothing a vertex surrounded by good tets does nothing, so skipping it is free (only used if optimize is true).Default: False
/w_amips (float)
/w_amips
Description
Relative weight of the AMIPS quality term against the envelope term during smoothing of non-offset-surface vertices. The envelope weight is derived as 1 - w_amips (only used if optimize is true).Default: 0.0001
/smoothing_mode (string)
/smoothing_mode
Description
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. ‘exact’: minimize w_amips * AMIPS + (1-w_amips) * (d/eps)^2 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.Default: 'projected'
Options: ['projected', 'exact']
/project_line_search_steps (int)
/project_line_search_steps
Description
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.Default: 12
/project_line_search_nested_steps (int)
/project_line_search_nested_steps
Description
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.Default: 0
/perform_sanity_checks (bool)
/perform_sanity_checks
Description
Check after every operation pass that no tet is inverted and no tracked-surface triangle left its envelope. Slow; for debugging (only used if optimize is true).Default: False