INDI (In-Vivo Diffusion)

In-vivo diffusion analysis (INDI)
A post-processing pipeline for in-vivo cardiac diffusion tensor imaging.

Table of Contents

• Introduction
• Installation
  • Quick start
• Basic Usage
• Developer installation
  • Install pre-commit
• Optional AI modules
• Documentation
• Troubleshooting
• License
• Acknowledgements

Introduction

INDI is a Python-based post-processing pipeline for in-vivo cardiac diffusion tensor imaging (cDTI). It supports Siemens, Philips, GE and United Imaging diffusion-weighted DICOMs, plus anonymised NIFTI data. Both STEAM and spin-echo sequences are handled.

What it does:

• Image registration
• Image curation and outlier handling
• Tensor fitting
• Segmentation and LV sectorisation
• Results export (VTK, HDF5, CSV, figures)

INDI is run from the command line. When processing a dataset for the first time, user input may be required (via pop-up matplotlib windows); these selections are saved for future runs.

For more information:

• See the documentation for details on the post-processing pipeline (under development 🚧).
• See YAML settings for configuration details (under development 🚧).

Installation

INDI has been tested on:

• macOS 15 with Python 3.12
• Ubuntu 24.04 with Python 3.12
• Windows 10 with Python 3.12

Quick start (any OS)

Install uv and then run

uv tool install git+https://github.com/ImperialCollegeLondon/INDI

Finally, you also need ImageMagick:

# mac os (from homebrew https://brew.sh/)
brew install imagemagick
# Ubuntu
sudo apt install imagemagick
# windows with winget
winget install ImageMagick.Q16-HDRI # Or download the installer from https://imagemagick.org/download/

---

Basic Usage Example

To post-process a synthetic phantom dataset with non-rigid distortions, first unzip the phantom data.

The test_phantom_cdti_dicoms folder contains a diffusion_images subfolder with simulated cDTI DICOMs. These files include noisy diffusion-weighted images with periodic non-rigid distortions, simulating a typical in-vivo scan. INDI always looks recursively for subfolders named diffusion_images. The DICOM files must be inside a folder with this name.

Before running INDI, copy the settings_template.yaml file near your data folder. This file contains default settings for the processing pipeline. Review and adjust the parameters as needed for your dataset. More information is available in the YAML settings documentation.

In your settings.yaml file, set the start_folder option to the path containing a diffusion_images subfolder. For example:

start_folder: /path/to/test_phantom_cdti_dicoms

Then, run:

indi /path/to/settings.yaml

Alternatively, you can leave the start_folder field blank and specify the path using the --start_folder command-line option:

indi path/to/settings.yaml --start_folder /path/to/start/folder

A video tutorial demonstrating how to run INDI with the phantom data is available below (note: the command shown in the video may be slightly outdated, but the rest of the content is still relevant):

---

Developer installation

Make sure you have git installed in your platform. Then clone the repository

git clone https://github.com/ImperialCollegeLondon/INDI
cd INDI

Set up the Python environment in the INDI root directory:

uv sync --group dev --group doc

Install pre-commit

uv run pre-commit install

Pre-commit will now run automatically on each commit. You can also run it manually:

uv run pre-commit run --all-files

This helps ensure code quality and style before committing changes.

Finally install ImageMagick:

# mac os (from homebrew https://brew.sh/)
brew install imagemagick
# Ubuntu
sudo apt install imagemagick
# windows with winget
winget install ImageMagick.Q16-HDRI # Or download the installer from https://imagemagick.org/download/

Note

You can run INDI without activating the environment by doing uv run indi

---

Installing Optional AI Modules (under development 🚧)

We provide an ensemble of U-Net models trained to segment cardiac borders in STEAM data. For details, see docs/documentation.md (under development 🚧). To use these models, install the AI dependencies with

# Developers
uv sync --group dev --group doc --extra ai
# Users
uv tool install "git+https://github.com/ImperialCollegeLondon/INDI[ai]"

---

Documentation

Note

Documentation is very much work in progress

From a development installation serve the documentation locally:

uv run mkdocs serve

---

Troubleshooting

Ubuntu

If you encounter issues displaying matplotlib windows, run:

xhost +

Windows

To allow the ImageMagick scripts to run enter command:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine`

License

INDI is licensed under the BSD license. See the LICENSE file for details.

If you use this software, please credit this website and "The CMR Unit, Royal Brompton Hospital".

Acknowledgements

• Royal Brompton Hospital (Guy's and St Thomas' NHS Foundation Trust), London, UK
• Imperial College London, UK
• Supported by the British Heart Foundation RG/19/1/34160 and RG/F/23/110115
• Chan Zuckerberg Initiative DAF, an advised fund of the Silicon Valley Community Foundation: 2024-337787
• EPSRC Healthcare Technologies EP/X014010/1