AssemblyNet: 3D Whole Brain MRI Segmentation

This repository presents the Docker image of our whole brain segmentation pipeline: AssemblyNet [paper].

Based on a large ensemble of convolution neural networks, AssemblyNet allows to segment a T1 MRI scan image in 133 labels, according to BrainColor protocol.

Given an input T1 image in nifti format, this Docker image will produce segmentation images (in native and MNI spaces) of intracranial cavity, brain tissues, brain macrostructures, cortical lobes, and cortical and subcortical structures, and also a report and a csv file with segmented volumes and expected bounds (if age is provided).

Here are examples of produced segmentations (in MNI space): structures, macrostructures, tissues, lobes, intracranial cavity corresponding to this processed T1 image. Here are examples of produced PDF and CSV volumetry reports: report.pdf and report.csv.

This Docker image is to be used only for non-commercial and non-medical purposes (research only). See license.

If you use this Docker image, please cite:
Pierrick Coupé, Boris Mansencal, Michaël Clément, Rémi Giraud, Baudouin Denis de Senneville, Vinh-Thong Ta, Vincent Lepetit, José V. Manjon
AssemblyNet: A large ensemble of CNNs for 3D whole brain MRI segmentation.
NeuroImage, Elsevier, 2020, 219, pp.117026. [paper] [bibtex]

Quick Start instructions

If you have already installed Docker, you can get the volbrain/assemblynet:1.0.0 image from Docker Hub repository:

sudo docker pull volbrain/assemblynet:1.0.0

If you have a NVIDIA GPU with at least 8GB, and have already installed NVIDIA Container Toolkit, you can run AssemblyNet on the GPU on the image /absolute/path/to/images/image.nii.gz:

sudo docker run --rm --gpus '"device=0"' -v /absolute/path/to/images:/data volbrain/assemblynet:1.0.0 /data/image.nii.gz

If you have a x86_64 CPU, you can run AssemblyNet on the CPU on the image /absolute/path/to/images/image.nii.gz:

sudo docker run --rm -v /absolute/path/to/images:/data volbrain/assemblynet:1.0.0 /data/image.nii.gz

See Installation instructions for detailed instructions on how to install all the dependencies.
See How to use AssemblyNet for detailed instructions on how to use AssemblyNet.

Installation instructions

Prerequisites

To run this Docker image on a CPU, you will need:

• a x86_64 CPU
• At least 6GB of RAM
• GNU/Linux [supported distributions] or Windows 10/11 with WSL [supported versions]
• Docker >= 19.03
• AssemblyNet Docker image
• MRI files in nifti format

To run this Docker image on a GPU, you will need:

• A NVIDIA GPU with at least 8GB and a CUDA Compute capability >= 6.0 (that is a GPU from the NVIDIA Pascal, Volta, Turing, and Ampere Architecture GPU families. For example Titan Xp, V100, GeForce RTX 2080, Geforce RTX 3080, A40, ...)
• GNU/Linux x86_64 with kernel version > 3.10 (for example Ubuntu 16.04 or above) [supported distributions] or Windows 10/11 with WSL 2 [supported versions]
• NVIDIA drivers >= 418.xx with xx>=40, 440.xx with xx>=33, 450.xx with xx>=51, 460.xx with xx>=27 or 470.xx [driver requirements]
• Docker >= 19.03
• NVIDIA Container Toolkit
• AssemblyNet Docker image
• MRI files in nifti format

Installation

Docker may be installed on supported versions of GNU/Linux or Windows 10/11 with WSL. The docker image can also be transformed in a Singularity image

Installation on GNU/Linux

Here are the detailled installation instructions on Ubuntu (18.04 or above).

Docker

Install Docker from official repository [instructions].
(Docker no longer releases updated packages for Ubuntu 16.04)

#Uninstall old versions of docker
sudo apt-get remove docker docker-engine docker.io containerd runc
#Install using the official repository
sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
#Verify that Docker Engine is installed correctly
sudo docker run hello-world
# it may download the hello-world docker image and then print "Hello from Docker!" and other information.

NVIDIA Driver [GPU-use only]

Install the proprietary NVIDIA driver.

You need a NVIDIA driver version >= 418.xx with xx>=40, 440.xx with xx>=33, 450.xx with xx>=51, 460.xx with xx>=27 or 470.xx [driver requirements]

For exemple:

sudo apt install nvidia-driver-470

NVIDIA Container Toolkit [GPU-use only]

Install NVIDIA Container Toolkit (nvidia-docker2 package) from official repository [instructions]

distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
   && curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - \
   && curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker
#Verify that Docker can access the GPU with:
sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
# it may download the nvidia/cuda:11.0-base docker image and then run nvidia-smi from inside the docker without any error.

For other linux distributions, see NVIDIA Container Toolkit installation instructions.

AssemblyNet Docker image

Pull the volbrain/assemblynet:1.0.0 image from Docker Hub repository:

sudo docker pull volbrain/assemblynet:1.0.0

See How to use AssemblyNet.

Installation on Windows 10/11 with WSL

Here are the detailled installation instructions on Windows 10 or 11.

Check Windows version

You need:

• Windows 10 64-bit: Home or Pro 2004 (build 19041) or higher, or Enterprise or Education 1909 (build 18363) or higher.
• Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher.

To check your Windows version and build number, select Windows logo key + R, type winver, select OK. You can update to the latest Windows version by selecting Start > Settings > Windows Update > Check for updates.

Enable BIOS virtualization support

BIOS-level hardware virtualization support must be enabled.

You can check the Performance tab on the Task Manager to see if virtualization is enabled, see virtualization support.

WSL2

Install Windows Subsystem for Linux (WSL) 2 [instructions]

Open PowerShell as Administrator (Start menu > PowerShell > right-click > Run as Administrator) and enter this command:

wsl --install

It should install the last Ubuntu LTS. You may need to reboot your machine.

You can check that WSL version 2 was installed: Open PowerShell as Administrator (Start menu > PowerShell > right-click > Run as Administrator) and enter this command:

wsl -l -v

Launch Ubuntu (Start menu > ubuntu). It should ask to create a default user. You may upgrade the system:

sudo apt-get update
sudo apt-get upgrade

Docker Desktop

Install Docker Desktop [instructions].

Download Docker Desktop 2.3+ and follow the installation instructions. Use of WSL 2 backend should be enabled by default during installation if WSL 2 was correctly installed.

You have to log off and log in again to be able to use Docker Desktop.

If your admin account is different to your user account, you must add the user to the docker-users group. Run Computer Management as an administrator and navigate to Local Users and Groups > Groups > docker-users. Right-click to add the user to the group. Log out and log back in for t