DeepMRSeg is a Python-based package for MRI image segmentation. The package is developed and maintained by the Center for Biomedical Image Computing and Analytics (CBICA) at the University of Pennsylvania. As the name implies, main modules of DeepMRSeg are built upon Deep Learning models that perform a set of image segmentation steps on MRI scans.
DeepMRSeg aims to provide users a robust, accurate and user-friendly toolset for performing common segmentation tasks in neuroimaging. In order to meet these challenges, the development of DeepMRSeg was guided by the following set of fundamental principles:
- Efficient network architecture: DeepMRSeg uses a modified UNet architecture that combines an ensemble of learners for a robust segmentation [1].
- Model repository with extensively trained models: We provide a set of pre-trained models for various segmentation tasks. We applied model training using very large and diverse MRI datasets with carefully curated and verified ground-truth labels.
- Easy installation and application: Using a few simple commands, users can easily install DeepMRSeg on different platforms, download pre-trained models, and apply these models on their images. Most applications require no or minimal pre-processing; thus, users can directly apply them on raw scans.
- Extensibility: DeepMRSeg is built using a generic network architecture and a software package that allows extending it with minimal effort. The model repository will grow in the future with regular addition of new models and tasks.
We have tested DeepMRSeg on the following platforms:
- Windows 10 Enterprise x64
- Ubuntu 18.04.3 , 20.04.2 It may also work on other platforms.
To setup your GPU for use with tensorflow, please follow the tensorflow guide for GPU support.
git clone https://github.com/CBICA/DeepMRSeg.git
cd DeepMRSeg
python setup.py install #install DeepMRSeg and its dependencies
conda create --name DeepMRSeg python=3.7.9
conda activate DeepMRSeg
Then follow steps from direct installation
After installation of the package, users can call DeepMRSeg commands on the command prompt (or on Anaconda prompt).
Pre-trained models for testing are hosted in DeepMRSeg-Models repository. Users can manually download a model from the model repository into a local folder.
Alternatively, the model can be downloaded to a pre-defined local folder (~/.deepmrseg/trained_models) automatically using the command:
deepmrseg_downloadmodel
Users can train their own model using a custom training dataset (training):
deepmrseg_train
or apply a pre-trained model on their image(s) (testing):
deepmrseg_test
Note that deepmrseg_train and deepmrseg_test are generic commands that allow users to run training and testing in an exhaustive way by supplying a set of user arguments.
Alternatively, we provide a simplified interface for the application of a specific segmentation task on user data:
deepmrseg_apply
Note that deepmrseg_apply is a wrapper to deepmrseg_test, which calls it with a pre-defined model automatically downloaded using deepmrseg_downloadmodel.
We provide here few examples using minimal argument sets as a quick reference. These examples also show 3 possible I/O options provided for different use cases (single subject, batch processing using an image list and batch processing of images in a folder).
Quick application on single subject using the wrapper scripts and a pre-trained model:
# Download the pre-trained ICV segmentation model
deepmrseg_downloadmodel --model dlicv
# Segment image
deepmrseg_apply --task dlicv --inImg subj1_T1.nii.gz --outImg subj1_T1_DLICV.nii.gz
Quick application for batch processing using an image list:
# User provides a csv file with columns: ID,InputMod1,InputMod2,...,OutputImage
deepmrseg_apply --task dlicv --sList subjectList.csv
Quick application for batch processing of all images in a folder:
# Testing is applied individually to all images with the given suffix in the input folder
deepmrseg_apply --task dlicv --inDir myindir --outDir myoutdir --inSuff _T1.nii.gz --outSuff _DLICV.nii.gz
Segmentation using the deepmrseg_test command:
#
deepmrseg_test --mdldir my/path/to/pretrained/model --sList subjectList.csv
Please see the user manual (or call the command with the -h option) for details of the complete command line arguments for deepmrseg_test.
Training a new model using the deepmrseg_train command:
#
deepmrseg_train --sList subjectList.csv --mdlDir my/path/to/output/model
Please see the user manual (or call the command with the -h option) for details of the complete command line arguments for deepmrseg_train.
[1] Doshi, Jimit, et al. DeepMRSeg: A convolutional deep neural network for anatomy and abnormality segmentation on MR images. arXiv preprint arXiv:1907.02110 (2019).
The DeepMRSeg package is currently developed and maintained by:
Others who contributed to the project are:
Development of the DeepMRSeg package is supported by the following grants:
- The software has been designed for research purposes only and has neither been reviewed nor approved for clinical use by the Food and Drug Administration (FDA) or by any other federal/state agency.
- This code (excluding dependent libraries) is governed by the license provided in https://www.med.upenn.edu/cbica/software-agreement-non-commercial.html unless otherwise specified.
- By using DeepMRSeg, you agree to the license as stated in the license file.
For more information, please contact CBICA Software.