This repository implements a unified model for super-resolving medical images (MRI and CT scans), which combines: super-resolution with a multi-channel denoising prior, rigid registration and a correction for interleaved slice acquisition. The archetype use-case is when having multiple scans of the same subject (e.g., T1w, T2w and FLAIR MRIs) and an analysis requires these scans to be represented on the same grid (i.e., having the same image size, affine matrix and voxel size). By default, the model reconstructs 1 mm isotropic images with a field-of-view that contains all input scans; however, this voxel size can be customised with the possibility of sub-millimetric reconstuctions. The model additionally supports multiple repeats of each MR sequence. There is an option that makes images registered and defined on the same grid, across subjects, where the grid size is optimal from a CNN fitting perspective. The implementation is written in PyTorch and should therefore execute fast on the GPU. The software can be run either through Docker -- which ensures the correct library and OS versions are used, plus requires no compilation -- or directly by interfacing with the Python code.
An installation-free demo of UniRes is available in Colab:
Clone UniRes:
git clone https://github.com/brudfors/UniResThen cd into the UniRes folder and install it by:
pip install .OBS: The algorithm runs much faster if the compiled backend is used:
NI_COMPILED_BACKEND="C" pip install --no-build-isolation .However, for running on the GPU, this only works if you ensure that the PyTorch installation uses the same CUDA version that is on your system; therefore, it might be worth installing PyTorch beforehand, i.e.:
pip install torch==1.9.0+cu111
NI_COMPILED_BACKEND="C" pip install --no-build-isolation .where the PyTorch CUDA version matches the output of nvcc --version.
Running UniRes is straight forward. Let's say you have three
MR images: T1.nii.gz, T2.nii.gz and PD.nii.gz, then
simply run unires in the terminal as:
unires T1.nii.gz T2.nii.gz PD.nii.gzThree 1 mm isotropic images are written to the same folder as the input
data, prefixed 'ur_'.
Algorithm options can be displayed by:
unires --helpAs an example, the voxel size of the super-resolved data is here set to 1.5 mm isotropic:
unires --vx 1.5 T1.nii.gz T2.nii.gz PD.nii.gzThere is also an option that makes images registered and defined on the same grid, across subjects, where the grid size is optimal from a CNN fitting perspective:
unires --common_output T1.nii.gz T2.nii.gz PD.nii.gzAs the unified super-resolution can take a few minutes (on a fast GPU ;), it is possible to instead use a trilinear reslice, this is enabled by:
unires --linear --common_output T1.nii.gz T2.nii.gz PD.nii.gzThis section describes setting up UniRes to run using NVIDIA's Docker engine on Ubuntu. As long as the NVIDIA Docker engine can be installed on MS Windows or Mac OSX there is no reason that these operating systems could not also be used. However, setting it up for Windows and OSX is not described here.
Make sure that you have installed the NVIDIA driver and Docker engine for your Linux distribution (you do not need to install the CUDA Toolkit on the host system). These commands should install Docker:
curl https://get.docker.com | sh
sudo systemctl start docker && sudo systemctl enable dockerRegarding the NVIDIA driver, I personally like the installation guide in [1] (step 2). Although this guide is targeted at Ubuntu 19.04, it should generalise to other Debian/Ubuntu versions (I used it for Ubuntu 18.04).
Execute the following commands to install the NVIDIA Docker engine:
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-docker2Next, edit/create /etc/docker/daemon.json with content (e.g., by sudo vim /etc/docker/daemon.json):
{
"runtimes": {
"nvidia": {
"path": "/usr/bin/nvidia-container-runtime",
"runtimeArgs": []
}
},
"default-runtime": "nvidia"
}
then do:
sudo systemctl restart dockerFinally, test that it works by starting nvidia-smi in a Docker container:
sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smicd to the content of the docker folder and run the following command to
build the UniRes image:
docker build --rm --tag unires:1.0 .If there are permission issues, the following can help:
sudo chmod 666 /var/run/docker.sockNow you can run UniRes via Docker containers started from the unires:1.0
image!
Let's say you have a folder named data in your current working directory,
which contains two MR images of the same subject: T1.nii.gz, PD.nii.gz.
You can then process these two scans with UniRes by executing:
docker run -it --rm -v $PWD/data:/home/docker/app/data unires:1.0 data/T1.nii.gz data/PD.nii.gzWhen the algorithm has finished, you will find the processed scans in
the same data folder, prefixed 'ur_'.
@inproceedings{brudfors2018mri,
title={MRI super-resolution using multi-channel total variation},
author={Brudfors, Mikael and Balbastre, Ya{\"e}l and Nachev, Parashkev and Ashburner, John},
booktitle={Annual Conference on Medical Image Understanding and Analysis},
pages={217--228},
year={2018},
organization={Springer}
}
@article{brudfors2019tool,
title={A Tool for Super-Resolving Multimodal Clinical MRI},
author={Brudfors, Mikael and Balbastre, Yael and Nachev, Parashkev and Ashburner, John},
journal={arXiv preprint arXiv:1909.01140},
year={2019}
}
.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent