Skip to content

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.