Package: napari-pystackreg
napari-pystackregRobust image registration for napari.Summarynapari-pystackreg offers the image registration capabilities of the python packagepystackregfor napari.DescriptionpyStackReg 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 pluginTurboRegand provides additionally the
functionality of the ImageJ pluginStackReg, both of which were written by Philippe Thevenaz/EPFL
(available athttp://bigwww.epfl.ch/thevenaz/turboreg/).pyStackReg provides the following five types of distortion:TranslationRigid 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).InstallationYou can installnapari-pystackregviapipfromPyPI:pip install napari-pystackregYou can also installnapari-pystackregviaconda:conda install -c conda-forge napari-pystackregOr install it via napari's plugin installer.Plugins > Install/Uninstall Plugins... > Filter for "napari-pystackreg" > InstallTo install latest development version:pip install git+https://github.com/glichtner/napari-pystackreg.gitUsageOpen Plugin User InterfaceStart up napari, e.g. from the command line:napariThen, load an image stack (e.g. viaFile > Open Image...) that you want to register. You can also use the example
stack provided by the pluging (File > Open Sample > napari-pystackreg: PC12 moving example).
Then, select thenapari-pystackregplugin from thePlugins > napari-pystackreg: pystackregmenu.User Interface OptionsA variety of options are available to control the registration process:Image Stack: The image layer that should be registered/transformed.Transformation: The type of transformation that should be applied.Translation: translationRigid body: translation + rotationScaled rotation: translation + rotation + scalingAffine: translation + rotation + scaling + shearingBilinear: non-linear transformation; does not preserve straight linesReference frame:The reference image for registration.Previous frame: Aligns each frame (image) to its previous frame in the stackMean (all frames): Aligns each frame (image) to the average of all images in the stackMean (first n frames): Aligns each frame (image) to the mean of the first n frames in the stack. n is a tuneable parameter.Moving-average stack before register: Apply a moving average to the stack before registration. This can be useful to
reduce noise in the stack (if the signal-to-noise ratio is very low). The moving average is applied to the stack only
for determining the transformation matrices, but not for the actual transforming of the stack.Transformation matrix file: Transformation matrices can be saved to or loaded from a file for permanent storage.Reference frameThe reference frame is the frame to which the other frames are aligned. The default option is to use thePrevious frame, which will register each frame to its respective previous frame in the stack. Alternatively, the
reference frame can be set to the mean of all frames in the stack (Mean (all frames)) or the mean of the first n
frames in the stack (Mean (first n frames)). The latter option can be useful if the first frames in the stack are more
stable than the later frames (e.g. if the first frames are taken before the sample is moved). When selecting theMean (first n frames)option, the number of frames to use for the mean can be set via the spinbox below the option.Moving average before registrationTo increase registration performance with low signal-to-noise ratio stacks, a moving average can be applied to the
stack before registration. The moving average is applied to the stack only for determining the
transformation matrices, but not for the actual transforming of the stack. That means that the transformed stack will
still contain the original frames (however registered), but not the averaged frames.When selecting theMoving-average stack before registeroption, the number of frames to use for the moving average can
be set via the spinbox below the option.Transformation matrix fileThe transformation matrices can be saved to or loaded from a file for permanent storage. This can be useful if you want
to apply the same transformation to another stack (e.g. a different channel of the same sample). The transformation
matrices are saved as a numpy array in a binary file (.npy). The file can be loaded via theLoadbutton and saved
via theSavebutton.Register/TransformTo perform the actual registration and transformation steps, click theRegisterandTransformbuttons, respectively.TheRegisterbutton will register the stack to the reference by determining the appropriate transformation matrices,
without actually transforming the stack. The transformation matrices can be saved to a file via theSavebutton in theTransformation matrix filesection.TheTransformbutton (1) will transform the stack to the reference by applying the transformation matrices that are
currently loaded to the stack selected inImage Stack. For the button to become active, either the transformation
matrices have to be loaded from a file via theLoadbutton in theTransformation matrix filesection, or theRegisterbutton has to be clicked first to determine the transformation matrices.TheTransformbutton will also add a new image layer to the napari viewer (2) with the transformed stack. The name of the
new layer will be the name of the original stack with the prefixRegistered.Finally, theRegister & Transformbutton will perform both the registration and transformation steps in one go.ContributingContributions are very welcome. Tests can be run withtox, please ensure
the coverage at least stays the same before you submit a pull request.LicenseDistributed under the terms of theApache Software License 2.0license,
"napari-pystackreg" is free and open source software.IssuesIf you encounter any problems, pleasefile an issuealong with a detailed description.AcknowledgmentsThisnapariplugin was generated withCookiecutterusing@napari'scookiecutter-napari-plugintemplate.