OpenMAP-T1

Languages: English | 日本語 (Japanese) | 中文 (Chinese)

OpenMAP-T1: A Rapid Deep-Learning Approach to Parcellate 280 Anatomical Regions to Cover the Whole Brain

Author: Kei Nishimaki, Kengo Onda, Kumpei Ikuta, Jill Chotiyanonta, Yuto Uchida, Susumu Mori, Hitoshi Iyatomi, Kenichi Oishi

The Russell H. Morgan Department of Radiology and Radiological Science, The Johns Hopkins University School of Medicine, Baltimore, MD, USA

Department of Applied Informatics, Graduate School of Science and Engineering, Hosei University, Tokyo, Japan

The Richman Family Precision Medicine Center of Excellence in Alzheimer's Disease, Johns Hopkins University School of Medicine, Baltimore, MD, USA

Abstract: This study introduces OpenMAP-T1, a deep learning-based method for rapid and accurate whole brain parcellation in T1-weighted brain MRI, aiming to overcome the limitations of conventional normalization-to-atlas-based approaches and multi-atlas label-fusion (MALF) techniques. Brain image parcellation is a fundamental process in neuroscientific and clinical research, enabling detailed analysis of specific cerebral regions. Normalization-to-atlas-based methods have been employed for this task, but they face limitations due to variations in brain morphology, especially in pathological conditions. The MALF techniques improved the accuracy of the image parcellation and robustness to variations in brain morphology but at the cost of high computational demand that requires lengthy processing time. OpenMAP-T1 integrates several convolutional neural network models across six phases: preprocessing, cropping, skull stripping, parcellation, hemisphere segmentation, and final merging. This process involves standardizing MRI images, isolating the brain tissue, and parcellating it into 280 anatomical structures that cover the whole brain, including detailed gray and white matter structures, while simplifying the parcellation processes and incorporating robust training to handle various scan types and conditions. The OpenMAP-T1 was tested on eight available open resources, including real-world clinical images, demonstrating robustness across different datasets with variations in scanner types, magnetic field strengths, and image processing techniques like defacing. Compared to existing methods, OpenMAP-T1 significantly reduced the processing time per image from several hours to less than 90 seconds without compromising accuracy. It was particularly effective in handling images with intensity inhomogeneity and varying head positions, conditions commonly seen in clinical settings. The adaptability of OpenMAP-T1 to a wide range of MRI datasets and robustness to various scan conditions highlight its potential as a versatile tool in neuroimaging.

Paper: https://onlinelibrary.wiley.com/doi/full/10.1002/hbm.70063

Cloud Application: https://huggingface.co/spaces/OishiLab/OpenMAP-T1

Published in Human Brain Mapping

Requirements

• Python 3.11 or later (required by pandas 3.0)
• PyTorch 2.12 or later (installed automatically with uv sync; install separately when using pip)
• Other pinned libraries: nibabel 5.4.2, pandas 3.0.3, scipy 1.17.1, SimpleITK 2.5.5, tqdm 4.68.2

Installation

OpenMAP-T1 parcellates the whole brain into 280 anatomical regions based on JHU-atlas in 50 (sec/case).

Installation with uv (Recommended)

uv is an extremely fast Python package installer and resolver written in Rust. It provides a faster alternative to pip for managing dependencies.

1. Install uv

Install uv using one of the following methods:

macOS and Linux: bash curl -LsSf https://astral.sh/uv/install.sh | sh

Windows: powershell powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Or using pip: bash pip install uv

1. Clone this repository, and go into the repository:

git clone https://github.com/OishiLab/OpenMAP-T1.git
cd OpenMAP-T1

1. Install dependencies with uv (including PyTorch):

uv sync

1. Please apply and download the OpenMAP-T1 v3 pre-trained model from the link below and place it in MODEL_FOLDER on your server.

2. You can run OpenMAP-T1!

Installation with pip (Alternative)

1. Install Python 3.11 or later and create a virtual environment.

2. Clone this repository, and go into the repository:

git clone https://github.com/OishiLab/OpenMAP-T1.git
cd OpenMAP-T1

1. Install PyTorch compatible with your environment.

https://pytorch.org/

The latest stable PyTorch (2.12+) requires Python 3.10 or later; this project requires Python 3.11 or later because of pandas 3.0.

Once you select your environment, the required commands will be displayed.

If you want to install an older PyTorch environment, you can download it from the link below.

https://pytorch.org/get-started/previous-versions/

1. Install libraries other than PyTorch:

pip install -r requirements.txt

1. Please apply and download the OpenMAP-T1 v3 pre-trained model from the link below and place it in MODEL_FOLDER on your server.

2. You can run OpenMAP-T1!

Docker Installation Instruction

The Docker image is based on python:3.13.2-slim and installs dependencies from requirements_for_docker.txt, which is exported from uv.lock. To regenerate it after dependency updates, run:

