Tessellation-based Mesh Regularizer

This repo offers the docker image of the regularization program to apply geometric preconditioning of a tessellation-based mesh (generated from Voronoi/Laguerre tessellations) as described in the Regularization of tessellation-based polyhedral models for robust and efficient finite element simulation of bioinspired composites paper.

---

1. Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux) installed and running.
• regularizer:latest docker image obtained from the release package.
• The install.ps1, install.bat, or install.sh scripts from cloning the repo.

2. Load the Docker image

1. Pull the published image:

   docker pull docker.io/rumi381/regularizer:latest

2. Set REG_IMAGE so wrappers use the pulled image:

   • PowerShell / Windows Terminal:

     setx REG_IMAGE "rumi381/regularizer:latest"

   • Bash / zsh:

     export REG_IMAGE=rumi381/regularizer:latest

3. Installation for Convenient Usage (Install the regularize wrapper)

Instead of typing the full path every time, you can install a global regularize command:

Windows (PowerShell & Command Prompt)

Step 1: Run the installation script

cd regularizer
.\install.ps1

Trobleshoot: If running script is blocked in your system, run the following command before running the install.ps1

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Step 2: Set up the regularize command (run the following step-by-step as Administrator)

• Step A: Create Scripts directory and regularize command

  # Step A: Create Scripts directory and regularize command
  $ScriptsDir = "C:\Scripts"
  if (-not (Test-Path $ScriptsDir)) { 
      New-Item -ItemType Directory -Path $ScriptsDir 
  }

• Step B: Create regularize.bat wrapper

  $BatchContent = '@echo off
  powershell.exe -ExecutionPolicy Bypass -File "C:\Users\%USERNAME%\.local\bin\reg.ps1" %*'
  $BatchContent | Out-File -FilePath "$ScriptsDir\regularize.bat" -Encoding ASCII

• Sep C: Add to PATH

  $CurrentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
  if ($CurrentPath -notlike "*$ScriptsDir*") {
      [Environment]::SetEnvironmentVariable("PATH", $CurrentPath + ";$ScriptsDir", "User")
      Write-Host "✓ Added $ScriptsDir to system PATH" -ForegroundColor Green
  }
  Write-Host "✅ Setup complete! Restart your terminal and use: regularize input.ovm --stats --bins 40" -ForegroundColor Green

Step 3: Test the command (restart PowerShell/Command Prompt first)

regularize -h
regularize --2d -h
regularize .\examples\UnitCube_poly1000_CLT200.ovm --stats
regularize --2d .\examples\RandomShape_poly.obj --stats --bins 40

Linux/macOS/WSL

Step 1: Run the installation script

cd regularizer
chmod +x install.sh
./install.sh

The script automatically creates the regularize command with help support

Note for WSL/Linux users: If you get "cannot execute: required file not found" error, run sed -i 's/\r$//' install.sh first to fix Windows line endings.

Step 2: Add to PATH and test

# Add to PATH (add this line to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc for zsh

Step 3: Restart the terminal and verify

regularize -h
regularize --2d -h
regularize .\examples\UnitCube_poly1000_CLT200.ovm --stats
regularize --2d .\examples\RandomShape_poly.obj --stats --bins 40

---

Available flags and their behaviors

The regularize command has two modes:

• 3D mode (default): regularize INPUT_OVM [options]
• 2D mode: regularize --2d INPUT_OBJ [options]

3D mode (INPUT_OVM: Polyhedral mesh)

• Core/help:

  • -h, --help: print full 3D help
  • positional INPUT_OVM: input OVM file path

• Paths and templates:

  • -o, --out OUT_OVM: output OVM path (default <inputDir>/<name>_out.ovm)
  • -c, --case CASE_DIR: OpenFOAM case dir (default <inputDir>/<name>_case)
  • --dict PATH: collapseDict template path
  • --mesh-quality PATH: meshQualityDict template path

• Stats and logging:

  • --stats: print input OVM edge stats/histogram and exit
  • --bins N: histogram bins for --stats (default 30)
  • --show-stats on|off: print input/output OVM edge stats during regularization (default on)
  • --quiet on|off: condensed OpenFOAM logging (default on)
  • --verbose: shorthand for --quiet off

