MeshTools3D v2.0.1

v2.0.1: ship macOS download-fix helper + docs

Bump project version to 2.0.1. Add scripts/macos-fix-download.sh
(dequarantine + ad-hoc re-sign + verify) and install it at the archive
root on macOS. Replace docs/macOS_bug_fix_v2.0-beta.md with the
version-agnostic docs/macos_download_fix.md; update README and install.md.

MeshTools3D v2.0.0

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

Release v2.0.0-beta.2

Second beta in the v2.0 line. Completes the orchestrator/library split for the meshing path, adds a standalone Laplace solver and a parameter-file builder, and wires up multi-platform release artifacts via GitHub Actions.

Highlights

• Three applications from one build tree
  • meshtools3d — the original mesh generator (now CGAL-isolated)
  • laplace_solver — standalone solver built on the new LaplacePipeline
  • parfile_builder — utility for generating parameter files
• MeshingPipeline library — meshing logic extracted into a reusable, CGAL-free library. CGAL is now confined to main.cpp and CGALDataType.hpp, so downstream consumers can link against the library without pulling CGAL into their build.
• LaplacePipeline library — same orchestrator/logic separation applied to the Laplace solve; powers the new laplace_solver app.
• CPack packaging — cpack produces installable archives per platform.
• GitHub Actions release workflow — on published release, builds and uploads artifacts for Ubuntu 22.04 and macOS. Windows is built but allowed to fail while the GetPot / boost::filesystem issues are tracked separately.
• Run provenance — meshtools3d snapshots the resolved parameters and full invocation per run for reproducibility.

Changes since v2.0-beta

• parfile_builder application added (applications/parfile_builder.cpp)
• Release workflow hardened; Windows job marked experimental
• Roadmap updated (Phase 2b complete, Phase 2c noted as optional)

Known limitations

• Windows builds are not guaranteed. The Windows job in CI is marked continue-on-error pending a fix to GetPot / boost::filesystem.
• Beta API: library headers may still shift before 2.0.0 final.
• No Python wrapper yet (Phase 3) and no CGAL upgrade (Phase 4).

MeshTools3D v2.0-beta (pre-release)

This is the first pre-release of the modernised MeshTools3D. It brings the tool onto CGAL 6.x, restructures the codebase into a reusable library + thin applications, and ships self-contained binaries via GitHub Actions. It is marked as a pre-release because the Python wrapper planned for v2.0 is not yet included — the command-line and library surface are expected to be stable, but the high-level Python API is still on the way.

Users running the legacy CGAL-4.x build should continue to use v1.0 for reproducibility of prior results.

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 as v1.0 and adds a modern build, a reusable C++ library, and a separate standalone Laplace solver that can operate on existing CARP meshes without CGAL.

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 two thin applications (meshtools3d, laplace_solver).
• 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.

Laplace pipeline extraction + standalone solver

• Laplace setup / solve / output extracted into m3d/LaplacePipeline.
• New applications/laplace_solver app — runs the harmonic-extension + thickness pipeline on an existing CARP mesh without dragging in CGAL.
• LaplaceBCConfig accepts both VTX file paths and in-memory node sets, so the same pipeline powers the meshtools3d integrated path and the standalone solver.
• VTK output split: when eval_thickness = true the VTK file carries potential + thickness; when eval_thickness = false 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() helper.
• Two meshing branches (labeled-image vs. manual-segmentation) collapsed into a single runCGALMeshing<Traits>() template dispatcher; 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 now 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 shell 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 and zips on release: published; filenames encode OS and architecture (e.g. meshtools3d-2.0.0-beta.1-macos-arm64.tar.gz).
• macOS: Homebrew dylibs bundled under lib/ with @loader_path rewrites, the tarball runs on a machine without Homebrew installed.
• Windows: vcpkg DLLs bundled alongside the executables.
• Linux: GMP, MPFR, and TBB are treated as system packages and documented as runtime dependencies.
• Push / PR CI (Linux-only) runs on every commit to development and master and on every PR targeting them.

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; binary path present but still untested — see limitations).
  • VTK (binary with correct endianness). Contents depend on eval_thickness (see above).
• Optional CARP-unit rescaling at output time (rescaleFactor).
• "Mesh-then-relabel" mode: mesh without segmentation labels and re-label triangles afterwards (sphereMultilabel example).
• Flags to disable boundary remeshing and mesh relabeling for backwards-compatible pipelines.
• User-selectable meshing parameters and output name/directory 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, available both integrated into meshtools3d and as the standalone laplace_solver app.
• Tetra / Tria centroid evaluation and tetra-gradient post-processing.
• Wall-thickness computation written to VTK.
• VTK writer for the Laplace potential field.

