INDI (In-Vivo Diffusion)

<p align="center"> <img src="assets/logo/indi_logo.png"> </p> <p align="center"> In-vivo diffusion analysis (INDI)<br> A post-processing pipeline for in-vivo cardiac diffusion tensor imaging. </p>

Table of Contents

• Introduction
• Installation
  • Quick start
  • Clone the repository
  • macOS
  • Ubuntu
  • Windows (Conda)
  • Optional AI modules
• For Development
  • Documentation
  • pre-commit
• Basic Usage
• 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)

git clone https://github.com/ImperialCollegeLondon/INDI.git
cd INDI
python3 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install .

Clone the Repository

First, install git for your operating system, then clone the repository:

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

---

Installation on macOS (Intel and Apple Silicon)

You may need to install Xcode and its Command Line Tools:

xcode-select --install

Install Homebrew and then Python 3.12:

brew install python@3.12

Install ImageMagick:

brew install imagemagick

Set up the Python environment in the INDI root directory:

[!NOTE] For development replace the pip install . command below with pip install -e ".[dev,doc]" to install INDI in editable mode with optional dependencies.

python3.12 -m venv .venv
source .venv/bin/activate
pip install .

---

Installation on Ubuntu 24.04

Install ImageMagick:

sudo apt install imagemagick

Install development tools:

sudo apt install git-all build-essential python3.12-venv
sudo apt-get install python3-tk python3-dev

Create the Python environment in the INDI root directory:

[!NOTE] For development replace the pip install . command below with pip install -e ".[dev,doc]" to install INDI in editable mode with optional dependencies.

python3 -m venv .venv
source .venv/bin/activate
pip install .

If you encounter issues displaying matplotlib windows, run:

xhost +

---

Installation on Windows 10 with Conda

Install Miniforge.

Create a new environment with conda:

conda create --name indi python=3.12
conda activate indi

Install the required packages:

[!NOTE] For development replace the pip install . command below with pip install -e ".[dev,doc]" to install INDI in editable mode with optional dependencies.

pip install .

To allow the ImageMagick scripts to run enter command:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine`

Install ImageMagick.

---

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:

pip install ".[ai]"

---

For Development

Install INDI in editable mode with optional dependencies:

pip install -e ".[dev,doc]"

Documentation

[!NOTE] Documentation is very much work in progress

To serve the documentation locally:

mkdocs serve

Install pre-commit

pre-commit install

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

pre-commit run --all-files

This helps ensure code quality and style before committing changes.

---

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, in your INDI Python environment, 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):

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