• Pass/behavior control:

  • --edges-only: run edge pass only (default behavior)
  • --faces-only: run face pass only (skip initial edge pass)
  • --faces on|off: toggle face pass (default off)
  • --faces-internal-only: run edge pass first, then face pass on internal faces only
  • --skip-check on|off: toggle pre/post external checkMesh (default on, meaning skipped)
  • --control-quality on|off: toggle quality feedback loop (default on)
  • --maxPointErr N: max times a point may create bad faces before freezing (default 5)
  • --boundary-priority on|off: promote boundary vertices in point priority (default off)

• Collapse parameters:

  • -L, --minEdgeLen VAL: collapse edges shorter than VAL (default 1e-6)
  • -A, --maxMergeAngle VAL: merge nearly inline edges up to VAL degrees (default 30)
  • --faceInitFactor VAL: initial face collapse length factor (default 0.5)
  • --faceToPointCoeff VAL: face-to-point collapse span coefficient (default 0.3)
  • --guardFraction VAL: guard fraction for sliver-face edge collapse (default 0.1)
  • --earlyPoint on|off: allow early face-to-point collapse (default on)
  • --earlyPointCoeff VAL: early-collapse multiplier (default 0.2)
  • --maxIter N: max outer collapse iterations (default 10)
  • --smoothIter N: max reduction-factor smoothing sweeps (default 2)
  • --edgeReduce VAL: edge reduction factor near error regions (default 0.5)
  • --faceReduce VAL: face reduction factor near error regions (default 0.5)
  • --maxPointErr N: max times a point may create bad faces before freezing (default 5)

• Mesh-quality parameters:

  • --mq-maxNonOrtho VAL: max non-orthogonality (default 65)
  • --mq-maxBoundarySkew VAL: max boundary skewness (default 20)
  • --mq-maxInternalSkew VAL: max internal skewness (default 4)
  • --mq-maxConcave VAL: max concavity angle (default 80)
  • --mq-minVol VAL: minimum cell-pyramid volume (default 1e-13)
  • --mq-minTetQuality VAL: minimum tet quality (default 1e-15)
  • --mq-minArea VAL: minimum face area (default -1)
  • --mq-minTwist VAL: minimum face twist (default 0.02)
  • --mq-minDeterminant VAL: minimum determinant (default 0.001)
  • --mq-minFaceWeight VAL: minimum face weight (default 0.05)
  • --mq-minVolRatio VAL: minimum neighbour volume ratio (default 0.01)
  • --mq-minTriangleTwist VAL: minimum triangle twist (default -1)
  • --mq-minEdgeLength VAL: minimum edge length check (default -1)

2D mode (--2d INPUT_OBJ: Polygonal mesh)

Use --2d to operate on planar OBJ meshes with the dedicated polygonal regularizer located in tools/2dMeshRegulizer. All 2D options are forwarded verbatim to polygonalMeshRegularizer.py, so existing workflows migrate directly. The output OBJ is written beside the input (or to --out).

• Core/help:

  • -h, --help: print full 2D help
  • positional INPUT_OBJ: input OBJ path
  • -o, --out OUT_OBJ: output OBJ path (default <inputDir>/<name>_out.obj)

• Stats and logging:

  • --stats: print input edge stats/histogram and exit
  • --bins N: histogram bins for stats output (default 30)
  • --show-stats on|off: print input/output edge stats during regularization (default on)
  • --verbose, -v: enable verbose run logs
  • --precision, -p N: coordinate precision (default 8)

• Regularization controls:

  • -L, --minEdgeLen VAL: collapse threshold (default p10 of mesh if omitted)
  • -maxA, --maxMergeAngle VAL: maximum polygon angle (default 140)
  • -minA, --minMergeAngle VAL: minimum polygon angle (default 30)
  • --minEdgeCount N: minimum edges per regularized polygon (default 4)
  • --maxIter N: max iterations (default: number of polygonal cells)

