EIT-Mesher

EIT-MESHER is C++ software, based on the CGAL library, which generates high quality Finite Element Model tetrahedral meshes from binary masks of 3D volume segmentations. Originally developed for biomedical applications in Electrical Impedance Tomography (EIT) to address the need for custom, non-linear refinement in certain areas (e.g. around electrodes), EIT-MESHER can also be used in other fields where custom FEM refinement is required, such as Diffuse Optical Tomography (DOT).

Example Usage
Unit Cube - 'Hello World' example
Meshing segmented brain data
Meshing from STL file
Mesh refinement examples
Mesh deformation

Citing this work

If you use this repository please cite the accompanying JORS article

Dowrick, T., Avery, J., Faulkner, M., Holder, D. and Aristovich, K., 2020. EIT-MESHER – Segmented FEM Mesh Generation and Refinement. Journal of Open Research Software, 8(1), p.27. DOI: http://doi.org/10.5334/jors.321

Using the Meshes

Examples for using the EIT-MESHER outputs with common EIT and DOT solvers are given in solvers examples

Build instructions (tested on Ubuntu 16, 17, 18 and WSL 1&2)

• Install dependencies

sudo apt-get install build-essential cmake libcgal-dev libcgal-qt5-dev libglu1-mesa libxi-dev libxmu-dev libglu1-mesa-dev

• Clone repository

git clone https://github.com/EIT-team/Mesher.git

• Make build & output directories

cd Mesher
mkdir build
mkdir output

• Compile

cd build
cmake ..
make

• Test

cd ../test/
./run_tests

• Run mesher ( from /Mesher root directory)

Usage:
./bin/mesher -i INPUT_INR -e INPUT_ELECTRODES -p INPUT_PARAMETERS
        -i input image file
        -e electrode position file
        -p parameter file
        -o output mesh name (default = new_mesh)
        -d output directory (default = output/)

Example:

./bin/mesher -i inputs/input.inr -e inputs/Electrodes.txt -p inputs/params.txt

Produces the following mesh as viewed in paraview

Docker instructions (for Ubuntu 19&20+, macOS)

EIT-MESHER can be built in a container to install on newer Linux installations. Windows users require WSL2 for docker to work.

Install container

The docker container can be obtained using two different methods:

• Build container from source (mesher is a name of your choice):

docker build -t mesher .

• Pull image directly from dockerhub without having to build, renaming the container to mesher (or name of your choice) :

docker pull doctorjimbles/eit-mesher
docker image tag doctorjimbles/eit-mesher:latest mesher:latest

Running Mesher from container

To test if it is working run the container with no inputs, this will call the mesher with defaults which runs the single example included in the container:

docker run --rm mesher

The --rm flag removes the container after its done to prevent having lots of unnecessary container IDs.

The mesher can then be called with the parameter arguments as normal Note these are files inside the container.

docker run --rm mesher -i inputs/input.inr -e inputs/Electrodes.txt -p inputs/params.txt

• Using your own data - mounting volumes

The container has two root directories /in and /out which can be mounted as volumes to map to directories on the host using the -v flag. So for example, if we had the MESHER repository in our home dir we would add the flags:

 -v ~/Mesher/inputs:/in -v ~/Mesher/output:/out

The mesher can then finally be called by combining the volume definitions and then directing the mesher at the new input location /in/. Note Parameters given must be with respect to the container file structure. So for example, to make the default mesh but using the inputs files in the repository on the host machine (assuming it is stored in /home/user/Mesher):

docker run --rm  -v ~/Mesher/inputs:/in -v ~/Mesher/output:/out  mesher -i /in/input.inr -e /in/Electrodes.txt -p /in/params.txt -d /out/ -o dockertest

This will result in an output mesh dockertest in /home/user/Mesher/output.

To run the NN scalp example (still assuming this repository is stored in /home/user/Mesher)

docker run --rm  -v ~/Mesher/examples/neonatescalp/:/in -v ~/Mesher/examples/neonatescalp/output:/out  mesher -i /in/NNscalp.inr -e /in/NNscalp_elecINRpos.txt -p /in/NNscalp_param.txt -d /out/ -o dockertestNN

• Improving slow file write on some systems

In some systems (reported on macOS 10.15.6, Docker Desktop 2.3.0.4, Docker Engine 19.03.12) it is much slower writing files into the mapped volume. Therefore to improve performance, it is possible to call the mesher and copy the files out afterwards. To do this we remove the --rm flag as we want to keep it, and add the --name flag to give it a name that makes more sense to us. We also drop the -v flag for the \out folder.

docker run --name NNmesher  -v ~/Mesher/examples/neonatescalp/:/in mesher -i /in/NNscalp.inr -e /in/NNscalp_elecINRpos.txt -p /in/NNscalp_param.txt -d /out/ -o dockertestNN

The mesher files can then be copied outside of the container

docker cp NNmesher:/out ./newoutputdir