MuscleMap: An Open-Source, Community-Supported Consortium for Whole-Body Quantitative MRI of Muscle

MuscleMap Toolbox

A free and open-source software toolbox for whole-body muscle segmentation and analysis.

Dependencies

Python 3.11.8

Installation

We provide a step-by-step installation and usage tutorial video here.

MuscleMap is also implemented as a dedicated 3D Slicer extension that enables automated muscle segmentation directly within the Slicer environment. Installation and usage tutorial video for the 3D Slicer extension can be found here.

Install python:
- We recommend installing Miniconda or Anaconda.

Create python environment:

conda create --name MuscleMap python=3.11.8

Activate python environment:
```
conda activate MuscleMap
```
Download MuscleMap repository:
1. Using the git command line tool:
```
git clone https://github.com/MuscleMap/MuscleMap
```
2. From your browser:
  1. Open https://github.com/MuscleMap/MuscleMap in your browser
  2. Click the green <> Code ▼ button
  3. Click Download Zip
  4. Unzip the MuscleMap repository
Navigate to MuscleMap repository:
```
cd ./MuscleMap
```
Install python packages:
```
pip install -e .
```
Install PyTorch with the correct CUDA Version for GPU support.

The MuscleMap Toolbox works with both CPU and GPU, but performs best with a GPU-enabled PyTorch installation. If you want to use the MuscleMap Toolbox with CPU only, skip Step 7.

The default installation of the MuscleMap dependencies (from Step 6) uses a CPU-only build of PyTorch. To use a GPU, you must manually install a GPU-enabled build of PyTorch. Proceed with Step 7.1 or Step 7.2 below, depending on your hardware:
- NVIDIA GPU with a compatible CUDA runtime, or
- AMD GPU with ROCm support (Note: ROCm is supported on Linux only and requires a ROCm-compatible AMD GPU).
- Step 7.1. — Check your system CUDA version (terminal)
  
  Open a terminal and run one of the following commands:
  
  For an NVIDIA GPU with CUDA runtime:
```
nvidia-smi
```
  For an AMD GPU with ROCm support:
```
 rocm-smi
```
  You then need to install the corresponding GPU-compatible version of PyTorch v2.4.0. We recommend installing the PyTorch wheel with pip.
- Step 7.2. — Open a Python console and run:
```
import torch
print("Is CUDA available?:", torch.cuda.is_available())
```
If PyTorch indicates that CUDA is available, then the system is functioning correctly. If PyTorch indicates that CUDA is not available, verify whether your system has a compatible driver installed (repeat Step 2). Note: This availability check is used by PyTorch for both CUDA and ROCm backends.
To use mm_register_to_template, you will need Spinal Cord Toolbox installed. We have only tested mm_register_to_template using Spinal Cord Toolbox Version 6.5.

Usage

Activate python environment:
```
conda activate MuscleMap
```

To run mm_segment:

mm_segment -i image.nii.gz

mm_segment uses our contrast agnostic whole-body segmentation model by default with currently 99 muscles and bones.

<details> <summary>Click to see the current segmentations with labels.</summary>

