mdreg documentation#

Model-driven image registration for medical imaging

Aim#

Pain-free motion-correction of medical image time series with changing image contrast.

Features#

A simple high-level interface mdreg.fit() for model-driven registration.
A collection of example data and scripts to help new users get started.
A harmonized interface for coregistration methods in three common packages.
A growing library of signal models for different applications.
Built-in plotting and visualisation options for inspection of results.
Built-in support for larger-than-RAM datasets using zarrays.
Built-in support for parallel computation using dask.

Installation#

To include the full functionality install with:

pip install mdreg[complete]

This installs packages needed for plotting and three coregistration packages (skimage, antspyx, itk-elastix).

Alternatively, a lightweight version with core functionality can be installed. It does not include plotting options and includes only one package (skimage) for coregistration:

pip install mdreg

Typical usage#

Consider a dataset consisting of:

a 4D array signal with a series of free-breathing 3D MRI images of the abdomen with variable flip angles (VFA).
a 1D array FA with the respective flip angles.

To remove the motion with mdreg, we first need to specify which model we want to use:

vfa = {
    'func': mdreg.fit_vfa_lin,
    'FA': FA,
}

And that’s it. We can now perform motion correction:

coreg, fit, defo, pars = mdreg.fit(signal, fit_image=vfa)

The function mdreg.fit() returns 4 arrays:

coreg is the signal array with motion removed;
fit is the array with model fits;
defo is the deformation field;
pars is an array with fitted parameters.

We can inspect the result visually using the built-in plot functions:

mdreg.plot.animation(coreg)

Getting started#

Have look at the user guide or dive straight in with the examples.

Citing#

When you use mdreg, please cite:

Kanishka Sharma, Fotios Tagkalakis, Irvin Teh, Bashair A Alhummiany, David Shelley, Margaret Saysell, Julie Bailey, Kelly Wroe, Cherry Coupland, Michael Mansfield, Steven P Sourbron. An open-source, platform independent library for model-driven registration in quantitative renal MRI. ISMRM workshop on renal MRI, Lisbon/Philadephia, sept 2021.

License#

mdreg is distributed under the Apache 2.0 license - a permissive, free license that allows users to use, modify, and distribute the software without restrictions.