Prismatic mesh (prismatic_mesh)¶
Work in progress
This component is under development. Its options may change, and it has no tutorial yet.
Work in progress. From a topological_offset construction (a .vtu, or a .msh with corr_input_vid), thins the offset band around the solid to a target thickness and, with prism_dominant, rebuilds it as prisms, pyramids and tets.
Spec source · Defaults · JSON Schema
Required¶
application¶
string · required · one of prismatic_mesh
Application name must be prismatic_mesh.
input¶
string · required
Construction .vtu or Gmsh 4.1 .msh with corr_input_vid. MSH can derive labels and cell tags from the tag_0/offset/ambient physical groups; explicit PRISM fields are also supported.
output¶
string · required
Output .vtu or .msh (Gmsh 4.1 ASCII) filename, relative to the JSON directory. A missing extension becomes .vtu.
Key options¶
thicknessratio¶
float · default 0.1
Positive target thickness relative to the mean length of unique input surface edges.
iterations¶
int · default 5
Number of original collapse/target-smoothing iterations. Zero computes targets without this optimization stage; hybrid relocation postpasses have independent iteration settings.
prism_dominant¶
bool · default false
After optimization, reconstruct conforming prisms, input-apex shell pyramids and tetrahedra. Retained background receives kernel-point pyramids in feasible disjoint quad-diagonal edge-star cavities. Preserve existing points, input volume and non-cavity background; fall back to conforming tet regions on failed geometry, overlap or search limits.
keep_background_mesh¶
bool · default false
Keep exterior background tetrahedra during optimization/output. Background must remain strictly positive. Without background_remeshing only offset vertices move. Targets are computed from the band alone.
Other options¶
rod_mode¶
bool · default false
Build rods from original-correspondence offset regions collapsed to vertex rings. Equalize degrees along each path and map matching transported material slots. Construct adjacent-ring prism layers atomically, swap exterior interfaces when needed, and connect retained background through pyramids. Preserve input volume, shell reconstruction and protected attachment stars; invalid layers retain tets. Requires explicit input labels and correspondence.
bad_tet_transition_expansion_rounds¶
int · default 0
Optional bounded outer retries after the configured hybrid relocation stages, in [0,5]. Each retry finds actual shell tets above relocation_amips_threshold, freezes their offset corner seeds, and marks all three offset vertices of every incident all-offset triangle. Preserve prior transition marks, rebuild conforming prism/pyramid/tet regions, then repeat the configured relocation stages with fresh stage-entry bounds. This grows exactly one vertex ring per retry, not a recursive flood. Input labels, correspondence and no-collapse topology protection are preserved. Zero disables; requires prism_dominant.
rod_radius¶
float · default 0.0
Rod mode only. Absolute target section radius; positive, or zero to use thicknessratio times the mean centerline edge length. Infeasible circular targets retain valid geometry and are reported.
ignore_background_mesh¶
bool · default false
Explicitly discard background tetrahedra before rod preprocessing and joint optimization. Keep input volume and offset band, remove background constraints and background-pyramid reconstruction, and do not reattach the discarded mesh. Overrides keep_background_mesh. Intended for a band-only result or a background-constraint comparison.
export_input_and_shell¶
bool · default false
Additionally export the union of input volume and offset band as <output_stem>_input_shell.msh and .vtu, using the same final coordinates, hybrid cells and attributes while omitting background cells.
min_tet_volume¶
float · default 0
Optional nonnegative signed-volume floor for new or modified shell tetrahedra, candidate pyramid decompositions and new background pyramid cavity cones. The default zero requires strictly positive volume using exact predicates, without a coordinate-scale-dependent cutoff. Background optimization and unchanged background tets also require strictly positive volume.
smoothing_max_backtracks¶
int · default 40
Maximum smoothing step halvings after the full target step; between 0 and 60.
jacobian_smoothing_iterations¶
int · default 0
Optional prism Jacobian smoothing rounds after tet optimization. Zero disables this stage. Only offset vertices move; input, correspondence and connectivity remain fixed.
relative_tet_volume_floor¶
float · default 0.0
Optional fraction in [0,1). Each collapse or smoothing move must retain more than this fraction of every modified surviving tet's volume, including background. Zero keeps the original strict-positive rule. Deleted collapse cells are excluded. The absolute band min_tet_volume floor still applies.
transition_smoothing_iterations¶
int · default 0
Optional local convex-envelope initialization and concave-hinge smoothing after hybrid construction, in [0,100]. Only outer offset vertices in protected/marked transition neighborhoods move. Input, correspondence, connectivity and completed rod-prism frames stay fixed; every step checks reference tets, native prism/pyramid Jacobians and native shape quality. Zero disables this stage.
thickness_smoothing_iterations¶
int · default 0
Optional final coupled offset smoothing rounds, in [0,200]. Fits shell normal offset distance and rod section radius/plane while improving native prism AMIPS. Neighboring free rod offsets may move together. Input and protected offset vertices, correspondence and connectivity stay fixed. Tets and pyramids supply positivity constraints only; their shape quality is not optimized. Zero disables this stage.
collapse_edge_relocation_iterations¶
int · default 20
First-class local-domain AMIPS relocation rounds, in [0,200]. Defaults to 20 for prism_dominant output, implicitly disabled for pure-tet output; an explicit zero disables this stage. Select bad actual shell tets with a same-correspondence/same-component offset edge. Parameterize the common endpoint triangle patch of the current offset surface into a convex-boundary harmonic disk. Move only the two ends using analytic incident-tet AMIPS gradients pulled back into that shared domain. Bound each halving line search by the first domain boundary or UV triangle-collapse event. Accept only strict decrease of the actual summed AMIPS over all incident tets, including background, while preserving cell positivity. Individual tet quality may worsen; no per-cell quality caps or additional Armijo sufficient-decrease test apply. No target position, normal, spring, thickness energy or thickness-scaled displacement bound is used. Invalid or non-disk patches are reported and skipped. Explicit nonzero requests require prism_dominant.
prism_tet_relocation_iterations¶
int · default 0
Optional final AMIPS-plus-thickness relocation rounds for bad shell tets emitted from Jacobian-valid prism candidates, in [0,200]. Residual same-component edges take priority in classification. Move only offset corners of the remaining bad tets, minimizing incident reference-tet AMIPS/3 plus relocation_thickness_weight times squared relative normal-thickness error. Honor a hard thickness-error band and per-cell quality caps; keep all neighboring native prisms/pyramids positive. Requires prism_dominant; zero disables this class.
tet_face_relocation_iterations¶
int · default 20
Final offset-face vertex relocation rounds, in [0,200], after domain and optional prism-tet relocation. Defaults to 20 for prism_dominant output, implicitly disabled for pure-tet output; an explicit zero disables this stage. Rescan all current actual shell tets regardless of AMIPS or original class. Select their movable offset vertices lying on all-offset triangular faces. Shared prism/pyramid corners may move when tet_face_relocation_allow_mixed_cells is true; all neighboring native cells must remain positive. Minimize all incident reference-tet AMIPS/3, including background and prism/pyramid reference decompositions, plus projected-thickness energy. Accept strictly decreasing actual combined energy while preserving positivity, thickness-error and displacement bounds; no individual quality caps or seed-quality monotonicity tests. Explicit nonzero requests require prism_dominant.
tet_face_relocation_allow_mixed_cells¶
bool · default true
Allow final tet-face relocation to move offset vertices shared with native prisms or pyramids, while preserving positivity of every incident native cell and reference tet. False reproduces the earlier selection restricted to entirely tetrahedral native one-rings. Only vertices incident to an actual shell tet are selected in either mode.
relocation_amips_threshold¶
float · default 100.0
Raw tet AMIPS threshold for classifying both bad-quality regions, finite and at least 3 (ideal tet = 3). First-class domain relocation has no per-tet acceptance cap and requires decreasing total incident AMIPS. Only second-class prism-tet relocation caps each touched tet at max(this threshold, its entry AMIPS), tightened after improvement. This threshold is not a global precondition on collapse/target smoothing.
relocation_thickness_weight¶
float · default 1000.0
Positive weight on sum((normal_thickness/target_thickness - 1)^2) for prism-tet and final tet-face relocation, added to all incident reference-tet AMIPS/3. Uses the fixed optimal normal, or column direction for singular/unavailable normals. It does not affect first-class offset-domain AMIPS relocation.
relocation_thickness_tolerance¶
float · default 0.1
Relative normal-thickness error allowed for prism-tet and final tet-face relocation, in [0,1). Existing out-of-band errors may improve without exceeding their error at entry to the corresponding stage. This is projected thickness, not nearest-surface distance. It does not constrain first-class offset-domain relocation.
relocation_max_displacement_ratio¶
float · default 0.5
Positive total displacement bound for prism-tet and final tet-face relocation, relative to target thickness and measured from entry to the corresponding stage. Individual steps are at most 0.2 thickness. First-class displacement is bounded by the common local surface domain instead. All stages preserve positivity, shell min_tet_volume and optional relative volume checks; only legacy prism-tet relocation imposes per-cell quality caps.
jacobian_target¶
float · default 0.01
Positive target det(J), normalized by twice input triangle area times initial mean column length.
jacobian_position_weight¶
float · default 0.001
Positive quadratic weight on displacement from the position before Jacobian smoothing, normalized by target thickness (initial column length if unavailable).
jacobian_max_step_ratio¶
float · default 0.25
Positive per-move displacement bound relative to thickness. Implemented with an inscribed axis-aligned box.
jacobian_max_displacement_ratio¶
float · default 0.5
Positive total displacement bound from the position before Jacobian smoothing, relative to thickness. Implemented with an inscribed axis-aligned box.
background_remeshing¶
bool · default false
Enable adaptive background 2-3/3-2 swaps and interior relaxation after each tet iteration, then retry collapse. Requires keep_background_mesh=true. Input/offset vertices and exterior boundary are fixed during remeshing.
background_remeshing_passes¶
int · default 2
Local remeshing passes per tet iteration; positive.
background_quality_threshold¶
float · default 0.1
Trigger on background mean ratio below this threshold in (0,1]; 1 is a regular tet, 0 is degenerate. Background-blocked collapses are also repair targets.
background_remeshing_max_operations¶
int · default 500
Maximum accepted background swaps/moves per tet iteration; positive.
background_remeshing_max_attempts¶
int · default 20000
Maximum attempted background swaps/moves per tet iteration; positive.
Run control¶
input_dir¶
string · default ""
Base directory for input; set by wmtk_app to the JSON directory.