Mouse Cardiac MRI Segmentation

Short Axis	Long Axis

Code for publication "Automated cardiac MRI analysis for robust profiling of heart failure models in mice".

This code provides model weights and inference scripts to segment mouse cardiac MRI scans in three different modalities: short-axis 3D cine, long-axis 4-chamber 2D cine, and long-axis 2-chamber 2D cine. The code generates segmentation masks, quantitative measurements, and visualization outputs.

Setup

This installation assumes you're running on a Linux system, preferably with a CUDA-enabled GPU (otherwise, the code will run very slowly). We recommend CUDA 12.x with at least 16GB VRAM.

This repo uses Git-LFS to store model weights. After cloning the repo, run:

git lfs install
git lfs pull

The code was tested using python 3.14 - much older versions may not work.

Set up the environment with these commands:

# create a new virtual environment
python -m venv venv
. venv/bin/activate

# if you have a GPU, run this command
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126 

# if you don't have a GPU, uncomment and run this command instead of the above
#pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# install other dependencies
pip install munch nibabel numpy pandas PyYAML scikit-image torchio opencv-python matplotlib

If you run into version issues, try installing the specific versions we tested, which are listed in requirements.txt:

pip install -r requirements.txt

Input Data Requirements

• Input data should be cine MRI scans (3D short axis or 2D long axis) in NIFTI format (.nii or .nii.gz) with floating point pixel values.

• Short axis scans should be saved with matrix size 192 x 192 x 12 x 20 (height x width x depth x timeframes).

• Long axis scans should be saved with matrix size 192 x 192 x 1 x 20 (height x width x depth x timeframes).

• The first frame is assumed to be end-diastole (ED). End-systole (ES) is identified automatically based on the frame with minimum left-ventricular volume.

Usage

To generate segmentations and summary metrics, run this command from the repo root directory:

python inference_segmentation.py \
    --input_dir <input_dir> \
    --output_dir <output_dir> \
    --modality <modality>

• input_dir should be a directory of .nii (or .nii.gz) files.
• output_dir is where outputs will be saved.
• modality should be one of: short_axis, long_axis_4ch, long_axis_2ch.

Example Scans

Example scans for the 3 possible input modalities are included in the test_data/ directory. To run inference on these:

python inference_segmentation.py \
    --input_dir test_data/short_axis \
    --output_dir test_outputs/short_axis \
    --modality short_axis

python inference_segmentation.py \
    --input_dir test_data/long_axis_4ch \
    --output_dir test_outputs/long_axis_4ch \
    --modality long_axis_4ch

python inference_segmentation.py \
    --input_dir test_data/long_axis_2ch \
    --output_dir test_outputs/long_axis_2ch \
    --modality long_axis_2ch

The resulting outputs will be saved to test_outputs (directory is created automatically).

Outputs

The script generates several output files organized into subdirectories:

output_dir/
├── results.csv              # Quantitative measurements (main output)
├── masks/                   # Segmentation masks as NIFTI files
│   └── *.nii               
└── visualizations/          # Video and plot outputs
    ├── *_video.mp4         # Animated segmentation overlays
    └── *_wall_thickness.png # Wall thickness analysis plots (3D only)

Output Files

results.csv

The primary output containing quantitative measurements for each input file. Columns vary by modality:

All Modalities:

• filename: Path to the input NIFTI file
• index_ED: Frame index identified as end-diastole (maximum ventricular filling)
• index_ES: Frame index identified as end-systole (minimum ventricular filling)

Short Axis (3D) Specific Columns:

• LVEDV: Left ventricular end-diastolic volume (mm³)
• LVESV: Left ventricular end-systolic volume (mm³)
• LVSV: Left ventricular stroke volume (LVEDV - LVESV, mm³)
• LVEF: Left ventricular ejection fraction (LVSV/LVEDV)
• LVM: Left ventricular mass (g)
• RVEDV: Right ventricular end-diastolic volume (mm³)
• RVESV: Right ventricular end-systolic volume (mm³)
• RVSV: Right ventricular stroke volume (mm³)
• RVEF: Right ventricular ejection fraction
• wED1-wED17: Wall thickness measurements at end-diastole for 17 AHA segments (mm)
• wES1-wES17: Wall thickness measurements at end-systole for 17 AHA segments (mm)

Long Axis (2D) Specific Columns:

• LA_max: Maximum left atrial area across all cardiac phases (mm²)
• LA_min: Minimum left atrial area across all cardiac phases (mm²)

masks/*.nii

Segmentation masks in NIFTI format matching the input image dimensions. Pixel values represent different cardiac structures, depending on the modality:

Short axis:

• 0: Background
• 1: Left ventricular blood pool
• 2: Left ventricular myocardium
• 3: Right ventricular blood pool

Long axis 2-chamber:

• 0: Background
• 1: Left ventricular myocardium
• 2: Left ventricular blood pool
• 3: Left atrial blood pool

Long axis 4-chamber:

• 0: Background
• 1: Left ventricular myocardium
• 2: Left ventricular blood pool
• 3: Left atrial blood pool
• 4: Right ventricular blood pool

visualizations/*_video.mp4

Animated videos showing the original image with segmentation contours overlaid for all cardiac phases. Useful for visual quality assessment of the segmentation.

visualizations/*_wall_thickness.png (3D only)

Detailed visualization of wall thickness measurements showing:

• Original image slices at diastole and systole
• Polar coordinate transformations
• AHA 17-segment model overlay
• Thickness measurements for each segment