MultiCompMesher

This program utilizes and extends CGAL 3D mesh generation functionality to generate an element-labeled multi-component tetrahedral mesh.

This program reads a list of watertight boundary surface meshes, and a sign file describing the spatial relationship between each desired component and the boundary meshes, then generates a tetrahedral mesh with each component labeled separately according to the boundaries and the component signs.

This program can not generate a tetrahedral mesh from .swc morphology data commonly acquired from Light Microscopic (LM) imaging. For this purpose please visit https://github.com/CNS-OIST/SWCTetMesher.

Prerequisite

• git
• a C++ compiler
• CMake
• CGAL
• Boost

Compilation

git clone https://github.com/CNS-OIST/MultiCompMesher.git
cd MultiCompMesher
mkdir build
cd build
cmake ..
make

Usage

The commands below assume you are still in MultiCompMesher/build

• Basic usage

  ./MultiCompMesher BOUNDARY-FILE COMPONENT-FILE OUTPUT
  

  • BOUNDARY-FILE: a plain text file where each line stores the path to a boundary surface mesh file (in .off|.obj|.stl|.ply|.ts|.vtp format).
    All lines starting with the # sign are considered as comments, and will be ignored by the program. Empty lines are also ignored.

  • COMPONENT-FILE: a plain text file where each line labels the relationship between each component and the boundaries using + (exclusive), - (inclusive) or * (ignored) signs.
    For example, assume that there are three boundaries, b1, b2 and b3. A component labeled -++ means the tetrahedrons of the component should be in b1, and should not be in b2 and b3. A component labelled +-* means the tetrahedrons of the component should not be in b1, should be in b2 and b3 is ignored (it could either be in or out of b3). The first component appears in the file will be labeled as component 1, and the rest will be labeled by incremental order. When a point could be in several components, it is attributed to the component with lowest identifier. All lines starting with the # sign are considered as comments, and will be ignored by the program. Empty lines are also ignored.

  • OUTPUT: Path to the output mesh file. The output mesh is in .mesh format, which can be opened and converted to other formats in Gmsh.

• Advance usage

  • Mesh repairing

    If there is problem with one or more boundary meshes, such as orientation issue, this program will try to repair the mesh and save the repaired version to another file. The program will then use the repaired mesh in later steps to generate the tetrahedral mesh.

  • Mesh intersection detection

    The program will automatically detect any intersection between mesh boundaries, and will raise an error if intersection is found. This is required for maintaining manifoldness of the generated mesh (--manifold 1 and --manifold 2, see Mainifoldness below). To skip the detection and continue the program as it is, add --no-intersect-check to the command.

  • Individual patch/component sizing control

    The --size-field-file SIZING-FIELD-FILE option accepts a SIZING-FIELD-FILE as input, allowing individual configuration of patches and components over the global settings. This is particularly useful if the user wants to increase the fineness of a specific patch/component without a dramatic increase of global element count.

    A SIZING-FIELD-FILE is a plain text file similar to the example file

    # patch between Cyto and ER
    patch 1 3 0.005 0.0001
    # component 2 (PSD)
    component 2 0.005
    # local refinement shell across a thin gap at (0.1, 0.2, 0.3)
    sphere 0.1 0.2 0.3 0 0.01 0.002
    

    Four types of inputs are accepted in the file:

    1. Comments and empty lines

       Lines starting with # are considered as comments and will be skipped in the process. Empty lines are also ignored.

    2. Patch setting

       patch COMPONENT-ID1 COMPONENT-ID2 PATCH-FC-SIZE PATCH-FC-DISTANCE
       

       The COMPONENT-ID is the order of appearance of components in the COMPONENT-FILE, note that 0 is the COMPONENT-ID for outer space, so patch 0 1 defines the patch of surface boundary formed by component 1.

       PATCH-FC-SIZE and PATCH-FC-DISTANCE are the fc-size and fc-distance configuration specific to this patch.

    3. Component setting

       component COMPONENT-ID COMPONENT-CC-SIZE
       

       The COMPONENT-ID is the order of appearance of components in the COMPONENT-FILE, note that 0 is the COMPONENT-ID for outer space, so COMPONENT-ID should always be positive.

       COMPONENT-CC-SIZE is the cc-size configuration specific to this component.

    4. Sphere setting (local refinement shell)

       sphere CX CY CZ INNER OUTER SIZE
       

       Refines cells and facets whose location falls within the spherical shell centred at (CX, CY, CZ) between radii INNER and OUTER down to SIZE (the smaller of the local and global size wins). Set INNER to 0 for a solid ball.

       Unlike patch/component, which key off component identity, a sphere is purely geometric, so it refines wherever it overlaps regardless of which compartments are nearby. This is intended for resolving thin gaps between compartments: a shell straddling a body's surface refines the cytosol layer in the gap (so close compartments don't collapse into contact) without refining the body's whole interior — many small spheres along a contact cost far fewer elements than refining an entire patch. Facet distance inside a sphere is scaled to a quarter of SIZE so the refined facets hug the surface tightly.

    5. Surface setting (local refinement near a marker surface)

       surface MARKER-OFF DISTANCE SIZE
       

       Refines cells and facets within DISTANCE of the marker surface mesh MARKER-OFF (any format CGAL can read) down to SIZE. Like sphere it is purely geometric, but it conforms to the marker's shape rather than a ball — the faithful way to refine along an arbitrary morphology marking (e.g. a synaptic active zone given as its own surface patch). Distance is computed with a CGAL AABB tree over the marker's triangles. For a flat patch this refines a slab hugging it; for many small markers, prefer this over packing spheres.

  • Mainifoldness

    This program supports three manifoldness settings in mesh generation, which can be speficified by one of the following options:

    1. --manifold 0: Apply the Non manifold option in CGAL.

    2. --manifold 1: Apply the Manifold option in CGAL.

    3. --manifold 2: Apply the Manifold with boundary option in CGAL.

