Skip to content
This repository has been archived by the owner on Jul 30, 2019. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Downloads shield


Travis Documentation Status DockerHub arXiv Tag

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)

Sytem Requirements

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 External libraries:

  • 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).

Installation Guide

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.

Expected Output

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 data folder

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.


Perform image registration of 2D and 3D volumes using state-of-the-art deformable registration.







No packages published