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
pystackreg/pystackreg.py
ADDED
|
@@ -0,0 +1,814 @@
|
|
|
1
|
+
# SPDX-License-Identifier: GPL-3.0-or-later
|
|
2
|
+
# Copyright (C) 2018-2026 Gregor Lichtner and PyStackReg contributors
|
|
3
|
+
"""Image and image-stack registration: the :class:`StackReg` class."""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import operator
|
|
8
|
+
import warnings
|
|
9
|
+
from collections.abc import Callable
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
import numpy as np
|
|
13
|
+
import numpy.typing as npt
|
|
14
|
+
|
|
15
|
+
from pystackreg import turboreg # type: ignore[attr-defined]
|
|
16
|
+
from pystackreg._internal import (
|
|
17
|
+
FrameSource,
|
|
18
|
+
Progress,
|
|
19
|
+
check_output_array,
|
|
20
|
+
detect_time_axis,
|
|
21
|
+
resolve_n_jobs,
|
|
22
|
+
run_tasks,
|
|
23
|
+
store_frame,
|
|
24
|
+
)
|
|
25
|
+
from pystackreg.util import simple_slice
|
|
26
|
+
|
|
27
|
+
__all__ = ["StackReg"]
|
|
28
|
+
|
|
29
|
+
#: Smallest image side (in pixels) that can be registered.
|
|
30
|
+
_MIN_REGISTRATION_SIZE = 3
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class StackReg:
|
|
34
|
+
"""
|
|
35
|
+
Python implementation of the ImageJ/Fiji StackReg plugin
|
|
36
|
+
(https://bigwww.epfl.ch/thevenaz/stackreg/ )
|
|
37
|
+
|
|
38
|
+
One instance holds one transformation type and the result of the most
|
|
39
|
+
recent registration. Instances are cheap to create; they are not meant to
|
|
40
|
+
be shared between threads that register concurrently (use one instance per
|
|
41
|
+
thread, or the ``n_jobs`` argument of the stack functions).
|
|
42
|
+
|
|
43
|
+
:type transformation: int
|
|
44
|
+
:param transformation: One of :attr:`TRANSLATION`, :attr:`RIGID_BODY`,
|
|
45
|
+
:attr:`SCALED_ROTATION`, :attr:`AFFINE`,
|
|
46
|
+
:attr:`BILINEAR`
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
TRANSLATION = 2
|
|
50
|
+
"""
|
|
51
|
+
Translation
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
RIGID_BODY = 3
|
|
55
|
+
"""
|
|
56
|
+
Rigid body (translation + rotation)
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
SCALED_ROTATION = 4
|
|
60
|
+
"""
|
|
61
|
+
Scaled rotation (translation + rotation + scaling)
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
AFFINE = 6
|
|
65
|
+
"""
|
|
66
|
+
Affine (translation + rotation + scaling + shearing)
|
|
67
|
+
"""
|
|
68
|
+
|
|
69
|
+
BILINEAR = 8
|
|
70
|
+
"""
|
|
71
|
+
Bilinear (non-linear transformation; does not preserve straight lines)
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
_valid_transformations = (
|
|
75
|
+
TRANSLATION,
|
|
76
|
+
RIGID_BODY,
|
|
77
|
+
SCALED_ROTATION,
|
|
78
|
+
AFFINE,
|
|
79
|
+
BILINEAR,
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
_valid_references = ("previous", "first", "mean")
|
|
83
|
+
|
|
84
|
+
_is_registered = False
|
|
85
|
+
|
|
86
|
+
def __init__(self, transformation: int) -> None:
|
|
87
|
+
if transformation not in self._valid_transformations:
|
|
88
|
+
raise ValueError(
|
|
89
|
+
f"Invalid transformation {transformation!r}; use one of "
|
|
90
|
+
"StackReg.TRANSLATION, RIGID_BODY, SCALED_ROTATION, AFFINE, "
|
|
91
|
+
"BILINEAR"
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
self._transformation = transformation
|
|
95
|
+
self._m: np.ndarray | None = None
|
|
96
|
+
self._tmats: np.ndarray | None = None
|
|
97
|
+
self._refpts: np.ndarray | None = None
|
|
98
|
+
self._movpts: np.ndarray | None = None
|
|
99
|
+
|
|
100
|
+
def is_registered(self) -> bool:
|
|
101
|
+
"""
|
|
102
|
+
Indicates whether register() was already called and a transformation matrix
|
|
103
|
+
was calculated
|
|
104
|
+
|
|
105
|
+
:rtype: bool
|
|
106
|
+
:return: True if a transformation matrix was already calculated
|
|
107
|
+
"""
|
|
108
|
+
return self._is_registered
|
|
109
|
+
|
|
110
|
+
def register(self, ref: npt.ArrayLike, mov: npt.ArrayLike) -> np.ndarray:
|
|
111
|
+
"""
|
|
112
|
+
Registers an image to a reference image: Only the transformation matrix
|
|
113
|
+
will be calculated, the image will not be transformed
|
|
114
|
+
(use transform() or register_transform() ).
|
|
115
|
+
|
|
116
|
+
As in StackReg, the last row and the last column of both images are
|
|
117
|
+
not used for the registration.
|
|
118
|
+
|
|
119
|
+
:type ref: array_like (M, N)
|
|
120
|
+
:param ref: Reference image (static)
|
|
121
|
+
|
|
122
|
+
:type mov: array_like (M, N)
|
|
123
|
+
:param mov:
|
|
124
|
+
The image that should be aligned to the reference image. Must have
|
|
125
|
+
the same shape as ``ref``.
|
|
126
|
+
|
|
127
|
+
:rtype: ndarray(3,3) or ndarray(4,4) for bilinear transformation
|
|
128
|
+
:return: Transformation matrix. It maps coordinates ``(x, y)``
|
|
129
|
+
(column, row) of the reference image onto coordinates of
|
|
130
|
+
``mov``; see :meth:`transform_points`.
|
|
131
|
+
|
|
132
|
+
:raises ValueError: if the images are not 2-D, differ in shape, are
|
|
133
|
+
smaller than 3 x 3 pixels or contain NaN or infinite values
|
|
134
|
+
"""
|
|
135
|
+
self._m, self._refpts, self._movpts = self._register_pair(
|
|
136
|
+
np.asarray(ref), np.asarray(mov)
|
|
137
|
+
)
|
|
138
|
+
self._is_registered = True
|
|
139
|
+
|
|
140
|
+
return self.get_matrix()
|
|
141
|
+
|
|
142
|
+
def _register_pair(
|
|
143
|
+
self, ref: np.ndarray, mov: np.ndarray
|
|
144
|
+
) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
|
|
145
|
+
"""
|
|
146
|
+
Validate and register one pair of images without touching the state of
|
|
147
|
+
this object (which makes it safe to call from several threads).
|
|
148
|
+
|
|
149
|
+
:return: (compact TurboReg matrix, reference points, moving points)
|
|
150
|
+
"""
|
|
151
|
+
for name, image in (("ref", ref), ("mov", mov)):
|
|
152
|
+
if image.ndim != 2:
|
|
153
|
+
raise ValueError(
|
|
154
|
+
f"{name} must be a two-dimensional image, got an array "
|
|
155
|
+
f"with {image.ndim} dimension(s)"
|
|
156
|
+
)
|
|
157
|
+
if ref.shape != mov.shape:
|
|
158
|
+
raise ValueError(
|
|
159
|
+
f"ref and mov must have the same shape, got {ref.shape} and {mov.shape}"
|
|
160
|
+
)
|
|
161
|
+
if min(ref.shape) < _MIN_REGISTRATION_SIZE:
|
|
162
|
+
raise ValueError(
|
|
163
|
+
f"Images must be at least {_MIN_REGISTRATION_SIZE} x "
|
|
164
|
+
f"{_MIN_REGISTRATION_SIZE} pixels for registration, got "
|
|
165
|
+
f"{ref.shape[0]} x {ref.shape[1]}"
|
|
166
|
+
)
|
|
167
|
+
for name, image in (("ref", ref), ("mov", mov)):
|
|
168
|
+
if image.dtype.kind == "f" and not np.isfinite(image).all():
|
|
169
|
+
raise ValueError(
|
|
170
|
+
f"{name} contains NaN or infinite values; such images "
|
|
171
|
+
"cannot be registered"
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
# StackReg hands TurboReg the images without their last row and column
|
|
175
|
+
return turboreg._register(ref[:-1, :-1], mov[:-1, :-1], self._transformation)
|
|
176
|
+
|
|
177
|
+
def transform(
|
|
178
|
+
self, mov: npt.ArrayLike, tmat: npt.ArrayLike | None = None
|
|
179
|
+
) -> np.ndarray:
|
|
180
|
+
"""
|
|
181
|
+
Transform an image according to a previous registration.
|
|
182
|
+
|
|
183
|
+
Either a transformation matrix has to be explicitly supplied or
|
|
184
|
+
register() has to be called before calling transform().
|
|
185
|
+
|
|
186
|
+
The image is resampled with cubic B-spline interpolation. Positions
|
|
187
|
+
that map outside of ``mov`` are set to 0. Because of the cubic
|
|
188
|
+
interpolation, values can slightly over- or undershoot the range of
|
|
189
|
+
the input (e.g. become negative next to sharp edges); see
|
|
190
|
+
:func:`pystackreg.util.to_uint16` for a conversion that clips.
|
|
191
|
+
|
|
192
|
+
:type mov: array_like (M, N)
|
|
193
|
+
:param mov: The image that will be transformed
|
|
194
|
+
|
|
195
|
+
:type tmat: ndarray(3,3) or ndarray(4,4) for bilinear transformation,
|
|
196
|
+
optional
|
|
197
|
+
:param tmat: The transformation matrix
|
|
198
|
+
|
|
199
|
+
:rtype: ndarray (M, N), float64
|
|
200
|
+
:return: Transformed image - will be of the same shape as the input image
|
|
201
|
+
(cropping may occur)
|
|
202
|
+
"""
|
|
203
|
+
if tmat is None:
|
|
204
|
+
if self._m is None:
|
|
205
|
+
raise RuntimeError(
|
|
206
|
+
"No transformation available: call register() first or "
|
|
207
|
+
"pass a transformation matrix"
|
|
208
|
+
)
|
|
209
|
+
m = self._m
|
|
210
|
+
else:
|
|
211
|
+
m = self._matrix_long_to_short(np.asarray(tmat))
|
|
212
|
+
|
|
213
|
+
return turboreg._transform(mov, m)
|
|
214
|
+
|
|
215
|
+
def register_transform(self, ref: npt.ArrayLike, mov: npt.ArrayLike) -> np.ndarray:
|
|
216
|
+
"""
|
|
217
|
+
Register and transform an image to a reference image.
|
|
218
|
+
|
|
219
|
+
:type ref: array_like (M, N)
|
|
220
|
+
:param ref: Reference image (static)
|
|
221
|
+
|
|
222
|
+
:type mov: array_like (M, N)
|
|
223
|
+
:param mov: The image that should be aligned to the reference image
|
|
224
|
+
|
|
225
|
+
:rtype: ndarray (M, N), float64
|
|
226
|
+
:return: Transformed image - will be of the same shape as the input image
|
|
227
|
+
(cropping may occur)
|
|
228
|
+
"""
|
|
229
|
+
self.register(ref, mov)
|
|
230
|
+
return self.transform(mov)
|
|
231
|
+
|
|
232
|
+
def get_matrix(self) -> np.ndarray:
|
|
233
|
+
"""
|
|
234
|
+
Get the current transformation matrix
|
|
235
|
+
|
|
236
|
+
:rtype: ndarray(3,3) or ndarray(4,4) for bilinear transformation
|
|
237
|
+
:return: The transformation matrix
|
|
238
|
+
"""
|
|
239
|
+
if self._m is None:
|
|
240
|
+
raise RuntimeError(
|
|
241
|
+
"No transformation available: call register() or set_matrix() first"
|
|
242
|
+
)
|
|
243
|
+
return self._matrix_short_to_long(self._m)
|
|
244
|
+
|
|
245
|
+
def set_matrix(self, mat: npt.ArrayLike) -> None:
|
|
246
|
+
"""
|
|
247
|
+
Sets the current transformation matrix
|
|
248
|
+
|
|
249
|
+
:type mat: ndarray(3,3) or ndarray(4,4) for bilinear transformation
|
|
250
|
+
:param mat: The transformation matrix
|
|
251
|
+
"""
|
|
252
|
+
mat = np.asarray(mat)
|
|
253
|
+
exp_shape = (4, 4) if self._transformation == self.BILINEAR else (3, 3)
|
|
254
|
+
|
|
255
|
+
if exp_shape != mat.shape:
|
|
256
|
+
raise ValueError(
|
|
257
|
+
f"Invalid shape of transformation matrix: Expected {exp_shape}, "
|
|
258
|
+
f"got {mat.shape}"
|
|
259
|
+
)
|
|
260
|
+
|
|
261
|
+
self._m = self._matrix_long_to_short(mat)
|
|
262
|
+
|
|
263
|
+
self._is_registered = True
|
|
264
|
+
|
|
265
|
+
def _matrix_short_to_long(self, m: np.ndarray) -> np.ndarray:
|
|
266
|
+
"""
|
|
267
|
+
Converts the transformation matrix from the short form used by TurboReg to
|
|
268
|
+
the canonical form from linear algebra.
|
|
269
|
+
|
|
270
|
+
:type m: array_like
|
|
271
|
+
:param m: TurboReg transformation matrix
|
|
272
|
+
|
|
273
|
+
:rtype: ndarray(3,3)
|
|
274
|
+
:return: Canonical transformation matrix
|
|
275
|
+
"""
|
|
276
|
+
|
|
277
|
+
if self._transformation == self.TRANSLATION:
|
|
278
|
+
mat = np.identity(3).astype(np.double)
|
|
279
|
+
mat[0:2, 2] = m[:, 0]
|
|
280
|
+
elif self._transformation in [
|
|
281
|
+
self.RIGID_BODY,
|
|
282
|
+
self.SCALED_ROTATION,
|
|
283
|
+
self.AFFINE,
|
|
284
|
+
]:
|
|
285
|
+
mat = np.identity(3).astype(np.double)
|
|
286
|
+
mat[0:2, :] = m[:, [1, 2, 0]]
|
|
287
|
+
else: # BILINEAR
|
|
288
|
+
mat = np.identity(4).astype(np.double)
|
|
289
|
+
mat[0:2, :] = m[:, [1, 2, 3, 0]]
|
|
290
|
+
|
|
291
|
+
return mat
|
|
292
|
+
|
|
293
|
+
def _matrix_long_to_short(self, mat: np.ndarray) -> np.ndarray:
|
|
294
|
+
"""
|
|
295
|
+
Converts the transformation matrix from the canonical form from linear algebra
|
|
296
|
+
to the short form used by TurboReg.
|
|
297
|
+
|
|
298
|
+
:type mat: ndarray(3,3)
|
|
299
|
+
:param mat: Canonical transformation matrix
|
|
300
|
+
|
|
301
|
+
:rtype: array_like
|
|
302
|
+
:return: TurboReg transformation matrix
|
|
303
|
+
"""
|
|
304
|
+
n_cols = 4 if self._transformation == self.BILINEAR else 3
|
|
305
|
+
if mat.ndim != 2 or mat.shape[0] < 2 or mat.shape[1] != n_cols:
|
|
306
|
+
raise ValueError(
|
|
307
|
+
f"Invalid shape of transformation matrix: Expected "
|
|
308
|
+
f"({n_cols}, {n_cols}), got {mat.shape}"
|
|
309
|
+
)
|
|
310
|
+
|
|
311
|
+
if self._transformation == self.TRANSLATION:
|
|
312
|
+
m = mat[0:2, 2].reshape((2, 1))
|
|
313
|
+
elif self._transformation in [
|
|
314
|
+
self.RIGID_BODY,
|
|
315
|
+
self.SCALED_ROTATION,
|
|
316
|
+
self.AFFINE,
|
|
317
|
+
]:
|
|
318
|
+
m = mat[0:2, [2, 0, 1]]
|
|
319
|
+
else: # BILINEAR
|
|
320
|
+
m = mat[0:2, [3, 0, 1, 2]]
|
|
321
|
+
|
|
322
|
+
return m.astype(np.double)
|
|
323
|
+
|
|
324
|
+
@staticmethod
|
|
325
|
+
def _detect_time_axis(img: np.ndarray) -> int:
|
|
326
|
+
"""
|
|
327
|
+
Detects the time axis of a movie/stack by returning the dimension with the
|
|
328
|
+
lowest average variability
|
|
329
|
+
|
|
330
|
+
:param img: 3-D stack
|
|
331
|
+
:return: index of the axis with the lowest average variance
|
|
332
|
+
"""
|
|
333
|
+
return detect_time_axis(img)
|
|
334
|
+
|
|
335
|
+
def get_points(self) -> tuple[np.ndarray | None, np.ndarray | None]:
|
|
336
|
+
"""
|
|
337
|
+
Returns the pairs of corresponding points from which the
|
|
338
|
+
transformation matrix can be calculated.
|
|
339
|
+
|
|
340
|
+
:rtype: (ndarray, ndarray)
|
|
341
|
+
:return: (Point coordinates of reference image, Point coordinates of image to
|
|
342
|
+
be aligned)
|
|
343
|
+
"""
|
|
344
|
+
return self._refpts, self._movpts
|
|
345
|
+
|
|
346
|
+
def transform_points(
|
|
347
|
+
self,
|
|
348
|
+
points: npt.ArrayLike,
|
|
349
|
+
tmat: npt.ArrayLike | None = None,
|
|
350
|
+
*,
|
|
351
|
+
inverse: bool = False,
|
|
352
|
+
) -> np.ndarray:
|
|
353
|
+
"""
|
|
354
|
+
Apply a transformation to point coordinates instead of to an image.
|
|
355
|
+
|
|
356
|
+
By default the points are moved in the same way as :meth:`transform`
|
|
357
|
+
moves image content: a feature located at ``points`` in the
|
|
358
|
+
unregistered image ``mov`` is found at the returned coordinates in the
|
|
359
|
+
registered image (i.e. in the frame of the reference image).
|
|
360
|
+
|
|
361
|
+
Coordinates are given as ``(x, y)`` = ``(column, row)``, with the
|
|
362
|
+
origin in the centre of the top-left pixel. Use ``points[..., ::-1]``
|
|
363
|
+
to convert from/to NumPy's ``(row, column)`` index order.
|
|
364
|
+
|
|
365
|
+
.. note:: The transformation matrix itself maps *reference*
|
|
366
|
+
coordinates onto *moving-image* coordinates (this is the direction
|
|
367
|
+
needed to resample an image). Multiplying a point by the matrix
|
|
368
|
+
therefore corresponds to ``inverse=True``.
|
|
369
|
+
|
|
370
|
+
:type points: array_like (..., 2)
|
|
371
|
+
:param points: Point coordinates ``(x, y)``
|
|
372
|
+
|
|
373
|
+
:type tmat: ndarray(3,3) or ndarray(4,4) for bilinear transformation,
|
|
374
|
+
optional
|
|
375
|
+
:param tmat: The transformation matrix; defaults to the matrix of the
|
|
376
|
+
last registration
|
|
377
|
+
|
|
378
|
+
:type inverse: bool, optional
|
|
379
|
+
:param inverse:
|
|
380
|
+
If False (default), map coordinates of the moving image to the
|
|
381
|
+
registered/reference frame. If True, map coordinates of the
|
|
382
|
+
reference frame to the moving image.
|
|
383
|
+
|
|
384
|
+
:rtype: ndarray (..., 2), float64
|
|
385
|
+
:return: Transformed point coordinates ``(x, y)``
|
|
386
|
+
"""
|
|
387
|
+
pts = np.asarray(points, dtype=np.float64)
|
|
388
|
+
if pts.ndim == 0 or pts.shape[-1] != 2:
|
|
389
|
+
raise ValueError(
|
|
390
|
+
"points must have shape (..., 2) holding (x, y) coordinates, "
|
|
391
|
+
f"got {pts.shape}"
|
|
392
|
+
)
|
|
393
|
+
if tmat is None:
|
|
394
|
+
mat = self.get_matrix()
|
|
395
|
+
else:
|
|
396
|
+
# round trip through the compact form: use exactly the part of
|
|
397
|
+
# the matrix that transform() uses
|
|
398
|
+
mat = self._matrix_short_to_long(
|
|
399
|
+
self._matrix_long_to_short(np.asarray(tmat))
|
|
400
|
+
)
|
|
401
|
+
|
|
402
|
+
x, y = pts[..., 0], pts[..., 1]
|
|
403
|
+
if self._transformation == self.BILINEAR:
|
|
404
|
+
u, v = _bilinear_map(mat, x, y) if inverse else _bilinear_solve(mat, x, y)
|
|
405
|
+
else:
|
|
406
|
+
if not inverse:
|
|
407
|
+
mat = np.linalg.inv(mat)
|
|
408
|
+
u = mat[0, 0] * x + mat[0, 1] * y + mat[0, 2]
|
|
409
|
+
v = mat[1, 0] * x + mat[1, 1] * y + mat[1, 2]
|
|
410
|
+
return np.stack([u, v], axis=-1)
|
|
411
|
+
|
|
412
|
+
def register_stack(
|
|
413
|
+
self,
|
|
414
|
+
img: npt.ArrayLike,
|
|
415
|
+
reference: str = "previous",
|
|
416
|
+
n_frames: int = 1,
|
|
417
|
+
axis: int = 0,
|
|
418
|
+
moving_average: int = 1,
|
|
419
|
+
verbose: bool = False,
|
|
420
|
+
progress_callback: Callable[..., Any] | None = None,
|
|
421
|
+
suppress_axis_warning: bool = False,
|
|
422
|
+
*,
|
|
423
|
+
n_jobs: int | None = 1,
|
|
424
|
+
) -> np.ndarray:
|
|
425
|
+
"""
|
|
426
|
+
Register a stack of images (movie).
|
|
427
|
+
Note that this function will not transform the image but only calculate the
|
|
428
|
+
transformation matrices.
|
|
429
|
+
For transformation use transform_stack() after this function or use
|
|
430
|
+
register_transform_stack() for a single call.
|
|
431
|
+
|
|
432
|
+
:type img: array_like(Ni..., Nj..., Nk...)
|
|
433
|
+
:param img: The 3D stack of images that should be aligned
|
|
434
|
+
|
|
435
|
+
:type reference: string, one of ['previous', 'first', 'mean']
|
|
436
|
+
:param reference:
|
|
437
|
+
* *'previous'*: Aligns each frame (image) to its previous frame in the
|
|
438
|
+
stack
|
|
439
|
+
* *'first:'* Aligns each frame (image) to the first frame in the stack -
|
|
440
|
+
if n_frames is > 1, then each frame is aligned to the
|
|
441
|
+
mean of the first n_frames of the stack
|
|
442
|
+
* *'mean'*: Aligns each frame (image) to the average of all images in the
|
|
443
|
+
stack
|
|
444
|
+
|
|
445
|
+
:type n_frames: int, optional
|
|
446
|
+
:param n_frames: If reference is 'first', then this parameter specifies the
|
|
447
|
+
number of frames from the beginning of the stack that should
|
|
448
|
+
be averaged to yield the reference image.
|
|
449
|
+
|
|
450
|
+
:type axis: int, optional
|
|
451
|
+
:param axis: The axis of the time dimension
|
|
452
|
+
|
|
453
|
+
:type moving_average: int, optional
|
|
454
|
+
:param moving_average:
|
|
455
|
+
If moving_average is greater than 1, a moving average of the stack is first
|
|
456
|
+
created (using a subset size of moving_average) before registration
|
|
457
|
+
|
|
458
|
+
:type verbose: bool, optional
|
|
459
|
+
:param verbose:
|
|
460
|
+
Specifies whether a progressbar should be shown using tqdm.
|
|
461
|
+
|
|
462
|
+
:type progress_callback: function, optional
|
|
463
|
+
:param progress_callback:
|
|
464
|
+
A function that is called after every iteration. This function should accept
|
|
465
|
+
the keyword arguments current_iteration:int and end_iteration:int.
|
|
466
|
+
It is always called from the thread that called this function,
|
|
467
|
+
also when ``n_jobs`` > 1.
|
|
468
|
+
|
|
469
|
+
:type suppress_axis_warning: bool, optional
|
|
470
|
+
:param suppress_axis_warning:
|
|
471
|
+
pystackreg will automatically try to determine the time axis and raise a
|
|
472
|
+
warning when the detected time axis is not equal to the supplied axis.
|
|
473
|
+
Set this option to True to suppress this warning.
|
|
474
|
+
|
|
475
|
+
:type n_jobs: int, optional
|
|
476
|
+
:param n_jobs:
|
|
477
|
+
Number of threads used to register frames in parallel. 1 (default)
|
|
478
|
+
registers sequentially in the calling thread; -1 uses all
|
|
479
|
+
available CPUs. The result does not depend on ``n_jobs``.
|
|
480
|
+
|
|
481
|
+
:rtype: ndarray(img.shape[axis], 3, 3)
|
|
482
|
+
:return: The transformation matrix for each image in the stack
|
|
483
|
+
"""
|
|
484
|
+
stack, axis = self._check_stack(img, axis)
|
|
485
|
+
n_workers = resolve_n_jobs(n_jobs)
|
|
486
|
+
|
|
487
|
+
if reference not in self._valid_references:
|
|
488
|
+
raise ValueError(f'Unknown reference "{reference}"')
|
|
489
|
+
|
|
490
|
+
if self._transformation == self.BILINEAR and reference == "previous":
|
|
491
|
+
raise ValueError(
|
|
492
|
+
"Bilinear stack transformation not supported with reference "
|
|
493
|
+
'== "previous" as a combination of bilinear transformations does not '
|
|
494
|
+
"generally result in a bilinear transformation. Use another reference "
|
|
495
|
+
"or manually register/transform images to their previous image."
|
|
496
|
+
)
|
|
497
|
+
|
|
498
|
+
n = stack.shape[axis]
|
|
499
|
+
n_frames = _check_count(n_frames, "n_frames")
|
|
500
|
+
# 0 is accepted and means "no moving average", like 1 (as in 0.2.x)
|
|
501
|
+
moving_average = max(1, _check_count(moving_average, "moving_average", 0))
|
|
502
|
+
if reference == "first" and n_frames > n:
|
|
503
|
+
raise ValueError(
|
|
504
|
+
f"n_frames ({n_frames}) exceeds the number of frames in the stack ({n})"
|
|
505
|
+
)
|
|
506
|
+
|
|
507
|
+
if not suppress_axis_warning:
|
|
508
|
+
lowest_var_axis = self._detect_time_axis(stack)
|
|
509
|
+
if axis != lowest_var_axis:
|
|
510
|
+
warnings.warn(
|
|
511
|
+
f"Detected axis {lowest_var_axis} as the possible time axis for "
|
|
512
|
+
f"the stack due to its low variability, but axis {axis} was "
|
|
513
|
+
"supplied for registration. Are you sure you supplied the "
|
|
514
|
+
"correct axis?",
|
|
515
|
+
stacklevel=2,
|
|
516
|
+
)
|
|
517
|
+
|
|
518
|
+
frames = FrameSource(stack, axis, moving_average)
|
|
519
|
+
|
|
520
|
+
# Frame 0 keeps the identity unless it is itself registered to a
|
|
521
|
+
# reference image it is not identical to.
|
|
522
|
+
first_index = 1
|
|
523
|
+
ref: np.ndarray | None = None
|
|
524
|
+
if reference == "first":
|
|
525
|
+
ref = frames.mean_of_first(n_frames)
|
|
526
|
+
if moving_average > 1:
|
|
527
|
+
first_index = 0
|
|
528
|
+
elif reference == "mean":
|
|
529
|
+
ref = frames.mean_of_all()
|
|
530
|
+
first_index = 0
|
|
531
|
+
|
|
532
|
+
tmatdim = 4 if self._transformation == self.BILINEAR else 3
|
|
533
|
+
tmats = np.repeat(
|
|
534
|
+
np.identity(tmatdim).reshape((1, tmatdim, tmatdim)), n, axis=0
|
|
535
|
+
).astype(np.double)
|
|
536
|
+
|
|
537
|
+
# Every task registers one frame to its reference and is independent
|
|
538
|
+
# of all other tasks, also for reference="previous": there, the
|
|
539
|
+
# pairwise transformations are chained after all tasks have finished.
|
|
540
|
+
last: dict[str, Any] = {}
|
|
541
|
+
|
|
542
|
+
def register_frame(i: int) -> None:
|
|
543
|
+
reference_image = frames.frame(i - 1) if ref is None else ref
|
|
544
|
+
m, refpts, movpts = self._register_pair(reference_image, frames.frame(i))
|
|
545
|
+
tmats[i] = self._matrix_short_to_long(m)
|
|
546
|
+
if i == n - 1:
|
|
547
|
+
last["result"] = (m, refpts, movpts)
|
|
548
|
+
|
|
549
|
+
indices = range(first_index, n)
|
|
550
|
+
with Progress(len(indices), verbose, progress_callback, "Registering") as p:
|
|
551
|
+
run_tasks(register_frame, indices, n_workers, p.step)
|
|
552
|
+
|
|
553
|
+
if reference == "previous":
|
|
554
|
+
for i in range(1, n):
|
|
555
|
+
tmats[i] = np.matmul(tmats[i], tmats[i - 1])
|
|
556
|
+
|
|
557
|
+
if "result" in last:
|
|
558
|
+
self._m, self._refpts, self._movpts = last["result"]
|
|
559
|
+
self._is_registered = True
|
|
560
|
+
self._tmats = tmats
|
|
561
|
+
|
|
562
|
+
return self._tmats
|
|
563
|
+
|
|
564
|
+
def transform_stack(
|
|
565
|
+
self,
|
|
566
|
+
img: npt.ArrayLike,
|
|
567
|
+
axis: int = 0,
|
|
568
|
+
tmats: npt.ArrayLike | None = None,
|
|
569
|
+
*,
|
|
570
|
+
n_jobs: int | None = 1,
|
|
571
|
+
out: np.ndarray | None = None,
|
|
572
|
+
verbose: bool = False,
|
|
573
|
+
progress_callback: Callable[..., Any] | None = None,
|
|
574
|
+
) -> np.ndarray:
|
|
575
|
+
"""
|
|
576
|
+
Transform a stack after registration.
|
|
577
|
+
|
|
578
|
+
:type img: array_like(Ni..., Nj..., Nk...)
|
|
579
|
+
:param img: The 3D stack of images that should be aligned
|
|
580
|
+
|
|
581
|
+
:type axis: int, optional
|
|
582
|
+
:param axis: The axis of the time dimension
|
|
583
|
+
|
|
584
|
+
:type tmats: ndarray(img.shape[axis], 3, 3), optional
|
|
585
|
+
:param tmats: The transformation matrix for each image in the stack
|
|
586
|
+
|
|
587
|
+
:type n_jobs: int, optional
|
|
588
|
+
:param n_jobs:
|
|
589
|
+
Number of threads used to transform frames in parallel. 1 (default)
|
|
590
|
+
transforms sequentially in the calling thread; -1 uses all
|
|
591
|
+
available CPUs. The result does not depend on ``n_jobs``.
|
|
592
|
+
|
|
593
|
+
:type out: ndarray, optional
|
|
594
|
+
:param out:
|
|
595
|
+
Array of the same shape as ``img`` that receives the result. By
|
|
596
|
+
default a new float64 array is allocated, which for integer input
|
|
597
|
+
needs several times the memory of the stack. Pass an array of a
|
|
598
|
+
smaller floating-point dtype, an integer dtype (values are rounded
|
|
599
|
+
and clipped to the range of the dtype), a ``numpy.memmap``, or
|
|
600
|
+
``img`` itself to transform the stack in place.
|
|
601
|
+
|
|
602
|
+
:type verbose: bool, optional
|
|
603
|
+
:param verbose:
|
|
604
|
+
Specifies whether a progressbar should be shown using tqdm.
|
|
605
|
+
|
|
606
|
+
:type progress_callback: function, optional
|
|
607
|
+
:param progress_callback:
|
|
608
|
+
A function that is called after every transformed frame with the
|
|
609
|
+
keyword arguments current_iteration:int and end_iteration:int.
|
|
610
|
+
|
|
611
|
+
:rtype: ndarray(Ni..., Nj..., Nk...)
|
|
612
|
+
:return: The transformed stack (``out`` if it was given, otherwise a
|
|
613
|
+
new float64 array)
|
|
614
|
+
"""
|
|
615
|
+
stack, axis = self._check_stack(img, axis)
|
|
616
|
+
n_workers = resolve_n_jobs(n_jobs)
|
|
617
|
+
|
|
618
|
+
if tmats is None:
|
|
619
|
+
if self._tmats is None:
|
|
620
|
+
raise RuntimeError(
|
|
621
|
+
"No transformation matrices given. Please register first or pass "
|
|
622
|
+
"transformation matrices explicitly."
|
|
623
|
+
)
|
|
624
|
+
matrices = self._tmats
|
|
625
|
+
else:
|
|
626
|
+
matrices = np.asarray(tmats)
|
|
627
|
+
|
|
628
|
+
n = stack.shape[axis]
|
|
629
|
+
tmatdim = 4 if self._transformation == self.BILINEAR else 3
|
|
630
|
+
if matrices.ndim != 3 or matrices.shape[1:] != (tmatdim, tmatdim):
|
|
631
|
+
raise ValueError(
|
|
632
|
+
f"tmats must have shape (N, {tmatdim}, {tmatdim}), got {matrices.shape}"
|
|
633
|
+
)
|
|
634
|
+
if matrices.shape[0] != n:
|
|
635
|
+
raise ValueError(
|
|
636
|
+
"Number of saved transformation matrices does not match stack length"
|
|
637
|
+
)
|
|
638
|
+
|
|
639
|
+
if out is None:
|
|
640
|
+
result = np.empty(stack.shape, dtype=np.float64)
|
|
641
|
+
else:
|
|
642
|
+
result = check_output_array(out, stack.shape)
|
|
643
|
+
|
|
644
|
+
def transform_frame(i: int) -> None:
|
|
645
|
+
frame = self.transform(simple_slice(stack, i, axis), matrices[i])
|
|
646
|
+
store_frame(result, i, axis, frame)
|
|
647
|
+
|
|
648
|
+
with Progress(n, verbose, progress_callback, "Transforming") as p:
|
|
649
|
+
run_tasks(transform_frame, range(n), n_workers, p.step)
|
|
650
|
+
|
|
651
|
+
return result
|
|
652
|
+
|
|
653
|
+
def register_transform_stack(
|
|
654
|
+
self,
|
|
655
|
+
img: npt.ArrayLike,
|
|
656
|
+
reference: str = "previous",
|
|
657
|
+
n_frames: int = 1,
|
|
658
|
+
axis: int = 0,
|
|
659
|
+
moving_average: int = 1,
|
|
660
|
+
verbose: bool = False,
|
|
661
|
+
progress_callback: Callable[..., Any] | None = None,
|
|
662
|
+
*,
|
|
663
|
+
suppress_axis_warning: bool = False,
|
|
664
|
+
n_jobs: int | None = 1,
|
|
665
|
+
out: np.ndarray | None = None,
|
|
666
|
+
) -> np.ndarray:
|
|
667
|
+
"""
|
|
668
|
+
Register and transform stack of images (movie).
|
|
669
|
+
|
|
670
|
+
:type img: array_like(Ni..., Nj..., Nk...)
|
|
671
|
+
:param img: The 3D stack of images that should be aligned
|
|
672
|
+
|
|
673
|
+
:type reference: string, one of ['previous', 'first', 'mean']
|
|
674
|
+
:param reference:
|
|
675
|
+
* *'previous'*: Aligns each frame (image) to its previous frame in the
|
|
676
|
+
stack
|
|
677
|
+
* *'first:'* Aligns each frame (image) to the first frame in the stack -
|
|
678
|
+
if n_frames is > 1, then each frame is aligned to the
|
|
679
|
+
mean of the first n_frames of the stack
|
|
680
|
+
* *'mean'*: Aligns each frame (image) to the average of all images in the
|
|
681
|
+
stack
|
|
682
|
+
|
|
683
|
+
:type n_frames: int, optional
|
|
684
|
+
:param n_frames: If reference is 'first', then this parameter specifies the
|
|
685
|
+
number of frames from the beginning of the stack that
|
|
686
|
+
should be averaged to yield the reference image.
|
|
687
|
+
|
|
688
|
+
:type axis: int, optional
|
|
689
|
+
:param axis: The axis of the time dimension
|
|
690
|
+
|
|
691
|
+
:type moving_average: int, optional
|
|
692
|
+
:param moving_average: If moving_average is greater than 1, a moving average of
|
|
693
|
+
the stack is first created (using a subset size of
|
|
694
|
+
moving_average) before registration
|
|
695
|
+
|
|
696
|
+
:type verbose: bool, optional
|
|
697
|
+
:param verbose:
|
|
698
|
+
Specifies whether a progressbar should be shown using tqdm (one
|
|
699
|
+
bar for the registration and one for the transformation).
|
|
700
|
+
|
|
701
|
+
:type progress_callback: function, optional
|
|
702
|
+
:param progress_callback:
|
|
703
|
+
A function that is called after every iteration of the
|
|
704
|
+
registration. This function should accept
|
|
705
|
+
the keyword arguments current_iteration:int and end_iteration:int.
|
|
706
|
+
|
|
707
|
+
:type suppress_axis_warning: bool, optional
|
|
708
|
+
:param suppress_axis_warning:
|
|
709
|
+
Set this option to True to suppress the warning that is raised
|
|
710
|
+
when the supplied axis does not look like the time axis.
|
|
711
|
+
|
|
712
|
+
:type n_jobs: int, optional
|
|
713
|
+
:param n_jobs:
|
|
714
|
+
Number of threads used for registration and transformation. 1
|
|
715
|
+
(default) is sequential; -1 uses all available CPUs.
|
|
716
|
+
|
|
717
|
+
:type out: ndarray, optional
|
|
718
|
+
:param out:
|
|
719
|
+
Array that receives the transformed stack, see
|
|
720
|
+
:meth:`transform_stack`.
|
|
721
|
+
|
|
722
|
+
:rtype: ndarray(Ni..., Nj..., Nk...)
|
|
723
|
+
:return: The transformed stack
|
|
724
|
+
"""
|
|
725
|
+
stack = np.asarray(img)
|
|
726
|
+
self.register_stack(
|
|
727
|
+
stack,
|
|
728
|
+
reference,
|
|
729
|
+
n_frames,
|
|
730
|
+
axis,
|
|
731
|
+
moving_average,
|
|
732
|
+
verbose,
|
|
733
|
+
progress_callback,
|
|
734
|
+
suppress_axis_warning,
|
|
735
|
+
n_jobs=n_jobs,
|
|
736
|
+
)
|
|
737
|
+
|
|
738
|
+
return self.transform_stack(
|
|
739
|
+
stack, axis, n_jobs=n_jobs, out=out, verbose=verbose
|
|
740
|
+
)
|
|
741
|
+
|
|
742
|
+
@staticmethod
|
|
743
|
+
def _check_stack(img: npt.ArrayLike, axis: int) -> tuple[np.ndarray, int]:
|
|
744
|
+
"""Validate a stack argument and normalise ``axis`` to 0, 1 or 2."""
|
|
745
|
+
stack = np.asarray(img)
|
|
746
|
+
if stack.ndim != 3:
|
|
747
|
+
raise ValueError(
|
|
748
|
+
f"Stack must have three dimensions, got {stack.ndim} dimension(s)"
|
|
749
|
+
)
|
|
750
|
+
try:
|
|
751
|
+
axis = operator.index(axis)
|
|
752
|
+
except TypeError:
|
|
753
|
+
raise TypeError(f"axis must be an integer, got {axis!r}") from None
|
|
754
|
+
if not -3 <= axis < 3:
|
|
755
|
+
raise ValueError(f"axis {axis} is out of bounds for a 3-D stack")
|
|
756
|
+
axis %= 3
|
|
757
|
+
if stack.shape[axis] == 0:
|
|
758
|
+
raise ValueError(f"Stack has no frames along axis {axis}")
|
|
759
|
+
return stack, axis
|
|
760
|
+
|
|
761
|
+
|
|
762
|
+
def _check_count(value: int, name: str, minimum: int = 1) -> int:
|
|
763
|
+
"""Validate an integer argument that must not be smaller than ``minimum``."""
|
|
764
|
+
try:
|
|
765
|
+
value = operator.index(value)
|
|
766
|
+
except TypeError:
|
|
767
|
+
raise TypeError(f"{name} must be an integer, got {value!r}") from None
|
|
768
|
+
if value < minimum:
|
|
769
|
+
raise ValueError(f"{name} must be at least {minimum}, got {value}")
|
|
770
|
+
return value
|
|
771
|
+
|
|
772
|
+
|
|
773
|
+
def _bilinear_map(
|
|
774
|
+
mat: np.ndarray, x: np.ndarray, y: np.ndarray
|
|
775
|
+
) -> tuple[np.ndarray, np.ndarray]:
|
|
776
|
+
"""Evaluate a bilinear transformation (4x4 matrix acting on x, y, xy, 1)."""
|
|
777
|
+
a, b = mat[0], mat[1]
|
|
778
|
+
return (
|
|
779
|
+
a[0] * x + a[1] * y + a[2] * x * y + a[3],
|
|
780
|
+
b[0] * x + b[1] * y + b[2] * x * y + b[3],
|
|
781
|
+
)
|
|
782
|
+
|
|
783
|
+
|
|
784
|
+
def _bilinear_solve(
|
|
785
|
+
mat: np.ndarray, x: np.ndarray, y: np.ndarray
|
|
786
|
+
) -> tuple[np.ndarray, np.ndarray]:
|
|
787
|
+
"""Invert a bilinear transformation for the given target coordinates.
|
|
788
|
+
|
|
789
|
+
A bilinear map has no matrix inverse. The solution that is continuously
|
|
790
|
+
connected to the affine case is found by Newton iteration started at the
|
|
791
|
+
target coordinates.
|
|
792
|
+
"""
|
|
793
|
+
a, b = mat[0], mat[1]
|
|
794
|
+
u = np.array(x, dtype=np.float64, copy=True)
|
|
795
|
+
v = np.array(y, dtype=np.float64, copy=True)
|
|
796
|
+
for _ in range(100):
|
|
797
|
+
fu = a[0] * u + a[1] * v + a[2] * u * v + a[3] - x
|
|
798
|
+
fv = b[0] * u + b[1] * v + b[2] * u * v + b[3] - y
|
|
799
|
+
j11, j12 = a[0] + a[2] * v, a[1] + a[2] * u
|
|
800
|
+
j21, j22 = b[0] + b[2] * v, b[1] + b[2] * u
|
|
801
|
+
det = j11 * j22 - j12 * j21
|
|
802
|
+
with np.errstate(divide="ignore", invalid="ignore"):
|
|
803
|
+
du = (j22 * fu - j12 * fv) / det
|
|
804
|
+
dv = (j11 * fv - j21 * fu) / det
|
|
805
|
+
u, v = u - du, v - dv
|
|
806
|
+
step = np.max(np.hypot(du, dv)) if du.size else 0.0
|
|
807
|
+
if not np.isfinite(step):
|
|
808
|
+
break
|
|
809
|
+
if step < 1e-10:
|
|
810
|
+
return u, v
|
|
811
|
+
raise RuntimeError(
|
|
812
|
+
"Could not invert the bilinear transformation for the given points "
|
|
813
|
+
"(the transformation is singular or too strongly distorted)"
|
|
814
|
+
)
|