Skip to content

MeshTools3D v2.0.0

Choose a tag to compare

View all tags
@alonsoJASL alonsoJASL released this 16 Jun 15:04
· 2 commits to master since this release
v2.0.0
4874347

First stable release of the modernised MeshTools3D. It moves the tool onto CGAL 6.x, restructures the codebase into a reusable CGAL-free library plus thin applications, and ships self-contained, multi-platform binaries via GitHub Actions.

Users who need to reproduce v1.0 results should continue to use the legacy CGAL-4.x build (v1.0) — see docs/install_legacy.md.

Overview

MeshTools3D generates 3D tetrahedral atrial meshes from .inr segmentations using CGAL's mesh-from-image pipeline, with optional Laplace-based harmonic extension and wall-thickness computation.

The v2.0 line keeps the same core functionality and data-file contract as v1.0 and adds a modern build, a reusable C++ library, a standalone Laplace solver that runs on existing CARP meshes without CGAL, and a parameter-file generator.

What's new since v1.0

CGAL 4.x → 6.x

  • Full migration to CGAL 6.x with target-based CMake linking (CGAL::CGAL, CGAL::CGAL_ImageIO, TBB::tbb).
  • TBB migrated from task_scheduler_init to tbb::global_control.
  • Custom labeled-image domain wrappers updated for the CGAL 5/6 API.
  • Legacy CGAL 4.14.3 build preserved in docker/Dockerfile.legacy* and docs/install_legacy.md for reproducibility of v1.0 results.

Reusable library (m3d/) + thin applications

  • The main.cpp monolith is factored into a reusable library (m3d/) and three thin applications.
  • The library is CGAL-free: CGAL only appears in applications/main.cpp and m3d/include/CGALDataType.hpp. All solver and mesh code accepts plain C++ data structures, so downstream consumers can link the library without pulling in CGAL.

Three applications from one build tree

  • meshtools3d — the original mesh generator (now CGAL-isolated).
  • laplace_solver — standalone harmonic-extension + thickness pipeline that runs on an existing CARP mesh, built on the new LaplacePipeline. No CGAL.
  • parfile_builder — stdlib-only generator that emits a complete parameter file with documented defaults (--set SECTION.KEY=VALUE overrides, stdout or -o PATH).

Laplace pipeline extraction

  • Laplace setup / solve / output extracted into m3d/LaplacePipeline.
  • LaplaceBCConfig accepts both VTX file paths and in-memory node sets, so the same pipeline powers the integrated meshtools3d path and the standalone solver.
  • VTK output split: with eval_thickness = 1 the VTK file carries potential + thickness; with eval_thickness = 0 it carries region_labels. Region labels are always written as .vtx files regardless.

Meshing-side refactor

  • MeshingParams struct extracted and loaded through loadMeshingParams().
  • TBB setup consolidated into configureTbbThreads().
  • Labeled-image and manual-segmentation branches collapsed into a single runCGALMeshing<Traits>() template; post-meshing boilerplate (writeMeditFile, validateTriangulation, populateCarpMeshFromC3t3) templated in m3d/include/MeshingPipeline.hpp.
  • main.cpp is now a thin driver of library calls.

Reproducibility

  • Every run snapshots its exact inputs next to the outputs:
    • <out_name>_params.data (verbatim copy of the data file) and
    • <out_name>_invocation.sh (re-runnable script containing argv). Sufficient to reproduce a run without guessing CLI overrides.

Packaging and CI

  • GitHub Actions release workflow builds Linux, macOS, and Windows binaries on each published release and attaches them to the GitHub Release.
  • CPack tarballs (Linux/macOS) and zips (Windows); filenames encode OS and architecture (e.g. meshtools3d-2.0.0-macos-arm64.tar.gz).
  • SHA256 checksum sidecars (.sha256) published per artifact, for automated download verification.
  • macOS: Homebrew dylibs bundled under lib/ with @loader_path rewrites; the tarball runs on a machine without Homebrew. The bundled libraries and executables are re-signed (ad-hoc) in-build, so the tools launch on Apple Silicon without a manual codesign step (see "Upgrade / install notes").
  • Windows: vcpkg DLLs bundled alongside the executables (best-effort, see Known limitations).
  • Linux: GMP, MPFR, TBB are treated as system packages and documented as runtime dependencies.
  • Push / PR CI (Linux-only) runs on every commit to development/master and on every PR targeting them.

