thunder-registration

algorithms for registering sequences of images

This package Includes a collection of algorithms for image registration. It is well-suited to registering movies obtained in the medical or neuroscience imaging domains, but can be applied to any image sequences requiring alignment.

The API is designed around algorithms that can be fit to data, all of which return a model that can be used to transform new data, in the style of scikit-learn. Built on numpy and scipy. Compatible with Python 2.7+ and 3.4+. Works well alongside thunder and supprts parallelization via spark, but can be used as a standalone package on local numpy arrays.

installation

pip install thunder-registration

example

In this example we create shifted copies of a reference image and then align them

# create shifted copies

from numpy import arange
from scipy.ndimage.interpolation import shift
reference = arange(9).reshape(3, 3)
deltas = [[1, 0], [0, 1]]
shifted = [shift(reference, delta, mode='wrap', order=0) for delta in deltas]

# perform registration

from registration import CrossCorr
register = CrossCorr()
model = register.fit(shifted, reference=reference)

# the estimated transformations should match the deltas we used

print(model.transformations)
>> {(0,): Displacement(delta=[1, 0]), (1,): Displacement(delta=[0, 1])}

usage

Import and construct an algorithm.

from registration import CrossCorr
algorithm = CrossCorr()

Fit the algorithm to data to compute registration parameters and return a model

model = algorithm.fit(data, opts)

The attribute model.transformations is a dictionary mapping image index to whatever transformation type was returned by the fitting. You can apply the estimated registration to the same or different data.

registered = model.transform(data)

api

algorithm

All algorithms have the following methods:

algorithm.fit(images, opts)

Fits the algorthm to the images, with optional arguments that will depend on the algorithm. The images can be a numpy ndarray or a thunder images object.

model

The result of fitting an algorithm to data is a model.

A model has the following properties and methods:

model.transformations

A dictionary mapping image index to the transformation returned by fitting.

model.transform(images)

Applies the estimated transformations to a new set of images. As with fitting, images can be a numpy ndarray or a thunder Images object.

list of algorithms

The following algorithms are available:

CrossCorr(axis=None).fit(images, reference)

Uses cross-correlation to estimate an integer n-dimensional displacement between all images and a reference.

• axis specify an axis to restrict estimates to e.g. axis=2 to only estimate displacements in (0,1)
• images can be a numpy ndarray or a thunder Images object
• reference an ndarray reference image

tests

Run tests with

py.test

Tests run locally with numpy by default, but the same tests can be run against a local spark installation using

py.test --engine=spark