Other parameters can be set to control the meshing process and optimize the mesh quality. You can list them using

./MultiCompMesher -h

The usage of these parameters can be found in the CGAL 3D mesh generation manual.

Concurrency (Parallel) mode

If Intel's TBB library is installed and found, the program will try to use concurrency mode for meshing. Users can disable it and uses sequential mode instead by setting the ACTIVATE_CONCURRENCY flag during compilation

cmake -DACTIVATE_CONCURRENCY=OFF ..

Example

This example generates a mesh modeling a dendritic spine, with three labeled components, the spine cytosol (excluding the other two components), the Endoplasmic Reticulum (ER), and the Postsynaptic Density (PSD) region.

The boundary file stores the path to the three boundary surfaces.

1. spine boundary
2. ER boundary
3. PSD boundary

The component file defines three components.

1. The spine cytosol excluding ER and PSD: -++
2. The ER: --+
3. The PSD: -+-

The command to generate the mesh is

# assumed still in MultiCompMesher/build

./MultiCompMesher ../example/boundaries.txt ../example/components.txt ../example/output --fc-size 0.01 --fc-distance 0.001 --cc-size 0.05 --odt --lloyd --perturb --exude --no-intersect-check

(The example PSD surface sits inside the spine by design, so the components overlap; --no-intersect-check skips the intersection guard for this case.) The mesh is written to output.mesh, then visualized in Gmsh. Note that each component is labeled and colored individually. To use the mesh in STEPS, the user needs to export it to the Abaqus inp format or the Gmsh 2.0 ASCii format in Gmsh.

Using these sizing settings, we can decrease the global resolution but increase the resolution of the ER membrane, as well as the PSD region component, resulting in a geometry-adapted mesh.

./MultiCompMesher ../example/boundaries.txt ../example/components.txt ../example/sizing-output --fc-size 0.1 --fc-distance 0.01 --cc-size 0.1 --odt --lloyd --perturb --exude --no-intersect-check --size-field-file ../example/sizefields.txt 

The sphere directive refines a purely geometric region rather than a named component. With this size field — a single solid ball centred on the ER — the mesh is coarse (cc-size 0.1) everywhere except inside the ball, which is refined to 0.012:

./MultiCompMesher ../example/boundaries.txt ../example/components.txt ../example/sphere-output --fc-size 0.1 --fc-distance 0.01 --cc-size 0.1 --odt --lloyd --perturb --exude --no-intersect-check --size-field-file ../example/sphere_sizefield.txt

A cross-section through sphere-output.mesh shows the dense tetrahedra confined to the ball (red outline), leaving the rest of the spine coarse — useful for refining a local region (or, with many small shells, a thin inter-compartment gap) without inflating the global element count.

The surface directive refines near a marker surface instead of a ball, so the refined region follows the marker's shape. With this size field — refine within 0.1 of the PSD surface down to 0.012 — the mesh stays coarse (cc-size 0.1) everywhere except in a shell hugging the PSD:

./MultiCompMesher ../example/boundaries.txt ../example/components.txt ../example/surface-output --fc-size 0.1 --fc-distance 0.01 --cc-size 0.1 --odt --lloyd --perturb --exude --no-intersect-check --size-field-file ../example/surface_sizefield.txt

A vertical cross-section through surface-output.mesh shows the dense tetrahedra following the PSD surface (red) — conforming to its shape — while the rest of the spine stays coarse. This is the faithful way to refine along an arbitrary morphology marking (e.g. a synaptic active zone supplied as its own surface patch) rather than approximating it with a ball.