Robust image registration for napari

    License PyPI Python Version tests codecov napari hub

    Robust image registration for napari.


    napari-pystackreg offers the image registration capabilities of the python package pystackreg for napari.


    pyStackReg is used to align (register) one or more images to a common reference image, as is required usually in time-resolved fluorescence or wide-field microscopy. It is directly ported from the source code of the ImageJ plugin TurboReg and provides additionally the functionality of the ImageJ plugin StackReg, both of which were written by Philippe Thevenaz/EPFL (available at

    pyStackReg provides the following five types of distortion:

    • translation
    • rigid body (translation + rotation)
    • scaled rotation (translation + rotation + scaling)
    • affine (translation + rotation + scaling + shearing)
    • bilinear (non-linear transformation; does not preserve straight lines)

    pyStackReg supports the full functionality of StackReg plus some additional options, e.g., using different reference images and having access to the actual transformation matrices (please see the examples below). Note that pyStackReg uses the high quality (i.e. high accuracy) mode of TurboReg that uses cubic spline interpolation for transformation.

    Please note: The bilinear transformation cannot be propagated, as a combination of bilinear transformations does not generally result in a bilinear transformation. Therefore, stack registration/transform functions won't work with bilinear transformation when using "previous" image as reference image. You can either use another reference ( "first" or "mean" for first or mean image, respectively), or try to register/transform each image of the stack separately to its respective previous image (and use the already transformed previous image as reference for the next image).

    This napari plugin was generated with Cookiecutter using @napari's cookiecutter-napari-plugin template.


    You can install napari-pystackreg via pip:

    pip install napari-pystackreg

    To install latest development version :

    pip install git+


    Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.


    Distributed under the terms of the Apache Software License 2.0 license, "napari-pystackreg" is free and open source software


    If you encounter any problems, please file an issue along with a detailed description.


    • 0.1.1

    Release date:

    • 07 July 2022

    First released:

    • 07 July 2022


    • Apache-2.0

    Supported data:

    • Information not submitted

    GitHub activity:

    • Stars: 2
    • Forks: 0
    • Issues + PRs: 1

    Python versions supported:

    Operating system:


    • magicgui
    • numpy
    • pystackreg (>=0.2.6)
    • qtpy

    Sign up to receive updates