Skip to main content

pyStackReg

Summary

Python/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.

Description

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 http://bigwww.epfl.ch/thevenaz/turboreg/).

pyStackReg provides the following four 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).

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).

Installation

The package is available on PyPi. Install it using:

pip install pystackreg

Documentation

The documentation can be found on readthedocs:

https://pystackreg.readthedocs.io/

Usage

The following example opens two different files and registers them using all different possible transformations

from pystackreg import StackReg
from skimage import io

#load reference and "moved" image
ref = io.imread('some_original_image.tif')
mov = io.imread('some_changed_image.tif')

#Translational transformation
sr = StackReg(StackReg.TRANSLATION)
out_tra = sr.register_transform(ref, mov)

#Rigid Body transformation
sr = StackReg(StackReg.RIGID_BODY)
out_rot = sr.register_transform(ref, mov)

#Scaled Rotation transformation
sr = StackReg(StackReg.SCALED_ROTATION)
out_sca = sr.register_transform(ref, mov)

#Affine transformation
sr = StackReg(StackReg.AFFINE)
out_aff = sr.register_transform(ref, mov)

#Bilinear transformation
sr = 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):

from pystackreg import StackReg
from skimage import io

img0 = 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 1st
sr.register(img0[0, :, :], img0[1,:,:])

# use the transformation from the above registration to register another frame
out = sr.transform(img1[1,:,:])

The next examples shows how to register and transform a whole stack:

from pystackreg import StackReg
from skimage import io

img0 = io.imread('some_multiframe_image.tif') # 3 dimensions : frames x width x height

sr = StackReg(StackReg.RIGID_BODY)

# register each frame to the previous (already registered) one
# this is what the original StackReg ImageJ plugin uses
out_previous = sr.register_transform_stack(img0, reference='previous')

# register to first image
out_first = sr.register_transform_stack(img0, reference='first')

# register to mean image
out_mean = sr.register_transform_stack(img0, reference='mean')

# register to mean of first 10 images
out_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):

from pystackreg import StackReg
from skimage import io

img0 = io.imread('some_multiframe_image.tif') # 3 dimensions : frames x width x height
img1 = io.imread('another_multiframe_image.tif') # same shape as img0

# both stacks must have the same shape
assert img0.shape == img1.shape

sr = StackReg(StackReg.RIGID_BODY)

# register each frame to the previous (already registered) one
# this is what the original StackReg ImageJ plugin uses
tmats = sr.register_stack(img0, reference='previous')
out = sr.transform_stack(img1)

# tmats contains the transformation matrices -> they can be saved
# and loaded at another time
import numpy as np
np.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 file
sr.transform_stack(img1, tmats=tmats_loaded)

# with the transformation matrices at hand you can also
# use the transformation algorithms from other packages:
from skimage import transform as tf

out = np.zeros(img0.shape).astype(np.float)

for i in range(tmats.shape[0]):
    tform = tf.AffineTransform(matrix=tmats[i, :, :])
    out[i, :, :] = tf.warp(img1[i, :, :], tform)

Author information

This 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/
\===================================================================*/

License

Below is the license of TurboReg/StackReg:

/*====================================================================
| Additional help available at http://bigwww.epfl.ch/thevenaz/turboreg/
|
| You'll be free to use this software for research purposes, but you
| should not redistribute it without our consent. In addition, we expect
| you to include a citation or acknowledgment whenever you present or
| publish results that are based on it.
\===================================================================*/

Metadata

Release files for pystackreg 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pystackreg 0.2.0
File Size Uploaded Provenance Actions
pystackreg-0.2.0.tar.gz 33.6 kB Without provenance Details for pystackreg-0.2.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pystackreg 0.2.0
File Actions
pystackreg-0.2.0-cp36-cp36m-win_amd64.whl CPython 3.6 CPython 3.6 pymalloc Windows x86-64 Details for pystackreg-0.2.0-cp36-cp36m-win_amd64.whl
pystackreg-0.2.0-cp36-cp36m-win32.whl CPython 3.6 CPython 3.6 pymalloc Windows x86-32 Details for pystackreg-0.2.0-cp36-cp36m-win32.whl
pystackreg-0.2.0-cp27-cp27m-win_amd64.whl CPython 2.7 CPython 2.7 pymalloc Windows x86-64 Details for pystackreg-0.2.0-cp27-cp27m-win_amd64.whl
pystackreg-0.2.0-cp27-cp27m-win32.whl CPython 2.7 CPython 2.7 pymalloc Windows x86-32 Details for pystackreg-0.2.0-cp27-cp27m-win32.whl

Total release size: 280.3 kB

Release files / pystackreg-0.2.0.tar.gz

Download URL pystackreg-0.2.0.tar.gz
Size 33.6 kB
Tags Source
SHA-256 checksum
How to use checksums
31324f77136d9666a0c25922edfd38af50d174386cf6661dc2dbcf2e95af67d8
BLAKE2b-256 checksum
How to use checksums
08f470e3c997f412b9d9e1476f041636b20da8dd1541ff4556199be01178d53d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.6

Release files / pystackreg-0.2.0-cp36-cp36m-win_amd64.whl

Download URL pystackreg-0.2.0-cp36-cp36m-win_amd64.whl
Size 60.1 kB
Tags CPython 3.6 CPython 3.6 pymalloc Windows x86-64
SHA-256 checksum
How to use checksums
b158d75989d719f19c4c51b640d8ac3ec08a111d25c265679372c8fa4dca60ec
BLAKE2b-256 checksum
How to use checksums
7aa8fcb6aa02f483c04cb8b5fa1ec290a965a1f74b31bd4081d2320f526c3adf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.6

Release files / pystackreg-0.2.0-cp36-cp36m-win32.whl

Download URL pystackreg-0.2.0-cp36-cp36m-win32.whl
Size 53.4 kB
Tags CPython 3.6 CPython 3.6 pymalloc Windows x86-32
SHA-256 checksum
How to use checksums
a57fee1ab596cd8ee695562e75a12e77e72df0be9363c8f94ef346104950c283
BLAKE2b-256 checksum
How to use checksums
7ebeb69b032a933ed004afb54dc13b4f43ef87c1aa7602e1819ace7b3051f817
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.6

Release files / pystackreg-0.2.0-cp27-cp27m-win_amd64.whl

Download URL pystackreg-0.2.0-cp27-cp27m-win_amd64.whl
Size 72.1 kB
Tags CPython 2.7 CPython 2.7 pymalloc Windows x86-64
SHA-256 checksum
How to use checksums
4e7c54b270b5d1673ca3894e54529952db7500d1f9ac0e6257cca058af7ecd9c
BLAKE2b-256 checksum
How to use checksums
9a2df3dc4eef1c11032c8fd20ff8af70827b299fdafd6a27348ccd39bb83686e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.6

Release files / pystackreg-0.2.0-cp27-cp27m-win32.whl

Download URL pystackreg-0.2.0-cp27-cp27m-win32.whl
Size 61.0 kB
Tags CPython 2.7 CPython 2.7 pymalloc Windows x86-32
SHA-256 checksum
How to use checksums
b911874df1aff1679833d40916067ac621877bf325628a3c01cdfa60c2fd0870
BLAKE2b-256 checksum
How to use checksums
f3886535e963a44b5f42aac6229559507e61d65b1ab3e93f6b2189f4f973dae1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.6

Security for pystackreg 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page