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