uv export --no-hashes --no-emit-project --no-dev -o requirements_for_docker.txt

1. Build the Docker Image

In summary, this command creates a Docker image named "openmap-t1" based on the Dockerfile and files in your current directory.

docker build -t openmap-t1 .

• docker build: This command builds a Docker image using the instructions provided in the Dockerfile.
• -t openmap-t1: The -t flag tags the image with the name "openmap-t1". This makes it easier to refer to later.

• .: The dot represents the build context, which means Docker will look for the Dockerfile and other necessary files in the current directory.

• Run the Docker Container

docker run --rm -it -v "$(pwd):/app" openmap-t1 -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER

• docker run: This starts a new container from a Docker image.

• --rm: Automatically removes the container when it stops running, keeping your system clean by not leaving behind stopped containers.

• -it Combines two options:

• -i keeps STDIN open (interactive mode).
• -t allocates a pseudo-TTY (allows terminal-like interaction).

Together, these options let you interact with the container through your terminal if needed.

• -v "$(pwd):/app": Mounts your current working directory (the result of $(pwd)) into the /app directory inside the container. This means:
• Any files in your current folder are available inside the container under /app.

• Any changes made inside the container (like output files) will be reflected on your host system.

• openmap-t1: This is the name of the Docker image from which the container is created. It should have been built previously using a command like docker build -t openmap-t1 ..

• -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER These are the command-line arguments passed to the application running inside the container:

• -i INPUT_FOLDER: Specifies the input folder path.
• -o OUTPUT_FOLDER: Specifies the output folder path.
• -m MODEL_FOLDER: Specifies the model folder path. Replace INPUT_FOLDER, OUTPUT_FOLDER, and MODEL_FOLDER with the appropriate directory names or paths that exist within the mounted /app directory (for example, input, output, and model).

How to download the pretrained model.

You can get the pretrained model from this link. Link of pretrained model

All Commands

Using OpenMAP-T1 is straightforward. You can use it in a terminal on Linux, macOS, or Windows. We provide CPU as well as GPU support. Running on GPU is a lot faster though and should always be preferred. Here is a minimal example of how you can use OpenMAP-T1.

Basic Usage

Run the script from your terminal using:

# uv (if you installed with uv sync)
uv run python src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER

# pip (activate virtual environment first: source .venv/bin/activate)
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER

# Docker
docker run --rm -it -v "$(pwd):/app" openmap-t1 -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER

# Save outputs as .nii (optional; default is .nii.gz)
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --output-ext .nii

• -i INPUT_FOLDER: Specifies the folder containing the input brain MRI images.
• -o OUTPUT_FOLDER: Defines the folder where the results will be saved. This folder will be created automatically if it does not exist.
• -m MODEL_FOLDER: Indicates the folder containing the pretrained models for processing.
• --output-ext {.nii.gz, .nii}: Output extension for generated NIfTI files. Default is .nii.gz.
• --output-space {native, conform, both}: Voxel grid for saved NIfTI outputs in cropped/, stripped/, and parcellated/. Default is native.
• native: Resample to the N4-corrected canonical input grid (default; same filenames as in earlier releases).
• conform: Keep the 1 mm isotropic 256³ processing grid; filenames include the _1mm suffix.
• both: Write both versions; 1 mm files are saved under conform/ with the _1mm suffix.

Output Space

Inference runs on a 1 mm isotropic grid internally. By default, saved parcellation maps and intermediate masks are resampled back to the N4-corrected canonical input geometry (native). To keep outputs on the 1 mm grid, or to save both grids, use --output-space:

# uv
uv run python src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --output-space conform
uv run python src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --output-space both

# pip
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --output-space conform
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --output-space both

1 mm outputs use the _1mm suffix (for example, A_Type1_Level5_1mm.nii.gz, A_cropped_mask_1mm.nii.gz). The original/ folder is always saved in the input-derived geometry. CSV regional volumes are always computed on the 1 mm grid, regardless of this option.

OpenMAP-T1 now allows you to perform only specific processing steps using the following mutually exclusive flags. By specifying these options, OpenMAP-T1 skips unnecessary processing steps, which can significantly reduce overall processing time.

• Only Face Cropping: If you only want to perform face cropping and skip the rest of the processing steps, use:

# uv
uv run python src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --only-face-cropping

# pip
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --only-face-cropping

# Docker
docker run --rm -it -v "$(pwd):/app" openmap-t1 -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --only-face-cropping

• Only Skull Stripping: If you want to perform only skull stripping and skip all other processing steps, use the skull stripping flag. Note that skull stripping requires face cropping as a prerequisite, so face cropping is not considered one of the "other processing" steps that are skipped, use:

# uv
uv run python src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --only-skull-stripping

# pip
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --only-skull-stripping

```

Docker

docker run --rm -it -v "$(pwd):/app" openmap-t1 -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER --only-skull-stripping