• Boundary-collapse controls:

  • -albc, --allow-boundary-collapse: enable boundary-edge collapse
  • -L_bc, --boundary-threshold VAL: boundary collapse threshold (default 0.2 * minEdgeLen)

---

Parameter reference and guidance

Use this section to choose knobs in terms of the regularize CLI. OpenFOAM dictionary names are shown only as mapping notes.

3D mode (regularize INPUT_OVM ...)

• Pass-selection knobs:

  • --edges-only: safest/default behavior; only short-edge and inline-edge cleanup.
  • --faces on or --faces-only: enables face-collapse logic; use when sliver/small faces remain after edge pass.
  • --faces-internal-only: recommended first face-pass setting when boundary fidelity is important.

• Primary aggressiveness knobs:

  • -L, --minEdgeLen: main edge-collapse threshold.
    • Increase to remove more short edges.
    • Decrease to preserve resolution/detail.
  • -A, --maxMergeAngle: controls merging of nearly collinear two-edge chains.
    • Higher value merges straighter chains more aggressively.

• Face-pass knobs (effective only when face pass runs):

  • --faceInitFactor: initial face-size trigger.
    • Higher value marks more faces as collapse candidates.
  • --faceToPointCoeff: bias toward collapse-to-point for very small faces.
    • Higher value increases point collapses.
  • --earlyPoint on|off and --earlyPointCoeff: allow/scale earlier point collapse.
    • Turn off to favor edge-style face collapse first.
  • --guardFraction: geometric safety margin for edge-collapse validity inside face collapse.
    • Higher value is more conservative.

• Quality feedback/stability knobs:

  • --control-quality on|off: keep on for production meshes; off removes recovery loop and can admit poor cells.
  • --maxIter: outer recovery iterations when quality issues appear.
  • --smoothIter: smoothing passes for local reduction fields.
  • --edgeReduce, --faceReduce: local reduction multipliers near problematic regions.
    • Lower values clamp local collapse lengths faster.
  • --maxPointErr: freezes repeatedly problematic points sooner/later.
    • Lower value = earlier freezing (more conservative).

• Mesh-quality limit knobs (--mq-*):

  • --mq-maxNonOrtho (default 65): upper bound on face non-orthogonality.
    • Stricter CFD/FEM robustness: 45-60.
    • Keep near default for general-purpose regularization.
  • --mq-maxBoundarySkew (default 20) and --mq-maxInternalSkew (default 4): skewness caps.
    • If boundary distortion is acceptable, boundary limit can be looser than internal.
    • For strict solvers, lower internal skew first.
  • --mq-maxConcave (default 80): max face concavity angle.
    • Lower value enforces more convex faces but can reduce accepted collapses.
    • Keep default unless concavity-driven issues are observed.
  • --mq-minVol (default 1e-13): minimum cell-pyramid volume.
    • Increase when near-zero/negative volume risk appears after aggressive collapses.
    • Avoid setting too high or many valid operations will be rejected.
  • --mq-minTetQuality (default 1e-15): minimum face-decomposition tet quality.
    • Raise gradually for stricter element-shape control if solver conditioning is poor.
  • --mq-minArea (default -1, disabled): minimum face area.
    • Enable with a small positive value only if tiny faces remain problematic.
  • --mq-minTwist (default 0.02): minimum face twist quality.
    • Increase if twisted faces remain; decrease only if it blocks necessary simplification.
  • --mq-minDeterminant (default 0.001): minimum normalized cell determinant.
    • Increase for stronger protection against folded/degenerate cells.
  • --mq-minFaceWeight (default 0.05): lower bound on interpolation/orthogonality face weight.
    • Increase for stricter stencil quality; may reduce accepted collapses near complex regions.
  • --mq-minVolRatio (default 0.01): minimum neighboring-cell volume ratio.
    • Raise to avoid extreme size jumps between adjacent cells.
  • --mq-minTriangleTwist (default -1, effectively disabled): minimum per-triangle twist.
    • Enable only if downstream tooling explicitly requires this constraint.
  • --mq-minEdgeLength (default -1, disabled): extra quality-time minimum edge-length check.
    • Enable if you must block creation/persistence of very short edges during quality checks.
  • Practical default guidance:
    • For most meshes, defaults are a solid starting point and usually sufficient for robust regularization.
    • Tighten only one or two limits at a time when specific quality defects persist.
    • If collapses stall early, relax the most restrictive limit instead of loosening all limits together.

