MrMesh: MRI to Mesh

Automatically generate cardiac segmentations, contours, and meshes from SAX MR images

Latest Release: Here

Features

• Generate 2D pixelwise segmentations (LV cavity, LV myocardium, and RV cavity) using mUNet
• Process mUnet outliers using EF, a novel computer vision based approach to generate anatomically plausible segmentations (LV cavity, LV myocardium, RV cavity, RV myocardium, and LV trebeculation)
• Extract endocardium and epicardium contours from the segmentations
• Generate 2D & 3D surface meshes, and 3D volume mesh of LV
• Refine meshes to a desired grid resolution

User Instruction

Preparations

0. Make sure you have Python3 and Matlab R2021a(9.10) runtime installed, or you can install them from the links below:
   Python3: https://www.python.org/downloads/release/python-380/
   Matlab runtime: https://www.mathworks.com/products/compiler/matlab-runtime.html
1. Download the stable release and extract the ziped file
2. Run GUI.exe (Currently only support Windows machine but the Mac version is coming soon)
   NOTE: the input folder contains two example dicom files. example1: segmentation works using mUNet only. example2: mUnet outlier, EF required. If you are using your own file(s), make sure they match the examples' file type and dimensions (2D images + time series + slices along z)
3. Wait until the mUnet segmentation finishes and the results are displayed
   NOTE: All outputs will be saved in the Output folder

Ready to generate all hell through a 3-step magic?

(1) Segmentation: mUnet

The UNet segmentations are displayed along with their MRI at end of distole. Click on EF Postprocessing if the segmentations are undesirable. Otherwise, skip (2) and go to Step (3)

(2) Postrocessing: EF

In EF prostprocessing you can adjust the parameters described by the publication and generate optimal segmentations.
NOTE: Please make sure you refer to the Parameter Optimization section before you start adjusting. NOTE: After you finish adjusting the slide bars, click on Run EF Postprocessing to display the new results.

If the software fails to automatically detects LV center, you may click on LV Manual Localization and click on the desired LV center to use.

If you wish to see more details, click on Show EF Process that shows the stepwise results by each operation described in the publication.

(3) Mesh Generation

When you are satisfied with your segmentations, click on Mesh Generation. Then, you can adjust all the mesh parameters (in most applications the default should be fine) but you may refer to the publication for details.

In brief:

• MAX_DEFORMATION_ITS: Number of iterations to run SurfCo (for surface mesh generation). More iterations usually result in finer resolution and more deformed (toward the coutours) mesh but larger computational cost.
• TARGETREDUCTION: controls how long the edges are shortened in each iteration. An inrease/decrease leads to lower/higher grid resolution of the 3D surface mesh. NOTE: adjust very gently (e.g. +-0.01).
• RESOLUTION: An inrease/decrease leads to higher/lower grid resolution of the 3D surface mesh. Controls the density of intial mesh built (before deformation). Less sensitive.
• PERCENTAGE: Strength of pulling force toward the countours when building the surface mesh.
• SMOOTH_STRENGTH and SMOOTH_LAMBDA: Controls smoothing strength of the 3D surface generated.
• REFINEITER2D and REFINEITER3D: Number of times to divide the lenghth of 2D surface and 3D volume meshes. More iterations result in increased grid resolution.

Developer Instruction

Dependencies

Read requirements.txt for a list of python packages used and their references.

To install all, run the command below:

pip install -r requirements.txt

Additional Pacakges

2 pip-uninstallable packages are required but are already included in this repo (No need to reinstall).
For details, refer to the git repositories below:
Segmentation: mUNet
Surface Mesh Generation: SurfCo