Documentation

  • docs/parameter_file_schema.md — public reference for the .par parameter file (the contract shared by parfile_builder and downstream consumers; parfile_builder is the source of truth).

Features

Meshing

  • Tetrahedral meshing from .inr segmentation (CGAL Labeled_image_mesh_domain_3).
  • Output formats:
    • INRIA .mesh (native CGAL medit format).
    • CARP .elem + .pts with per-region .vtx point lists (ASCII; a binary path exists but is still untested — see limitations).
    • VTK (binary with correct endianness). Contents depend on eval_thickness.
  • Optional CARP-unit rescaling at output time (rescaleFactor).
  • "Mesh-then-relabel" mode: mesh without segmentation labels and re-label triangles afterwards.
  • Flags to disable boundary remeshing and mesh relabeling for backwards-compatible pipelines.
  • Meshing parameters and output name/directory set via the data file; CLI flags override the data file.

Surface region extraction

  • Endocardium / epicardium / mitral-valve node extraction on constrained boundaries.
  • Epi/endo identification by surface point count (largest → epi, second-largest → endo); optional swap flag.

Laplace solver & thickness

  • Harmonic extension over the tetrahedral mesh, both integrated into meshtools3d and as the standalone laplace_solver.
  • Tetra / Tria centroid evaluation and tetra-gradient post-processing.
  • Wall-thickness computation written to VTK.

Performance

  • Intel TBB shared-memory parallelism for meshing.
  • Thread count via the TBB_NUM_THREADS environment variable (defaults to 1 to avoid saturating the host).
  • Docker image auto-detects available cores.

Portability

  • Builds on Linux, macOS (arm64 and x86_64), and Windows.
  • Self-contained release tarballs / zips from CI.
  • Dockerfile for the CGAL-6 container; docker/Dockerfile.legacy* preserved for the CGAL-4.14.3 reproducibility build.

Build & dependencies

  • CGAL 6.1.1 (the release CI pins this version).
  • CMake ≥ 3.21.
  • GMP, MPFR, Boost, Intel TBB (oneTBB), Eigen, zlib.
  • C++17.

Platform deps:

  • Linux: libgmp-dev libmpfr-dev libboost-dev libtbb-dev zlib1g-dev libeigen3-dev.
  • macOS: brew install gmp mpfr boost tbb eigen (plus CGAL 6.1.1 tarball).
  • Windows: vcpkg (cgal, tbb, zlib).

See docs/install.md for the standard build, docs/install_legacy.md for the v1.0 environment.

Upgrade / install notes

  • Data-file keys and CLI flags are unchanged from v1.0. A v1.0 data file drives a v2.0 run without edits.
  • Output file names and formats are unchanged aside from the VTK-content split (see "Laplace pipeline extraction"), which applies to the same filename the v1.0 path already wrote.
  • The _params.data and _invocation.sh snapshot files are new and appear next to your outputs on every run.
  • macOS (Apple Silicon): these binaries are signed in-build, so no manual codesign step is needed. If macOS still blocks a download launched from Finder, clear the quarantine flag once: xattr -dr com.apple.quarantine <extracted-folder>. (The earlier beta.2 manual re-signing workaround in docs/macOS_bug_fix_v2.0-beta.md no longer applies to v2.0.0 artifacts.)

Known limitations

  • Windows is best-effort. The Windows release job is continue-on-error pending a GetPot / boost::filesystem fix; a build may not be produced for a given release. Linux and macOS are the supported platforms.
  • CARP binary output (out_carp_binary = 1) exists but is untested against a real openCARP consumer.
  • .mesh output is not implemented inside the Mesh class — only CGAL's c3t3.output_to_medit can produce it, so an already-loaded Mesh cannot re-emit .mesh.
  • Boundary-triangle output (standalone surface mesh export) is not implemented.
  • Triangle re-orientation with outward normals is implemented but unused.

Contributors

  • Cesare Corrado — original author
  • Jose Alonso Solis-Lemus

Verifying a downloaded artifact

# Check the published checksum
sha256sum -c meshtools3d-2.0.0-<os>-<arch>.tar.gz.sha256

# Extract and confirm the three tools run
tar xzf meshtools3d-2.0.0-<os>-<arch>.tar.gz
./meshtools3d-2.0.0-<os>-<arch>/bin/meshtools3d --help
./meshtools3d-2.0.0-<os>-<arch>/bin/laplace_solver --help
./meshtools3d-2.0.0-<os>-<arch>/bin/parfile_builder --help
Assets 6
Loading