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

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

License

Notifications You must be signed in to change notification settings

neurodata/ndreg

Repository files navigation

Downloads shield

ndreg

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.

Demo

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:

http://0.0.0.0:8888/?token=SOME_TOKEN

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.