Debian Codegraph @

pyvista/core/utilities/transform.py

raw
1 """Module containing the Transform class."""
2
3 from __future__ import annotations
4
5 from collections.abc import Sequence
6 from typing import TYPE_CHECKING
7 from typing import Literal
8 from typing import cast
9 from typing import overload
10
11 import numpy as np
12
13 import pyvista as pv
14 from pyvista import _vtk
15 from pyvista.core import _validation
16 from pyvista.core._vtk_utilities import DisableVtkSnakeCase
17 from pyvista.core._vtk_utilities import vtkPyVistaOverride
18 from pyvista.core.utilities.arrays import array_from_vtkmatrix
19 from pyvista.core.utilities.arrays import vtkmatrix_from_array
20 from pyvista.core.utilities.misc import _NoNewAttrMixin
21 from pyvista.core.utilities.misc import assert_empty_kwargs
22 from pyvista.core.utilities.transformations import _decomposition_as_homogeneous
23 from pyvista.core.utilities.transformations import apply_transformation_to_points
24 from pyvista.core.utilities.transformations import axis_angle_rotation
25 from pyvista.core.utilities.transformations import decomposition
26 from pyvista.core.utilities.transformations import reflection
27
28 if TYPE_CHECKING: # pragma: no cover
29 from scipy.spatial.transform import Rotation
30
31 from pyvista import DataSet
32 from pyvista import MultiBlock
33 from pyvista import Prop3D
34 from pyvista.core._typing_core import MatrixLike
35 from pyvista.core._typing_core import NumpyArray
36 from pyvista.core._typing_core import RotationLike
37 from pyvista.core._typing_core import TransformLike
38 from pyvista.core._typing_core import VectorLike
39 from pyvista.core._typing_core import _DataSetOrMultiBlockType
40 from pyvista.core.utilities.transformations import _FiveArrays
41
42
43 class Transform(
44 _NoNewAttrMixin,
45 DisableVtkSnakeCase,
46 vtkPyVistaOverride,
47 _vtk.vtkTransform,
48 ):
49 """Describes linear transformations via a 4x4 matrix.
50
51 A :class:`Transform` can be used to describe the full range of linear (also known
52 as affine) coordinate transformations in three dimensions, which are internally
53 represented as a 4x4 homogeneous transformation matrix.
54
55 The transformation methods (e.g. :meth:`translate`, :meth:`rotate`,
56 :meth:`compose`) can operate in either :meth:`pre_multiply` or
57 :meth:`post_multiply` mode. In pre-multiply mode, any additional transformations
58 will occur *before* any transformations represented by the current :attr:`matrix`.
59 In post-multiply mode (the default), the additional transformation will occur
60 *after* any transformations represented by the current matrix.
61
62 .. note::
63
64 This class performs all of its operations in a right-handed coordinate system
65 with right-handed rotations. Some other graphics libraries use left-handed
66 coordinate systems and rotations.
67
68 .. versionadded:: 0.45
69
70 Parameters
71 ----------
72 trans : TransformLike | Sequence[TransformLike], optional
73 Initialize the transform with a transformation or sequence of transformations.
74 By default, the transform is initialized as the identity matrix.
75
76 point : VectorLike[float], optional
77 Point to use when composing transformations.
78 If set, two additional transformations are composed and added to
79 the :attr:`matrix_list`:
80
81 - :meth:`translate` to ``point`` before the transformation
82 - :meth:`translate` away from ``point`` after the transformation
83
84 By default, this value is ``None``, which means that the scale, rotation, etc.
85 transformations are performed about the origin ``(0, 0, 0)``.
86
87 multiply_mode : 'pre' | 'post', optional
88 Multiplication mode to use when composing. Set this to ``'pre'`` for
89 pre-multiplication or ``'post'`` for post-multiplication.
90
91 See Also
92 --------
93 pyvista.DataObjectFilters.transform
94 Apply a transformation to a mesh.
95 pyvista.Prop3D.transform
96 Transform an actor.
97
98 Examples
99 --------
100 Create a transformation and use ``+`` to compose a translation.
101
102 >>> import numpy as np
103 >>> import pyvista as pv
104 >>> position = (-0.6, -0.8, 2.1)
105 >>> translation_T = pv.Transform() + position
106 >>> translation_T.matrix
107 array([[ 1. , 0. , 0. , -0.6],
108 [ 0. , 1. , 0. , -0.8],
109 [ 0. , 0. , 1. , 2.1],
110 [ 0. , 0. , 0. , 1. ]])
111
112 Using ``+`` performs the same concatenation as calling :meth:`translate`.
113
114 >>> np.array_equal(
115 ... translation_T.matrix, pv.Transform().translate(position).matrix
116 ... )
117 True
118
119 Create a transformation and use ``*`` to compose a scaling matrix.
120
121 >>> scale_factor = 2.0
122 >>> scaling_T = pv.Transform() * scale_factor
123 >>> scaling_T.matrix
124 array([[2., 0., 0., 0.],
125 [0., 2., 0., 0.],
126 [0., 0., 2., 0.],
127 [0., 0., 0., 1.]])
128
129 Using ``*`` performs the same concatenation as calling :meth:`scale`.
130
131 >>> np.array_equal(scaling_T.matrix, pv.Transform().scale(scale_factor).matrix)
132 True
133
134 Compose the two transformations using ``*``. This will compose with
135 post-multiplication such that the transformations are applied in order from left to
136 right, i.e. translate first, then scale.
137
138 >>> transform_post = translation_T * scaling_T
139 >>> transform_post.matrix
140 array([[ 2. , 0. , 0. , -1.2],
141 [ 0. , 2. , 0. , -1.6],
142 [ 0. , 0. , 2. , 4.2],
143 [ 0. , 0. , 0. , 1. ]])
144
145 Post-multiplication is equivalent to using matrix multiplication on the
146 arrays directly but with the arguments reversed:
147
148 >>> mat_mul = scaling_T.matrix @ translation_T.matrix
149 >>> np.array_equal(transform_post.matrix, mat_mul)
150 True
151
152 Alternatively, compose the transformations by chaining the methods with a
153 single :class:`Transform` instance. Note that post-multiply is used by default.
154
155 >>> transform_post = pv.Transform()
156 >>> transform_post.multiply_mode
157 'post'
158 >>> _ = transform_post.translate(position).scale(scale_factor)
159 >>> transform_post.matrix
160 array([[ 2. , 0. , 0. , -1.2],
161 [ 0. , 2. , 0. , -1.6],
162 [ 0. , 0. , 2. , 4.2],
163 [ 0. , 0. , 0. , 1. ]])
164
165 Use :attr:`n_transformations` to check that there are two transformations.
166
167 >>> transform_post.n_transformations
168 2
169
170 Use :attr:`matrix_list` to get a list of the transformations. Since
171 post-multiplication is used, the translation matrix is first in the list since
172 it was applied first, and the scale matrix is second.
173
174 >>> transform_post.matrix_list[0] # translation
175 array([[ 1. , 0. , 0. , -0.6],
176 [ 0. , 1. , 0. , -0.8],
177 [ 0. , 0. , 1. , 2.1],
178 [ 0. , 0. , 0. , 1. ]])
179
180 >>> transform_post.matrix_list[1] # scaling
181 array([[2., 0., 0., 0.],
182 [0., 2., 0., 0.],
183 [0., 0., 2., 0.],
184 [0., 0., 0., 1.]])
185
186 Create a similar transform but use pre-multiplication this time. Compose the
187 transformations in the same order as before using :meth:`translate` and :meth:`scale`.
188
189 >>> transform_pre = pv.Transform().pre_multiply()
190 >>> _ = transform_pre.translate(position).scale(scale_factor)
191
192 This is equivalent to using matrix multiplication directly on the arrays:
193
194 >>> mat_mul = translation_T.matrix @ scaling_T.matrix
195 >>> np.array_equal(transform_pre.matrix, mat_mul)
196 True
197
198 Show the matrix list again. Note how the order with pre-multiplication is the
199 reverse of post-multiplication.
200
201 >>> transform_pre.matrix_list[0] # scaling
202 array([[2., 0., 0., 0.],
203 [0., 2., 0., 0.],
204 [0., 0., 2., 0.],
205 [0., 0., 0., 1.]])
206
207 >>> transform_pre.matrix_list[1] # translation
208 array([[ 1. , 0. , 0. , -0.6],
209 [ 0. , 1. , 0. , -0.8],
210 [ 0. , 0. , 1. , 2.1],
211 [ 0. , 0. , 0. , 1. ]])
212
213 Apply the two post- and pre-multiplied transformations to a dataset and plot them.
214 Note how the meshes have different positions since post- and pre-multiplication
215 produce different transformations.
216
217 >>> mesh_post = pv.Sphere().transform(transform_post, inplace=False)
218 >>> mesh_pre = pv.Cone().transform(transform_pre, inplace=False)
219 >>> pl = pv.Plotter()
220 >>> _ = pl.add_mesh(mesh_post, color='goldenrod')
221 >>> _ = pl.add_mesh(mesh_pre, color='teal')
222 >>> _ = pl.add_axes_at_origin()
223 >>> pl.show()
224
225 Get the composed inverse transformation matrix of the pre-multiplication case.
226
227 >>> inverse_matrix = transform_pre.inverse_matrix
228 >>> inverse_matrix
229 array([[ 0.5 , 0. , 0. , 0.3 ],
230 [ 0. , 0.5 , 0. , 0.4 ],
231 [ 0. , 0. , 0.5 , -1.05],
232 [ 0. , 0. , 0. , 1. ]])
233
234 Similar to using :attr:`matrix_list`, we can inspect the individual transformation
235 inverses with :attr:`inverse_matrix_list`.
236
237 >>> transform_pre.inverse_matrix_list[0] # inverse scaling
238 array([[0.5, 0. , 0. , 0. ],
239 [0. , 0.5, 0. , 0. ],
240 [0. , 0. , 0.5, 0. ],
241 [0. , 0. , 0. , 1. ]])
242
243 >>> transform_pre.inverse_matrix_list[1] # inverse translation
244 array([[ 1. , 0. , 0. , 0.6],
245 [ 0. , 1. , 0. , 0.8],
246 [ 0. , 0. , 1. , -2.1],
247 [ 0. , 0. , 0. , 1. ]])
248
249 Transform the mesh by its inverse to restore it to its original un-scaled state
250 and positioning at the origin.
251
252 >>> mesh_pre_inverted = mesh_pre.transform(inverse_matrix, inplace=False)
253 >>> pl = pv.Plotter()
254 >>> _ = pl.add_mesh(mesh_pre_inverted, color='teal')
255 >>> _ = pl.add_axes_at_origin()
256 >>> pl.show()
257
258 """
259
260 def __init__(
261 self: Transform,
262 trans: TransformLike | Sequence[TransformLike] | None = None,
263 *,
264 point: VectorLike[float] | None = None,
265 multiply_mode: Literal['pre', 'post'] = 'post',
266 ) -> None:
267 super().__init__()
268 self.multiply_mode = multiply_mode
269 self.point = point
270 self.check_finite = True
271 if trans is not None:
272 if isinstance(trans, Sequence):
273 if all(isinstance(item, Sequence) for item in trans):
274 # Init from a nested sequence array
275 self.compose(trans)
276 else:
277 # Init from sequence of transformations
278 [self.compose(t) for t in trans]
279 else:
280 self.compose(trans)
281
282 self._decomposition_cache: _FiveArrays | None = None
283 self._decomposition_mtime = -1
284
285 def __add__(self: Transform, other: VectorLike[float]) -> Transform:
286 """:meth:`translate` this transform using post-multiply semantics."""
287 try:
288 return self.copy().translate(other, multiply_mode='post')
289 except TypeError:
290 msg = (
291 f"Unsupported operand type(s) for +: '{self.__class__.__name__}' "
292 f"and '{type(other).__name__}'\n"
293 f'The right-side argument must be a length-3 vector.'
294 )
295 raise TypeError(msg)
296 except ValueError:
297 msg = (
298 f"Unsupported operand value(s) for +: '{self.__class__.__name__}' "
299 f"and '{type(other).__name__}'\n"
300 f'The right-side argument must be a length-3 vector.'
301 )
302 raise ValueError(msg)
303
304 def __radd__(self: Transform, other: VectorLike[float]) -> Transform:
305 """:meth:`translate` this transform using pre-multiply semantics."""
306 try:
307 return self.copy().translate(other, multiply_mode='pre')
308 except TypeError:
309 msg = (
310 f"Unsupported operand type(s) for +: '{type(other).__name__}' "
311 f"and '{self.__class__.__name__}'\n"
312 f'The left-side argument must be a length-3 vector.'
313 )
314 raise TypeError(msg)
315 except ValueError:
316 msg = (
317 f"Unsupported operand value(s) for +: '{type(other).__name__}' "
318 f"and '{self.__class__.__name__}'\n"
319 f'The left-side argument must be a length-3 vector.'
320 )
321 raise ValueError(msg)
322
323 def __mul__(self: Transform, other: float | VectorLike[float] | TransformLike) -> Transform:
324 """:meth:`compose` this transform using post-multiply semantics.
325
326 Use :meth:`scale` for single numbers and length-3 vector inputs, and
327 :meth:`compose` otherwise for transform-like inputs.
328 """
329 copied = self.copy()
330 try:
331 transform = copied.scale(other, multiply_mode='post') # type: ignore[arg-type]
332 except (ValueError, TypeError):
333 try:
334 transform = copied.compose(other, multiply_mode='post')
335 except TypeError:
336 msg = (
337 f"Unsupported operand type(s) for *: '{self.__class__.__name__}' "
338 f"and '{type(other).__name__}'\n"
339 f'The right-side argument must be transform-like.'
340 )
341 raise TypeError(msg)
342 except ValueError:
343 msg = (
344 f"Unsupported operand value(s) for *: '{self.__class__.__name__}' "
345 f"and '{type(other).__name__}'\n"
346 f'The right-side argument must be a single number or a length-3 vector '
347 f'or have 3x3 or 4x4 shape.'
348 )
349 raise ValueError(msg)
350 return transform
351
352 def __rmul__(self: Transform, other: float | VectorLike[float]) -> Transform:
353 """:meth:`scale` this transform using pre-multiply semantics."""
354 try:
355 return self.copy().scale(other, multiply_mode='pre')
356 except TypeError:
357 msg = (
358 f"Unsupported operand type(s) for *: '{type(other).__name__}' "
359 f"and '{self.__class__.__name__}'\n"
360 f'The left-side argument must be a single number or a length-3 vector.'
361 )
362 raise TypeError(msg)
363 except ValueError:
364 msg = (
365 f"Unsupported operand value(s) for *: '{type(other).__name__}' "
366 f"and '{self.__class__.__name__}'\n"
367 f'The left-side argument must be a single number or a length-3 vector.'
368 )
369 raise ValueError(msg)
370
371 def copy(self: Transform) -> Transform:
372 """Return a deep copy of the transform.
373
374 Returns
375 -------
376 Transform
377 Deep copy of this transform.
378
379 Examples
380 --------
381 Create a scaling transform.
382
383 >>> import pyvista as pv
384 >>> transform = pv.Transform().scale(1, 2, 3)
385 >>> transform.matrix
386 array([[1., 0., 0., 0.],
387 [0., 2., 0., 0.],
388 [0., 0., 3., 0.],
389 [0., 0., 0., 1.]])
390
391 Copy the transform.
392
393 >>> copied = transform.copy()
394 >>> copied.matrix
395 array([[1., 0., 0., 0.],
396 [0., 2., 0., 0.],
397 [0., 0., 3., 0.],
398 [0., 0., 0., 1.]])
399
400 >>> copied is transform
401 False
402
403 """
404 new_transform = Transform()
405 new_transform.DeepCopy(self)
406
407 # Need to copy other props not stored by vtkTransform
408 new_transform.multiply_mode = self.multiply_mode
409
410 return new_transform
411
412 def __repr__(self: Transform) -> str:
413 """Representation of the transform."""
414
415 def _matrix_repr() -> str:
416 repr_ = np.array_repr(self.matrix)
417 return repr_.replace('array(', ' ').replace(')', '').replace(' [', '[')
418
419 matrix_repr_lines = _matrix_repr().split('\n')
420 lines = [
421 f'{type(self).__name__} ({hex(id(self))})',
422 f' Num Transformations: {self.n_transformations}',
423 f' Matrix: {matrix_repr_lines[0]}',
424 f' {matrix_repr_lines[1]}',
425 f' {matrix_repr_lines[2]}',
426 f' {matrix_repr_lines[3]}',
427 ]
428 return '\n'.join(lines)
429
430 @property
431 def point(self: Transform) -> tuple[float, float, float] | None: # numpydoc ignore=RT01
432 """Point to use when composing some transformations such as scale, rotation, etc.
433
434 If set, two additional transformations are composed and added to
435 the :attr:`matrix_list`:
436
437 - :meth:`translate` to ``point`` before the transformation
438 - :meth:`translate` away from ``point`` after the transformation
439
440 By default, this value is ``None``, which means that the scale, rotation, etc.
441 transformations are performed about the origin ``(0, 0, 0)``.
442
443 """
444 return self._point
445
446 @point.setter
447 def point(self: Transform, point: VectorLike[float] | None) -> None:
448 self._point = (
449 None
450 if point is None
451 else _validation.validate_array3(point, dtype_out=float, to_tuple=True, name='point')
452 )
453
454 @property
455 def multiply_mode(self: Transform) -> Literal['pre', 'post']: # numpydoc ignore=RT01
456 """Set or get the multiplication mode.
457
458 Set this to ``'pre'`` to set the multiplication mode to :meth:`pre_multiply`.
459 Set this to ``'post'`` to set it to :meth:`post_multiply`.
460
461 In pre-multiply mode, any additional transformations (e.g. using
462 :meth:`translate`, :meth:`compose`, etc.) will occur *before* any
463 transformations represented by the current :attr:`matrix`.
464 In post-multiply mode, the additional transformation will occur *after* any
465 transformations represented by the current matrix.
466 """
467 return self._multiply_mode
468
469 @multiply_mode.setter
470 def multiply_mode(self: Transform, multiply_mode: Literal['pre', 'post']) -> None:
471 _validation.check_contains(
472 ['pre', 'post'], must_contain=multiply_mode, name='multiply mode'
473 )
474 self.pre_multiply() if multiply_mode == 'pre' else self.post_multiply()
475
476 def pre_multiply(self: Transform) -> Transform: # numpydoc ignore=RT01
477 """Set the multiplication mode to pre-multiply.
478
479 In pre-multiply mode, any additional transformations (e.g. using
480 :meth:`translate`, :meth:`compose`, etc.) will occur *before* any
481 transformations represented by the current :attr:`matrix`.
482
483 Examples
484 --------
485 >>> import pyvista as pv
486 >>> transform = pv.Transform().pre_multiply()
487 >>> transform.multiply_mode
488 'pre'
489
490 """
491 self._multiply_mode: Literal['pre', 'post'] = 'pre'
492 self.PreMultiply()
493 return self
494
495 def post_multiply(self: Transform) -> Transform: # numpydoc ignore=RT01
496 """Set the multiplication mode to post-multiply.
497
498 In post-multiply mode, any additional transformations (e.g. using
499 :meth:`translate`, :meth:`compose`, etc.) will occur *after* any
500 transformations represented by the current :attr:`matrix`.
501
502 Examples
503 --------
504 >>> import pyvista as pv
505 >>> transform = pv.Transform().post_multiply()
506 >>> transform.multiply_mode
507 'post'
508
509 """
510 self._multiply_mode = 'post'
511 self.PostMultiply()
512 return self
513
514 def scale(
515 self: Transform,
516 *factor: float | VectorLike[float],
517 point: VectorLike[float] | None = None,
518 multiply_mode: Literal['pre', 'post'] | None = None,
519 ) -> Transform: # numpydoc ignore=RT01
520 """Compose a scale matrix.
521
522 Create a scale matrix and :meth:`compose` it with the current
523 transformation :attr:`matrix` according to pre-multiply or post-multiply
524 semantics.
525
526 Internally, the matrix is stored in the :attr:`matrix_list`.
527
528 Parameters
529 ----------
530 *factor : float | VectorLike[float]
531 Scale factor(s) to use. Use a single number for uniform scaling or
532 three numbers for non-uniform scaling. The three factors may be
533 passed as a single vector (one arg) or an unpacked vector (three args).
534
535 point : VectorLike[float], optional
536 Point to scale from. By default, the object's :attr:`point` is used,
537 but this can be overridden.
538 If set, two additional transformations are composed and added to
539 the :attr:`matrix_list`:
540
541 - :meth:`translate` to ``point`` before the scaling
542 - :meth:`translate` away from ``point`` after the scaling
543
544 multiply_mode : 'pre' | 'post', optional
545 Multiplication mode to use when composing the matrix. By default, the
546 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
547 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
548
549 See Also
550 --------
551 pyvista.DataObjectFilters.scale
552 Scale a mesh.
553
554 pyvista.DataObjectFilters.resize
555 Resize a mesh.
556
557 scale_factors, has_scale
558 Get info about the transform's scale component.
559
560 Examples
561 --------
562 Compose a scale matrix.
563
564 >>> import pyvista as pv
565 >>> transform = pv.Transform().scale(1, 2, 3)
566 >>> transform.matrix
567 array([[1., 0., 0., 0.],
568 [0., 2., 0., 0.],
569 [0., 0., 3., 0.],
570 [0., 0., 0., 1.]])
571
572 Compose a second scale matrix using ``*``.
573
574 >>> transform = transform * 2
575 >>> transform.matrix
576 array([[2., 0., 0., 0.],
577 [0., 4., 0., 0.],
578 [0., 0., 6., 0.],
579 [0., 0., 0., 1.]])
580
581 Scale from a point. Check the :attr:`matrix_list` to see that a translation
582 is added before and after the scaling.
583
584 >>> transform = pv.Transform().scale(7, point=(1, 2, 3))
585 >>> translation_to_origin = transform.matrix_list[0]
586 >>> translation_to_origin
587 array([[ 1., 0., 0., -1.],
588 [ 0., 1., 0., -2.],
589 [ 0., 0., 1., -3.],
590 [ 0., 0., 0., 1.]])
591
592 >>> scale = transform.matrix_list[1]
593 >>> scale
594 array([[7., 0., 0., 0.],
595 [0., 7., 0., 0.],
596 [0., 0., 7., 0.],
597 [0., 0., 0., 1.]])
598
599 >>> translation_from_origin = transform.matrix_list[2]
600 >>> translation_from_origin
601 array([[1., 0., 0., 1.],
602 [0., 1., 0., 2.],
603 [0., 0., 1., 3.],
604 [0., 0., 0., 1.]])
605
606 """
607 valid_factor = _validation.validate_array3(
608 factor, # type: ignore[arg-type]
609 broadcast=True,
610 dtype_out=float,
611 name='scale factor',
612 )
613 transform = _vtk.vtkTransform()
614 transform.Scale(valid_factor)
615 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
616
617 def reflect(
618 self: Transform,
619 *normal: float | VectorLike[float],
620 point: VectorLike[float] | None = None,
621 multiply_mode: Literal['pre', 'post'] | None = None,
622 ) -> Transform: # numpydoc ignore=RT01
623 """Compose a reflection matrix.
624
625 Create a reflection matrix and :meth:`compose` it with the current
626 transformation :attr:`matrix` according to pre-multiply or post-multiply
627 semantics.
628
629 Internally, the matrix is stored in the :attr:`matrix_list`.
630
631 Parameters
632 ----------
633 *normal : float | VectorLike[float]
634 Normal direction for reflection. May be a single vector (one arg) or
635 unpacked vector (three args).
636
637 point : VectorLike[float], optional
638 Point to reflect about. By default, the object's :attr:`point` is used,
639 but this can be overridden.
640 If set, two additional transformations are composed and added to
641 the :attr:`matrix_list`:
642
643 - :meth:`translate` to ``point`` before the reflection
644 - :meth:`translate` away from ``point`` after the reflection
645
646 multiply_mode : 'pre' | 'post', optional
647 Multiplication mode to use when composing the matrix. By default, the
648 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
649 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
650
651 See Also
652 --------
653 flip_x, flip_y, flip_z
654 Convenience methods for reflecting about the x-, y-, or z-axis.
655
656 pyvista.DataObjectFilters.reflect
657 Reflect a mesh.
658
659 reflection, has_reflection
660 Get info about the transform's reflection component.
661
662 Examples
663 --------
664 Compose a reflection matrix.
665
666 >>> import pyvista as pv
667 >>> transform = pv.Transform()
668 >>> _ = transform.reflect(0, 0, 1)
669 >>> transform.matrix
670 array([[ 1., 0., 0., 0.],
671 [ 0., 1., 0., 0.],
672 [ 0., 0., -1., 0.],
673 [ 0., 0., 0., 1.]])
674
675 Compose a second reflection matrix.
676
677 >>> _ = transform.reflect((1, 0, 0))
678 >>> transform.matrix
679 array([[-1., 0., 0., 0.],
680 [ 0., 1., 0., 0.],
681 [ 0., 0., -1., 0.],
682 [ 0., 0., 0., 1.]])
683
684 """
685 valid_normal = _validation.validate_array3(
686 normal, # type: ignore[arg-type]
687 dtype_out=float,
688 name='reflection normal',
689 )
690 transform = reflection(valid_normal)
691 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
692
693 def flip_x(
694 self: Transform,
695 *,
696 point: VectorLike[float] | None = None,
697 multiply_mode: Literal['pre', 'post'] | None = None,
698 ) -> Transform: # numpydoc ignore=RT01
699 """Compose a reflection about the x-axis.
700
701 Create a reflection about the x-axis and :meth:`compose` it
702 with the current transformation :attr:`matrix` according to pre-multiply or
703 post-multiply semantics.
704
705 Internally, the matrix is stored in the :attr:`matrix_list`.
706
707 Parameters
708 ----------
709 point : VectorLike[float], optional
710 Point to reflect about. By default, the object's :attr:`point` is used,
711 but this can be overridden.
712 If set, two additional transformations are composed and added to
713 the :attr:`matrix_list`:
714
715 - :meth:`translate` to ``point`` before the reflection
716 - :meth:`translate` away from ``point`` after the reflection
717
718 multiply_mode : 'pre' | 'post', optional
719 Multiplication mode to use when composing the matrix. By default, the
720 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
721 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
722
723 See Also
724 --------
725 reflect, flip_y, flip_z
726 Similar reflection methods.
727
728 pyvista.DataObjectFilters.flip_x
729 Flip a mesh about the x-axis.
730
731 reflection, has_reflection
732 Get info about the transform's reflection component.
733
734 Examples
735 --------
736 Compose a reflection about the x-axis.
737
738 >>> import pyvista as pv
739 >>> transform = pv.Transform()
740 >>> _ = transform.flip_x()
741 >>> transform.matrix
742 array([[-1., 0., 0., 0.],
743 [ 0., 1., 0., 0.],
744 [ 0., 0., 1., 0.],
745 [ 0., 0., 0., 1.]])
746
747 Compose a second reflection, but this time about a point.
748
749 >>> _ = transform.flip_x(point=(4, 5, 6))
750 >>> transform.matrix
751 array([[1., 0., 0., 8.],
752 [0., 1., 0., 0.],
753 [0., 0., 1., 0.],
754 [0., 0., 0., 1.]])
755
756 """
757 return self.reflect((1, 0, 0), point=point, multiply_mode=multiply_mode)
758
759 def flip_y(
760 self: Transform,
761 *,
762 point: VectorLike[float] | None = None,
763 multiply_mode: Literal['pre', 'post'] | None = None,
764 ) -> Transform: # numpydoc ignore=RT01
765 """Compose a reflection about the y-axis.
766
767 Create a reflection about the y-axis and :meth:`compose` it
768 with the current transformation :attr:`matrix` according to pre-multiply or
769 post-multiply semantics.
770
771 Internally, the matrix is stored in the :attr:`matrix_list`.
772
773 Parameters
774 ----------
775 point : VectorLike[float], optional
776 Point to reflect about. By default, the object's :attr:`point` is used,
777 but this can be overridden.
778 If set, two additional transformations are composed and added to
779 the :attr:`matrix_list`:
780
781 - :meth:`translate` to ``point`` before the reflection
782 - :meth:`translate` away from ``point`` after the reflection
783
784 multiply_mode : 'pre' | 'post', optional
785 Multiplication mode to use when composing the matrix. By default, the
786 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
787 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
788
789 See Also
790 --------
791 reflect, flip_x, flip_z
792 Similar reflection methods.
793
794 pyvista.DataObjectFilters.flip_y
795 Flip a mesh about the y-axis.
796
797 reflection, has_reflection
798 Get info about the transform's reflection component.
799
800 Examples
801 --------
802 Compose a reflection about the y-axis.
803
804 >>> import pyvista as pv
805 >>> transform = pv.Transform()
806 >>> _ = transform.flip_y()
807 >>> transform.matrix
808 array([[ 1., 0., 0., 0.],
809 [ 0., -1., 0., 0.],
810 [ 0., 0., 1., 0.],
811 [ 0., 0., 0., 1.]])
812
813 Compose a second reflection, but this time about a point.
814
815 >>> _ = transform.flip_y(point=(4, 5, 6))
816 >>> transform.matrix
817 array([[ 1., 0., 0., 0.],
818 [ 0., 1., 0., 10.],
819 [ 0., 0., 1., 0.],
820 [ 0., 0., 0., 1.]])
821
822 """
823 return self.reflect((0, 1, 0), point=point, multiply_mode=multiply_mode)
824
825 def flip_z(
826 self: Transform,
827 *,
828 point: VectorLike[float] | None = None,
829 multiply_mode: Literal['pre', 'post'] | None = None,
830 ) -> Transform: # numpydoc ignore=RT01
831 """Compose a reflection about the z-axis.
832
833 Create a reflection about the z-axis and :meth:`compose` it
834 with the current transformation :attr:`matrix` according to pre-multiply or
835 post-multiply semantics.
836
837 Internally, the matrix is stored in the :attr:`matrix_list`.
838
839 Parameters
840 ----------
841 point : VectorLike[float], optional
842 Point to reflect about. By default, the object's :attr:`point` is used,
843 but this can be overridden.
844 If set, two additional transformations are composed and added to
845 the :attr:`matrix_list`:
846
847 - :meth:`translate` to ``point`` before the reflection
848 - :meth:`translate` away from ``point`` after the reflection
849
850 multiply_mode : 'pre' | 'post', optional
851 Multiplication mode to use when composing the matrix. By default, the
852 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
853 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
854
855 See Also
856 --------
857 reflect, flip_x, flip_y
858 Similar reflection methods.
859
860 pyvista.DataObjectFilters.flip_z
861 Flip a mesh about the z-axis.
862
863 reflection, has_reflection
864 Get info about the transform's reflection component.
865
866 Examples
867 --------
868 Compose a reflection about the z-axis.
869
870 >>> import pyvista as pv
871 >>> transform = pv.Transform()
872 >>> _ = transform.flip_z()
873 >>> transform.matrix
874 array([[ 1., 0., 0., 0.],
875 [ 0., 1., 0., 0.],
876 [ 0., 0., -1., 0.],
877 [ 0., 0., 0., 1.]])
878
879 Compose a second reflection, but this time about a point.
880
881 >>> _ = transform.flip_z(point=(4, 5, 6))
882 >>> transform.matrix
883 array([[ 1., 0., 0., 0.],
884 [ 0., 1., 0., 0.],
885 [ 0., 0., 1., 12.],
886 [ 0., 0., 0., 1.]])
887
888 """
889 return self.reflect((0, 0, 1), point=point, multiply_mode=multiply_mode)
890
891 def translate(
892 self: Transform,
893 *vector: float | VectorLike[float],
894 multiply_mode: Literal['pre', 'post'] | None = None,
895 ) -> Transform: # numpydoc ignore=RT01
896 """Compose a translation matrix.
897
898 Create a translation matrix and :meth:`compose` it with the current
899 transformation :attr:`matrix` according to pre-multiply or post-multiply
900 semantics.
901
902 Internally, the matrix is stored in the :attr:`matrix_list`.
903
904 Parameters
905 ----------
906 *vector : float | VectorLike[float]
907 Vector to use for translation. May be a single vector (one arg) or
908 unpacked vector (three args).
909
910 multiply_mode : 'pre' | 'post', optional
911 Multiplication mode to use when composing the matrix. By default, the
912 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
913 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
914
915 See Also
916 --------
917 pyvista.DataObjectFilters.translate
918 Translate a mesh.
919
920 translation, has_translation
921 Get info about the transform's translation component.
922
923 Examples
924 --------
925 Compose a translation matrix.
926
927 >>> import pyvista as pv
928 >>> transform = pv.Transform().translate(1, 2, 3)
929 >>> transform.matrix
930 array([[1., 0., 0., 1.],
931 [0., 1., 0., 2.],
932 [0., 0., 1., 3.],
933 [0., 0., 0., 1.]])
934
935 Compose a second translation matrix using ``+``.
936
937 >>> transform = transform + (1, 1, 1)
938 >>> transform.matrix
939 array([[1., 0., 0., 2.],
940 [0., 1., 0., 3.],
941 [0., 0., 1., 4.],
942 [0., 0., 0., 1.]])
943
944 """
945 valid_vector = _validation.validate_array3(
946 vector, # type: ignore[arg-type]
947 dtype_out=float,
948 name='translation vector',
949 )
950 transform = _vtk.vtkTransform()
951 transform.Translate(valid_vector)
952 return self.compose(transform, multiply_mode=multiply_mode)
953
954 def rotate(
955 self: Transform,
956 rotation: RotationLike,
957 *,
958 point: VectorLike[float] | None = None,
959 multiply_mode: Literal['pre', 'post'] | None = None,
960 ) -> Transform: # numpydoc ignore=RT01
961 """Compose a rotation matrix.
962
963 Create a rotation matrix and :meth:`compose` it with the current
964 transformation :attr:`matrix` according to pre-multiply or post-multiply
965 semantics. The rotation may be right-handed or left-handed.
966
967 Internally, the matrix is stored in the :attr:`matrix_list`.
968
969 Parameters
970 ----------
971 rotation : RotationLike
972 3x3 rotation matrix or a SciPy ``Rotation`` object.
973
974 point : VectorLike[float], optional
975 Point to rotate about. By default, the object's :attr:`point` is used,
976 but this can be overridden.
977 If set, two additional transformations are composed and added to
978 the :attr:`matrix_list`:
979
980 - :meth:`translate` to ``point`` before the rotation
981 - :meth:`translate` away from ``point`` after the rotation
982
983 multiply_mode : 'pre' | 'post', optional
984 Multiplication mode to use when composing the matrix. By default, the
985 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
986 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
987
988 See Also
989 --------
990 rotate_x, rotate_y, rotate_z, rotate_vector
991 Similar rotation methods.
992 rotation_matrix, rotation_axis_angle, as_rotation, has_rotation
993 Get this transform's rotation component.
994 pyvista.DataObjectFilters.rotate
995 Rotate a mesh.
996
997 Examples
998 --------
999 Compose a rotation matrix. In this case the rotation rotates about the
1000 z-axis by 90 degrees.
1001
1002 >>> import pyvista as pv
1003 >>> rotation_z_90 = [[0, -1, 0], [1, 0, 0], [0, 0, 1]]
1004 >>> transform = pv.Transform().rotate(rotation_z_90)
1005 >>> transform.matrix
1006 array([[ 0., -1., 0., 0.],
1007 [ 1., 0., 0., 0.],
1008 [ 0., 0., 1., 0.],
1009 [ 0., 0., 0., 1.]])
1010
1011 Compose a second rotation matrix. In this case we use the same rotation as
1012 before.
1013
1014 >>> _ = transform.rotate(rotation_z_90)
1015
1016 The result is a matrix that rotates about the z-axis by 180 degrees.
1017
1018 >>> transform.matrix
1019 array([[-1., 0., 0., 0.],
1020 [ 0., -1., 0., 0.],
1021 [ 0., 0., 1., 0.],
1022 [ 0., 0., 0., 1.]])
1023
1024 Rotate about a point. Check the :attr:`matrix_list` to see that a translation
1025 is added before and after the rotation.
1026
1027 >>> transform = pv.Transform().rotate(rotation_z_90, point=(1, 2, 3))
1028 >>> translation_to_origin = transform.matrix_list[0]
1029 >>> translation_to_origin
1030 array([[ 1., 0., 0., -1.],
1031 [ 0., 1., 0., -2.],
1032 [ 0., 0., 1., -3.],
1033 [ 0., 0., 0., 1.]])
1034
1035 >>> rotation = transform.matrix_list[1]
1036 >>> rotation
1037 array([[ 0., -1., 0., 0.],
1038 [ 1., 0., 0., 0.],
1039 [ 0., 0., 1., 0.],
1040 [ 0., 0., 0., 1.]])
1041
1042 >>> translation_from_origin = transform.matrix_list[2]
1043 >>> translation_from_origin
1044 array([[1., 0., 0., 1.],
1045 [0., 1., 0., 2.],
1046 [0., 0., 1., 3.],
1047 [0., 0., 0., 1.]])
1048
1049 """
1050 valid_rotation = _validation.validate_rotation(rotation)
1051 return self._compose_with_translations(
1052 valid_rotation, point=point, multiply_mode=multiply_mode
1053 )
1054
1055 def rotate_x(
1056 self: Transform,
1057 angle: float,
1058 *,
1059 point: VectorLike[float] | None = None,
1060 multiply_mode: Literal['pre', 'post'] | None = None,
1061 ) -> Transform: # numpydoc ignore=RT01
1062 """Compose a rotation about the x-axis.
1063
1064 Create a matrix for rotation about the x-axis and :meth:`compose`
1065 it with the current transformation :attr:`matrix` according to pre-multiply or
1066 post-multiply semantics.
1067
1068 Internally, the matrix is stored in the :attr:`matrix_list`.
1069
1070 Parameters
1071 ----------
1072 angle : float
1073 Angle in degrees to rotate about the x-axis.
1074
1075 point : VectorLike[float], optional
1076 Point to rotate about. By default, the object's :attr:`point` is used,
1077 but this can be overridden.
1078 If set, two additional transformations are composed and added to
1079 the :attr:`matrix_list`:
1080
1081 - :meth:`translate` to ``point`` before the rotation
1082 - :meth:`translate` away from ``point`` after the rotation
1083
1084 multiply_mode : 'pre' | 'post', optional
1085 Multiplication mode to use when composing the matrix. By default, the
1086 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
1087 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
1088
1089 See Also
1090 --------
1091 rotate_y, rotate_z, rotate_vector, rotate
1092 Similar rotation methods.
1093 rotation_matrix, rotation_axis_angle, as_rotation, has_rotation
1094 Get this transform's rotation component.
1095 pyvista.DataObjectFilters.rotate_x
1096 Rotate a mesh about the x-axis.
1097
1098 Examples
1099 --------
1100 Compose a rotation about the x-axis.
1101
1102 >>> import pyvista as pv
1103 >>> transform = pv.Transform().rotate_x(90)
1104 >>> transform.matrix
1105 array([[ 1., 0., 0., 0.],
1106 [ 0., 0., -1., 0.],
1107 [ 0., 1., 0., 0.],
1108 [ 0., 0., 0., 1.]])
1109
1110 Compose a second rotation about the x-axis.
1111
1112 >>> _ = transform.rotate_x(45)
1113
1114 The result is a matrix that rotates about the x-axis by 135 degrees.
1115
1116 >>> transform.matrix
1117 array([[ 1. , 0. , 0. , 0. ],
1118 [ 0. , -0.70710678, -0.70710678, 0. ],
1119 [ 0. , 0.70710678, -0.70710678, 0. ],
1120 [ 0. , 0. , 0. , 1. ]])
1121
1122 """
1123 transform = axis_angle_rotation((1, 0, 0), angle, deg=True)
1124 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
1125
1126 def rotate_y(
1127 self: Transform,
1128 angle: float,
1129 *,
1130 point: VectorLike[float] | None = None,
1131 multiply_mode: Literal['pre', 'post'] | None = None,
1132 ) -> Transform: # numpydoc ignore=RT01
1133 """Compose a rotation about the y-axis.
1134
1135 Create a matrix for rotation about the y-axis and :meth:`compose`
1136 it with the current transformation :attr:`matrix` according to pre-multiply or
1137 post-multiply semantics.
1138
1139 Internally, the matrix is stored in the :attr:`matrix_list`.
1140
1141 Parameters
1142 ----------
1143 angle : float
1144 Angle in degrees to rotate about the y-axis.
1145
1146 point : VectorLike[float], optional
1147 Point to rotate about. By default, the object's :attr:`point` is used,
1148 but this can be overridden.
1149 If set, two additional transformations are composed and added to
1150 the :attr:`matrix_list`:
1151
1152 - :meth:`translate` to ``point`` before the rotation
1153 - :meth:`translate` away from ``point`` after the rotation
1154
1155 multiply_mode : 'pre' | 'post', optional
1156 Multiplication mode to use when composing the matrix. By default, the
1157 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
1158 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
1159
1160 See Also
1161 --------
1162 rotate_x, rotate_z, rotate_vector, rotate
1163 Similar rotation methods.
1164 rotation_matrix, rotation_axis_angle, as_rotation, has_rotation
1165 Get this transform's rotation component.
1166 pyvista.DataObjectFilters.rotate_y
1167 Rotate a mesh about the y-axis.
1168
1169 Examples
1170 --------
1171 Compose a rotation about the y-axis.
1172
1173 >>> import pyvista as pv
1174 >>> transform = pv.Transform().rotate_y(90)
1175 >>> transform.matrix
1176 array([[ 0., 0., 1., 0.],
1177 [ 0., 1., 0., 0.],
1178 [-1., 0., 0., 0.],
1179 [ 0., 0., 0., 1.]])
1180
1181 Compose a second rotation about the y-axis.
1182
1183 >>> _ = transform.rotate_y(45)
1184
1185 The result is a matrix that rotates about the y-axis by 135 degrees.
1186
1187 >>> transform.matrix
1188 array([[-0.70710678, 0. , 0.70710678, 0. ],
1189 [ 0. , 1. , 0. , 0. ],
1190 [-0.70710678, 0. , -0.70710678, 0. ],
1191 [ 0. , 0. , 0. , 1. ]])
1192
1193 """
1194 transform = axis_angle_rotation((0, 1, 0), angle, deg=True)
1195 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
1196
1197 def rotate_z(
1198 self: Transform,
1199 angle: float,
1200 *,
1201 point: VectorLike[float] | None = None,
1202 multiply_mode: Literal['pre', 'post'] | None = None,
1203 ) -> Transform: # numpydoc ignore=RT01
1204 """Compose a rotation about the z-axis.
1205
1206 Create a matrix for rotation about the z-axis and :meth:`compose`
1207 it with the current transformation :attr:`matrix` according to pre-multiply or
1208 post-multiply semantics.
1209
1210 Internally, the matrix is stored in the :attr:`matrix_list`.
1211
1212 Parameters
1213 ----------
1214 angle : float
1215 Angle in degrees to rotate about the z-axis.
1216
1217 point : VectorLike[float], optional
1218 Point to rotate about. By default, the object's :attr:`point` is used,
1219 but this can be overridden.
1220 If set, two additional transformations are composed and added to
1221 the :attr:`matrix_list`:
1222
1223 - :meth:`translate` to ``point`` before the rotation
1224 - :meth:`translate` away from ``point`` after the rotation
1225
1226 multiply_mode : 'pre' | 'post', optional
1227 Multiplication mode to use when composing the matrix. By default, the
1228 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
1229 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
1230
1231 See Also
1232 --------
1233 rotate_x, rotate_y, rotate_vector, rotate
1234 Similar rotation methods.
1235 rotation_matrix, rotation_axis_angle, as_rotation, has_rotation
1236 Get this transform's rotation component.
1237 pyvista.DataObjectFilters.rotate_z
1238 Rotate a mesh about the z-axis.
1239
1240 Examples
1241 --------
1242 Compose a rotation about the z-axis.
1243
1244 >>> import pyvista as pv
1245 >>> transform = pv.Transform().rotate_z(90)
1246 >>> transform.matrix
1247 array([[ 0., -1., 0., 0.],
1248 [ 1., 0., 0., 0.],
1249 [ 0., 0., 1., 0.],
1250 [ 0., 0., 0., 1.]])
1251
1252 Compose a second rotation about the z-axis.
1253
1254 >>> _ = transform.rotate_z(45)
1255
1256 The result is a matrix that rotates about the z-axis by 135 degrees.
1257
1258 >>> transform.matrix
1259 array([[-0.70710678, -0.70710678, 0. , 0. ],
1260 [ 0.70710678, -0.70710678, 0. , 0. ],
1261 [ 0. , 0. , 1. , 0. ],
1262 [ 0. , 0. , 0. , 1. ]])
1263
1264 """
1265 transform = axis_angle_rotation((0, 0, 1), angle, deg=True)
1266 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
1267
1268 def rotate_vector(
1269 self: Transform,
1270 vector: VectorLike[float],
1271 angle: float,
1272 *,
1273 point: VectorLike[float] | None = None,
1274 multiply_mode: Literal['pre', 'post'] | None = None,
1275 ) -> Transform: # numpydoc ignore=RT01
1276 """Compose a rotation about a vector.
1277
1278 Create a matrix for rotation about the vector and :meth:`compose`
1279 it with the current transformation :attr:`matrix` according to pre-multiply or
1280 post-multiply semantics.
1281
1282 Internally, the matrix is stored in the :attr:`matrix_list`.
1283
1284 Parameters
1285 ----------
1286 vector : VectorLike[float]
1287 Vector to rotate about.
1288
1289 angle : float
1290 Angle in degrees to rotate about the vector.
1291
1292 point : VectorLike[float], optional
1293 Point to rotate about. By default, the object's :attr:`point` is used,
1294 but this can be overridden.
1295 If set, two additional transformations are composed and added to
1296 the :attr:`matrix_list`:
1297
1298 - :meth:`translate` to ``point`` before the rotation
1299 - :meth:`translate` away from ``point`` after the rotation
1300
1301 multiply_mode : 'pre' | 'post', optional
1302 Multiplication mode to use when composing the matrix. By default, the
1303 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
1304 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
1305
1306 See Also
1307 --------
1308 rotate_x, rotate_y, rotate_z, rotate
1309 Similar rotation methods.
1310 rotation_matrix, rotation_axis_angle, as_rotation, has_rotation
1311 Get this transform's rotation component.
1312 pyvista.DataObjectFilters.rotate_vector
1313 Rotate a mesh about a vector.
1314
1315 Examples
1316 --------
1317 Compose a rotation of 30 degrees about the ``(1, 1, 1)`` axis.
1318
1319 >>> import pyvista as pv
1320 >>> transform = pv.Transform().rotate_vector((1, 1, 1), 30)
1321 >>> transform.matrix
1322 array([[ 0.9106836 , -0.24401694, 0.33333333, 0. ],
1323 [ 0.33333333, 0.9106836 , -0.24401694, 0. ],
1324 [-0.24401694, 0.33333333, 0.9106836 , 0. ],
1325 [ 0. , 0. , 0. , 1. ]])
1326
1327 Compose a second rotation of 45 degrees about the ``(1, 2, 3)`` axis.
1328
1329 >>> _ = transform.rotate_vector((1, 2, 3), 45)
1330 >>> transform.matrix
1331 array([[ 0.38042304, -0.50894634, 0.77217351, 0. ],
1332 [ 0.83349512, 0.55045308, -0.04782562, 0. ],
1333 [-0.40070461, 0.66179682, 0.63360933, 0. ],
1334 [ 0. , 0. , 0. , 1. ]])
1335
1336 """
1337 transform = axis_angle_rotation(vector, angle, deg=True)
1338 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
1339
1340 def compose(
1341 self: Transform,
1342 transform: TransformLike,
1343 *,
1344 point: VectorLike[float] | None = None,
1345 multiply_mode: Literal['pre', 'post'] | None = None,
1346 ) -> Transform: # numpydoc ignore=RT01
1347 """Compose a transformation matrix.
1348
1349 Create a 4x4 matrix from any transform-like input and compose it with the
1350 current transformation :attr:`matrix` according to pre-multiply or post-multiply
1351 semantics.
1352
1353 Internally, the matrix is stored in the :attr:`matrix_list`.
1354
1355 Parameters
1356 ----------
1357 transform : TransformLike
1358 Any transform-like input such as a 3x3 or 4x4 array or matrix.
1359
1360 point : VectorLike[float], optional
1361 Point to transform about. By default, the object's :attr:`point` is used,
1362 but this can be overridden.
1363 If set, two additional transformations are composed and added to
1364 the :attr:`matrix_list`:
1365
1366 - :meth:`translate` to ``point`` before the transformation
1367 - :meth:`translate` away from ``point`` after the transformation
1368
1369 .. versionadded:: 0.47
1370
1371 multiply_mode : 'pre' | 'post', optional
1372 Multiplication mode to use when composing the matrix. By default, the
1373 object's :attr:`multiply_mode` is used, but this can be overridden. Set this
1374 to ``'pre'`` for pre-multiplication or ``'post'`` for post-multiplication.
1375
1376 See Also
1377 --------
1378 decompose
1379
1380 Examples
1381 --------
1382 Define an arbitrary 4x4 affine transformation matrix and compose it.
1383
1384 >>> import pyvista as pv
1385 >>> array = [
1386 ... [0.707, -0.707, 0, 0],
1387 ... [0.707, 0.707, 0, 0],
1388 ... [0, 0, 1, 1.5],
1389 ... [0, 0, 0, 2],
1390 ... ]
1391 >>> transform = pv.Transform().compose(array)
1392 >>> transform.matrix
1393 array([[ 0.707, -0.707, 0. , 0. ],
1394 [ 0.707, 0.707, 0. , 0. ],
1395 [ 0. , 0. , 1. , 1.5 ],
1396 [ 0. , 0. , 0. , 2. ]])
1397
1398 Define a second transformation and use ``*`` to compose it.
1399
1400 >>> array = [[1, 0, 0], [0, 0, -1], [0, -1, 0]]
1401 >>> transform = transform * array
1402 >>> transform.matrix
1403 array([[ 0.707, -0.707, 0. , 0. ],
1404 [ 0. , 0. , -1. , -1.5 ],
1405 [-0.707, -0.707, 0. , 0. ],
1406 [ 0. , 0. , 0. , 2. ]])
1407
1408 Compose the transform about a point. Check the :attr:`matrix_list` to see that a
1409 translation is added before and after the transform.
1410
1411 >>> transform = pv.Transform().compose(transform, point=(1, 2, 3))
1412 >>> transform.matrix_list # doctest: +NORMALIZE_WHITESPACE
1413 [array([[ 1., 0., 0., -1.],
1414 [ 0., 1., 0., -2.],
1415 [ 0., 0., 1., -3.],
1416 [ 0., 0., 0., 1.]]),
1417 array([[ 0.707, -0.707, 0. , 0. ],
1418 [ 0. , 0. , -1. , -1.5 ],
1419 [-0.707, -0.707, 0. , 0. ],
1420 [ 0. , 0. , 0. , 2. ]]),
1421 array([[1., 0., 0., 1.],
1422 [0., 1., 0., 2.],
1423 [0., 0., 1., 3.],
1424 [0., 0., 0., 1.]])]
1425
1426
1427 """
1428 return self._compose_with_translations(transform, point=point, multiply_mode=multiply_mode)
1429
1430 def _compose(
1431 self: Transform,
1432 transform: TransformLike,
1433 *,
1434 multiply_mode: Literal['pre', 'post'] | None = None,
1435 ) -> Transform: # numpydoc ignore=RT01
1436 # Make sure we have a vtkTransform
1437 if isinstance(transform, _vtk.vtkTransform):
1438 vtk_transform = transform
1439 else:
1440 array = _validation.validate_transform4x4(
1441 transform, must_be_finite=self.check_finite, name='matrix'
1442 )
1443 vtk_transform = _vtk.vtkTransform()
1444 vtk_transform.SetMatrix(vtkmatrix_from_array(array))
1445
1446 if multiply_mode is not None:
1447 # Override multiply mode
1448 original_mode = self.multiply_mode
1449 self.multiply_mode = multiply_mode
1450
1451 self.Concatenate(vtk_transform)
1452
1453 if multiply_mode is not None:
1454 self.multiply_mode = original_mode
1455
1456 return self
1457
1458 @property
1459 def matrix(self: Transform) -> NumpyArray[float]:
1460 """Return or set the current transformation matrix.
1461
1462 Notes
1463 -----
1464 This matrix is a single 4x4 matrix computed from composing all
1465 transformations. Use :attr:`matrix_list` instead to get a list of the
1466 individual transformations.
1467
1468 See Also
1469 --------
1470 inverse_matrix
1471 Return the inverse of the current transformation.
1472
1473 Returns
1474 -------
1475 NDArray[float]
1476 Current transformation matrix.
1477
1478 """
1479 array = array_from_vtkmatrix(self.GetMatrix())
1480 if self.check_finite:
1481 _validation.check_finite(array, name='matrix')
1482 return array
1483
1484 @matrix.setter
1485 def matrix(self: Transform, trans: TransformLike) -> None:
1486 array = _validation.validate_transform4x4(
1487 trans, must_be_finite=self.check_finite, name='matrix'
1488 )
1489 self.SetMatrix(vtkmatrix_from_array(array))
1490
1491 @property
1492 def inverse_matrix(self: Transform) -> NumpyArray[float]:
1493 """Return the inverse of the current transformation :attr:`~Transform.matrix`.
1494
1495 Notes
1496 -----
1497 This matrix is a single 4x4 matrix computed from composing the inverse of
1498 all transformations. Use :attr:`inverse_matrix_list` instead to get a list of
1499 the individual inverse transformations.
1500
1501 See Also
1502 --------
1503 matrix
1504 Return the current transformation matrix.
1505
1506 Returns
1507 -------
1508 NDArray[float]
1509 Current inverse transformation matrix.
1510
1511 """
1512 array = array_from_vtkmatrix(self.GetInverse().GetMatrix()) # type: ignore[attr-defined]
1513 if self.check_finite:
1514 _validation.check_finite(array, name='matrix')
1515 return array
1516
1517 @property
1518 def matrix_list(self: Transform) -> list[NumpyArray[float]]:
1519 """Return a list of all current transformation matrices.
1520
1521 Notes
1522 -----
1523 The list comprises all 4x4 transformation matrices. Use :attr:`matrix` instead
1524 to get the composed result as a single 4x4 matrix.
1525
1526 See Also
1527 --------
1528 inverse_matrix_list
1529 Return the current transformation matrix.
1530
1531 Returns
1532 -------
1533 list[NDArray[float]]
1534 List of all current transformation matrices.
1535
1536 """
1537 return [
1538 array_from_vtkmatrix(self.GetConcatenatedTransform(i).GetMatrix())
1539 for i in range(self.n_transformations)
1540 ]
1541
1542 @property
1543 def inverse_matrix_list(self: Transform) -> list[NumpyArray[float]]:
1544 """Return a list of all inverse transformations applied by this :class:`Transform`.
1545
1546 Notes
1547 -----
1548 The list comprises all 4x4 inverse transformation matrices. Use
1549 :attr:`inverse_matrix` instead to get the composed result as a single
1550 4x4 matrix.
1551
1552 See Also
1553 --------
1554 matrix_list
1555 Return a list of all transformation matrices.
1556
1557 Returns
1558 -------
1559 list[NDArray[float]]
1560 List of all current inverse transformation matrices.
1561
1562 """
1563 return [
1564 array_from_vtkmatrix(self.GetConcatenatedTransform(i).GetInverse().GetMatrix()) # type: ignore[attr-defined]
1565 for i in range(self.n_transformations)
1566 ]
1567
1568 @property
1569 def n_transformations(self: Transform) -> int: # numpydoc ignore: RT01
1570 """Return the current number of composed transformations."""
1571 return self.GetNumberOfConcatenatedTransforms()
1572
1573 @overload
1574 def apply(
1575 self: Transform,
1576 obj: VectorLike[float] | MatrixLike[float],
1577 /,
1578 mode: Literal['points', 'vectors'] | None = ...,
1579 *,
1580 inverse: bool = ...,
1581 copy: bool = ...,
1582 ) -> NumpyArray[float]: ...
1583 @overload
1584 def apply(
1585 self: Transform,
1586 obj: _DataSetOrMultiBlockType,
1587 /,
1588 mode: Literal['active_vectors', 'all_vectors'] = ...,
1589 *,
1590 inverse: bool = ...,
1591 copy: bool = ...,
1592 ) -> _DataSetOrMultiBlockType: ...
1593 @overload
1594 def apply(
1595 self: Transform,
1596 obj: Prop3D,
1597 /,
1598 mode: Literal['replace', 'pre-multiply', 'post-multiply'] = ...,
1599 *,
1600 inverse: bool = ...,
1601 copy: bool = ...,
1602 ) -> Prop3D: ...
1603 def apply(
1604 self: Transform,
1605 obj: VectorLike[float] | MatrixLike[float] | DataSet | MultiBlock | Prop3D,
1606 /,
1607 mode: Literal[
1608 'points',
1609 'vectors',
1610 'active_vectors',
1611 'all_vectors',
1612 'replace',
1613 'pre-multiply',
1614 'post-multiply',
1615 ]
1616 | None = None,
1617 *,
1618 inverse: bool = False,
1619 copy: bool = True,
1620 ):
1621 """Apply the current transformation :attr:`~Transform.matrix` to points, vectors, a dataset, or actor.
1622
1623 .. note::
1624
1625 Points with integer values are cast to a float type before the
1626 transformation is applied. A similar casting is also performed when
1627 transforming datasets. See also the notes at
1628 :func:`~pyvista.DataObjectFilters.transform`
1629 which is used by this filter under the hood.
1630
1631 Parameters
1632 ----------
1633 obj : VectorLike[float] | MatrixLike[float] | DataSet | MultiBlock | Prop3D
1634 Object to apply the transformation to.
1635
1636 mode : str, optional
1637 Define how to apply the transformation. Different modes may be used depending
1638 on the input type.
1639
1640 #. For array inputs:
1641
1642 - ``'points'`` transforms point arrays.
1643 - ``'vectors'`` transforms vector arrays. The translation component of
1644 the transformation is removed for vectors.
1645
1646 By default, ``'points'`` mode is used for array inputs.
1647
1648 #. For dataset inputs:
1649
1650 The dataset's points are always transformed, and its vectors are
1651 transformed based on the mode:
1652
1653 - ``'active_vectors'`` transforms active normals and active vectors
1654 arrays only.
1655 - ``'all_vectors'`` transforms `all` input vectors, i.e. all arrays
1656 with three components. This mode is equivalent to setting
1657 ``transform_all_input_vectors=True``
1658 with :meth:`pyvista.DataObjectFilters.transform`.
1659
1660 By default, only ``'active_vectors'`` are transformed.
1661
1662 #. For actor inputs:
1663
1664 - ``'pre-multiply'`` pre-multiplies this transform with the actor's
1665 :attr:`~pyvista.Prop3D.user_matrix`.
1666 - ``'post-multiply'`` post-multiplies this transform with the actor's
1667 user-matrix.
1668 - ``'replace'`` replaces the actor's user-matrix with this transform's
1669 :attr:`matrix`.
1670
1671 By default, ``'post-multiply'`` mode is used for actors.
1672
1673 inverse : bool, default: False
1674 Apply the transformation using the :attr:`inverse_matrix` instead of the
1675 :attr:`matrix`.
1676
1677 copy : bool, default: True
1678 Return a copy of the input with the transformation applied. Set this to
1679 ``False`` to transform the input directly and return it. Setting this to
1680 ``False`` only applies to NumPy float arrays, datasets, and actors; a copy
1681 is always returned for tuple and list inputs or arrays with integers.
1682
1683 Returns
1684 -------
1685 output : np.ndarray | DataSet | MultiBlock | Prop3D
1686 Transformed array, dataset, or actor.
1687
1688 See Also
1689 --------
1690 apply_to_points
1691 Equivalent to ``apply(obj, 'points')`` for point-array inputs.
1692 apply_to_vectors
1693 Equivalent to ``apply(obj, 'vectors')`` for vector-array inputs.
1694 apply_to_dataset
1695 Equivalent to ``apply(obj, mode)`` for dataset inputs where ``mode`` may be
1696 ``'active_vectors'`` or ``'all_vectors'``.
1697 apply_to_actor
1698 Equivalent to ``apply(obj, mode)`` for actor inputs where ``mode`` may be
1699 ``'pre-multiply'``, ``'post-multiply'``, or ``'replace'``.
1700 pyvista.DataObjectFilters.transform
1701 Transform a dataset.
1702 pyvista.Prop3D.transform
1703 Transform an actor.
1704
1705 Examples
1706 --------
1707 Apply a transformation to a point.
1708
1709 >>> import numpy as np
1710 >>> import pyvista as pv
1711 >>> point = (1.0, 2.0, 3.0)
1712 >>> transform = pv.Transform().scale(2).translate((0.0, 0.0, 1.0))
1713 >>> transformed = transform.apply(point)
1714 >>> transformed
1715 array([2., 4., 7.])
1716
1717 Apply a transformation to a points array.
1718
1719 >>> array = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
1720 >>> transformed = transform.apply(array)
1721 >>> transformed
1722 array([[ 2., 4., 7.],
1723 [ 8., 10., 13.]])
1724
1725 Apply a transformation to a vector array. Use the same array as before but
1726 use the ``'vectors'`` mode. Note how the translation component is not applied
1727 to vectors.
1728
1729 >>> transformed = transform.apply(array, 'vectors')
1730 >>> transformed
1731 array([[ 2., 4., 6.],
1732 [ 8., 10., 12.]])
1733
1734 Apply a transformation to a dataset.
1735
1736 >>> dataset = pv.PolyData(array)
1737 >>> transformed = transform.apply(dataset)
1738 >>> transformed.points
1739 pyvista_ndarray([[ 2., 4., 6.],
1740 [ 8., 10., 12.]])
1741
1742 Apply the inverse.
1743
1744 >>> transformed = transform.apply(dataset, inverse=True)
1745 >>> transformed.points
1746 pyvista_ndarray([[0.5, 1. , 1. ],
1747 [2. , 2.5, 2.5]])
1748
1749 Apply a transformation to an actor.
1750
1751 >>> actor = pv.Actor()
1752 >>> transformed_actor = transform.apply(actor)
1753 >>> transformed_actor.user_matrix
1754 array([[2., 0., 0., 0.],
1755 [0., 2., 0., 0.],
1756 [0., 0., 2., 0.],
1757 [0., 0., 0., 1.]])
1758
1759 """ # noqa: E501
1760
1761 def _check_mode(kind: str, mode_: str | None, allowed_modes: list[str | None]) -> None:
1762 if mode_ not in allowed_modes:
1763 msg = (
1764 f"Transformation mode '{mode_}' is not supported for {kind}. "
1765 'Mode must be one of'
1766 f'\n{allowed_modes}'
1767 )
1768 raise ValueError(msg)
1769
1770 _validation.check_contains(
1771 [
1772 'points',
1773 'vectors',
1774 'active_vectors',
1775 'all_vectors',
1776 'replace',
1777 'pre-multiply',
1778 'post-multiply',
1779 None,
1780 ],
1781 must_contain=mode,
1782 name='mode',
1783 )
1784 _validation.check_instance(
1785 obj,
1786 (
1787 np.ndarray,
1788 Sequence,
1789 pv.DataSet,
1790 pv.MultiBlock,
1791 pv.Prop3D,
1792 ),
1793 )
1794
1795 inplace = not copy
1796 # Transform dataset
1797 if isinstance(obj, (pv.DataSet, pv.MultiBlock)):
1798 allowed = ['active_vectors', 'all_vectors', None]
1799 _check_mode('datasets', mode, allowed)
1800 if mode in ['active_vectors', None]:
1801 mode = None
1802
1803 return obj.transform(
1804 self.copy().invert() if inverse else self,
1805 inplace=inplace,
1806 transform_all_input_vectors=bool(mode),
1807 )
1808
1809 matrix = self.inverse_matrix if inverse else self.matrix
1810
1811 # Transform actor
1812 if isinstance(obj, pv.Prop3D):
1813 allowed = ['replace', 'pre-multiply', 'post-multiply', None]
1814 _check_mode('actors', mode, allowed)
1815 if mode in ['post-multiply', None]:
1816 return obj.transform(matrix, 'post', inplace=inplace)
1817 elif mode == 'pre-multiply':
1818 return obj.transform(matrix, 'pre', inplace=inplace)
1819 else:
1820 actor = obj.copy() if copy else obj
1821 actor.user_matrix = matrix
1822 return actor
1823
1824 # Transform array
1825 allowed = ['points', 'vectors', None]
1826 _check_mode('arrays', mode, allowed)
1827
1828 if mode == 'vectors':
1829 # Remove translation
1830 matrix[:3, 3] = 0
1831
1832 # Validate array - make sure we have floats
1833 array: NumpyArray[float] = _validation.validate_array(obj, must_have_shape=[(3,), (-1, 3)])
1834 array = array if np.issubdtype(array.dtype, np.floating) else array.astype(float)
1835
1836 # Transform a 1D array
1837 out: NumpyArray[float] | None
1838 if array.shape == (3,):
1839 out = (matrix @ (*array, 1))[:3]
1840 if inplace:
1841 array[:] = out
1842 out = array
1843 return out
1844
1845 # Transform a 2D array
1846 out = apply_transformation_to_points(matrix, array, inplace=inplace)
1847 return out if out is not None else array
1848
1849 def apply_to_points(
1850 self,
1851 points: VectorLike[float] | MatrixLike[float],
1852 /,
1853 *,
1854 inverse: bool = False,
1855 copy: bool = True,
1856 ) -> NumpyArray[float]:
1857 """Apply the current transformation :attr:`~Transform.matrix` to a point or points.
1858
1859 This is equivalent to ``apply(points, 'points')``. See :meth:`apply` for
1860 details and examples.
1861
1862 Parameters
1863 ----------
1864 points : VectorLike[float] | MatrixLike[float]
1865 Single point or ``Nx3`` points array to apply the transformation to.
1866
1867 inverse : bool, default: False
1868 Apply the transformation using the :attr:`inverse_matrix` instead of the
1869 :attr:`matrix`.
1870
1871 copy : bool, default: True
1872 Return a copy of the input with the transformation applied. Set this to
1873 ``False`` to transform the input directly and return it. Only applies to
1874 NumPy arrays. A copy is always returned for tuple and list
1875 inputs or point arrays with integers.
1876
1877 Returns
1878 -------
1879 np.ndarray
1880 Transformed points.
1881
1882 See Also
1883 --------
1884 apply
1885 Apply this transformation to any input.
1886 apply_to_vectors
1887 Apply this transformation to vectors.
1888 apply_to_dataset
1889 Apply this transformation to a dataset.
1890 apply_to_actor
1891 Apply this transformation to an actor.
1892
1893 """
1894 return self.apply(points, 'points', inverse=inverse, copy=copy)
1895
1896 def apply_to_vectors(
1897 self,
1898 vectors: VectorLike[float] | MatrixLike[float],
1899 /,
1900 *,
1901 inverse: bool = False,
1902 copy: bool = True,
1903 ) -> NumpyArray[float]:
1904 """Apply the current transformation :attr:`~Transform.matrix` to a vector or vectors.
1905
1906 This is equivalent to ``apply(vectors, 'vectors')``. See :meth:`apply` for
1907 details and examples.
1908
1909 Parameters
1910 ----------
1911 vectors : VectorLike[float] | MatrixLike[float]
1912 Single vector or ``Nx3`` vectors array to apply the transformation to.
1913
1914 inverse : bool, default: False
1915 Apply the transformation using the :attr:`inverse_matrix` instead of the
1916 :attr:`matrix`.
1917
1918 copy : bool, default: True
1919 Return a copy of the input with the transformation applied. Set this to
1920 ``False`` to transform the input directly and return it. Only applies to
1921 NumPy arrays. A copy is always returned for tuple and list
1922 inputs or point arrays with integers.
1923
1924 Returns
1925 -------
1926 np.ndarray
1927 Transformed vectors.
1928
1929 See Also
1930 --------
1931 apply
1932 Apply this transformation to any input.
1933 apply_to_points
1934 Apply this transformation to points.
1935 apply_to_dataset
1936 Apply this transformation to a dataset.
1937 apply_to_actor
1938 Apply this transformation to an actor.
1939
1940 """
1941 return self.apply(vectors, 'vectors', inverse=inverse, copy=copy)
1942
1943 def apply_to_dataset(
1944 self,
1945 dataset: _DataSetOrMultiBlockType,
1946 /,
1947 mode: Literal['active_vectors', 'all_vectors'] = 'active_vectors',
1948 *,
1949 copy: bool = True,
1950 inverse: bool = False,
1951 ) -> _DataSetOrMultiBlockType:
1952 """Apply the current transformation :attr:`~Transform.matrix` to a dataset.
1953
1954 This is equivalent to ``apply(dataset, mode)``. See :meth:`apply` for details
1955 and examples.
1956
1957 Parameters
1958 ----------
1959 dataset : DataSet | MultiBlock
1960 Object to apply the transformation to.
1961
1962 mode : 'active_vectors' | 'all_vectors', default: 'active_vectors'
1963 Mode for transforming the dataset's vectors:
1964
1965 - ``'active_vectors'`` transforms active normals and active vectors arrays
1966 only.
1967 - ``'all_vectors'`` transforms `all` input vectors, i.e. all arrays with
1968 three components. This mode is equivalent to setting
1969 ``transform_all_input_vectors=True``
1970 with :meth:`pyvista.DataObjectFilters.transform`.
1971
1972 inverse : bool, default: False
1973 Apply the transformation using the :attr:`inverse_matrix` instead of the
1974 :attr:`matrix`.
1975
1976 copy : bool, default: True
1977 Return a copy of the input with the transformation applied. Set this to
1978 ``False`` to transform the input directly and return it.
1979
1980 Returns
1981 -------
1982 output : DataSet | MultiBlock
1983 Transformed dataset.
1984
1985 See Also
1986 --------
1987 apply
1988 Apply this transformation to any input.
1989 apply_to_points
1990 Apply this transformation to points.
1991 apply_to_vectors
1992 Apply this transformation to vectors.
1993 apply_to_actor
1994 Apply this transformation to an actor.
1995 pyvista.DataObjectFilters.transform
1996 Transform a dataset.
1997
1998 """
1999 return self.apply(dataset, mode, inverse=inverse, copy=copy)
2000
2001 def apply_to_actor(
2002 self,
2003 actor: Prop3D,
2004 /,
2005 mode: Literal['pre-multiply', 'post-multiply', 'replace'] = 'post-multiply',
2006 *,
2007 copy: bool = True,
2008 inverse: bool = False,
2009 ) -> Prop3D:
2010 """Apply the current transformation :attr:`~Transform.matrix` to an actor.
2011
2012 This is equivalent to ``apply(actor, mode)``. See :meth:`apply` for details and
2013 examples.
2014
2015 Parameters
2016 ----------
2017 actor : Prop3D
2018 Actor to apply the transformation to.
2019
2020 mode : 'pre-multiply', 'post-multiply', 'replace', default: 'post-multiply'
2021 Mode for transforming the actor:
2022
2023 - ``'pre-multiply'`` pre-multiplies this transform with the actor's
2024 :attr:`~pyvista.Prop3D.user_matrix`.
2025 - ``'post-multiply'`` post-multiplies this transform with the actor's
2026 user-matrix.
2027 - ``'replace'`` replaces the actor's user-matrix with this transform's
2028 :attr:`matrix`.
2029
2030 By default, ``'post-multiply'`` mode is used.
2031
2032 inverse : bool, default: False
2033 Apply the transformation using the :attr:`inverse_matrix` instead of the
2034 :attr:`matrix`.
2035
2036 copy : bool, default: True
2037 Return a copy of the input with the transformation applied. Set this to
2038 ``False`` to transform the input directly and return it.
2039
2040 Returns
2041 -------
2042 Prop3D
2043 Transformed actor.
2044
2045 See Also
2046 --------
2047 apply
2048 Apply this transformation to any input.
2049 apply_to_points
2050 Apply this transformation to points.
2051 apply_to_vectors
2052 Apply this transformation to vectors.
2053 apply_to_dataset
2054 Apply this transformation to a dataset.
2055 pyvista.Prop3D.transform
2056 Transform an actor.
2057
2058 """
2059 return self.apply(actor, mode, inverse=inverse, copy=copy)
2060
2061 def decompose(self: Transform, *, homogeneous: bool = False) -> _FiveArrays:
2062 """Decompose the current transformation into its components.
2063
2064 Decompose the :attr:`matrix` ``M`` into
2065
2066 - translation ``T``
2067 - rotation ``R``
2068 - reflection ``N``
2069 - scaling ``S``
2070 - shearing ``K``
2071
2072 such that, when represented as 4x4 matrices, ``M = TRNSK``. The decomposition is
2073 unique and is computed with polar matrix decomposition.
2074
2075 By default, compact representations of the transformations are returned (e.g. as a
2076 3-element vector or a 3x3 matrix). Optionally, 4x4 matrices may be returned instead.
2077
2078 .. note::
2079
2080 - The rotation is orthonormal and right-handed with positive determinant.
2081 - The scaling factors are positive.
2082 - The reflection is either ``1`` (no reflection) or ``-1`` (has reflection)
2083 and can be used like a scaling factor.
2084
2085 Parameters
2086 ----------
2087 homogeneous : bool, default: False
2088 If ``True``, return the components (translation, rotation, etc.) as 4x4
2089 homogeneous matrices. By default, reflection is a scalar, translation and
2090 scaling are length-3 vectors, and rotation and shear are 3x3 matrices.
2091
2092 Returns
2093 -------
2094 numpy.ndarray
2095 Translation component ``T``. Returned as a 3-element vector (or a 4x4
2096 translation matrix if ``homogeneous`` is ``True``).
2097
2098 numpy.ndarray
2099 Rotation component ``R``. Returned as a 3x3 orthonormal rotation matrix of row
2100 vectors (or a 4x4 rotation matrix if ``homogeneous`` is ``True``).
2101
2102 numpy.ndarray
2103 Reflection component ``N``. Returned as a NumPy scalar (or a 4x4 reflection
2104 matrix if ``homogeneous`` is ``True``).
2105
2106 numpy.ndarray
2107 Scaling component ``S``. Returned as a 3-element vector (or a 4x4 scaling matrix
2108 if ``homogeneous`` is ``True``).
2109
2110 numpy.ndarray
2111 Shear component ``K``. Returned as a 3x3 matrix with ones on the diagonal and
2112 shear values in the off-diagonals (or as a 4x4 shearing matrix if ``homogeneous``
2113 is ``True``).
2114
2115 See Also
2116 --------
2117 compose
2118 Compose a transformation.
2119
2120 translation, has_translation
2121 Get info about this transform's translation component.
2122
2123 rotation_matrix, rotation_axis_angle, as_rotation, has_rotation
2124 Get info about this transform's rotation component.
2125
2126 reflection, has_reflection
2127 Get info about this transform's reflection component.
2128
2129 scale_factors, has_scale
2130 Get info about this transform's scale component.
2131
2132 shear_matrix, has_shear
2133 Get info about this transform's shear component.
2134
2135 Examples
2136 --------
2137 Create a transform by composing scaling, rotation, and translation
2138 matrices.
2139
2140 >>> import numpy as np
2141 >>> import pyvista as pv
2142 >>> transform = pv.Transform()
2143 >>> _ = transform.scale(1, 2, 3)
2144 >>> _ = transform.rotate_z(90)
2145 >>> _ = transform.translate(4, 5, 6)
2146 >>> transform
2147 Transform (...)
2148 Num Transformations: 3
2149 Matrix: [[ 0., -2., 0., 4.],
2150 [ 1., 0., 0., 5.],
2151 [ 0., 0., 3., 6.],
2152 [ 0., 0., 0., 1.]]
2153
2154 Decompose the matrix.
2155
2156 >>> T, R, N, S, K = transform.decompose()
2157
2158 Since the input has no shear this component is the identity matrix.
2159 Similarly, there are no reflections so its value is ``1``. All other components
2160 are recovered perfectly and match the input.
2161
2162 >>> K # shear
2163 array([[1., 0., 0.],
2164 [0., 1., 0.],
2165 [0., 0., 1.]])
2166
2167 >>> S # scale
2168 array([1., 2., 3.])
2169
2170 >>> N # reflection
2171 array(1.)
2172
2173 >>> R # rotation
2174 array([[ 0., -1., 0.],
2175 [ 1., 0., 0.],
2176 [ 0., 0., 1.]])
2177
2178 >>> T # translation
2179 array([4., 5., 6.])
2180
2181 Compose a shear component using pre-multiplication so that shearing is
2182 the first transformation.
2183
2184 >>> shear = np.eye(4)
2185 >>> shear[0, 1] = 0.1 # xy shear
2186 >>> _ = transform.compose(shear, multiply_mode='pre')
2187
2188 Repeat the decomposition and show its components. Note how the decomposed shear
2189 does not perfectly match the input shear matrix values. The values of the
2190 scaling and rotation components are also affected and do not exactly match the
2191 input. This is expected, because the shear can be partially factored as a
2192 combination of rotation and scaling.
2193
2194 >>> T, R, N, S, K = transform.decompose()
2195
2196 >>> K # shear
2197 array([[1. , 0.03333333, 0. ],
2198 [0.01663894, 1. , 0. ],
2199 [0. , 0. , 1. ]])
2200
2201 >>> S # scale
2202 array([0.99944491, 2.0022213 , 3. ])
2203
2204 >>> N # reflection
2205 array(1.)
2206
2207 >>> R # rotation
2208 array([[ 0.03331483, -0.99944491, 0. ],
2209 [ 0.99944491, 0.03331483, 0. ],
2210 [ 0. , 0. , 1. ]])
2211
2212 >>> T # translation
2213 array([4., 5., 6.])
2214
2215 Although the values may not match the input exactly, the decomposition is
2216 nevertheless valid and can be used to re-compose the original transformation.
2217
2218 >>> T, R, N, S, K = transform.decompose(homogeneous=True)
2219 >>> T @ R @ N @ S @ K
2220 array([[-5.76153045e-17, -2.00000000e+00, 0.00000000e+00,
2221 4.00000000e+00],
2222 [ 1.00000000e+00, 1.00000000e-01, 0.00000000e+00,
2223 5.00000000e+00],
2224 [ 0.00000000e+00, 0.00000000e+00, 3.00000000e+00,
2225 6.00000000e+00],
2226 [ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00,
2227 1.00000000e+00]])
2228
2229 Alternatively, re-compose the transformation as a new
2230 :class:`~pyvista.Transform` with pre-multiplication.
2231
2232 >>> recomposed = pv.Transform([T, R, N, S, K], multiply_mode='pre')
2233 >>> np.allclose(recomposed.matrix, transform.matrix)
2234 True
2235
2236 Compose a reflection and decompose the transform again.
2237
2238 >>> _ = transform.flip_x()
2239 >>> T, R, N, S, K = transform.decompose()
2240
2241 The reflection component is now ``-1``.
2242
2243 >>> N # reflection
2244 array(-1.)
2245
2246 The decomposition may be simplified to a ``TRSK`` decomposition by combining
2247 the reflection component with either the rotation or the scaling term.
2248
2249 Multiplying the reflection with the rotation will make it a left-handed rotation
2250 with negative determinant:
2251
2252 >>> R = R * N
2253 >>> np.linalg.det(R) < 0
2254 np.True_
2255
2256 Alternatively, keep the rotation right-handed but make the scaling factors negative:
2257
2258 >>> S = S * N
2259 >>> S # scale
2260 array([-0.99944491, -2.0022213 , -3. ])
2261
2262 """
2263 if (current_mtime := self.GetMTime()) != self._decomposition_mtime:
2264 # Recompute and cache
2265 self._decomposition_cache = decomposition(self.matrix, homogeneous=False)
2266 self._decomposition_mtime = current_mtime
2267
2268 cache = cast('_FiveArrays', self._decomposition_cache)
2269 if homogeneous:
2270 return _decomposition_as_homogeneous(*cache)
2271 return cache
2272
2273 def invert(self: Transform) -> Transform: # numpydoc ignore: RT01
2274 """Invert the current transformation.
2275
2276 The current transformation :attr:`matrix` (including all matrices in the
2277 :attr:`matrix_list`) is inverted every time :meth:`invert` is called.
2278
2279 Use :attr:`is_inverted` to check if the transformations are currently inverted.
2280
2281 Examples
2282 --------
2283 Compose an arbitrary transformation.
2284
2285 >>> import pyvista as pv
2286 >>> transform = pv.Transform().scale(2.0)
2287 >>> transform.matrix
2288 array([[2., 0., 0., 0.],
2289 [0., 2., 0., 0.],
2290 [0., 0., 2., 0.],
2291 [0., 0., 0., 1.]])
2292
2293 Check if the transformation is inverted.
2294
2295 >>> transform.is_inverted
2296 False
2297
2298 Invert the transformation and show the matrix.
2299
2300 >>> _ = transform.invert()
2301 >>> transform.matrix
2302 array([[0.5, 0. , 0. , 0. ],
2303 [0. , 0.5, 0. , 0. ],
2304 [0. , 0. , 0.5, 0. ],
2305 [0. , 0. , 0. , 1. ]])
2306
2307 Check that the transformation is inverted.
2308
2309 >>> transform.is_inverted
2310 True
2311
2312 Invert it again to restore it back to its original state.
2313
2314 >>> _ = transform.invert()
2315 >>> transform.matrix
2316 array([[2., 0., 0., 0.],
2317 [0., 2., 0., 0.],
2318 [0., 0., 2., 0.],
2319 [0., 0., 0., 1.]])
2320 >>> transform.is_inverted
2321 False
2322
2323 """
2324 self.Inverse()
2325 return self
2326
2327 def identity(self: Transform) -> Transform: # numpydoc ignore: RT01
2328 """Set the transformation to the identity transformation.
2329
2330 This can be used to "reset" the transform.
2331
2332 Examples
2333 --------
2334 Compose an arbitrary transformation.
2335
2336 >>> import pyvista as pv
2337 >>> transform = pv.Transform().scale(2.0)
2338 >>> transform.matrix
2339 array([[2., 0., 0., 0.],
2340 [0., 2., 0., 0.],
2341 [0., 0., 2., 0.],
2342 [0., 0., 0., 1.]])
2343
2344 Reset the transformation to the identity matrix.
2345
2346 >>> _ = transform.identity()
2347 >>> transform.matrix
2348 array([[1., 0., 0., 0.],
2349 [0., 1., 0., 0.],
2350 [0., 0., 1., 0.],
2351 [0., 0., 0., 1.]])
2352
2353 """
2354 self.Identity()
2355 return self
2356
2357 @property
2358 def is_inverted(self: Transform) -> bool: # numpydoc ignore: RT01
2359 """Get the inverse flag of the transformation.
2360
2361 This flag is modified whenever :meth:`invert` is called.
2362 """
2363 return bool(self.GetInverseFlag())
2364
2365 def _compose_with_translations(
2366 self: Transform,
2367 transform: TransformLike,
2368 point: VectorLike[float] | None = None,
2369 multiply_mode: Literal['pre', 'post'] | None = None,
2370 ) -> Transform:
2371 translate_before, translate_after = self._get_point_translations(
2372 point=point, multiply_mode=multiply_mode
2373 )
2374 if translate_before:
2375 self._compose(translate_before, multiply_mode=multiply_mode)
2376
2377 self._compose(transform, multiply_mode=multiply_mode)
2378
2379 if translate_after:
2380 self._compose(translate_after, multiply_mode=multiply_mode)
2381
2382 return self
2383
2384 def _get_point_translations(
2385 self: Transform,
2386 point: VectorLike[float] | None,
2387 multiply_mode: Literal['pre', 'post'] | None,
2388 ) -> tuple[None | Transform, None | Transform]:
2389 point = point if point is not None else self.point
2390 if point is not None:
2391 point_array = _validation.validate_array3(point, dtype_out=float, name='point')
2392 translate_away = Transform().translate(-point_array)
2393 translate_toward = Transform().translate(point_array)
2394 if multiply_mode == 'post' or (
2395 multiply_mode is None and self._multiply_mode == 'post'
2396 ):
2397 return translate_away, translate_toward
2398 else:
2399 return translate_toward, translate_away
2400 return None, None
2401
2402 @property
2403 def check_finite(self: Transform) -> bool: # numpydoc ignore: RT01
2404 """Check that the :attr:`~Transform.matrix` and :attr:`~Transform.inverse_matrix` have finite values.
2405
2406 If ``True``, all transformations are checked to ensure they only contain
2407 finite values (i.e. no ``NaN`` or ``Inf`` values) and a ``ValueError`` is raised
2408 otherwise. This is useful to catch cases where the transformation(s) are poorly
2409 defined and/or are numerically unstable.
2410
2411 This flag is enabled by default.
2412 """ # noqa: E501
2413 return self._check_finite
2414
2415 @check_finite.setter
2416 def check_finite(self: Transform, value: bool) -> None:
2417 self._check_finite = bool(value)
2418
2419 @property
2420 def translation(self) -> tuple[float, float, float]: # numpydoc ignore=RT01
2421 """Return the translation component of the current transformation :attr:`~Transform.matrix`.
2422
2423 .. versionadded:: 0.47
2424
2425 See Also
2426 --------
2427 has_translation, translate, decompose
2428
2429 Examples
2430 --------
2431 Compose a translation and get the translation component.
2432
2433 >>> import pyvista as pv
2434 >>> trans = pv.Transform() + (1, 2, 3)
2435 >>> trans.translation
2436 (1.0, 2.0, 3.0)
2437
2438 Compose a second translation and get the component again.
2439
2440 >>> trans += (4, 5, 6)
2441 >>> trans.translation
2442 (5.0, 7.0, 9.0)
2443
2444 """ # noqa: E501
2445 return self.GetPosition()
2446
2447 @property
2448 def rotation_axis_angle(
2449 self,
2450 ) -> tuple[tuple[float, float, float], float]: # numpydoc ignore=RT01
2451 """Return the rotation component of the current transformation :attr:`~Transform.matrix` as a vector and angle.
2452
2453 .. versionadded:: 0.47
2454
2455 See Also
2456 --------
2457 has_rotation, rotation_matrix, rotate_vector, as_rotation, decompose
2458
2459 Examples
2460 --------
2461 Compose a rotation from a vector and angle.
2462
2463 >>> import pyvista as pv
2464 >>> trans = pv.Transform().rotate_vector((1, 2, 3), 30)
2465
2466 Get the rotation axis and angle.
2467
2468 >>> axis, angle = trans.rotation_axis_angle
2469 >>> axis
2470 (0.2672, 0.5345, 0.8017)
2471 >>> angle
2472 30.0
2473
2474 Compose a second rotation around the same axis and get the axis and angle again.
2475
2476 >>> _ = trans.rotate_vector((1, 2, 3), 40)
2477 >>> axis, angle = trans.rotation_axis_angle
2478 >>> axis
2479 (0.2672, 0.5345, 0.8017)
2480 >>> angle
2481 70.0
2482
2483 """ # noqa: E501
2484 # Decompose first to ensure we have a proper rotation
2485 _, R, _, _, _ = self.decompose()
2486 wxyz = Transform(R).GetOrientationWXYZ()
2487 return wxyz[1:4], wxyz[0]
2488
2489 @property
2490 def rotation_matrix(self) -> NumpyArray[float]: # numpydoc ignore=RT01
2491 """Return the rotation component of the current transformation :attr:`~Transform.matrix` as a 3x3 matrix.
2492
2493 The rotation is orthonormal and right-handed with positive determinant.
2494
2495 .. versionadded:: 0.47
2496
2497 See Also
2498 --------
2499 has_rotation, rotation_axis_angle, rotate, as_rotation, decompose
2500
2501 Examples
2502 --------
2503 Compose a rotation about the z-axis.
2504
2505 >>> import pyvista as pv
2506 >>> trans = pv.Transform().rotate_z(90)
2507
2508 Get the rotation matrix.
2509
2510 >>> trans.rotation_matrix
2511 array([[ 0., -1., 0.],
2512 [ 1., 0., 0.],
2513 [ 0., 0., 1.]])
2514
2515 Compose a second rotation and get the rotation matrix again.
2516
2517 >>> _ = trans.rotate_y(-90)
2518 >>> trans.rotation_matrix
2519 array([[ 0., 0., -1.],
2520 [ 1., 0., 0.],
2521 [ 0., -1., 0.]])
2522
2523 """ # noqa: E501
2524 _, R, _, _, _ = self.decompose()
2525 return R
2526
2527 @property
2528 def reflection(self) -> Literal[1, -1]: # numpydoc ignore=RT01
2529 """Return the reflection component of the current transformation :attr:`~Transform.matrix` as an integer.
2530
2531 ``1`` is returned if there is no reflection, and ``-1`` is returned if there
2532 is a reflection.
2533
2534 See Also
2535 --------
2536 has_reflection, reflect, decompose
2537
2538 Examples
2539 --------
2540 Create a transform and get its reflection.
2541
2542 >>> import pyvista as pv
2543 >>> trans = pv.Transform()
2544 >>> trans.reflection
2545 1
2546
2547 Compose a reflection about the x-axis and get the reflection again.
2548
2549 >>> _ = trans.flip_x()
2550 >>> trans.reflection
2551 -1
2552
2553 Compose a second reflection and get the reflection again.
2554
2555 >>> _ = trans.flip_y()
2556 >>> trans.reflection
2557 1
2558
2559 """ # noqa: E501
2560 _, _, N, _, _ = self.decompose()
2561 return N.astype(int).tolist()
2562
2563 @property
2564 def scale_factors(self) -> tuple[float, float, float]: # numpydoc ignore=RT01
2565 """Return the scaling component of the current transformation :attr:`~Transform.matrix`.
2566
2567 The scaling factors are always positive.
2568
2569 .. versionadded:: 0.47
2570
2571 See Also
2572 --------
2573 has_scale, scale, decompose
2574
2575 Examples
2576 --------
2577 Compose a scale matrix and get the scale factors.
2578
2579 >>> import pyvista as pv
2580 >>> trans = pv.Transform() * (1, 2, 3)
2581 >>> trans.scale_factors
2582 (1.0, 2.0, 3.0)
2583
2584 Compose a second scale matrix and get the factors again.
2585
2586 >>> trans *= (4, 5, 6)
2587 >>> trans.scale_factors
2588 (4.0, 10.0, 18.0)
2589
2590 """
2591 # Use PyVista's decompose instead of vtk's GetScale() method
2592 _, _, _, S, _ = self.decompose()
2593 return tuple(S.tolist())
2594
2595 @property
2596 def shear_matrix(self) -> NumpyArray[float]: # numpydoc ignore=RT01
2597 """Return the shear component of the current transformation :attr:`~Transform.matrix` as a 3x3 matrix.
2598
2599 .. versionadded:: 0.47
2600
2601 See Also
2602 --------
2603 has_shear, compose, decompose
2604
2605 Examples
2606 --------
2607 Compose a symmetric shear matrix.
2608
2609 >>> import numpy as np
2610 >>> import pyvista as pv
2611 >>> shear = np.eye(4)
2612 >>> shear[0, 1] = 0.1
2613 >>> shear[1, 0] = 0.1
2614 >>> trans = pv.Transform(shear)
2615
2616 Get the shear matrix. The shear matrix is the same as the input in this particular example,
2617 but in general this is not the case.
2618
2619 >>> trans.shear_matrix
2620 array([[1. , 0.1, 0. ],
2621 [0.1, 1. , 0. ],
2622 [0. , 0. , 1. ]])
2623
2624 Compose an asymmetric shear matrix instead.
2625
2626 >>> shear = np.eye(4)
2627 >>> shear[0, 1] = 0.1
2628 >>> trans = pv.Transform(shear)
2629
2630 Get the shear matrix. In this case, shear differs from the input because asymmetric shear
2631 can be decomposed into scale factors and a rotation.
2632
2633 >>> trans.shear_matrix
2634 array([[1. , 0.05 , 0. ],
2635 [0.04975124, 1. , 0. ],
2636 [0. , 0. , 1. ]])
2637
2638 >>> trans.scale_factors
2639 (0.9987523388778445, 1.0037461005722337, 1.0)
2640
2641 >>> axis, angle = trans.rotation_axis_angle
2642 >>> axis
2643 (0.0, 0.0, -1.0)
2644 >>> angle
2645 2.8624
2646
2647 """ # noqa: E501
2648 _, _, _, _, K = self.decompose()
2649 return K
2650
2651 @property
2652 def has_translation(self) -> bool: # numpydoc ignore=RT01
2653 """Return ``True`` if the current transformation :attr:`~Transform.matrix` has a translation component.
2654
2655 .. versionadded:: 0.47
2656
2657 See Also
2658 --------
2659 translation, translate, decompose
2660
2661 """ # noqa: E501
2662 return not np.allclose(self.translation, np.zeros((3,)))
2663
2664 @property
2665 def has_rotation(self) -> bool: # numpydoc ignore=RT01
2666 """Return ``True`` if the current transformation :attr:`~Transform.matrix` has a rotation component.
2667
2668 .. versionadded:: 0.47
2669
2670 See Also
2671 --------
2672 rotation_matrix, rotate, decompose
2673
2674 """ # noqa: E501
2675 return not np.allclose(self.rotation_matrix, np.eye(3))
2676
2677 @property
2678 def has_reflection(self) -> bool: # numpydoc ignore=RT01
2679 """Return ``True`` if the current transformation :attr:`~Transform.matrix` has a reflection component.
2680
2681 .. versionadded:: 0.47
2682
2683 See Also
2684 --------
2685 reflection, reflect, decompose
2686
2687 """ # noqa: E501
2688 return self.reflection == -1
2689
2690 @property
2691 def has_scale(self) -> bool: # numpydoc ignore=RT01
2692 """Return ``True`` if the current transformation :attr:`~Transform.matrix` has a scale component.
2693
2694 .. versionadded:: 0.47
2695
2696 See Also
2697 --------
2698 scale_factors, scale, decompose
2699
2700 """ # noqa: E501
2701 return not np.allclose(self.scale_factors, np.ones((3,)))
2702
2703 @property
2704 def has_shear(self) -> bool: # numpydoc ignore=RT01
2705 """Return ``True`` if the current transformation :attr:`~Transform.matrix` has a shear component.
2706
2707 .. versionadded:: 0.47
2708
2709 See Also
2710 --------
2711 shear_matrix, compose, decompose
2712
2713 """ # noqa: E501
2714 return not np.allclose(self.shear_matrix, np.eye(3))
2715
2716 def as_rotation(
2717 self,
2718 representation: Literal['quat', 'matrix', 'rotvec', 'mrp', 'euler', 'davenport']
2719 | None = None,
2720 *args,
2721 **kwargs,
2722 ) -> Rotation | NumpyArray[float]:
2723 """Return the rotation component as a SciPy ``Rotation`` or any of its representations.
2724
2725 The current :attr:`matrix` is first decomposed to extract the rotation component
2726 and then returned with the specified representation.
2727
2728 .. note::
2729
2730 This method depends on the ``scipy`` package which must be installed to use it.
2731
2732 Parameters
2733 ----------
2734 representation : str, optional
2735 Representation of the rotation.
2736
2737 - ``'quat'``: Represent as a quaternion using
2738 :meth:`~scipy.spatial.transform.Rotation.as_quat`. Returns a length-4 vector.
2739 - ``'matrix'``: Represent as a 3x3 matrix using
2740 :meth:`~scipy.spatial.transform.Rotation.as_matrix`.
2741 - ``'rotvec'``: Represent as a rotation vector using
2742 :meth:`~scipy.spatial.transform.Rotation.as_rotvec`.
2743 - ``'mrp'``: Represent as a Modified Rodrigues Parameters (MRPs) vector using
2744 :meth:`~scipy.spatial.transform.Rotation.as_mrp`.
2745 - ``'euler'``: Represent as Euler angles using
2746 :meth:`~scipy.spatial.transform.Rotation.as_euler`.
2747 - ``'davenport'``: Represent as Davenport angles using
2748 :meth:`~scipy.spatial.transform.Rotation.as_davenport`.
2749
2750 If no representation is given, then an instance of
2751 :class:`scipy.spatial.transform.Rotation` is returned by default.
2752
2753 *args
2754 Arguments passed to the ``Rotation`` method for the specified
2755 representation.
2756
2757 **kwargs
2758 Keyword arguments passed to the ``Rotation`` method for the specified
2759 representation.
2760
2761 Returns
2762 -------
2763 output : scipy.spatial.transform.Rotation | np.ndarray
2764 Rotation object or array depending on the representation.
2765
2766 See Also
2767 --------
2768 rotation_matrix, rotation_axis_angle, decompose
2769 Get this transform's rotation component `without` using SciPy.
2770 rotate, rotate_x, rotate_y, rotate_z, rotate_vector
2771 Compose a rotation matrix.
2772
2773 Examples
2774 --------
2775 Create a rotation matrix and initialize a :class:`Transform` from it.
2776
2777 >>> import numpy as np
2778 >>> import pyvista as pv
2779 >>> matrix = [[0, -1, 0], [1, 0, 0], [0, 0, 1]]
2780 >>> transform = pv.Transform(matrix)
2781
2782 Represent the rotation as :class:`scipy.spatial.transform.Rotation` instance.
2783
2784 >>> rot = transform.as_rotation()
2785 >>> type(rot)
2786 <class 'scipy.spatial.transform._rotation.Rotation'>
2787
2788 Represent the rotation as a quaternion.
2789
2790 >>> rot = transform.as_rotation('quat')
2791 >>> rot
2792 array([0. , 0. , 0.70710678, 0.70710678])
2793
2794 Represent the rotation as a rotation vector. The vector has a direction
2795 ``(0, 0, 1)`` and magnitude of ``pi/2``.
2796
2797 >>> rot = transform.as_rotation('rotvec')
2798 >>> rot
2799 array([0. , 0. , 1.57079633])
2800
2801 Represent the rotation as a Modified Rodrigues Parameters vector.
2802
2803 >>> rot = transform.as_rotation('mrp')
2804 >>> rot
2805 array([0. , 0. , 0.41421356])
2806
2807 Represent the rotation as x-y-z Euler angles in degrees.
2808
2809 >>> rot = transform.as_rotation('euler', 'xyz', degrees=True)
2810 >>> rot
2811 array([ 0., 0., 90.])
2812
2813 Represent the rotation as extrinsic x-y-z Davenport angles in degrees.
2814
2815 >>> rot = transform.as_rotation(
2816 ... 'davenport', np.eye(3), 'extrinsic', degrees=True
2817 ... )
2818 >>> rot
2819 array([-1.27222187e-14, 0.00000000e+00, 9.00000000e+01])
2820
2821 """
2822 try:
2823 from scipy.spatial.transform import Rotation # noqa: PLC0415
2824 except ImportError:
2825 msg = "The 'scipy' package must be installed to use `as_rotation`"
2826 raise ImportError(msg)
2827
2828 if isinstance(representation, str):
2829 representation = representation.lower() # type: ignore[assignment]
2830
2831 _validation.check_contains(
2832 ['quat', 'matrix', 'rotvec', 'mrp', 'euler', 'davenport', None],
2833 must_contain=representation,
2834 name='representation',
2835 )
2836 if representation in ['rotation', 'matrix']:
2837 assert_empty_kwargs(**kwargs)
2838
2839 _, R, _, _, _ = self.decompose()
2840
2841 if representation == 'matrix':
2842 out = R
2843 else:
2844 rotation = Rotation.from_matrix(R)
2845 if representation is None:
2846 out = rotation
2847 elif representation == 'quat':
2848 out = rotation.as_quat(*args, **kwargs)
2849 elif representation == 'rotvec':
2850 out = rotation.as_rotvec(*args, **kwargs)
2851 elif representation == 'mrp':
2852 out = rotation.as_mrp(*args, **kwargs)
2853 elif representation == 'euler':
2854 out = rotation.as_euler(*args, **kwargs)
2855 elif representation == 'davenport':
2856 out = rotation.as_davenport(*args, **kwargs)
2857 else: # pragma: no cover
2858 msg = f"Unexpected rotation type '{representation}'" # type: ignore[unreachable]
2859 raise RuntimeError(msg)
2860 return out