Package: pystackreg
pyStackRegSummaryPython/C++ port of the ImageJ extension TurboReg/StackReg written by Philippe Thevenaz/EPFL.A python extension for the automatic alignment of a source image or a stack (movie) to a target image/reference frame.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).InstallationThe package is available on conda forge and on PyPi.Install usingcondacondainstallpystackreg-cconda-forgeInstall usingpippipinstallpystackregDocumentationThe documentation can be found on readthedocs:https://pystackreg.readthedocs.io/TutorialA tutorial notebook can be found in theexamples/notebooksfolder
or statically here:https://pystackreg.readthedocs.io/en/latest/tutorial.htmlUsageThe following example opens two different files and registers them using all different possible transformationsfrompystackregimportStackRegfromskimageimportio#load reference and "moved" imageref=io.imread('some_original_image.tif')mov=io.imread('some_changed_image.tif')#Translational transformationsr=StackReg(StackReg.TRANSLATION)out_tra=sr.register_transform(ref,mov)#Rigid Body transformationsr=StackReg(StackReg.RIGID_BODY)out_rot=sr.register_transform(ref,mov)#Scaled Rotation transformationsr=StackReg(StackReg.SCALED_ROTATION)out_sca=sr.register_transform(ref,mov)#Affine transformationsr=StackReg(StackReg.AFFINE)out_aff=sr.register_transform(ref,mov)#Bilinear transformationsr=StackReg(StackReg.BILINEAR)out_bil=sr.register_transform(ref,mov)The next example shows how to separate registration from transformation (e.g., to register in one color channel and then use that information to transform another color channel):frompystackregimportStackRegfromskimageimportioimg0=io.imread('some_multiframe_image.tif')img1=io.imread('another_multiframe_image.tif')# img0.shape: frames x width x height (3D)sr=StackReg(StackReg.RIGID_BODY)# register 2nd image to 1stsr.register(img0[0,:,:],img0[1,:,:])# use the transformation from the above registration to register another frameout=sr.transform(img1[1,:,:])The next examples shows how to register and transform a whole stack:frompystackregimportStackRegfromskimageimportioimg0=io.imread('some_multiframe_image.tif')# 3 dimensions : frames x width x heightsr=StackReg(StackReg.RIGID_BODY)# register each frame to the previous (already registered) one# this is what the original StackReg ImageJ plugin usesout_previous=sr.register_transform_stack(img0,reference='previous')# register to first imageout_first=sr.register_transform_stack(img0,reference='first')# register to mean imageout_mean=sr.register_transform_stack(img0,reference='mean')# register to mean of first 10 imagesout_first10=sr.register_transform_stack(img0,reference='first',n_frames=10)# calculate a moving average of 10 images, then register the moving average to the mean of# the first 10 images and transform the original image (not the moving average)out_moving10=sr.register_transform_stack(img0,reference='first',n_frames=10,moving_average=10)The next example shows how to separate registration from transformation for a stack (e.g., to register in one color channel and then use that information to transform another color channel):frompystackregimportStackRegfromskimageimportioimg0=io.imread('some_multiframe_image.tif')# 3 dimensions : frames x width x heightimg1=io.imread('another_multiframe_image.tif')# same shape as img0# both stacks must have the same shapeassertimg0.shape==img1.shapesr=StackReg(StackReg.RIGID_BODY)# register each frame to the previous (already registered) one# this is what the original StackReg ImageJ plugin usestmats=sr.register_stack(img0,reference='previous')out=sr.transform_stack(img1)# tmats contains the transformation matrices -> they can be saved# and loaded at another timeimportnumpyasnpnp.save('transformation_matrices.npy',tmats)tmats_loaded=np.load('transformation_matrices.npy')# make sure you use the correct transformation here!sr=StackReg(StackReg.RIGID_BODY)# transform stack using the tmats loaded from filesr.transform_stack(img1,tmats=tmats_loaded)# with the transformation matrices at hand you can also# use the transformation algorithms from other packages:fromskimageimporttransformastfout=np.zeros(img0.shape).astype(np.float)foriinrange(tmats.shape[0]):out[i,:,:]=tf.warp(img1[i,:,:],tmats[i,:,:],order=3)Author informationThis is a port of the original Java code by Philippe Thevenaz to C++ with a Python wrapper around it. All credit goes to the original author:/*====================================================================
| Philippe Thevenaz
| EPFL/STI/IMT/LIB/BM.4.137
| Station 17
| CH-1015 Lausanne VD
| Switzerland
|
| phone (CET): +41(21)693.51.61
| fax: +41(21)693.37.01
| RFC-822: philippe.thevenaz@epfl.ch
| X-400: /C=ch/A=400net/P=switch/O=epfl/S=thevenaz/G=philippe/
| URL: http://bigwww.epfl.ch/
\===================================================================*/

/*====================================================================
| This work is based on the following paper:
|
| P. Thevenaz, U.E. Ruttimann, M. Unser
| A Pyramid Approach to Subpixel Registration Based on Intensity
| IEEE Transactions on Image Processing
| vol. 7, no. 1, pp. 27-41, January 1998.
|
| This paper is available on-line at
| http://bigwww.epfl.ch/publications/thevenaz9801.html
|
| Other relevant on-line publications are available at
| http://bigwww.epfl.ch/publications/
\===================================================================*/LicenseYou are free to use this software for commercial and non-commercial
purposes. However, we expect you to include a citation or acknowledgement
whenever you present or publish research results that are based
on this software. You are free to modify this software or derive
works from it, but you are only allowed to distribute it under the
same terms as this license specifies. Additionally, you must include
a reference to the research paper above in all software and works
derived from this software.Changelog0.2.7fixedAxis argument not used for method “mean” in register_stack() (PR #26)0.2.6addedexposing simple_slice and running_mean functions in util packageadded conversion function to any integer dtype0.2.5fixedCompilation in environment without numpy0.2.3addedAdded example data and tutorial notebookAdded unit testsAdditional documentationDetection of time series axis in stacks - will raise a warning if supplied axis in
stack registration does not correspond to the detected axischangedprogress_callbackfunction now gets called with the iteration number, not
iteration index (iteration number = iteration index + 1)fixedFixed exception when using a different axis than 0 for registering stacks0.2.2changedLicense changed to allow distribution on python package repositories0.2.1addedprogress callback function can be supplied toregister_stack()andregister_transform_stack()functions via theprogress_callbackthat is then called after every iteration (i.e. after each image registration)changedprogress bar output not shown by default, has to be enabled by using theverbose=Trueparameter in theregister_stack()andregister_transform_stack()functions0.2.0addedbilinear transformation