Open resource for Multiple Anatomical structure Parcellation for T1-weighted brain MRI - beta version for CSF region quantification
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
Paper: https://onlinelibrary.wiley.com/doi/full/10.1002/hbm.70063
OpenMAP-T1c parcellates the whole brain into 280 anatomical regions based on JHU-atlas in 50 (sec/case).
-
install python and make virtual environment
Python 3.9 or later is recommended. -
Clone this repository, and go into the repository:
git clone https://github.com/OishiLab/OpenMAP-T1c.git
cd OpenMAP-T1c
- Please install PyTorch compatible with your environment.
https://pytorch.org/
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/
- Install libraries other than PyTorch:
pip install -r requirements.txt
-
Please apply and download the pre-trained model from the link below and upload it to your server.
-
You can run OpenMAP-T1c !!
You can get the pretrained model from this link. Link of pretrained model
Using OpenMAP-T1 is straightforward. You can use it in any terminal on your linux system. We provide CPU as well as GPU support. Running on GPU is a lot faster though and should always be preferred. Here is a minimalistic example of how you can use OpenMAP-T1.
Run the script from your terminal using:
python3 src/parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER
- -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.
If you want to run the script on a specific GPU (for example, GPU 1), prepend the command with the CUDA_VISIBLE_DEVICES=N.
CUDA_VISIBLE_DEVICES=1 python3 parcellation.py -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER
If the error occurs for Windows users, please change Python3 to Python.
All images you input must be in NifTi format and have a .nii extension.
INPUR_FOLDER/
├ A.nii or .nii.gz
├ B.nii or .nii.gz
├ *.nii or .nii.gz
OUTPUT_FOLDER/
├── A
│ ├── cropped
│ │ ├── A_cropped_mask.nii
│ │ └── A_cropped.nii
│ ├── csv
│ │ ├── A_Type1_Level1.csv # volume for each ROI based on level/Level_ROI_Name.csv Type1_Level1
│ │ ├── A_Type1_Level2.csv
│ │ ├── A_Type1_Level3.csv
│ │ ├── A_Type1_Level4.csv
│ │ ├── A_Type1_Level5.csv
│ │ ├── A_Type2_Level1.csv
│ │ ├── A_Type2_Level2.csv
│ │ ├── A_Type2_Level3.csv
│ │ ├── A_Type2_Level4.csv
│ │ ├── A_Type2_Level5.csv
│ │ └── A_SylvianRatio.csv # Ratio of Sylvian Fissure to CSF Sulcus
│ ├── original
│ │ ├── A_N4.nii
│ │ └── A.nii # input image
│ ├── parcellated
│ │ ├── A_Type1_Level1.nii # parcellation map based on level/Level_ROI_Name.csv Type1_Level1
│ │ ├── A_Type1_Level2.nii
│ │ ├── A_Type1_Level3.nii
│ │ ├── A_Type1_Level4.nii
│ │ ├── A_Type1_Level5.nii
│ │ ├── A_Type2_Level1.nii
│ │ ├── A_Type2_Level2.nii
│ │ ├── A_Type2_Level3.nii
│ │ ├── A_Type2_Level4.nii
│ │ └── A_Type2_Level5.nii
│ └── stripped
│ ├── A_stripped_mask.nii
│ └── A_stripped.nii
├── ...
MODEL_FOLDER/
├ CNet/CNet.pth
├ SSNet/SSNet.pth
├ PNet/PNet.pth
└ HNet/HNet.pth
The OpenMAP-T1c parcellates the entire brain into five hierarchical structural levels, with the coarsest level comprising eight structures and the finest level comprising 280 structures.
-
For additional visualization and detailed analysis, you can also utilize 3D Slicer. 3D Slicer is a free, open-source platform for medical image computing that provides robust tools for segmentation, registration, and 3D visualization, making it an excellent choice for exploring the parcellation maps generated by OpenMAP-T1c.
-
For additional visualization and detailed analysis, ROIEditor is also an excellent tool. ROIEditor is a free, open-source application specifically designed for creating and editing regions of interest (ROIs) in medical imaging. Its user-friendly interface facilitates precise segmentation and fine-tuning, making it ideal for isolating and analyzing specific regions on parcellation maps generated by OpenMAP-T1c.
-
What are the contributions of OpenMAP-T1c?
For GPUs, OpenMAP-T1c processes T1-weighted images in just 1–2 minutes. Even on CPUs, processing completes in roughly 30 minutes. Moreover, OpenMAP-T1c is highly robust against variations in imaging environments and brain atrophy. -
Which atlas is used in OpenMAP-T1c?
OpenMAP-T1c employs the JHU atlas. -
Can OpenMAP-T1c be used with 2D imaging data?
Although not included in the paper, our private tests indicate that OpenMAP-T1 can also work with 2D imaging. However, using 2D data might result in some regions being lost. -
How much GPU memory do I need to run OpenMAP-T1c?
We ran all our experiments on NVIDIA RTX3090 GPUs with 24 GB memory. For inference you will need less, but since inference in implemented by exploiting the fully convolutional nature of CNNs the amount of memory required depends on your image. Typical image should run with less than 4 GB of GPU memory consumption. If you run into out of memory problems please check the following: 1) Make sure the voxel spacing of your data is correct and 2) Ensure your MRI image only contains the head region. -
What is the difference between Type 1 and Type 2?
Type 1 outputs the brain surface structure by separating it into the cortex and the subcortical white matter. Typically, Type 1 is used in most cases. In contrast, Type 2 outputs the cortex and the subcortical white matter as a single ROI. Type 2 may be employed when it is desirable to minimize the number of ROIs in data analysis or when quantifying parameters such as regional cerebral blood flow using low-resolution PET images. -
Will you provide the training code as well?
No. The training code is tightly wound around the data which we cannot make public.
@techreport{nishimaki2024openmap,
title={OpenMAP-T1: A Rapid Deep-Learning Approach to Parcellate 280 Anatomical Regions to Cover the Whole Brain},
author={Nishimaki, Kei and Onda, Kengo and Ikuta, Kumpei and Chotiyanonta, Jill and Uchida, Yuto and Mori, Susumu and Iyatomi, Hitoshi and Oishi, Kenichi and Alzheimer's Disease Neuroimaging Initiative and Australian Imaging Biomarkers and Lifestyle Flagship Study of Ageing},
year={2024},
institution={Wiley Online Library}
}
The following studies have utilized OpenMAP-T1 for advanced segmentation and analysis in T1-weighted MRI.
- Change points for dynamic biomarkers in the Alzheimer's disease pathological cascade: A 30-year cohort study
Authors: Yuto Uchida, Kei Nishimaki, Anja Soldan, Corinne Pettigrew, Sara Grace Ho, Abhay Moghekar, Mei-Cheng Wang, Michael I. Miller, Marilyn Albert, Kenichi Oishi; Journal: Alzheimer's & dementia - Acceleration of Brain Atrophy and Progression From Normal Cognition to Mild Cognitive Impairment
Authors: Yuto Uchida, MD, PhD; Kei Nishimaki; Anja Soldan, PhD; Abhay Moghekar, MBBS; Marilyn Albert, PhD; Kenichi Oishi, MD, PhD;
Journal: JAMA Network Open - A Neural Network Approach to Identify Left–Right Orientation of Anatomical Brain MRI
Authors: Kei Nishimaki; Hitoshi Iyatomi, PhD; Kenichi Oishi, MD, PhD;
Journal: Brain and Behavior