Debian Codegraph @

pyvista/plotting/camera.py

raw
1 """Module containing pyvista implementation of :vtk:`vtkCamera`."""
2
3 from __future__ import annotations
4
5 from pathlib import Path
6 from weakref import proxy
7 import xml.dom.minidom as md
8 from xml.etree import ElementTree as ET
9
10 import numpy as np
11
12 import pyvista as pv
13 from pyvista import _vtk
14 from pyvista._deprecate_positional_args import _deprecate_positional_args
15 from pyvista.core._vtk_utilities import DisableVtkSnakeCase
16 from pyvista.core.utilities.misc import _NoNewAttrMixin
17
18 from .helpers import view_vectors
19
20
21 class Camera(_NoNewAttrMixin, DisableVtkSnakeCase, _vtk.vtkCamera):
22 """PyVista wrapper for the VTK Camera class.
23
24 Parameters
25 ----------
26 renderer : pyvista.Renderer, optional
27 Renderer to attach the camera to.
28
29 Examples
30 --------
31 Create a camera at the pyvista module level.
32
33 >>> import pyvista as pv
34 >>> camera = pv.Camera()
35
36 Access the active camera of a plotter and get the position of the
37 camera.
38
39 >>> pl = pv.Plotter()
40 >>> pl.camera.position
41 (1.0, 1.0, 1.0)
42
43 """
44
45 def __init__(self, renderer=None):
46 """Initialize a new camera descriptor."""
47 self._parallel_projection = False
48 self._elevation = 0.0
49 self._azimuth = 0.0
50 self._is_set = False
51 self._focus = None # Used by BackgroundRenderer
52
53 if renderer:
54 if not isinstance(renderer, pv.Renderer):
55 msg = 'Camera only accepts a pyvista.Renderer or None as the ``renderer`` argument'
56 raise TypeError(msg)
57 self._renderer = proxy(renderer)
58 else:
59 self._renderer = None # type: ignore[assignment]
60
61 def __eq__(self, other) -> bool:
62 """Compare whether the relevant attributes of two cameras are equal."""
63 # attributes which are native python types and thus implement __eq__
64
65 native_attrs = [
66 'position',
67 'focal_point',
68 'parallel_projection',
69 'distance',
70 'thickness',
71 'parallel_scale',
72 'clipping_range',
73 'view_angle',
74 'roll',
75 ]
76 for attr in native_attrs:
77 if getattr(self, attr) != getattr(other, attr):
78 return False
79
80 this_trans = self.model_transform_matrix
81 that_trans = other.model_transform_matrix
82 trans_count = sum(1 for trans in [this_trans, that_trans] if trans is not None)
83 if trans_count == 1:
84 # either but not both are None
85 return False
86 return not (trans_count == 2 and not np.array_equal(this_trans, that_trans))
87
88 __hash__ = None # type: ignore[assignment] # https://github.com/pyvista/pyvista/pull/7671
89
90 def __repr__(self):
91 """Print a repr specifying the id of the camera and its camera type."""
92 repr_str = f'{self.__class__.__name__} ({hex(id(self))})'
93 repr_str += f'\n Position: {self.position}'
94 repr_str += f'\n Focal Point: {self.focal_point}'
95 repr_str += f'\n Parallel Projection: {self.parallel_projection}'
96 repr_str += f'\n Distance: {self.distance}'
97 repr_str += f'\n Thickness: {self.thickness}'
98 repr_str += f'\n Parallel Scale: {self.parallel_scale}'
99 repr_str += f'\n Clipping Range: {self.clipping_range}'
100 repr_str += f'\n View Angle: {self.view_angle}'
101 repr_str += f'\n Roll: {self.roll}'
102 return repr_str
103
104 def __str__(self):
105 """Return the object string representation."""
106 return self.__repr__()
107
108 def __del__(self):
109 """Delete the camera."""
110 self.RemoveAllObservers()
111
112 @property
113 def is_set(self) -> bool: # numpydoc ignore=RT01
114 """Get or set whether this camera has been configured."""
115 return self._is_set
116
117 @is_set.setter
118 def is_set(self, value: bool):
119 self._is_set = bool(value)
120
121 @classmethod
122 def from_paraview_pvcc(cls, filename: str | Path) -> Camera:
123 """Load a Paraview camera file (.pvcc extension).
124
125 Returns a pyvista.Camera object for which attributes has been read
126 from the filename argument.
127
128 Parameters
129 ----------
130 filename : str or pathlib.Path
131 Path to Paraview camera file (.pvcc).
132
133 Returns
134 -------
135 pyvista.Camera
136 Camera from the camera file.
137
138 Examples
139 --------
140 >>> import pyvista as pv
141 >>> pl = pv.Plotter()
142 >>> pl.camera = pv.Camera.from_paraview_pvcc('camera.pvcc') # doctest:+SKIP
143 >>> pl.camera.position
144 (1.0, 1.0, 1.0)
145
146 """
147 to_find = {
148 'CameraPosition': ('position', float),
149 'CameraFocalPoint': ('focal_point', float),
150 'CameraViewAngle': ('view_angle', float),
151 'CameraViewUp': ('up', float),
152 'CameraParallelProjection': ('parallel_projection', int),
153 'CameraParallelScale': ('parallel_scale', float),
154 }
155 camera = cls()
156
157 tree = ET.parse(filename)
158 root = tree.getroot()[0]
159 for element in root:
160 attrib = element.attrib
161 attrib_name = attrib['name']
162
163 if attrib_name in to_find:
164 name, typ = to_find[attrib_name]
165 nelems = int(attrib['number_of_elements'])
166
167 # Set the camera attributes
168 if nelems == 3:
169 values = [typ(e.attrib['value']) for e in element]
170 setattr(camera, name, values)
171 elif nelems == 1:
172 # Special case for bool since bool("0") returns True.
173 # So first convert to int from `to_find` and then apply bool
174 if 'name' in element[-1].attrib and element[-1].attrib['name'] == 'bool':
175 val = bool(typ(element[0].attrib['value']))
176 else:
177 val = typ(element[0].attrib['value'])
178 setattr(camera, name, val)
179
180 camera.is_set = True
181 return camera
182
183 def to_paraview_pvcc(self, filename: str | Path):
184 """Write the camera parameters to a Paraview camera file (.pvcc extension).
185
186 Parameters
187 ----------
188 filename : str or pathlib.Path
189 Path to Paraview camera file (.pvcc).
190
191 Examples
192 --------
193 >>> import pyvista as pv
194 >>> pl = pv.Plotter()
195 >>> pl.camera.to_paraview_pvcc('camera.pvcc') # doctest:+SKIP
196
197 """
198 root = ET.Element('PVCameraConfiguration')
199 root.attrib['description'] = 'ParaView camera configuration'
200 root.attrib['version'] = '1.0'
201
202 dico = dict(group='views', type='RenderView', id='0', servers='21')
203 proxy = ET.SubElement(root, 'Proxy', dico)
204
205 # Add tuples
206 to_find = {
207 'CameraPosition': 'position',
208 'CameraFocalPoint': 'focal_point',
209 'CameraViewUp': 'up',
210 }
211 for name, attr in to_find.items():
212 e = ET.SubElement(
213 proxy,
214 'Property',
215 dict(name=name, id=f'0.{name}', number_of_elements='3'),
216 )
217
218 for i in range(3):
219 tmp = ET.Element('Element')
220 tmp.attrib['index'] = str(i)
221 tmp.attrib['value'] = str(getattr(self, attr)[i])
222 e.append(tmp)
223
224 # Add single values
225 to_find = {
226 'CameraViewAngle': 'view_angle',
227 'CameraParallelScale': 'parallel_scale',
228 'CameraParallelProjection': 'parallel_projection',
229 }
230
231 for name, attr in to_find.items():
232 e = ET.SubElement(
233 proxy,
234 'Property',
235 dict(name=name, id=f'0.{name}', number_of_elements='1'),
236 )
237 tmp = ET.Element('Element')
238 tmp.attrib['index'] = '0'
239
240 val = getattr(self, attr)
241 if not isinstance(val, bool):
242 tmp.attrib['value'] = str(val)
243 e.append(tmp)
244 else:
245 tmp.attrib['value'] = '1' if val else '0'
246 e.append(tmp)
247 e.append(ET.Element('Domain', dict(name='bool', id=f'0.{name}.bool')))
248
249 xmlstr = ET.tostring(root).decode()
250 newxml = md.parseString(xmlstr)
251 with Path(filename).open('w') as outfile:
252 outfile.write(newxml.toprettyxml(indent='\t', newl='\n'))
253
254 @property
255 def position(self): # numpydoc ignore=RT01
256 """Return or set the position of the camera in world coordinates.
257
258 Examples
259 --------
260 >>> import pyvista as pv
261 >>> pl = pv.Plotter()
262 >>> pl.camera.position
263 (1.0, 1.0, 1.0)
264 >>> pl.camera.position = (2.0, 1.0, 1.0)
265 >>> pl.camera.position
266 (2.0, 1.0, 1.0)
267
268 """
269 return self.GetPosition()
270
271 @position.setter
272 def position(self, value):
273 self.SetPosition(value)
274 self._elevation = 0.0
275 self._azimuth = 0.0
276 if self._renderer: # type: ignore[truthy-bool]
277 self.reset_clipping_range()
278 self.is_set = True
279
280 def reset_clipping_range(self):
281 """Reset the camera clipping range based on the bounds of the visible actors.
282
283 Examples
284 --------
285 >>> import pyvista as pv
286 >>> pl = pv.Plotter()
287 >>> _ = pl.add_mesh(pv.Sphere())
288 >>> pl.camera.clipping_range = (1, 2)
289 >>> pl.camera.reset_clipping_range() # doctest:+SKIP
290 (0.0039213485598532955, 3.9213485598532953)
291
292 """
293 if self._renderer is None:
294 msg = 'Camera is must be associated with a renderer to reset its clipping range.' # type: ignore[unreachable]
295 raise AttributeError(msg)
296 self._renderer.reset_camera_clipping_range()
297
298 @property
299 def focal_point(self): # numpydoc ignore=RT01
300 """Location of the camera's focus in world coordinates.
301
302 Examples
303 --------
304 >>> import pyvista as pv
305 >>> pl = pv.Plotter()
306 >>> pl.camera.focal_point
307 (0.0, 0.0, 0.0)
308 >>> pl.camera.focal_point = (2.0, 0.0, 0.0)
309 >>> pl.camera.focal_point
310 (2.0, 0.0, 0.0)
311
312 """
313 return self.GetFocalPoint()
314
315 @focal_point.setter
316 def focal_point(self, point):
317 self.SetFocalPoint(point)
318 self.is_set = True
319
320 @property
321 def model_transform_matrix(self): # numpydoc ignore=RT01
322 """Return or set the camera's model transformation matrix.
323
324 Examples
325 --------
326 >>> import pyvista as pv
327 >>> import numpy as np
328 >>> pl = pv.Plotter()
329 >>> pl.camera.model_transform_matrix
330 array([[1., 0., 0., 0.],
331 [0., 1., 0., 0.],
332 [0., 0., 1., 0.],
333 [0., 0., 0., 1.]])
334 >>> pl.camera.model_transform_matrix = np.array(
335 ... [
336 ... [1.0, 0.0, 0.0, 0.0],
337 ... [0.0, 1.0, 0.0, 0.0],
338 ... [0.0, 0.0, 1.0, 0.0],
339 ... [0.0, 0.0, 0.0, 0.5],
340 ... ]
341 ... )
342 >>>
343 array([[1., 0., 0., 0.],
344 [0., 1., 0., 0.],
345 [0., 0., 1., 0.],
346 [0., 0., 0., 0.5]])
347
348 """
349 vtk_matrix = self.GetModelTransformMatrix()
350 matrix = np.empty((4, 4))
351 vtk_matrix.DeepCopy(matrix.ravel(), vtk_matrix)
352 return matrix
353
354 @model_transform_matrix.setter
355 def model_transform_matrix(self, matrix):
356 vtk_matrix = _vtk.vtkMatrix4x4()
357 vtk_matrix.DeepCopy(matrix.ravel())
358 self.SetModelTransformMatrix(vtk_matrix)
359
360 @property
361 def distance(self): # numpydoc ignore=RT01
362 """Return or set the distance of the focal point from the camera.
363
364 Notes
365 -----
366 Setting the distance keeps the camera fixed and moves the focal point.
367
368 Examples
369 --------
370 >>> import pyvista as pv
371 >>> pl = pv.Plotter()
372 >>> pl.camera.distance
373 1.73205
374 >>> pl.camera.distance = 2.0
375 >>> pl.camera.distance
376 2.0
377
378 """
379 return self.GetDistance()
380
381 @distance.setter
382 def distance(self, distance):
383 self.SetDistance(distance)
384 self.is_set = True
385
386 @property
387 def thickness(self): # numpydoc ignore=RT01
388 """Return or set the distance between clipping planes.
389
390 Examples
391 --------
392 >>> import pyvista as pv
393 >>> pl = pv.Plotter()
394 >>> pl.camera.thickness
395 1000.0
396 >>> pl.camera.thickness = 100
397 >>> pl.camera.thickness
398 100.0
399
400 """
401 return self.GetThickness()
402
403 @thickness.setter
404 def thickness(self, length):
405 self.SetThickness(length)
406
407 @property
408 def parallel_scale(self): # numpydoc ignore=RT01
409 """Return or set the scaling used for a parallel projection.
410
411 Examples
412 --------
413 >>> import pyvista as pv
414 >>> pl = pv.Plotter()
415 >>> pl.camera.parallel_scale
416 1.0
417 >>> pl.camera.parallel_scale = 2.0
418 >>> pl.camera.parallel_scale
419 2.0
420
421 """
422 return self.GetParallelScale()
423
424 @parallel_scale.setter
425 def parallel_scale(self, scale):
426 self.SetParallelScale(scale)
427
428 def zoom(self, value):
429 """Set the zoom of the camera.
430
431 In perspective mode, decrease the view angle by the specified
432 factor.
433
434 In parallel mode, decrease the parallel scale by the specified
435 factor. A value greater than 1 is a zoom-in, a value less than
436 1 is a zoom-out.
437
438 Parameters
439 ----------
440 value : float or str
441 Zoom of the camera. If a float, must be greater than 0. Otherwise,
442 if a string, must be ``"tight"``. If tight, the plot will be zoomed
443 such that the actors fill the entire viewport.
444
445 Examples
446 --------
447 Show the Default zoom.
448
449 >>> import pyvista as pv
450 >>> pl = pv.Plotter()
451 >>> _ = pl.add_mesh(pv.Sphere())
452 >>> pl.camera.zoom(1.0)
453 >>> pl.show()
454
455 Show 2x zoom.
456
457 >>> pl = pv.Plotter()
458 >>> _ = pl.add_mesh(pv.Sphere())
459 >>> pl.camera.zoom(2.0)
460 >>> pl.show()
461
462 Zoom so the actor fills the entire render window.
463
464 >>> pl = pv.Plotter()
465 >>> _ = pl.add_mesh(pv.Sphere())
466 >>> pl.camera.zoom('tight')
467 >>> pl.show()
468
469 """
470 if isinstance(value, str):
471 if value != 'tight':
472 msg = 'If a string, ``zoom`` can only be "tight"'
473 raise ValueError(msg)
474 self.tight()
475 return
476
477 self.Zoom(value)
478 self.is_set = True
479
480 @property
481 def up(self): # numpydoc ignore=RT01
482 """Return or set the "up" of the camera.
483
484 Examples
485 --------
486 >>> import pyvista as pv
487 >>> pl = pv.Plotter()
488 >>> pl.camera.up
489 (0.0, 0.0, 1.0)
490 >>> pl.camera.up = (0.410018, 0.217989, 0.885644)
491 >>> pl.camera.up
492 (0.410018, 0.217989, 0.885644)
493
494 """
495 return self.GetViewUp()
496
497 @up.setter
498 def up(self, vector):
499 self.SetViewUp(vector)
500 self.is_set = True
501
502 def enable_parallel_projection(self):
503 """Enable parallel projection.
504
505 The camera will have a parallel projection. Parallel
506 projection is often useful when viewing images or 2D datasets,
507 but will look odd when viewing 3D datasets.
508
509 Examples
510 --------
511 >>> import pyvista as pv
512 >>> from pyvista import demos
513 >>> pl = pv.demos.orientation_plotter()
514 >>> pl.enable_parallel_projection()
515 >>> pl.show()
516
517 """
518 self._parallel_projection = True
519 self.SetParallelProjection(True)
520
521 def disable_parallel_projection(self):
522 """Disable the use of parallel projection.
523
524 This is default behavior.
525
526 Examples
527 --------
528 >>> import pyvista as pv
529 >>> from pyvista import demos
530 >>> pl = pv.demos.orientation_plotter()
531 >>> pl.disable_parallel_projection()
532 >>> pl.show()
533
534 """
535 self._parallel_projection = False
536 self.SetParallelProjection(False)
537
538 @property
539 def parallel_projection(self): # numpydoc ignore=RT01
540 """Return the state of the parallel projection.
541
542 Examples
543 --------
544 >>> import pyvista as pv
545 >>> from pyvista import demos
546 >>> pl = pv.Plotter()
547 >>> pl.disable_parallel_projection()
548 >>> pl.parallel_projection
549 False
550
551 """
552 return self._parallel_projection
553
554 @parallel_projection.setter
555 def parallel_projection(self, state):
556 if state:
557 self.enable_parallel_projection()
558 else:
559 self.disable_parallel_projection()
560
561 @property
562 def clipping_range(self): # numpydoc ignore=RT01
563 """Return or set the location of the clipping planes.
564
565 Clipping planes are the near and far clipping planes along
566 the direction of projection.
567
568 Examples
569 --------
570 >>> import pyvista as pv
571 >>> pl = pv.Plotter()
572 >>> pl.camera.clipping_range
573 (0.01, 1000.01)
574 >>> pl.camera.clipping_range = (1, 10)
575 >>> pl.camera.clipping_range
576 (1.0, 10.0)
577
578 """
579 return self.GetClippingRange()
580
581 @clipping_range.setter
582 def clipping_range(self, points):
583 if points[0] > points[1]:
584 msg = 'Near point must be lower than the far point.'
585 raise ValueError(msg)
586 self.SetClippingRange(points[0], points[1])
587
588 @property
589 def view_angle(self): # numpydoc ignore=RT01
590 """Return or set the camera view angle.
591
592 Examples
593 --------
594 >>> import pyvista as pv
595 >>> pl = pv.Plotter()
596 >>> pl.camera.view_angle
597 30.0
598 >>> pl.camera.view_angle = 60.0
599 >>> pl.camera.view_angle
600 60.0
601
602 """
603 return self.GetViewAngle()
604
605 @view_angle.setter
606 def view_angle(self, value):
607 self.SetViewAngle(value)
608
609 @property
610 def direction(self): # numpydoc ignore=RT01
611 """Vector from the camera position to the focal point.
612
613 Examples
614 --------
615 >>> import pyvista as pv
616 >>> pl = pv.Plotter()
617 >>> pl.camera.direction # doctest:+SKIP
618 (-0.5773502691896257, -0.5773502691896257, -0.5773502691896257)
619
620 """
621 return self.GetDirectionOfProjection()
622
623 def view_frustum(self, aspect=1.0):
624 """Get the view frustum.
625
626 Parameters
627 ----------
628 aspect : float, default: 1.0
629 The aspect of the viewport to compute the planes.
630
631 Returns
632 -------
633 pyvista.PolyData
634 View frustum.
635
636 Examples
637 --------
638 >>> import pyvista as pv
639 >>> pl = pv.Plotter()
640 >>> frustum = pl.camera.view_frustum(1.0)
641 >>> frustum.n_points
642 8
643 >>> frustum.n_cells
644 6
645
646 """
647 frustum_planes = [0] * 24
648 self.GetFrustumPlanes(aspect, frustum_planes) # type: ignore[arg-type]
649 planes = _vtk.vtkPlanes()
650 planes.SetFrustumPlanes(frustum_planes) # type: ignore[arg-type]
651
652 frustum_source = _vtk.vtkFrustumSource()
653 frustum_source.ShowLinesOff()
654 frustum_source.SetPlanes(planes)
655 frustum_source.Update()
656
657 return pv.wrap(frustum_source.GetOutput())
658
659 @property
660 def roll(self): # numpydoc ignore=RT01
661 """Return or set the roll of the camera about the direction of projection.
662
663 This will spin the camera about its axis.
664
665 Examples
666 --------
667 >>> import pyvista as pv
668 >>> pl = pv.Plotter()
669 >>> pl.camera.roll
670 -120.00000000000001
671 >>> pl.camera.roll = 45.0
672 >>> pl.camera.roll
673 45.0
674
675 """
676 return self.GetRoll()
677
678 @roll.setter
679 def roll(self, angle):
680 self.SetRoll(angle)
681 self.is_set = True
682
683 @property
684 def elevation(self): # numpydoc ignore=RT01
685 """Return or set the vertical rotation of the scene.
686
687 Rotate the camera about the cross product of the negative of
688 the direction of projection and the view up vector, using the
689 focal point as the center of rotation.
690
691 Examples
692 --------
693 >>> import pyvista as pv
694 >>> pl = pv.Plotter()
695 >>> pl.camera.elevation
696 0.0
697 >>> pl.camera.elevation = 45.0
698 >>> pl.camera.elevation
699 45.0
700
701 """
702 return self._elevation
703
704 @elevation.setter
705 def elevation(self, angle):
706 if self._elevation:
707 self.Elevation(-self._elevation)
708 self._elevation = angle
709 self.Elevation(angle)
710 self.is_set = True
711
712 @property
713 def azimuth(self): # numpydoc ignore=RT01
714 """Return or set the azimuth of the camera.
715
716 Rotate the camera about the view up vector centered at the
717 focal point. Note that the view up vector is whatever was set
718 via SetViewUp, and is not necessarily perpendicular to the
719 direction of projection.
720
721 Examples
722 --------
723 >>> import pyvista as pv
724 >>> pl = pv.Plotter()
725 >>> pl.camera.azimuth
726 0.0
727 >>> pl.camera.azimuth = 45.0
728 >>> pl.camera.azimuth
729 45.0
730
731 """
732 return self._azimuth
733
734 @azimuth.setter
735 def azimuth(self, angle):
736 if self._azimuth:
737 self.Azimuth(-self._azimuth)
738 self._azimuth = angle
739 self.Azimuth(angle)
740 self.is_set = True
741
742 def copy(self):
743 """Return a deep copy of the camera.
744
745 Returns
746 -------
747 pyvista.Camera
748 Deep copy of the camera.
749
750 Examples
751 --------
752 Create a camera and check that it shares a transformation
753 matrix with its shallow copy.
754
755 >>> import pyvista as pv
756 >>> import numpy as np
757 >>> camera = pv.Camera()
758 >>> camera.model_transform_matrix = np.array(
759 ... [
760 ... [1.0, 0.0, 0.0, 0.0],
761 ... [0.0, 1.0, 0.0, 0.0],
762 ... [0.0, 0.0, 1.0, 0.0],
763 ... [0.0, 0.0, 0.0, 1.0],
764 ... ]
765 ... )
766 >>> copied_camera = camera.copy()
767 >>> copied_camera == camera
768 True
769 >>> camera.model_transform_matrix = np.array(
770 ... [
771 ... [1.0, 0.0, 0.0, 0.0],
772 ... [0.0, 1.0, 0.0, 0.0],
773 ... [0.0, 0.0, 1.0, 0.0],
774 ... [0.0, 0.0, 0.0, 0.5],
775 ... ]
776 ... )
777 >>> copied_camera == camera
778 False
779
780 """
781 immutable_attrs = [
782 'position',
783 'focal_point',
784 'model_transform_matrix',
785 'distance',
786 'thickness',
787 'parallel_scale',
788 'up',
789 'clipping_range',
790 'view_angle',
791 'roll',
792 'parallel_projection',
793 'is_set',
794 ]
795 new_camera = Camera()
796
797 for attr in immutable_attrs:
798 value = getattr(self, attr)
799 setattr(new_camera, attr, value)
800
801 return new_camera
802
803 @_deprecate_positional_args
804 def tight( # noqa: PLR0917
805 self,
806 padding=0.0,
807 adjust_render_window: bool = True, # noqa: FBT001, FBT002
808 view='xy',
809 negative: bool = False, # noqa: FBT001, FBT002
810 ):
811 """Adjust the camera position so that the actors fill the entire renderer.
812
813 The camera view direction is reoriented to be normal to the ``view``
814 plane. When ``negative=False``, The first letter of ``view`` refers
815 to the axis that points to the right. The second letter of ``view``
816 refers to axis that points up. When ``negative=True``, the first
817 letter refers to the axis that points left. The up direction is
818 unchanged.
819
820 Parallel projection is enabled when using this function.
821
822 Parameters
823 ----------
824 padding : float, default: 0.0
825 Additional padding around the actor(s). This is effectively a zoom,
826 where a value of 0.01 results in a zoom out of 1%.
827
828 adjust_render_window : bool, default: True
829 Adjust the size of the render window as to match the dimensions of
830 the visible actors.
831
832 view : {'xy', 'yx', 'xz', 'zx', 'yz', 'zy'}, default: 'xy'
833 Plane to which the view is oriented.
834
835 negative : bool, default: False
836 Whether to view in opposite direction.
837
838 Notes
839 -----
840 This resets the view direction to look at a plane with parallel projection.
841
842 Examples
843 --------
844 Display the bird image with a tight view.
845
846 >>> import pyvista as pv
847 >>> from pyvista import examples
848 >>> bird = examples.download_bird()
849 >>> pl = pv.Plotter(border=True, border_width=5)
850 >>> _ = pl.add_mesh(bird, rgb=True)
851 >>> pl.camera.tight()
852 >>> pl.show()
853
854 Set the background to blue use a 5% padding around the image.
855
856 >>> pl = pv.Plotter()
857 >>> _ = pl.add_mesh(bird, rgb=True)
858 >>> pl.background_color = 'b'
859 >>> pl.camera.tight(padding=0.05)
860 >>> pl.show()
861
862 """
863 # Inspired by vedo resetCamera. Thanks @marcomusy.
864 x0, x1, y0, y1, z0, z1 = self._renderer.bounds
865
866 self.enable_parallel_projection()
867
868 self._renderer.ComputeAspect()
869 aspect = self._renderer.GetAspect()
870
871 position0 = np.array([x0, y0, z0])
872 position1 = np.array([x1, y1, z1])
873 objects_size = position1 - position0
874 position = position0 + objects_size / 2
875
876 direction, viewup = view_vectors(view, negative=negative)
877 horizontal = np.cross(direction, viewup)
878
879 vert_dist = abs(objects_size @ viewup)
880 horiz_dist = abs(objects_size @ horizontal)
881
882 # set focal point to objects' center
883 # offset camera position from objects center by dist in opposite of viewing direction
884 # (actual distance doesn't matter due to parallel projection)
885 dist = 1
886 camera_position = position + dist * direction
887
888 self.SetViewUp(*viewup)
889 self.SetPosition(*camera_position)
890 self.SetFocalPoint(*position)
891
892 ps = max(horiz_dist / aspect[0], vert_dist) / 2
893 self.parallel_scale = ps * (1 + padding)
894 self._renderer.ResetCameraClippingRange(x0, x1, y0, y1, z0, z1)
895
896 if adjust_render_window:
897 ren_win = self._renderer.GetRenderWindow()
898 size = list(ren_win.GetSize())
899 size_ratio = size[0] / size[1]
900 tight_ratio = horiz_dist / vert_dist
901 resize_ratio = tight_ratio / size_ratio
902 if resize_ratio < 1:
903 size[0] = round(size[0] * resize_ratio)
904 else:
905 size[1] = round(size[1] / resize_ratio)
906
907 ren_win.SetSize(size)
908
909 # simply call tight again to reset the parallel scale due to the
910 # resized window
911 self.tight(padding=padding, adjust_render_window=False, view=view, negative=negative)
912
913 self.is_set = True