Input / utilities

• Dedicated class for reading and handling .inr volumes.
• Search tree to localise boundary triangles within a bounding box.
• CGAL extensions wrapping the segmentation as a domain-membership function.
• Point location via trilinear interpolation.
• Chrono utility for time profiling.

Performance

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

Portability

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

Build & dependencies

• CGAL 6.1.1 (tested; 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. For reproducing the v1.0
environment, see docs/install_legacy.md.

Known limitations

Pre-release / pending for v2.0 final

• Python wrapper not yet present. The planned API — subprocess runner + GetPot data-file builder from Python dicts/dataclasses + CARP/VTX output parsers — is deferred to v2.0. v2.0-beta users should continue to build data files by hand.
• No CI smoke test. The push/PR CI is build-only; it does not run a reference example end-to-end yet. Planned for v2.0 or shortly after.
• No automated Docker publish. The image is built locally; CI does not yet push to a registry on master merges.

Inherited from v1.0 (unchanged)

• CARP binary output path 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 object cannot re-emit .mesh.
• Boundary-triangle output (standalone surface mesh export) not implemented.
• Triangle re-orientation with outward normals is implemented but unused.

Upgrade notes from v1.0

• Data-file keys and CLI flags are unchanged. A v1.0 data file should drive a v2.0-beta run without edits.
• Output file names and formats are unchanged aside from the VTK-content split (see "VTK output split" above), 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.

Contributors

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

Status

Pre-release. The command-line and library surface are expected to be stable for v2.0; the remaining work before v2.0 final is the Python wrapper plus post-release polish (CI smoke test, Docker publish). Feedback on the standalone laplace_solver workflow and the new packaging is especially welcome during the beta.

MeshTools3D — Legacy Release (v1.0)

This release archives the long-standing CGAL 4.x build of MeshTools3D that has been in active use for atrial mesh generation since 2015. It is published now to preserve a reproducible, citable snapshot of the tool as it was used in years of research. Active development has moved to other branches; this branch is frozen and will receive no further feature work.

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.

Features

Meshing

• Tetrahedral meshing from .inr segmentation input (CGAL Labeled_image_mesh_domain_3).
• Output formats:
  • INRIA .mesh (native CGAL medit format)
  • CARP .elem + .pts with per-region .vtx point lists (ASCII; binary path present but untested)
  • VTK (unlabeled, binary with correct endianness)
• Optional CARP-unit rescaling at output time (rescaleFactor).
• "Mesh-then-relabel" mode: mesh without segmentation labels and re-label triangles afterwards
  (sphereMultilabel example).
• Flags to disable boundary remeshing and mesh relabeling for backwards-compatible pipelines.
• User-selectable meshing algorithm and output mesh name/directory via 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.
• Tetra / Tria centroid evaluation and tetra-gradient post-processing.
• Wall-thickness computation written to VTK.
• VTK writer for the Laplace potential field.

Performance

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

Input / utilities

• Dedicated class for reading and handling .inr volumes.
• Search tree to localise boundary triangles within a bounding box.
• CGAL extensions wrapping the segmentation as a domain-membership function.
• Point location via trilinear interpolation.
• Chrono utility for time profiling.

Portability

• Builds on Linux, macOS, and Windows.
• Dockerfile and dockerM3D.sh helper for containerised use (no local compilation required).

Build & dependencies

• CGAL 4.6 – 4.14.3 (tested range; docs/install_legacy.md documents the reproducible CGAL 4.14.3
  / Ubuntu 20.04 path)
• CMake ≥ 3.x (3.16.9 in the reference legacy build)
• GMP 6.2.1, MPFR 4.1.0, Eigen 3.3.9, zlib 1.2.13, Boost, Intel TBB 2020.3

See docs/install_legacy.md for the full step-by-step legacy build, and Dockerfile for the
container build.

Known limitations (inherited, will not be fixed on this branch)

• CARP binary output path exists but is untested.
• .mesh output not implemented inside the Mesh class.
• Boundary-triangle output not implemented.
• Triangle re-orientation with outward normals is implemented but unused.

Contributors

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

Status

Frozen. This branch is preserved for reproducibility of prior results. New development continues on other branches with an updated CGAL pipeline and refactored architecture.