pystackreg 0.3.0__cp314-cp314-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pystackreg/__init__.py +28 -0
- pystackreg/_internal.py +271 -0
- pystackreg/py.typed +0 -0
- pystackreg/pystackreg.py +814 -0
- pystackreg/turboreg.cp314-win_amd64.pyd +0 -0
- pystackreg/util/__init__.py +181 -0
- pystackreg/version.py +1 -0
- pystackreg-0.3.0.dist-info/DELVEWHEEL +2 -0
- pystackreg-0.3.0.dist-info/METADATA +360 -0
- pystackreg-0.3.0.dist-info/RECORD +15 -0
- pystackreg-0.3.0.dist-info/WHEEL +5 -0
- pystackreg-0.3.0.dist-info/licenses/LICENSE +674 -0
- pystackreg-0.3.0.dist-info/licenses/NOTICE +109 -0
- pystackreg-0.3.0.dist-info/top_level.txt +1 -0
- pystackreg.libs/msvcp140-a4c2229bdc2a2a630acdc095b4d86008.dll +0 -0
|
Binary file
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# SPDX-License-Identifier: GPL-3.0-or-later
|
|
2
|
+
# Copyright (C) 2018-2026 Gregor Lichtner and PyStackReg contributors
|
|
3
|
+
"""
|
|
4
|
+
Collection of utility functions for pystackreg
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
import numpy.typing as npt
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
"max_displacement",
|
|
16
|
+
"running_mean",
|
|
17
|
+
"simple_slice",
|
|
18
|
+
"to_int_dtype",
|
|
19
|
+
"to_uint16",
|
|
20
|
+
]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def to_uint16(arr: npt.ArrayLike) -> np.ndarray:
|
|
24
|
+
"""
|
|
25
|
+
Converts image data array to a 16 bit unsigned integer array.
|
|
26
|
+
|
|
27
|
+
.. warning:: Data loss may occur as data points outside of 16 bit (0-65535) are
|
|
28
|
+
clipped.
|
|
29
|
+
|
|
30
|
+
StackReg generally output float arrays. This utility function can be used to convert
|
|
31
|
+
such an output array to 16 bit data by clipping to 16 bit (to remove values < 0 and
|
|
32
|
+
greater 16 bit) and rounding the floats.
|
|
33
|
+
|
|
34
|
+
:type arr: array_like (Ni..., M, Nk...)
|
|
35
|
+
:param arr: Source array (usually float)
|
|
36
|
+
|
|
37
|
+
:rtype: ndarray(Ni..., Nj..., Nk...)
|
|
38
|
+
:return: Input array clipped & rounded to unsigned 16 bit integer
|
|
39
|
+
"""
|
|
40
|
+
return to_int_dtype(arr, np.uint16)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def to_int_dtype(arr: npt.ArrayLike, dtype: npt.DTypeLike) -> np.ndarray:
|
|
44
|
+
"""
|
|
45
|
+
Converts image data array to an integer array of the given dtype.
|
|
46
|
+
|
|
47
|
+
.. warning:: Data loss may occur as data points outside of the datatypes min/max are
|
|
48
|
+
clipped.
|
|
49
|
+
|
|
50
|
+
StackReg generally output float arrays. This utility function can be used to convert
|
|
51
|
+
such an output array to integer data by clipping to the bounds of the integer dtype
|
|
52
|
+
and rounding the floats (half to even, as :func:`numpy.round` does).
|
|
53
|
+
|
|
54
|
+
:type arr: array_like (Ni..., M, Nk...)
|
|
55
|
+
:param arr: Source array (usually float)
|
|
56
|
+
|
|
57
|
+
:type dtype: type
|
|
58
|
+
:param dtype: Integer datatype (e.g. np.uint16). For a non-integer dtype the
|
|
59
|
+
input is returned unchanged.
|
|
60
|
+
|
|
61
|
+
:rtype: ndarray(Ni..., Nj..., Nk...)
|
|
62
|
+
:return: Input array clipped & rounded to integer dtype
|
|
63
|
+
"""
|
|
64
|
+
arr = np.asarray(arr)
|
|
65
|
+
|
|
66
|
+
if not np.issubdtype(dtype, np.integer):
|
|
67
|
+
return arr
|
|
68
|
+
|
|
69
|
+
ii = np.iinfo(dtype)
|
|
70
|
+
|
|
71
|
+
return np.round(arr.clip(min=ii.min, max=ii.max)).astype(dtype)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def simple_slice(arr: np.ndarray, inds: Any, axis: int) -> np.ndarray:
|
|
75
|
+
"""
|
|
76
|
+
Take elements from an array along an axis.
|
|
77
|
+
|
|
78
|
+
This does the same as np.take() except only supports simple slicing, not
|
|
79
|
+
advanced indexing, and thus is much faster
|
|
80
|
+
|
|
81
|
+
:type arr: array_like (Ni..., M, Nk...)
|
|
82
|
+
:param arr: The source array to slice from
|
|
83
|
+
|
|
84
|
+
:type inds: int or array_like (Nj...)
|
|
85
|
+
:param inds:
|
|
86
|
+
The indices of the values to extract
|
|
87
|
+
|
|
88
|
+
:type axis: int
|
|
89
|
+
:param axis: The axis over which to select values
|
|
90
|
+
|
|
91
|
+
:rtype: ndarray(Ni..., Nj..., Nk...)
|
|
92
|
+
:return: The returned array has the same type as arr
|
|
93
|
+
"""
|
|
94
|
+
|
|
95
|
+
sl: list[Any] = [slice(None)] * arr.ndim
|
|
96
|
+
sl[axis] = inds
|
|
97
|
+
return arr[tuple(sl)]
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def running_mean(x: npt.ArrayLike, N: int, axis: int = 0) -> np.ndarray:
|
|
101
|
+
"""
|
|
102
|
+
Calculate running mean (=moving average) across a given axis.
|
|
103
|
+
|
|
104
|
+
The array is padded with the first and last value such that
|
|
105
|
+
the resulting running mean has the same dimensions as the input array.
|
|
106
|
+
|
|
107
|
+
.. note:: This function builds padded and cumulated copies of the whole
|
|
108
|
+
array. :meth:`pystackreg.StackReg.register_stack` computes the same
|
|
109
|
+
moving average frame by frame and does not use it.
|
|
110
|
+
|
|
111
|
+
:type x: array_like (Ni..., Nj..., Nk...)
|
|
112
|
+
:param x: The source array
|
|
113
|
+
|
|
114
|
+
:type N: int
|
|
115
|
+
:param N:
|
|
116
|
+
Number of elements to average over
|
|
117
|
+
|
|
118
|
+
:type axis: int, optional
|
|
119
|
+
:param axis: The axis across which the running mean is calculated
|
|
120
|
+
|
|
121
|
+
:rtype: ndarray(Ni..., Nj..., Nk...)
|
|
122
|
+
:return: The returned array has the same shape and type as x
|
|
123
|
+
"""
|
|
124
|
+
x = np.asarray(x)
|
|
125
|
+
pad_width = [[0, 0]] * len(x.shape)
|
|
126
|
+
pad_width[axis] = [int(np.ceil(N / 2)), int(np.floor(N / 2))]
|
|
127
|
+
cumsum = np.cumsum(np.pad(x, pad_width, "edge"), axis=axis)
|
|
128
|
+
upper = simple_slice(cumsum, slice(N, None), axis)
|
|
129
|
+
lower = simple_slice(cumsum, slice(None, -N), axis)
|
|
130
|
+
return (upper - lower) / float(N)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def max_displacement(
|
|
134
|
+
tmats: npt.ArrayLike, shape: tuple[int, int]
|
|
135
|
+
) -> np.ndarray | float:
|
|
136
|
+
"""
|
|
137
|
+
Largest distance (in pixels) by which a transformation moves any point of
|
|
138
|
+
an image.
|
|
139
|
+
|
|
140
|
+
This is a single, interpretable measure of the *amplitude* of a
|
|
141
|
+
transformation that works for all transformation types. It can be used
|
|
142
|
+
to detect implausible registration results, e.g. frames for which an
|
|
143
|
+
affine registration converged to a strongly scaled or sheared solution::
|
|
144
|
+
|
|
145
|
+
tmats = sr.register_stack(stack, reference="first")
|
|
146
|
+
suspicious = max_displacement(tmats, stack.shape[1:]) > 25
|
|
147
|
+
|
|
148
|
+
The displacement of an affine or bilinear map over a rectangle is largest
|
|
149
|
+
at one of the corners, so only the four image corners are evaluated.
|
|
150
|
+
|
|
151
|
+
:type tmats: ndarray(3, 3), ndarray(4, 4) or a stack of them (N, 3, 3) /
|
|
152
|
+
(N, 4, 4)
|
|
153
|
+
:param tmats: Transformation matrix or matrices as returned by
|
|
154
|
+
:meth:`pystackreg.StackReg.register` and
|
|
155
|
+
:meth:`pystackreg.StackReg.register_stack`
|
|
156
|
+
|
|
157
|
+
:type shape: (int, int)
|
|
158
|
+
:param shape: Image shape ``(rows, columns)``
|
|
159
|
+
|
|
160
|
+
:rtype: float or ndarray(N)
|
|
161
|
+
:return: Maximal displacement in pixels (one value per matrix)
|
|
162
|
+
"""
|
|
163
|
+
mats = np.asarray(tmats, dtype=np.float64)
|
|
164
|
+
single = mats.ndim == 2
|
|
165
|
+
if single:
|
|
166
|
+
mats = mats[np.newaxis]
|
|
167
|
+
if mats.ndim != 3 or mats.shape[1:] not in ((3, 3), (4, 4)):
|
|
168
|
+
raise ValueError(
|
|
169
|
+
"tmats must have shape (3, 3), (4, 4), (N, 3, 3) or (N, 4, 4), "
|
|
170
|
+
f"got {np.shape(tmats)}"
|
|
171
|
+
)
|
|
172
|
+
rows, cols = shape
|
|
173
|
+
x = np.array([0.0, cols - 1.0, 0.0, cols - 1.0])
|
|
174
|
+
y = np.array([0.0, 0.0, rows - 1.0, rows - 1.0])
|
|
175
|
+
if mats.shape[1] == 3:
|
|
176
|
+
vec = np.stack([x, y, np.ones(4)])
|
|
177
|
+
else:
|
|
178
|
+
vec = np.stack([x, y, x * y, np.ones(4)])
|
|
179
|
+
mapped = mats[:, :2, :] @ vec # (N, 2, 4)
|
|
180
|
+
dist = np.hypot(mapped[:, 0, :] - x, mapped[:, 1, :] - y).max(axis=1)
|
|
181
|
+
return float(dist[0]) if single else dist
|
pystackreg/version.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.3.0"
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
Version: 1.13.2
|
|
2
|
+
Arguments: ['C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-80umhsuw\\cp314-win_amd64\\build\\venv\\Scripts\\delvewheel', 'repair', '-w', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-80umhsuw\\cp314-win_amd64\\repaired_wheel', '-v', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-80umhsuw\\cp314-win_amd64\\built_wheel\\pystackreg-0.3.0-cp314-cp314-win_amd64.whl']
|
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pystackreg
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Image registration (Python/C++ port of the ImageJ/Fiji plugins TurboReg and StackReg)
|
|
5
|
+
Author: Gregor Lichtner
|
|
6
|
+
Maintainer: Gregor Lichtner
|
|
7
|
+
License-Expression: GPL-3.0-or-later
|
|
8
|
+
Project-URL: Homepage, https://github.com/glichtner/pystackreg
|
|
9
|
+
Project-URL: Documentation, https://pystackreg.readthedocs.io/
|
|
10
|
+
Project-URL: Repository, https://github.com/glichtner/pystackreg
|
|
11
|
+
Project-URL: Issues, https://github.com/glichtner/pystackreg/issues
|
|
12
|
+
Project-URL: Changelog, https://github.com/glichtner/pystackreg/blob/master/CHANGELOG.rst
|
|
13
|
+
Keywords: image registration,image alignment,motion correction,microscopy,TurboReg,StackReg,ImageJ
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Operating System :: MacOS
|
|
18
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
19
|
+
Classifier: Programming Language :: C++
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
28
|
+
Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
29
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
30
|
+
Classifier: Typing :: Typed
|
|
31
|
+
Requires-Python: >=3.10
|
|
32
|
+
Description-Content-Type: text/x-rst
|
|
33
|
+
License-File: LICENSE
|
|
34
|
+
License-File: NOTICE
|
|
35
|
+
Requires-Dist: numpy>=1.22
|
|
36
|
+
Requires-Dist: tqdm
|
|
37
|
+
Provides-Extra: test
|
|
38
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
39
|
+
Requires-Dist: tifffile; extra == "test"
|
|
40
|
+
Requires-Dist: scipy; extra == "test"
|
|
41
|
+
Provides-Extra: docs
|
|
42
|
+
Requires-Dist: sphinx>=7; extra == "docs"
|
|
43
|
+
Requires-Dist: sphinx-rtd-theme; extra == "docs"
|
|
44
|
+
Provides-Extra: dev
|
|
45
|
+
Requires-Dist: pystackreg[test]; extra == "dev"
|
|
46
|
+
Requires-Dist: ruff; extra == "dev"
|
|
47
|
+
Requires-Dist: mypy; extra == "dev"
|
|
48
|
+
Requires-Dist: codespell; extra == "dev"
|
|
49
|
+
Requires-Dist: build; extra == "dev"
|
|
50
|
+
Requires-Dist: twine; extra == "dev"
|
|
51
|
+
Requires-Dist: pre-commit; extra == "dev"
|
|
52
|
+
Dynamic: license-file
|
|
53
|
+
|
|
54
|
+
pyStackReg
|
|
55
|
+
==========
|
|
56
|
+
|
|
57
|
+
.. start-badges
|
|
58
|
+
|
|
59
|
+
.. image:: https://github.com/glichtner/pystackreg/actions/workflows/ci.yml/badge.svg
|
|
60
|
+
:target: https://github.com/glichtner/pystackreg/actions/workflows/ci.yml
|
|
61
|
+
:alt: Tests
|
|
62
|
+
|
|
63
|
+
.. image:: https://readthedocs.org/projects/pystackreg/badge/?version=latest
|
|
64
|
+
:target: https://pystackreg.readthedocs.io/en/latest/?badge=latest
|
|
65
|
+
:alt: Documentation Status
|
|
66
|
+
|
|
67
|
+
.. image:: https://badge.fury.io/py/pystackreg.svg
|
|
68
|
+
:alt: PyPI Package latest release
|
|
69
|
+
:target: https://pypi.org/project/pystackreg
|
|
70
|
+
|
|
71
|
+
.. image:: https://img.shields.io/conda/vn/conda-forge/pystackreg.svg
|
|
72
|
+
:alt: conda-forge package
|
|
73
|
+
:target: https://anaconda.org/conda-forge/pystackreg
|
|
74
|
+
|
|
75
|
+
.. image:: https://img.shields.io/pypi/pyversions/pystackreg.svg
|
|
76
|
+
:alt: Supported Python Versions
|
|
77
|
+
:target: https://pypi.org/project/pystackreg/
|
|
78
|
+
|
|
79
|
+
.. image:: https://pepy.tech/badge/pystackreg
|
|
80
|
+
:alt: Downloads
|
|
81
|
+
:target: https://pepy.tech/project/pystackreg/
|
|
82
|
+
|
|
83
|
+
.. end-badges
|
|
84
|
+
|
|
85
|
+
Summary
|
|
86
|
+
-------
|
|
87
|
+
Python/C++ port of the ImageJ extension TurboReg/StackReg written by Philippe Thevenaz/EPFL.
|
|
88
|
+
|
|
89
|
+
A python extension for the automatic alignment of a source image or a stack (movie) to a target image/reference frame.
|
|
90
|
+
|
|
91
|
+
Description
|
|
92
|
+
-----------
|
|
93
|
+
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 https://bigwww.epfl.ch/thevenaz/turboreg/).
|
|
94
|
+
|
|
95
|
+
The registration is intensity based: a multi-resolution (pyramid) Marquardt-Levenberg optimizer minimizes the mean squared difference between the reference image and the transformed image, using cubic B-spline interpolation. It works on plain NumPy arrays, needs neither ImageJ nor a Java runtime, and returns the transformation matrices so that they can be stored, inspected and applied to other data.
|
|
96
|
+
|
|
97
|
+
pyStackReg provides the following five types of distortion:
|
|
98
|
+
|
|
99
|
+
- translation
|
|
100
|
+
- rigid body (translation + rotation)
|
|
101
|
+
- scaled rotation (translation + rotation + scaling)
|
|
102
|
+
- affine (translation + rotation + scaling + shearing)
|
|
103
|
+
- bilinear (non-linear transformation; does not preserve straight lines)
|
|
104
|
+
|
|
105
|
+
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.
|
|
106
|
+
|
|
107
|
+
Beyond the ImageJ plugins, pyStackReg offers
|
|
108
|
+
|
|
109
|
+
- three reference strategies for stacks: the previous frame (what StackReg does), the first frame(s), or the mean of the stack, optionally after a moving average,
|
|
110
|
+
- multi-threaded registration and transformation of stacks (``n_jobs``),
|
|
111
|
+
- memory-efficient processing of large stacks (preallocated, memory-mapped or in-place output),
|
|
112
|
+
- transformation of point coordinates with the estimated transformations.
|
|
113
|
+
|
|
114
|
+
Results agree with the original plugins: for the scaled-rotation, affine and bilinear models the estimated landmarks and transformed images are bit-identical to those of TurboReg in the test suite, for the translation and rigid-body models they agree to better than 1e-6 pixel (see the `validation notes <https://pystackreg.readthedocs.io/en/latest/validation.html>`_).
|
|
115
|
+
|
|
116
|
+
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).
|
|
117
|
+
|
|
118
|
+
Scope and known limitations
|
|
119
|
+
...........................
|
|
120
|
+
- pyStackReg registers 2D images. A 3D array is treated as a *stack of 2D frames* (a time series or a series of sections), each of which gets its own 2D transformation. It does not perform volumetric (3D) registration.
|
|
121
|
+
- The optimizer is local. pystackreg (and StackReg/TurboReg) cannot recover large displacements, e.g. rotations by about 30 degrees or more or shifts of a large fraction of the image size (see https://github.com/glichtner/pystackreg/issues/30 for a workaround).
|
|
122
|
+
- Both images must show the same kind of contrast; the method is not suited for multi-modal registration.
|
|
123
|
+
- Transformed images are interpolated with cubic splines and can contain values slightly outside the range of the input, including negative values. This is the behavior of TurboReg; use ``pystackreg.util.to_uint16`` or an integer ``out`` array to clip and round.
|
|
124
|
+
- Images must not contain NaN or infinite values.
|
|
125
|
+
|
|
126
|
+
Installation
|
|
127
|
+
------------
|
|
128
|
+
The package is available on conda forge and on PyPi. Binary wheels are provided for Linux (x86-64, aarch64), macOS (x86-64, arm64) and Windows (x86-64) for Python 3.10 and newer; NumPy 1.22 or newer (including NumPy 2) is required.
|
|
129
|
+
|
|
130
|
+
- Install using **conda**
|
|
131
|
+
|
|
132
|
+
.. code-block:: console
|
|
133
|
+
|
|
134
|
+
conda install pystackreg -c conda-forge
|
|
135
|
+
|
|
136
|
+
- Install using **pip**
|
|
137
|
+
|
|
138
|
+
.. code-block:: console
|
|
139
|
+
|
|
140
|
+
pip install pystackreg
|
|
141
|
+
|
|
142
|
+
Installing from source requires a C++11 compiler (``pip install .`` in a checkout of the repository).
|
|
143
|
+
|
|
144
|
+
Documentation
|
|
145
|
+
-------------
|
|
146
|
+
The documentation can be found on readthedocs:
|
|
147
|
+
|
|
148
|
+
https://pystackreg.readthedocs.io/
|
|
149
|
+
|
|
150
|
+
Tutorial
|
|
151
|
+
--------
|
|
152
|
+
* A tutorial notebook can be found in the `examples/notebooks` folder
|
|
153
|
+
or statically here: https://pystackreg.readthedocs.io/en/latest/tutorial.html
|
|
154
|
+
|
|
155
|
+
Usage
|
|
156
|
+
-----
|
|
157
|
+
The following example opens two different files and registers them using all different possible transformations
|
|
158
|
+
|
|
159
|
+
.. code-block:: python
|
|
160
|
+
|
|
161
|
+
from pystackreg import StackReg
|
|
162
|
+
from skimage import io
|
|
163
|
+
|
|
164
|
+
#load reference and "moved" image
|
|
165
|
+
ref = io.imread('some_original_image.tif')
|
|
166
|
+
mov = io.imread('some_changed_image.tif')
|
|
167
|
+
|
|
168
|
+
#Translational transformation
|
|
169
|
+
sr = StackReg(StackReg.TRANSLATION)
|
|
170
|
+
out_tra = sr.register_transform(ref, mov)
|
|
171
|
+
|
|
172
|
+
#Rigid Body transformation
|
|
173
|
+
sr = StackReg(StackReg.RIGID_BODY)
|
|
174
|
+
out_rot = sr.register_transform(ref, mov)
|
|
175
|
+
|
|
176
|
+
#Scaled Rotation transformation
|
|
177
|
+
sr = StackReg(StackReg.SCALED_ROTATION)
|
|
178
|
+
out_sca = sr.register_transform(ref, mov)
|
|
179
|
+
|
|
180
|
+
#Affine transformation
|
|
181
|
+
sr = StackReg(StackReg.AFFINE)
|
|
182
|
+
out_aff = sr.register_transform(ref, mov)
|
|
183
|
+
|
|
184
|
+
#Bilinear transformation
|
|
185
|
+
sr = StackReg(StackReg.BILINEAR)
|
|
186
|
+
out_bil = sr.register_transform(ref, mov)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
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):
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
.. code-block:: python
|
|
193
|
+
|
|
194
|
+
from pystackreg import StackReg
|
|
195
|
+
from skimage import io
|
|
196
|
+
|
|
197
|
+
img0 = io.imread('some_multiframe_image.tif')
|
|
198
|
+
img1 = io.imread('another_multiframe_image.tif')
|
|
199
|
+
# img0.shape: frames x height x width (3D)
|
|
200
|
+
|
|
201
|
+
sr = StackReg(StackReg.RIGID_BODY)
|
|
202
|
+
|
|
203
|
+
# register 2nd image to 1st
|
|
204
|
+
sr.register(img0[0, :, :], img0[1,:,:])
|
|
205
|
+
|
|
206
|
+
# use the transformation from the above registration to register another frame
|
|
207
|
+
out = sr.transform(img1[1,:,:])
|
|
208
|
+
|
|
209
|
+
The next examples shows how to register and transform a whole stack:
|
|
210
|
+
|
|
211
|
+
.. code-block:: python
|
|
212
|
+
|
|
213
|
+
from pystackreg import StackReg
|
|
214
|
+
from skimage import io
|
|
215
|
+
|
|
216
|
+
img0 = io.imread('some_multiframe_image.tif') # 3 dimensions : frames x height x width
|
|
217
|
+
|
|
218
|
+
sr = StackReg(StackReg.RIGID_BODY)
|
|
219
|
+
|
|
220
|
+
# register each frame to the previous (already registered) one
|
|
221
|
+
# this is what the original StackReg ImageJ plugin uses
|
|
222
|
+
out_previous = sr.register_transform_stack(img0, reference='previous')
|
|
223
|
+
|
|
224
|
+
# register to first image
|
|
225
|
+
out_first = sr.register_transform_stack(img0, reference='first')
|
|
226
|
+
|
|
227
|
+
# register to mean image
|
|
228
|
+
out_mean = sr.register_transform_stack(img0, reference='mean')
|
|
229
|
+
|
|
230
|
+
# register to mean of first 10 images
|
|
231
|
+
out_first10 = sr.register_transform_stack(img0, reference='first', n_frames=10)
|
|
232
|
+
|
|
233
|
+
# calculate a moving average of 10 images, then register the moving average to the mean of
|
|
234
|
+
# the first 10 images and transform the original image (not the moving average)
|
|
235
|
+
out_moving10 = sr.register_transform_stack(img0, reference='first', n_frames=10, moving_average = 10)
|
|
236
|
+
|
|
237
|
+
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):
|
|
238
|
+
|
|
239
|
+
.. code-block:: python
|
|
240
|
+
|
|
241
|
+
from pystackreg import StackReg
|
|
242
|
+
from skimage import io
|
|
243
|
+
|
|
244
|
+
img0 = io.imread('some_multiframe_image.tif') # 3 dimensions : frames x height x width
|
|
245
|
+
img1 = io.imread('another_multiframe_image.tif') # same shape as img0
|
|
246
|
+
|
|
247
|
+
# both stacks must have the same shape
|
|
248
|
+
assert img0.shape == img1.shape
|
|
249
|
+
|
|
250
|
+
sr = StackReg(StackReg.RIGID_BODY)
|
|
251
|
+
|
|
252
|
+
# register each frame to the previous (already registered) one
|
|
253
|
+
# this is what the original StackReg ImageJ plugin uses
|
|
254
|
+
tmats = sr.register_stack(img0, reference='previous')
|
|
255
|
+
out = sr.transform_stack(img1)
|
|
256
|
+
|
|
257
|
+
# tmats contains the transformation matrices -> they can be saved
|
|
258
|
+
# and loaded at another time
|
|
259
|
+
import numpy as np
|
|
260
|
+
np.save('transformation_matrices.npy', tmats)
|
|
261
|
+
|
|
262
|
+
tmats_loaded = np.load('transformation_matrices.npy')
|
|
263
|
+
|
|
264
|
+
# make sure you use the correct transformation here!
|
|
265
|
+
sr = StackReg(StackReg.RIGID_BODY)
|
|
266
|
+
|
|
267
|
+
# transform stack using the tmats loaded from file
|
|
268
|
+
sr.transform_stack(img1, tmats=tmats_loaded)
|
|
269
|
+
|
|
270
|
+
# with the transformation matrices at hand you can also
|
|
271
|
+
# use the transformation algorithms from other packages:
|
|
272
|
+
from skimage import transform as tf
|
|
273
|
+
|
|
274
|
+
out = np.zeros(img0.shape, dtype=float)
|
|
275
|
+
|
|
276
|
+
for i in range(tmats.shape[0]):
|
|
277
|
+
out[i, :, :] = tf.warp(img1[i, :, :], tmats[i, :, :], order=3)
|
|
278
|
+
|
|
279
|
+
Large stacks can be processed with several threads and without allocating a second, larger copy of the data:
|
|
280
|
+
|
|
281
|
+
.. code-block:: python
|
|
282
|
+
|
|
283
|
+
import numpy as np
|
|
284
|
+
from pystackreg import StackReg
|
|
285
|
+
|
|
286
|
+
# memory-mapped 16-bit stack on disk: frames x height x width
|
|
287
|
+
img = np.load('large_stack.npy', mmap_mode='r+')
|
|
288
|
+
|
|
289
|
+
sr = StackReg(StackReg.RIGID_BODY)
|
|
290
|
+
|
|
291
|
+
# use all CPU cores; results are identical to the sequential run
|
|
292
|
+
tmats = sr.register_stack(img, reference='previous', n_jobs=-1, verbose=True)
|
|
293
|
+
|
|
294
|
+
# write the registered frames back into the same array (rounded and
|
|
295
|
+
# clipped to 16 bit) instead of creating a float64 stack of four times the size
|
|
296
|
+
sr.transform_stack(img, n_jobs=-1, out=img)
|
|
297
|
+
|
|
298
|
+
The transformation matrices map coordinates ``(x, y)`` of the reference image onto coordinates of the unregistered image. To move point coordinates in the same way as the image content is moved, use ``transform_points``:
|
|
299
|
+
|
|
300
|
+
.. code-block:: python
|
|
301
|
+
|
|
302
|
+
sr = StackReg(StackReg.AFFINE)
|
|
303
|
+
tmat = sr.register(ref, mov)
|
|
304
|
+
|
|
305
|
+
# positions (x, y) = (column, row) of features detected in the unregistered image
|
|
306
|
+
points = np.array([[120.5, 80.0], [33.2, 14.9]])
|
|
307
|
+
|
|
308
|
+
# ... and where they are in the registered image
|
|
309
|
+
registered_points = sr.transform_points(points)
|
|
310
|
+
|
|
311
|
+
Contributing and support
|
|
312
|
+
------------------------
|
|
313
|
+
Questions, bug reports and feature requests are welcome in the
|
|
314
|
+
`issue tracker <https://github.com/glichtner/pystackreg/issues>`_. For a bug
|
|
315
|
+
report, please include the versions of pyStackReg, NumPy and Python and a
|
|
316
|
+
minimal example that reproduces the problem.
|
|
317
|
+
|
|
318
|
+
Pull requests are welcome as well. A development installation compiles the
|
|
319
|
+
C++ extension and needs a C++11 compiler::
|
|
320
|
+
|
|
321
|
+
git clone https://github.com/glichtner/pystackreg
|
|
322
|
+
cd pystackreg
|
|
323
|
+
pip install -e ".[dev]"
|
|
324
|
+
pytest
|
|
325
|
+
|
|
326
|
+
Changes to the native code must reproduce the results of earlier releases
|
|
327
|
+
(see `Validation <https://pystackreg.readthedocs.io/en/latest/validation.html>`_).
|
|
328
|
+
Contributions are accepted under the license of the project
|
|
329
|
+
(GPL-3.0-or-later).
|
|
330
|
+
|
|
331
|
+
Attribution and citation
|
|
332
|
+
------------------------
|
|
333
|
+
pyStackReg is a port of existing software, not a new registration algorithm:
|
|
334
|
+
|
|
335
|
+
- **Method:** P. Thévenaz, U.E. Ruttimann, M. Unser: *A Pyramid Approach to
|
|
336
|
+
Subpixel Registration Based on Intensity*, IEEE Transactions on Image
|
|
337
|
+
Processing, vol. 7, no. 1, pp. 27-41, January 1998,
|
|
338
|
+
`doi:10.1109/83.650848 <https://doi.org/10.1109/83.650848>`_.
|
|
339
|
+
- **Original software:** the ImageJ plugins
|
|
340
|
+
`TurboReg <https://bigwww.epfl.ch/thevenaz/turboreg/>`_ and
|
|
341
|
+
`StackReg <https://bigwww.epfl.ch/thevenaz/stackreg/>`_ by Philippe Thévenaz,
|
|
342
|
+
Biomedical Imaging Group, École polytechnique fédérale de Lausanne (EPFL).
|
|
343
|
+
- **pyStackReg** (translation of TurboReg from Java to C++, Python/NumPy
|
|
344
|
+
interface, stack registration with several reference modes, parallel
|
|
345
|
+
processing): Gregor Lichtner and contributors (see ``AUTHORS.rst``).
|
|
346
|
+
|
|
347
|
+
If you present or publish results obtained with pyStackReg, please cite the
|
|
348
|
+
paper by Thévenaz et al. (1998) - the authors of TurboReg ask for this - and
|
|
349
|
+
pyStackReg itself (see ``CITATION.cff``).
|
|
350
|
+
|
|
351
|
+
License
|
|
352
|
+
-------
|
|
353
|
+
pyStackReg is free software, distributed under the terms of the
|
|
354
|
+
`GNU General Public License <https://www.gnu.org/licenses/gpl-3.0.html>`_,
|
|
355
|
+
version 3 or (at your option) any later version; see ``LICENSE``. This is the
|
|
356
|
+
license under which TurboReg and StackReg are distributed by their author.
|
|
357
|
+
|
|
358
|
+
Copyright notices, the conditions of use of the original software and the
|
|
359
|
+
license notices of earlier pyStackReg versions (up to 0.2.8, which were
|
|
360
|
+
published under different terms) are in ``NOTICE``.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
pystackreg/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
2
|
+
pystackreg/pystackreg.py,sha256=GxzwQOGDZBdXsbJPUiioJiWM1y9k6RpKvtkkERDWpk8,31480
|
|
3
|
+
pystackreg/turboreg.cp314-win_amd64.pyd,sha256=pc8SDcY_3Zq6TUrEbQTNrTdeooFSVnNg35N1BY0zUsI,138240
|
|
4
|
+
pystackreg/version.py,sha256=uY3cMAMpdqMKE578vu86FHlJK6FgmnTzyGQFF28Mpx0,23
|
|
5
|
+
pystackreg/_internal.py,sha256=fZbsMmsuWOmHll0wpRqfgD3p4bFDsJ5gll76b3oHypk,10507
|
|
6
|
+
pystackreg/__init__.py,sha256=Qf3WFz9MSe0ct2Nm8J5XFqOiVTzUDI8r5s4Gj9tF2J4,976
|
|
7
|
+
pystackreg/util/__init__.py,sha256=3L9RCVt1TalYp64gSHcTojfn0zhn0jaXpzyIT6S0mUE,6272
|
|
8
|
+
pystackreg-0.3.0.dist-info/DELVEWHEEL,sha256=bOubvFrAUH6q4vgGMc6yCojSZ0KgOKZ5z1fmsKVzhZ0,409
|
|
9
|
+
pystackreg-0.3.0.dist-info/METADATA,sha256=sNDkAhJnOtqdgUhlbICdWpTpPuhGcb3PcH12dlUPGII,16385
|
|
10
|
+
pystackreg-0.3.0.dist-info/RECORD,,
|
|
11
|
+
pystackreg-0.3.0.dist-info/top_level.txt,sha256=qoYoHJMwck_foa97p1OZ--g0IdqGo7AFRQOsJmblwLY,11
|
|
12
|
+
pystackreg-0.3.0.dist-info/WHEEL,sha256=GjNoWUKTwVqYOh-GAeOqmWs8K5Mlz_Ym2F39m91XU8Q,101
|
|
13
|
+
pystackreg-0.3.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
|
|
14
|
+
pystackreg-0.3.0.dist-info/licenses/NOTICE,sha256=cZ9Us44VtoiDfkjpdToS41m3YYZFYgZRzdtUILmCUCo,4904
|
|
15
|
+
pystackreg.libs/msvcp140-a4c2229bdc2a2a630acdc095b4d86008.dll,sha256=pMIim9wqKmMKzcCVtNhgCOXD47x3cxdDVPPaT1vrnN4,575056
|