This is Neurodata's open-source Python package that performs affine and deformable (LDDMM) image registration.
Easiest way to use
Download gigantum and import ndreg project (see here for details)
The recommended way to use this package is to install Docker. Docker is currently available on Mac OS X El Capitan 10.11 and newer macOS releases, the following Ubuntu versions: Zesty 17.04 (LTS), Yakkety 16.10, Xenial 16.04 (LTS), Trusty 14.04 (LTS), and Windows 10.
Note: Certain optimizations made within the package may require a 64-bit machine with an Intel processor
Software Dependencies (with version numbers)
The only software dependency needed if using the recommended method is Docker. However the main dependency
- Insight Segmentation and Registration Toolkit (ITK) -- 5.0
Versions tested on
We have tested the Docker image and build on macOS High Sierra (on MacBook Pro with 2.9 GHz Intel Core i7 and 16 GB RAM) and Ubuntu Xenial 16.04.3 LTS (with 64 GB RAM).
Once Docker is installed on your machine, pull the
neurodata/ndreg image from Docker Hub here as follows:
docker pull neurodata/ndreg
It will typically take a few minutes to pull the entire Docker image.
Instructions to run demo
In order to use the functionality built into this Docker image, you need to run the Docker image:
docker run -p 8888:8888 neurodata/ndreg
This should print a link to the terminal console that looks like this:
Go to this link in your browser by copying and pasting it.
Next, click on
ndreg_demo_real_data.ipynb. Once the notebook opens, you can run all cells by clicking on 'Cell' and then 'Run All'.
The expected run time for this demo is ~30 minutes.
In order to identify ensure you have the correct output, refer to the Jupyter notebook here.
Use on your own data
In order to run
ndreg on data you have on a local machine, use the following command in your terminal:
docker run -v path/to/local/dir:/run/data/ -p 8888:8888 neurodata/ndreg
-v is passed as an argument in order to mount a local volume to a Docker container. Replace
path/to/local/dir with the absolute (or relative) path to your data locally. You do not need to modify the
:/run/data/ portion of the command; that portion of the command will mount your local volume to the
/run/data/ directory in the Docker container.
If all goes well, a link similar to the one above should be printed. Go to this link in your browser by copying and pasting it. You should see a list of folders (including a
data folder) and the demo Jupyter notebook
ndreg_demo_real_data.ipynb. Your local data will appear in the
In order to reuse the demo Jupyter notebook, modify the cell that contains the
params variable and replace the path to the image data (and path to atlas data if you are not registering to the Allen Reference Atlas), voxel spacing variables, and brain orientations within that cell. (To understand more about the 3-letter orientation scheme see here. (Note: all voxel spacing is recorded in millimeters (mm)). Once these variables are modified, the rest of the notebook can be run as is.