```
  Left Levator Scapulae 1101
  Right Levator Scapulae 1102
  Left Semispinalis Cervicis And Multifidus 1111
  Right Semispinalis Cervicis And Multifidus 1112
  Left Semispinalis Capitis 1121
  Right Semispinalis Capitis 1122
  Left Splenius Capitis 1131
  Right Splenius Capitis 1132
  Left Sternocleidomastoid 1141
  Right Sternocleidomastoid 1142
  Left Longus Colli 1151
  Right Longus Colli 1152
  Left Trapezius 1161
  Right Trapezius 1162
  Left Supraspinatus 2101
  Right Supraspinatus 2102
  Left Subscapularis 2111
  Right Subscapularis 2112
  Left Infraspinatus 2121
  Right Infraspinatus 2122
  Left Deltoid 2141
  Right Deltoid 2142
  Left Rhomboid 4101
  Right Rhomboid 4102
  Left Thoracolumbar Multifidus 5101
  Right Thoracolumbar Multifidus 5102
  Left Erector Spinae 5111
  Right Erector Spinae 5112
  Left Psoas Major 5121
  Right Psoas Major 5122
  Left Quadratus Lumborum 5131
  Right Quadratus Lumborum 5132
  Left Lattisimus Dorsi 5141
  Right Lattisimus Dorsi 5142
  Left Gluteus Minimus 6101
  Right Gluteus Minimus 6102
  Left Gluteus Medius 6111
  Right Gluteus Medius 6112
  Left Gluteus Maximus 6121
  Right Gluteus Maximus 6122
  Left Tensor Fascia Latae 6131
  Right Tensor Fascia Latae 6132
  Left Iliacus 6141
  Right Iliacus 6142
  Left Ilium 6151
  Right Ilium 6152
  Sacrum 6160
  Left Femur 6171
  Right Femur 6172
  Left Piriformis 6181
  Right Piriformis 6182
  Left Pectineus 6191
  Right Pectineus 6192
  Left Obturator Internus 6201
  Right Obturator Internus 6202
  Left Obturator Externus 6211
  Right Obturator Externus 6212
  Left Gemelli and Quadratus Femoris 6221
  Right Gemelli and Quadratus Femoris 6222
  Left Vastus Lateralis 7101
  Right Vastus Lateralis 7102
  Left Vastus Intermedius 7111
  Right Vastus Intermedius 7112
  Left Vastus Medialis 7121
  Right Vastus Medialis 7122
  Left Rectus Femoris 7131
  Right Rectus Femoris 7132
  Left Sartorius 7141
  Right Sartorius 7142
  Left Gracilis 7151
  Right Gracilis 7152
  Left Semimembranosus 7161
  Right Semimembranosus 7162
  Left Semitendinosus 7171
  Right Semitendinosus 7172
  Left Biceps Femoris Long Head 7181
  Right Biceps Femoris Long Head 7182
  Left Biceps Femoris Short Head 7191
  Right Biceps Femoris Short Head 7192
  Left Adductor Magnus 7201
  Right Adductor Magnus 7202
  Left Adductor Longus 7211
  Right Adductor Longus 7212
  Left Adductor Brevis 7221
  Right Adductor Brevis 7222
  Left Anterior Compartment 8101
  Right Anterior Compartment 8102
  Left Deep Posterior Compartment 8111
  Right Deep Posterior Compartment 8112
  Left Lateral Compartment 8121
  Right Lateral Compartment 8122
  Left Soleus 8131
  Right Soleus 8132
  Left Gastrocnemius 8141
  Right Gastrocnemius 8142
  Left Tibia 8151
  Right Tibia 8152
  Left Fibula 8161
  Right Fibula 8162
```

</details>

The default spatial overlap during sliding window inference is 90%. If inference speed needs to be increased, the spatial overlap can be lowered. For large high-resolution or whole-body images, we recommend lowering the spatial inference to 75%:
```
mm_segment -i image.nii.gz -s 75
```
Users may specify our legacy region segmentation models (version 0.0) with -r.
- Available regions: abdomen, pelvis, thigh, forearm and leg.
Note: The legacy regional models are maintained for backward compatibility only. Active development and state-of-the-art MuscleMap performance are provided exclusively by the whole-body model.
mm_segment will use GPU if detected. Users can force mm_segment to use CPU with -g N.
Run mm_segment -h to see all available options.
We are continuously expanding the whole-body model. We are working on adding the arm, forearm, hand, abdomen, spine, hip rotators, pelvic floor, and foot. If you have an immediate need, please open an issue.

We highly recommend visualizing and manually correcting the segmentations for errors. We use ITK-SNAP and Slicer, which are free and open-source.

If the models do not work well on your images, please open an issue. If you share your images, we will update the MuscleMap segmentation model to improve its accuracy on your images.

To run mm_extract_metrics:
1. For T1w and T2w MRI:
```
mm_extract_metrics -m gmm -r wholebody -i image.nii.gz -s image_dseg.nii.gz -c 3
```
- Users may specify Gaussian mixture modeling (gmm) or kmeans clustering (kmeans) with -m.
- Users may specify 2 or 3 components with -c.
- For gmm, probability maps are ouput for each component and label (*_softseg.nii.gz).
- For gmm and kmeans, binarized segmentations are ouput for each component and label (*_seg.nii.gz).
1. For Dixon Fat-Water MRI:
```
mm_extract_metrics -m dixon -r wholebody -f image_fat.nii.gz -w image_water.nii.gz -s image_dseg.nii.gz
```
2. For Dixo

MuscleMap

Install / Use

README

MuscleMap: An Open-Source, Community-Supported Consortium for Whole-Body Quantitative MRI of Muscle

MuscleMap Toolbox

Dependencies

Installation

Usage