Skip to content

Latest commit

 

History

History
253 lines (175 loc) · 12.2 KB

README.md

File metadata and controls

253 lines (175 loc) · 12.2 KB
Raw

CobivecoX

Consistent biventricular coordinates (https://doi.org/10.1016/j.media.2021.102247 / https://arxiv.org/abs/2102.02898)

CobivecoX on geometries including the four valve annuli

abstract_medima2023_whitebackground

Cobiveco 1.0 on geometries with a flat base

Coordinates

Overview

This is a MATLAB implementation to compute local coordinates on tetrahedral meshes of biventricular cardiac geometries. Also provided are functions to utilize the results for transferring data, standardized visualization of data and alignment of the heart with the global coordinate axes. CobivecoX is backwards compatible with Cobiveco and can be applied to both meshes with and without including the valve annuli.

How to install CobivecoX (macOS Monterey)

  1. A MATLAB installation version 2022a (or above) is required to run CobivecoX. Check this link on how to install it if required.

Here is the list of all Add-ons needed to add in MATLAB:

  • Image Processing Toolbox
  • Mapping Toolbox
  • Signal Processing Toolbox
  • Statistics and Machine Learning Toolbox
  • Curve Fitting Toolbox
  • Parallel Computing Toolbox

If you already have MATLAB and need to change licences, see this link to activate the app. Ones MATLAB is running, you can check if a spesific add-on is anabled by using the command matlab.addons.isAddonEnabled('NameOfToolbox') (it returns the logical value 1 if it is enabled). Alternatively, addons = matlab.addons.installedAddons shows a list of all installed add-ons.

  1. Install vtk (For MacOS you can follow this guide).

  2. Install cmake using the command

    $ brew install cmake

  3. Install the dependencies [1,2,3] needed running the dependencies/install_cobiveco.sh using the command

    $ sh install_cobiveco.sh

    Note: once mmg is installed, check that the bin directory is non-empty using the command

    $ ls dependencies/mmg/build/bin

    If the files mmg2d_O3, mmg3d_O3, mmgs_O3 are present, you can go on to the next step. Else perform download the mmg binary from here and move mmg2d_O3, mmg3d_O3, mmgs_O3 to dependencies/mmg/build/bin.

    When running any example later, a warning about unidentified developer may occur. This can be solved by editing the setting as descibed here.

  4. Paraview will be used during the calculation of the coordinates and is highly recommended for visualization. Install Paraview. You can download Paraview here (recommended on Mac: ParaView-5.11.0-RC1-MPI-OSX10.13-Python3.9-x86_64.dmg). The installation was tested was Paraview 5.10 and 5.11 .

  5. Check that pvpython can be evoked from the commandline. If not, add the path to your ~/.zshrc. First, check where pvpython is located.

    $ which pvpython

    The output will look something like this:

    /Applications/ParaView-5.10.1.app/Contents/bin/pvpython

    Modify the following commands to represent your path. Then, add pvpython to your ~/.zshrc using your favorite editor or just by doing:

    $ echo "export PATH="$PATH:/Applications/ParaView-5.10.1.app/Contents/bin/"" >> ~/.zshrc
$ ln -s /Applications/ParaView-5.10.0.app/Contents/bin/pvpython ~/bin

  6. To switch between environments in Matlab, we recommend using conda. However, one can also create a python environment using the requirements.txt file, which is more light-weight, than choosing anaconda. However, one should be aware, that you can switch between calling pvpython and python and might need to modify the execution of condalab in the matlab code. See step 9 below.

To create a python environment one can simply execute the following:

pip install -r requirements.txt

or use conda to create a minimal environment

conda install --file requirements.txt

The tested and recommended version of this code is currently using anaconda. You can install Anaconda using [this guide](https://docs.anaconda.com/anaconda/ install/mac-os/) (commandline-installation recommended). This guide for conda might also be useful if the is user not familiar with it.

  1. Create a conda environment called base using the cobivecox.yml.

    You can use the following command to create the python environment with the dependencies needed:

    $ conda env create -f cobivecox.yml

  2. The conda path has to be put in manually in the code.Use the command

    $ which conda

    or

    $ conda env list

    in the terminal to receive the path.

    Copy the path you got in line 19 of the function createBoundarySurfacesAB.m (you can find this function in the directory functions)

    $ condaPath = '{*the path from which conda*}';

  3. To avoid communication errors, open MATLAB from your terminal. One can add the shortcut to their ~/.zshrc

   $ alias matlab="/Applications/MATLAB_R2022b.app/bin/matlab"

and then use the following command in the directory examples

   $ matlab

to open the program.

Dependencies

Before using Cobiveco, its dependencies [1,2,3] need to be installed by running dependencies/install_cobiveco.sh.

Usage

  1. Open MATLAB from the commandline.

If you set the matlabalias as described above you can do that in the directory examples using the follwoing command:

$ matlab

to open the program.

Input Files To Compute Coordinates

  1. To use CobivecoX, the user needs to provide the following input files in a directory named {filename} containing the following files:
  • {filename}_av.ply
  • {filename}_endo_lv.ply
  • {filename}_endo_rv.ply
  • {filename}_epi_base.ply
  • {filename}_epi_no_base.ply
  • {filename}_mv.ply
  • {filename}_pv.ply
  • {filename}_tv.ply
  • {filename}.vtu

Note that the folder {filename} needs to be in examples.

  1. In case of needing the original Cobiveco, the following input files have to be provided:
  • {filename}_base.ply
  • {filename}_endo_lv.ply
  • {filename}_endo_rv.ply
  • {filename}_epi.ply
  • {filename}.vtu

Computing coordinates

Coordinates can be computed with:

% Create a cobiveco object, providing a config struct with input and output path prefixes
c = cobiveco(struct('inPrefix','{filename}/{filename}', 'outPrefix','result_{filename}/'));

% Run computation of all coordinates
c.prepareMesh0;
if c.cfg.CobivecoX == true
    c.computeAllCobivecoX;
else 
    c.computeAllCobiveco;
end

% Optional: Retrieve the result and a config struct with all parameters
result = c.result;
config = c.cfg;

Run help cobiveco for more information.

An example can be found in the directory examples named examples_single_cobiveco_run.m. Please note that at line 18 all {filename} placeholders have to be substituted with the name of the file and directory names.

Finally, once MATLAB has finished exporting the result, it can be visualized opening ParaView and selecting the result.vtu file in the result_{filename} directory.

Utilities

The following utilities are provided:

Examples

The following examples illustrate the use of Cobiveco:

Hints

To speed up the computation for fine meshes (several millions of nodes), we recommend to increase the sizing parameters of Mmg. This way, all coordinates except the binary transventricular coordinate are automatically computed on coarser meshes and interpolated to the original mesh. As the non-binary coordinates are spatially low-frequent, an edge length of slightly below 1 mm (or at maximum one third of the smallest wall thickness) is sufficient. If you want to compute coordinates for a mesh with an average edge length of 0.3 mm, for example, scale the default value for the input 'mmgSizingParam' by a factor of 0.9/0.3 = 3 to use an effective edge length of about 0.9 mm for the computations:

c = cobiveco(struct('inPrefix','heart', 'outPrefix','result/', 'mmgSizingParam',3*[0.1 0.9 1.1]));

License

All source code is subject to the terms of the Apache License 2.0. Copyright 2021 Steffen Schuler, Karlsruhe Institute of Technology.

Contacts

Lisa Pankewitz Simula Research Laboratory [email protected] / www.simula.no

Steffen Schuler & Axel Loewe Institute of Biomedical Engineering Karlsruhe Institute of Technology [email protected] / www.ibt.kit.edu

References

Schuler, S., Pilia, N., Potyagaylo, D., Loewe, A., 2021. Cobiveco: Consistent biventricular coordinates for precise and intuitive description of position in the heart – with MATLAB implementation. Medical Image Analysis.

[1] Dapogny, C. et al., 2014. Three-dimensional adaptive domain remeshing, implicit domain meshing, and applications to free and moving boundary problems. J Comput Phys.

[2] Jacobson, A., 2018. gptoolbox: Geometry processing toolbox.

[3] Schuler, S., 2020. vtkToolbox: A MEX interface to the VTK library.

[4] Bai, W. et al., 2015. A bi-ventricular cardiac atlas built from 1000+ high resolution MR images of healthy subjects and an analysis of shape and motion. Med Image Anal 26, 133–45.

[5] Schuler, S. et al., 2021. Biventricular statistical shape model of the human heart adapted for computer simulations. Zenodo.