• Operational/diagnostic knobs:

  • --skip-check off: run external checkMesh before/after pipeline.
  • --show-stats on|off: print input/output OVM edge histograms around run.
  • --boundary-priority on|off: preserve boundary vertices more strongly during OVM->FOAM conversion.

2D mode (regularize --2d INPUT_OBJ ...)

• Core aggressiveness and convergence:

  • -L, --minEdgeLen: target edge-collapse threshold.
    • If omitted, threshold defaults to input P10 edge length.
    • Increase for stronger cleanup; decrease to preserve detail.
  • --maxIter: max iterations.
    • Default is effective mesh-size scaling when left at parser default.

• Shape-quality constraints:

  • -minA, --minMergeAngle: minimum interior angle allowed after candidate collapse.
    • Higher value prevents sharp angles; may reduce accepted collapses.
  • -maxA, --maxMergeAngle: maximum interior angle allowed.
    • Lower value avoids flat/elongated polygons; may reduce accepted collapses.
  • --minEdgeCount: minimum polygon side count after operations.
    • Higher value preserves richer polygons; lower allows stronger simplification.

• Boundary processing:

  • -albc, --allow-boundary-collapse: enables boundary-edge collapse branch.
  • -L_bc, --boundary-threshold: boundary collapse cutoff.
    • If omitted, uses 0.2 * --minEdgeLen (or 0.2 * P10 when -L omitted).

• Stats/output controls:

  • --stats: print input stats/histogram and exit.
  • --bins: histogram bins.
  • --show-stats on|off: for regularization runs, print input and output stats.
  • -p, --precision: OBJ output coordinate precision.
  • -v, --verbose: detailed iteration/collapse logging.

• 2D tuning workflow:

  • Run --stats first, then choose -L near P10 or P25.
  • If too few collapses occur, increase -L or relax angle bounds.
  • If shape quality degrades, lower -L, tighten -maxA, or increase -minA/--minEdgeCount.

Interpreting logs

• "Collapsing N small edges / in line edges": edge-collapsing activity. Raise --minEdgeLen/--maxMergeAngle if too low.
• "Collapsing X faces (to point = a, to edge = b)": face-collapsing activity. Raise --faceInitFactor or --faceToPointCoeff to increase.
• "Uncollapsed edges = U / T": edges dropped after consistency checks (preventing pinched faces/cell collapse). Large U suggests over-aggressive thresholds.
• "Number of bad faces": tracked quality issues across outer iterations; should decrease to zero as thresholds are relaxed/smoothed.

---

Usage examples

Use the same commands you would run when building the image locally—only the Docker image source changed.

• Stats on a volumetric OVM mesh

  regularize path/to/input_mesh.ovm --stats --bins 40

• Full 3D regularization with custom tolerances

  regularize path/to/input_mesh.ovm --faces-internal-only -L 0.5 -A 60 --faceInitFactor 0.9 --maxIter 100 --smoothIter 100

• 2D OBJ workflow

  regularize --2d path/to/input_mesh.obj --stats
  regularize --2d path/to/input_mesh.obj -L 0.35 -albc -L_bc 0.1

For additional parameters, run regularize -h or regularize --2d -h.

---

Citation

For more details, you can read the regularization paper DOI. And if you use this regularization program in academic work, please cite:

@article{rumi2026regularization,
  title={Regularization of tessellation-based polyhedral models for robust and efficient finite element simulation of bioinspired composites},
  author={Rumi, Md Jalal Uddin and Zeng, Xiaowei},
  journal={Advances in Engineering Software},
  volume={217},
  pages={104165},
  year={2026},
  publisher={Elsevier}
}

---

You are now ready to work with the regularizer entirely from the distributed Docker image.