| 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 |