Debian Codegraph @

pyvista/plotting/lights.py

raw
1 """Module containing pyvista implementation of :vtk:`vtkLight`."""
2
3 from __future__ import annotations
4
5 from enum import IntEnum
6 from typing import TYPE_CHECKING
7
8 import numpy as np
9
10 from pyvista import _vtk
11 from pyvista._deprecate_positional_args import _deprecate_positional_args
12 from pyvista.core import _validation
13 from pyvista.core._vtk_utilities import DisableVtkSnakeCase
14 from pyvista.core.utilities.arrays import vtkmatrix_from_array
15 from pyvista.core.utilities.misc import _NoNewAttrMixin
16
17 from .colors import Color
18
19 if TYPE_CHECKING:
20 from pyvista.core._typing_core import TransformLike
21
22 from ._typing import ColorLike
23
24
25 class LightType(IntEnum):
26 """An enumeration for the light types."""
27
28 HEADLIGHT = 1
29 CAMERA_LIGHT = 2
30 SCENE_LIGHT = 3
31
32 def __str__(self):
33 """Pretty name for a light type."""
34 return self.name.replace('_', ' ').title()
35
36
37 class Light(_NoNewAttrMixin, DisableVtkSnakeCase, _vtk.vtkLight):
38 """Light class.
39
40 Parameters
41 ----------
42 position : sequence[float], optional
43 The position of the light. The interpretation of the position
44 depends on the type of the light and whether the light has a
45 transformation matrix. See also the :py:attr:`position`
46 property.
47
48 focal_point : sequence[float], optional
49 The focal point of the light. The interpretation of the focal
50 point depends on the type of the light and whether the light
51 has a transformation matrix. See also the
52 :py:attr:`focal_point` property.
53
54 color : ColorLike, optional
55 The color of the light. The ambient, diffuse and specular
56 colors will all be set to this color on creation.
57
58 light_type : str | int, default: 'scene light'
59 The type of the light. If a string, one of ``'headlight'``,
60 ``'camera light'`` or ``'scene light'``. If an int, one of 1,
61 2 or 3, respectively. The class constants ``Light.HEADLIGHT``,
62 ``Light.CAMERA_LIGHT`` and ``Light.SCENE_LIGHT`` are also
63 available, respectively.
64
65 - A headlight is attached to the camera, looking at its
66 focal point along the axis of the camera.
67
68 - A camera light also moves with the camera, but it can
69 occupy a general position with respect to it.
70
71 - A scene light is stationary with respect to the scene,
72 as it does not follow the camera. This is the default.
73
74 intensity : float, optional
75 The brightness of the light (between 0 and 1).
76
77 positional : bool, optional
78 Set if the light is positional.
79
80 The default is a directional light, i.e. an infinitely distant
81 point source. A positional light with a cone angle of at least
82 90 degrees acts like a spherical point source. A positional
83 light with a cone angle that is less than 90 degrees is known
84 as a spotlight.
85
86 cone_angle : float, optional
87 Cone angle of a positional light in degrees.
88
89 show_actor : bool, default: False
90 Show an actor for a spotlight that depicts the geometry of the
91 beam.
92
93 exponent : float, optional
94 The exponent of the cosine used for spotlights. See also the
95 :py:attr:`exponent` property.
96
97 shadow_attenuation : float, optional
98 The value of shadow attenuation.
99
100 By default a light will be completely blocked when in shadow.
101 By setting this value to less than 1.0 you can control how
102 much light is attenuated when in shadow. Note that changing
103 the :py:attr:`attenuation_values` of the light can make it pass
104 through objects even if its shadow attenuation is 1.
105
106 attenuation_values : sequence, optional
107 Quadratic attenuation constants.
108
109 The values are a 3-length sequence which specifies the constant,
110 linear and quadratic constants in this order. These parameters
111 only have an effect for positional lights.
112
113 Examples
114 --------
115 Create a light at (10, 10, 10) and set its diffuse color to red.
116
117 >>> import pyvista as pv
118 >>> light = pv.Light(position=(10, 10, 10))
119 >>> light.diffuse_color = 1.0, 0.0, 0.0
120
121 Create a positional light at (0, 0, 3) with a cone angle of
122 30, exponent of 20, and a visible actor.
123
124 >>> light = pv.Light(
125 ... position=(0, 0, 3),
126 ... show_actor=True,
127 ... positional=True,
128 ... cone_angle=30,
129 ... exponent=20,
130 ... )
131
132 """
133
134 # pull in light type enum values as class constants
135 HEADLIGHT = LightType.HEADLIGHT
136 CAMERA_LIGHT = LightType.CAMERA_LIGHT
137 SCENE_LIGHT = LightType.SCENE_LIGHT
138
139 @_deprecate_positional_args
140 def __init__( # noqa: PLR0917
141 self,
142 position=None,
143 focal_point=None,
144 color=None,
145 light_type='scene light',
146 intensity=None,
147 positional=None,
148 cone_angle=None,
149 show_actor=False, # noqa: FBT002
150 exponent=None,
151 shadow_attenuation=None,
152 attenuation_values=None,
153 ):
154 """Initialize the light."""
155 super().__init__()
156 self._renderers = []
157 self.actor = None
158
159 if position is not None:
160 self.position = position
161 if focal_point is not None:
162 self.focal_point = focal_point
163
164 if color is not None:
165 self.ambient_color = color
166 self.diffuse_color = color
167 self.specular_color = color
168
169 if isinstance(light_type, str):
170 # be forgiving: ignore spaces and case
171 light_type_orig = light_type
172 type_normalized = light_type.replace(' ', '').lower()
173 mapping = {
174 'headlight': LightType.HEADLIGHT,
175 'cameralight': LightType.CAMERA_LIGHT,
176 'scenelight': LightType.SCENE_LIGHT,
177 }
178 try:
179 light_type = mapping[type_normalized]
180 except KeyError:
181 light_keys = ', '.join(mapping)
182 msg = (
183 f'Invalid light_type "{light_type_orig}"\n'
184 f'Choose from one of the following: {light_keys}'
185 )
186 raise ValueError(msg) from None
187 elif not isinstance(light_type, int):
188 msg = f'Parameter light_type must be int or str, not {type(light_type).__name__}.'
189 raise TypeError(msg)
190 # LightType is an int subclass
191
192 self.light_type = light_type
193
194 if intensity is not None:
195 self.intensity = intensity
196
197 if cone_angle is not None:
198 self.cone_angle = cone_angle
199
200 if exponent is not None:
201 self.exponent = exponent
202
203 if positional is not None:
204 self.positional = positional
205
206 if shadow_attenuation is not None:
207 self.shadow_attenuation = shadow_attenuation
208
209 if attenuation_values is not None:
210 self.attenuation_values = attenuation_values
211
212 # Add the light actor
213 self.actor = _vtk.vtkLightActor()
214 self.actor.SetLight(self)
215 self.actor.SetVisibility(show_actor)
216
217 def __repr__(self) -> str:
218 """Print a repr specifying the id of the light and its light type."""
219 return f'<{self.__class__.__name__} ({self.light_type}) at {hex(id(self))}>'
220
221 def __eq__(self, other) -> bool:
222 """Compare whether the relevant attributes of two lights are equal."""
223 # attributes which are native python types and thus implement __eq__
224 native_attrs = [
225 'light_type',
226 'position',
227 'focal_point',
228 'ambient_color',
229 'diffuse_color',
230 'specular_color',
231 'intensity',
232 'on',
233 'positional',
234 'exponent',
235 'cone_angle',
236 'attenuation_values',
237 'shadow_attenuation',
238 ]
239 for attr in native_attrs:
240 if getattr(self, attr) != getattr(other, attr):
241 return False
242
243 # check transformation matrix element by element (if it exists)
244 this_trans = self.transform_matrix
245 that_trans = other.transform_matrix
246 trans_count = sum(1 for trans in [this_trans, that_trans] if trans is not None)
247 if trans_count == 1:
248 # either but not both are None
249 return False
250 if trans_count == 2:
251 for i in range(4):
252 for j in range(4):
253 if this_trans.GetElement(i, j) != that_trans.GetElement(i, j):
254 return False
255 return True
256
257 __hash__ = None # type: ignore[assignment] # https://github.com/pyvista/pyvista/pull/7671
258
259 def __del__(self):
260 """Clean up when the light is being destroyed."""
261 self.actor = None
262 self._renderers.clear()
263
264 @property
265 def shadow_attenuation(self): # numpydoc ignore=RT01
266 """Return or set the value of shadow attenuation.
267
268 By default a light will be completely blocked when in shadow.
269 By setting this value to less than 1.0 you can control how
270 much light is attenuated when in shadow. Note that changing
271 the :py:attr:`attenuation_values` of the light can make it pass
272 through objects even if its shadow attenuation is 1.
273
274 Examples
275 --------
276 Set the shadow attenuation to 0.5
277
278 >>> import pyvista as pv
279 >>> light = pv.Light()
280 >>> light.shadow_attenuation = 0.5
281 >>> light.shadow_attenuation
282 0.5
283
284 """
285 return self.GetShadowAttenuation()
286
287 @shadow_attenuation.setter
288 def shadow_attenuation(self, value):
289 self.SetShadowAttenuation(value)
290
291 @property
292 def ambient_color(self): # numpydoc ignore=RT01
293 """Return or set the ambient color of the light.
294
295 When setting, the color must be a 3-length sequence or a string.
296 For example:
297
298 * ``color='white'``
299 * ``color='w'``
300 * ``color=[1.0, 1.0, 1.0]``
301 * ``color='#FFFFFF'``
302
303 Examples
304 --------
305 Create a light and set its ambient color to red.
306
307 >>> import pyvista as pv
308 >>> light = pv.Light()
309 >>> light.ambient_color = 'red'
310 >>> light.ambient_color
311 Color(name='red', hex='#ff0000ff', opacity=255)
312
313 """
314 return Color(self.GetAmbientColor())
315
316 @ambient_color.setter
317 def ambient_color(self, color: ColorLike):
318 self.SetAmbientColor(Color(color).float_rgb)
319
320 @property
321 def diffuse_color(self): # numpydoc ignore=RT01
322 """Return or set the diffuse color of the light.
323
324 When setting, the color must be a 3-length sequence or a string.
325 For example:
326
327 * ``color='white'``
328 * ``color='w'``
329 * ``color=[1.0, 1.0, 1.0]``
330 * ``color='#FFFFFF'``
331
332 Examples
333 --------
334 Create a light and set its diffuse color to blue.
335
336 >>> import pyvista as pv
337 >>> light = pv.Light()
338 >>> light.diffuse_color = (0.0, 0.0, 1.0)
339 >>> light.diffuse_color
340 Color(name='blue', hex='#0000ffff', opacity=255)
341
342 """
343 return Color(self.GetDiffuseColor())
344
345 @diffuse_color.setter
346 def diffuse_color(self, color: ColorLike):
347 self.SetDiffuseColor(Color(color).float_rgb)
348
349 @property
350 def specular_color(self): # numpydoc ignore=RT01
351 """Return or set the specular color of the light.
352
353 When setting, the color must be a 3-length sequence or a string.
354 For example:
355
356 * ``color='white'``
357 * ``color='w'``
358 * ``color=[1.0, 1.0, 1.0]``
359 * ``color='#FFFFFF'``
360
361 Examples
362 --------
363 Create a light and set its specular color to bright green.
364
365 >>> import pyvista as pv
366 >>> light = pv.Light()
367 >>> light.specular_color = '#00FF00'
368 >>> light.specular_color
369 Color(name='lime', hex='#00ff00ff', opacity=255)
370
371 """
372 return Color(self.GetSpecularColor())
373
374 @specular_color.setter
375 def specular_color(self, color: ColorLike):
376 self.SetSpecularColor(Color(color).float_rgb)
377
378 @property
379 def position(self): # numpydoc ignore=RT01
380 """Return the position of the light.
381
382 Note: the position is defined in the coordinate space
383 indicated by the light's transformation matrix (if it
384 exists). To get the light's world space position, use the
385 (read-only) :py:attr:`world_position` property.
386
387 Examples
388 --------
389 Create a light positioned at ``(10, 10, 10)`` after
390 initialization, and note how the position is unaffected by a
391 non-trivial transform matrix.
392
393 >>> import numpy as np
394 >>> import pyvista as pv
395 >>> light = pv.Light()
396 >>> light.position = (10, 10, 10)
397 >>> # set a "random" transformation matrix
398 >>> light.transform_matrix = np.arange(4 * 4).reshape(4, 4)
399 >>> light.position
400 (10.0, 10.0, 10.0)
401
402 """
403 return self.GetPosition()
404
405 @position.setter
406 def position(self, pos):
407 self.SetPosition(pos)
408
409 @property
410 def world_position(self): # numpydoc ignore=RT01
411 """Return the world space position of the light.
412
413 The world space position is the :py:attr:`position` property
414 transformed by the light's transform matrix if it exists. The
415 value of this read-only property corresponds to the
416 :vtk:`vtkLight.GetTransformedPosition` method.
417
418 Examples
419 --------
420 Create a light with a transformation matrix that corresponds to a
421 90-degree rotation around the z-axis and a shift by (0, 0, -1), and
422 check that the light's position transforms as expected.
423
424 >>> import numpy as np
425 >>> import pyvista as pv
426 >>> light = pv.Light(position=(1, 0, 3))
427 >>> trans = np.zeros((4, 4))
428 >>> trans[:-1, :-1] = [[0, -1, 0], [1, 0, 0], [0, 0, 1]]
429 >>> trans[:-1, -1] = [0, 0, -1]
430 >>> light.transform_matrix = trans
431 >>> light.position
432 (1.0, 0.0, 3.0)
433 >>> light.world_position
434 (0.0, 1.0, 2.0)
435
436 """
437 return self.GetTransformedPosition()
438
439 @property
440 def focal_point(self): # numpydoc ignore=RT01
441 """Return the focal point of the light.
442
443 Note: the focal point is defined in the coordinate space
444 indicated by the light's transformation matrix (if it
445 exists). To get the light's world space focal point, use the
446 (read-only) :py:attr:`world_focal_point` property.
447
448 Examples
449 --------
450 Create a light at (10, 10, 10) shining at (0, 0, 1).
451
452 >>> import pyvista as pv
453 >>> light = pv.Light(position=(10, 10, 10))
454 >>> light.focal_point = (0, 0, 1)
455
456 """
457 return self.GetFocalPoint()
458
459 @focal_point.setter
460 def focal_point(self, pos):
461 self.SetFocalPoint(pos)
462
463 @property
464 def world_focal_point(self): # numpydoc ignore=RT01
465 """Return the world space focal point of the light.
466
467 The world space focal point is the :py:attr:`focal_point`
468 property transformed by the light's transform matrix if it
469 exists. The value of this read-only property corresponds to
470 the :vtk:`vtkLight.GetTransformedFocalPoint` method.
471
472 Examples
473 --------
474 Create a light with a transformation matrix that corresponds
475 to a 90-degree rotation around the z-axis and a shift by (0,
476 0, -1), and check that the light's focal point transforms as
477 expected.
478
479 >>> import numpy as np
480 >>> import pyvista as pv
481 >>> light = pv.Light(focal_point=(1, 0, 3))
482 >>> trans = np.zeros((4, 4))
483 >>> trans[:-1, :-1] = [[0, -1, 0], [1, 0, 0], [0, 0, 1]]
484 >>> trans[:-1, -1] = [0, 0, -1]
485 >>> light.transform_matrix = trans
486 >>> light.focal_point
487 (1.0, 0.0, 3.0)
488 >>> light.world_focal_point
489 (0.0, 1.0, 2.0)
490
491 """
492 return self.GetTransformedFocalPoint()
493
494 @property
495 def intensity(self): # numpydoc ignore=RT01
496 """Return or set the brightness of the light (between 0 and 1).
497
498 Examples
499 --------
500 Light the two sides of a cube with lights of different
501 brightness.
502
503 >>> import pyvista as pv
504 >>> pl = pv.Plotter(lighting='none')
505 >>> _ = pl.add_mesh(pv.Cube(), color='cyan')
506 >>> light_bright = pv.Light(position=(3, 0, 0), light_type='scene light')
507 >>> light_dim = pv.Light(position=(0, 3, 0), light_type='scene light')
508 >>> light_dim.intensity = 0.5
509 >>> for light in light_bright, light_dim:
510 ... light.positional = True
511 ... pl.add_light(light)
512 >>> pl.show()
513
514 """
515 return self.GetIntensity()
516
517 @intensity.setter
518 def intensity(self, intensity):
519 self.SetIntensity(intensity)
520
521 @property
522 def on(self): # numpydoc ignore=RT01
523 """Return or set whether the light is on.
524
525 This corresponds to the Switch state of the :vtk:`vtkLight` class.
526
527 Examples
528 --------
529 Create a light, check if it's on by default, and turn it off.
530
531 >>> import pyvista as pv
532 >>> light = pv.Light()
533 >>> light.on
534 True
535 >>> light.on = False
536
537 """
538 return bool(self.GetSwitch())
539
540 @on.setter
541 def on(self, state):
542 self.SetSwitch(state)
543
544 @property
545 def positional(self): # numpydoc ignore=RT01
546 """Return or set whether the light is positional.
547
548 The default is a directional light, i.e. an infinitely distant
549 point source. A positional light with a cone angle of at least
550 90 degrees acts like a spherical point source. A positional
551 light with a cone angle that is less than 90 degrees is known
552 as a spotlight.
553
554 Attenuation and cone angles are only used for positional
555 lights. The :py:attr:`exponent` property is only used for
556 spotlights. Positional lights with a cone angle of at least
557 90 degrees don't show angular dependence of their beams, but
558 they display attenuation.
559
560 If the light is changed to directional, its actor (if previously
561 shown) is automatically hidden.
562
563 Examples
564 --------
565 Create a spotlight shining on the origin.
566
567 >>> import pyvista as pv
568 >>> light = pv.Light(position=(1, 1, 1))
569 >>> light.positional = True
570 >>> light.cone_angle = 30
571
572 """
573 return bool(self.GetPositional())
574
575 @positional.setter
576 def positional(self, state):
577 if not state:
578 self.hide_actor()
579 self.SetPositional(state)
580 self._check_actor()
581
582 def _check_actor(self):
583 """Check if the light actor should be added or removed from attached renderers.
584
585 This should be called whenever positional state or cone angle
586 are changed.
587
588 """
589 if self.actor is None:
590 # only should occur on __init__
591 return
592
593 actor_state = self.cone_angle < 90 and self.positional
594 actor_name = self.actor.GetAddressAsString('')
595
596 # add or remove the actor from the renderer
597 for renderer in self._renderers:
598 if actor_state:
599 if actor_name not in renderer.actors:
600 renderer.add_actor(self.actor, render=False)
601 elif actor_name in renderer.actors:
602 renderer.remove_actor(self.actor, render=False)
603
604 @property
605 def exponent(self): # numpydoc ignore=RT01
606 """Return or set the exponent of the cosine used for spotlights.
607
608 With a spotlight (a positional light with cone angle less than
609 90 degrees) the shape of the light beam within the light cone
610 varies with the angle from the light's axis, and the variation
611 of the intensity depends as the cosine of this angle raised to
612 an exponent, which is 1 by default. Increasing the exponent
613 makes the beam sharper (more focused around the axis),
614 decreasing it spreads the beam out.
615
616 Note that since the angular dependence defined by this
617 property and the truncation performed by the
618 :py:attr:`cone_angle` are independent, for spotlights with
619 narrow beams (small :py:attr:`cone_angle`) it is harder to see
620 the angular variation of the intensity, and a lot higher
621 exponent might be necessary to visibly impact the angular
622 distribution of the beam.
623
624 Examples
625 --------
626 Plot three planes lit by three spotlights with exponents of 1,
627 2 and 5. The one with the lowest exponent has the broadest
628 beam.
629
630 >>> import pyvista as pv
631 >>> pl = pv.Plotter(lighting='none')
632 >>> for offset, exponent in zip([0, 1.5, 3], [1, 2, 5]):
633 ... _ = pl.add_mesh(pv.Plane(center=(offset, 0, 0)), color='white')
634 ... light = pv.Light(
635 ... position=(offset, 0, 0.1),
636 ... focal_point=(offset, 0, 0),
637 ... )
638 ... light.exponent = exponent
639 ... light.positional = True
640 ... light.cone_angle = 80
641 ... pl.add_light(light)
642 >>> pl.view_xy()
643 >>> pl.show()
644
645 """
646 return self.GetExponent()
647
648 @exponent.setter
649 def exponent(self, exp):
650 self.SetExponent(exp)
651
652 @property
653 def cone_angle(self): # numpydoc ignore=RT01
654 """Return or set the cone angle of a positional light.
655
656 The angle is in degrees and is measured between the axis of
657 the cone and an extremal ray of the cone. A value smaller than
658 90 has spot lighting effects, anything equal to and above 90
659 is just a positional light, i.e. a spherical point source.
660
661 Regarding the angular distribution of the light, the cone
662 angle merely truncates the beam, the shape of which is defined
663 by the :py:attr:`exponent`. If the cone angle is at least 90
664 degrees then there is no angular dependence.
665
666 If the light's cone angle is increased to 90 degrees or above,
667 its actor (if previously shown) is automatically hidden.
668
669 See Also
670 --------
671 :ref:`beam_shape_example`
672
673 Examples
674 --------
675 Plot three planes lit by three spotlights with varying cone
676 angles. Use a large exponent to cause a visible angular
677 variation of the intensity of the beams.
678
679 >>> import pyvista as pv
680 >>> pl = pv.Plotter(lighting='none')
681 >>> for offset, angle in zip([0, 1.5, 3], [70, 30, 20]):
682 ... _ = pl.add_mesh(pv.Plane(center=(offset, 0, 0)), color='white')
683 ... light = pv.Light(position=(offset, 0, 1), focal_point=(offset, 0, 0))
684 ... light.exponent = 15
685 ... light.positional = True
686 ... light.cone_angle = angle
687 ... pl.add_light(light)
688 >>> pl.view_xy()
689 >>> pl.show()
690
691 """
692 return self.GetConeAngle()
693
694 @cone_angle.setter
695 def cone_angle(self, angle):
696 if angle >= 90:
697 self.hide_actor()
698 self.SetConeAngle(angle)
699 self._check_actor()
700
701 @property
702 def attenuation_values(self): # numpydoc ignore=RT01
703 """Return or set the quadratic attenuation constants.
704
705 The values are 3-length sequences which specify the constant,
706 linear and quadratic constants in this order. These parameters
707 only have an effect for positional lights.
708
709 Attenuation refers to the dampening of a beam of light as it
710 gets further away from the point source. The three constants
711 describe three different profiles for dampening with
712 distance. A larger attenuation constant corresponds to more
713 rapid decay with distance.
714
715 See Also
716 --------
717 :ref:`attenuation_example`
718
719 Examples
720 --------
721 Plot three cubes lit by two lights with different attenuation
722 profiles. The blue light has slower linear attenuation, the
723 green one has quadratic attenuation that makes it decay
724 faster. Note that there are no shadow effects included so each
725 box gets lit by both lights.
726
727 >>> import pyvista as pv
728 >>> pl = pv.Plotter(lighting='none')
729 >>> for offset in 1, 2.5, 4:
730 ... _ = pl.add_mesh(pv.Cube(center=(offset, offset, 0)), color='white')
731 >>> colors = ['b', 'g']
732 >>> all_attenuations = [(0, 0.1, 0), (0, 0, 0.1)]
733 >>> centers = [(0, 1, 0), (1, 0, 0)]
734 >>> for color, attenuation_constants, center in zip(
735 ... colors, all_attenuations, centers
736 ... ):
737 ... light = pv.Light(position=center, color=color)
738 ... light.focal_point = (1 + center[0], 1 + center[1], 0)
739 ... light.cone_angle = 90
740 ... light.positional = True
741 ... light.attenuation_values = attenuation_constants
742 ... pl.add_light(light)
743 >>> pl.view_vector((-1, -1, 1))
744 >>> pl.show()
745
746 """
747 return self.GetAttenuationValues()
748
749 @attenuation_values.setter
750 def attenuation_values(self, values):
751 self.SetAttenuationValues(values)
752
753 @property
754 def transform_matrix(self): # numpydoc ignore=RT01
755 """Return (if any) or set the transformation matrix of the light.
756
757 The transformation matrix is ``None`` by default, and it is
758 stored as a :vtk:`vtkMatrix4x4` object when set. If set, the
759 light's parameters (position and focal point) are transformed
760 by the matrix before being rendered. See also the
761 :py:attr:`world_position` and :py:attr:`world_focal_point`
762 read-only properties that can differ from :py:attr:`position`
763 and :py:attr:`focal_point`, respectively.
764
765 The 4-by-4 transformation matrix is a tool to encode a general
766 linear transformation and a translation (an affine
767 transform). The 3-by-3 principal submatrix (the top left
768 corner of the matrix) encodes a three-dimensional linear
769 transformation (e.g. some rotation around the origin). The top
770 three elements in the last column of the matrix encode a
771 three-dimensional translation. The last row of the matrix is
772 redundant.
773
774 Examples
775 --------
776 Create a light with a transformation matrix that corresponds
777 to a 90-degree rotation around the z-axis and a shift by (0,
778 0, -1), and check that the light's position transforms as
779 expected.
780
781 >>> import numpy as np
782 >>> import pyvista as pv
783 >>> light = pv.Light(position=(1, 0, 3))
784 >>> trans = np.zeros((4, 4))
785 >>> trans[:-1, :-1] = [[0, -1, 0], [1, 0, 0], [0, 0, 1]]
786 >>> trans[:-1, -1] = [0, 0, -1]
787 >>> light.transform_matrix = trans
788 >>> light.position
789 (1.0, 0.0, 3.0)
790 >>> light.world_position
791 (0.0, 1.0, 2.0)
792
793 """
794 return self.GetTransformMatrix()
795
796 @transform_matrix.setter
797 def transform_matrix(self, matrix: TransformLike):
798 if matrix is None or isinstance(matrix, _vtk.vtkMatrix4x4):
799 self.SetTransformMatrix(matrix)
800 else:
801 trans = _validation.validate_transform4x4(matrix)
802 self.SetTransformMatrix(vtkmatrix_from_array(trans))
803
804 @property
805 def light_type(self): # numpydoc ignore=RT01
806 """Return or set the light type.
807
808 The default light type is a scene light which lives in world
809 coordinate space.
810
811 A headlight is attached to the camera and always points at the
812 camera's focal point.
813
814 A camera light also moves with the camera, but it can have an
815 arbitrary relative position to the camera. Camera lights are
816 defined in a coordinate space where the camera is located at
817 (0, 0, 1), looking towards (0, 0, 0) at a distance of 1, with
818 up being (0, 1, 0). Camera lights use the transform matrix to
819 establish this space, i.e. they have a fixed :py:attr:`position`
820 with respect to the camera, and moving the camera only
821 affects the :py:attr:`world_position` via changes in the
822 :py:attr:`transform_matrix` (and the same goes for the focal
823 point).
824
825 The property returns class constant values from an enum:
826
827 - ``Light.HEADLIGHT == 1``
828 - ``Light.CAMERA_LIGHT == 2``
829 - ``Light.SCENE_LIGHT == 3``
830
831 If setting the value, either an integer code or a class constant enum
832 value must be used.
833
834 Examples
835 --------
836 Check the type of lights for the first two lights of the default
837 light kit of plotters.
838
839 >>> import pyvista as pv
840 >>> pl = pv.Plotter()
841 >>> lights = pl.renderer.lights[:2]
842 >>> [light.light_type for light in lights]
843 [<LightType.HEADLIGHT: 1>, <LightType.CAMERA_LIGHT: 2>]
844
845 Change the light type of the default light kit's headlight to a scene light.
846
847 >>> import pyvista as pv
848 >>> pl = pv.Plotter()
849 >>> lights = pl.renderer.lights[:2]
850 >>> lights[0].light_type = pv.Light.SCENE_LIGHT
851 >>> [light.light_type for light in lights]
852 [<LightType.SCENE_LIGHT: 3>, <LightType.CAMERA_LIGHT: 2>]
853
854 """
855 return LightType(self.GetLightType())
856
857 @light_type.setter
858 def light_type(self, ltype):
859 if not isinstance(ltype, int):
860 # note that LightType is an int subclass
861 msg = f'Light type must be an integer subclass instance, got {ltype} instead.'
862 raise TypeError(msg)
863 self.SetLightType(ltype)
864
865 @property
866 def is_headlight(self): # numpydoc ignore=RT01
867 """Return whether the light is a headlight.
868
869 Examples
870 --------
871 Verify that the first light of the default light kit is a headlight.
872
873 >>> import pyvista as pv
874 >>> pl = pv.Plotter()
875 >>> lights = pl.renderer.lights
876 >>> [light.is_headlight for light in lights]
877 [True, False, False, False, False]
878
879 """
880 return bool(self.LightTypeIsHeadlight())
881
882 @property
883 def is_camera_light(self): # numpydoc ignore=RT01
884 """Return whether the light is a camera light.
885
886 Examples
887 --------
888 Verify that four out of five lights of the default light kit
889 are camera lights.
890
891 >>> import pyvista as pv
892 >>> pl = pv.Plotter()
893 >>> lights = pl.renderer.lights
894 >>> [light.is_camera_light for light in lights]
895 [False, True, True, True, True]
896
897 """
898 return bool(self.LightTypeIsCameraLight())
899
900 @property
901 def is_scene_light(self): # numpydoc ignore=RT01
902 """Return whether the light is a scene light.
903
904 Examples
905 --------
906 Verify that none of the lights of the default light kit are
907 scene lights.
908
909 >>> import pyvista as pv
910 >>> pl = pv.Plotter()
911 >>> lights = pl.renderer.lights
912 >>> [light.is_scene_light for light in lights]
913 [False, False, False, False, False]
914
915 """
916 return bool(self.LightTypeIsSceneLight())
917
918 def switch_on(self):
919 """Switch on the light.
920
921 Examples
922 --------
923 Create a light, switch it off and switch it back on again.
924
925 >>> import pyvista as pv
926 >>> light = pv.Light()
927 >>> light.on = False
928 >>> light.switch_on()
929
930 """
931 self.SwitchOn()
932
933 def switch_off(self):
934 """Switch off the light.
935
936 Examples
937 --------
938 Create a light and switch it off.
939
940 >>> import pyvista as pv
941 >>> light = pv.Light()
942 >>> light.switch_off()
943
944 """
945 self.SwitchOff()
946
947 def set_direction_angle(self, elev, azim):
948 """Set the position and focal point of a directional light.
949
950 The light is switched to directional (non-positional). The
951 focal point is set to the origin. The position is defined in
952 terms of an elevation and an azimuthal angle, both in degrees.
953
954 Note that the equivalent :vtk:`vtkLight.SetDirectionAngle` method
955 uses a surprising coordinate system where the (x', y', z') axes of
956 the method correspond to the (z, x, y) axes of the renderer.
957 This method reimplements the functionality in a way that ``elev``
958 is the conventional elevation and ``azim`` is the conventional azimuth.
959 In particular:
960
961 * ``elev = 0``, ``azim = 0`` is the +x direction
962 * ``elev = 0``, ``azim = 90`` is the +y direction
963 * ``elev = 90``, ``azim = 0`` is the +z direction
964
965 Parameters
966 ----------
967 elev : float
968 The elevation of the directional light.
969
970 azim : float
971 The azimuthal angle of the directional light.
972
973 Examples
974 --------
975 Create a light that shines on the origin from a 30-degree
976 elevation in the xz plane.
977
978 >>> import pyvista as pv
979 >>> light = pv.Light()
980 >>> light.set_direction_angle(30, 0)
981
982 """
983 self.positional = False
984 self.focal_point = (0, 0, 0)
985 theta = np.radians(90 - elev)
986 phi = np.radians(azim)
987 self.position = (np.sin(theta) * np.cos(phi), np.sin(theta) * np.sin(phi), np.cos(theta))
988
989 @_deprecate_positional_args
990 def copy(self, deep=True): # noqa: FBT002
991 """Return a shallow or a deep copy of the light.
992
993 The only mutable attribute of :class:`pyvista.Light` is the
994 transformation matrix (if it exists). Thus asking for a
995 shallow copy merely implies that the returned light and the
996 original share the transformation matrix instance.
997
998 Parameters
999 ----------
1000 deep : bool, default: True
1001 Whether to return a deep copy rather than a shallow
1002 one.
1003
1004 Returns
1005 -------
1006 pyvista.Light
1007 Copied light.
1008
1009 Examples
1010 --------
1011 Create a light and check that it shares a transformation
1012 matrix with its shallow copy.
1013
1014 >>> import pyvista as pv
1015 >>> light = pv.Light()
1016 >>> light.transform_matrix = [
1017 ... [1, 0, 0, 0],
1018 ... [0, 1, 0, 0],
1019 ... [0, 0, 1, 0],
1020 ... [0, 0, 0, 1],
1021 ... ]
1022 >>> shallow_copied = light.copy(deep=False)
1023 >>> shallow_copied == light
1024 True
1025 >>> shallow_copied.transform_matrix is light.transform_matrix
1026 True
1027
1028 """
1029 immutable_attrs = [
1030 'light_type',
1031 'position',
1032 'focal_point',
1033 'ambient_color',
1034 'diffuse_color',
1035 'specular_color',
1036 'intensity',
1037 'on',
1038 'positional',
1039 'exponent',
1040 'cone_angle',
1041 'attenuation_values',
1042 'shadow_attenuation',
1043 ]
1044 new_light = Light()
1045
1046 for attr in immutable_attrs:
1047 value = getattr(self, attr)
1048 setattr(new_light, attr, value)
1049
1050 if deep and self.transform_matrix is not None:
1051 new_light.transform_matrix = _vtk.vtkMatrix4x4()
1052 new_light.transform_matrix.DeepCopy(self.transform_matrix)
1053 else:
1054 new_light.transform_matrix = self.transform_matrix
1055
1056 # light actors are private, always copy, but copy visibility state as well
1057 new_light.actor.SetVisibility(self.actor.GetVisibility()) # type: ignore[union-attr]
1058
1059 return new_light
1060
1061 def set_headlight(self):
1062 """Set the light to be a headlight.
1063
1064 Headlights are fixed to the camera and always point to the
1065 focal point of the camera. Calling this method will reset the
1066 light's transformation matrix.
1067
1068 Examples
1069 --------
1070 >>> import pyvista as pv
1071 >>> light = pv.Light()
1072 >>> light.set_headlight()
1073 >>> light.light_type
1074 <LightType.HEADLIGHT: 1>
1075
1076 """
1077 self.SetLightTypeToHeadlight()
1078
1079 def set_camera_light(self):
1080 """Set the light to be a camera light.
1081
1082 A camera light moves with the camera, but it can have an
1083 arbitrary relative position to the camera. Camera lights are
1084 defined in a coordinate space where the camera is located at
1085 (0, 0, 1), looking towards (0, 0, 0) at a distance of 1, with
1086 up being (0, 1, 0). Camera lights use the transformation
1087 matrix to establish this space. Calling this method will
1088 reset the light's transformation matrix.
1089
1090 Examples
1091 --------
1092 >>> import pyvista as pv
1093 >>> light = pv.Light()
1094 >>> light.set_camera_light()
1095 >>> light.light_type
1096 <LightType.CAMERA_LIGHT: 2>
1097
1098 """
1099 self.SetLightTypeToCameraLight()
1100
1101 def set_scene_light(self):
1102 """Set the light to be a scene light.
1103
1104 Scene lights are stationary with respect to the scene.
1105 Calling this method will reset the light's transformation
1106 matrix.
1107
1108 Examples
1109 --------
1110 >>> import pyvista as pv
1111 >>> light = pv.Light()
1112 >>> light.set_scene_light()
1113 >>> light.light_type
1114 <LightType.SCENE_LIGHT: 3>
1115
1116 """
1117 self.SetLightTypeToSceneLight()
1118
1119 @classmethod
1120 def from_vtk(cls, vtk_light):
1121 """Create a light from a :vtk:`vtkLight`, resulting in a copy.
1122
1123 Parameters
1124 ----------
1125 vtk_light : :vtk:`vtkLight`
1126 The :vtk:`vtkLight` to be copied.
1127
1128 Returns
1129 -------
1130 pyvista.Light
1131 Wrapped light.
1132
1133 """
1134 if not isinstance(vtk_light, _vtk.vtkLight):
1135 msg = f'Expected vtk.vtkLight object, got {type(vtk_light).__name__} instead.'
1136 raise TypeError(msg)
1137
1138 light = cls()
1139 light.light_type = vtk_light.GetLightType() # resets transformation matrix
1140 light.position = vtk_light.GetPosition()
1141 light.focal_point = vtk_light.GetFocalPoint()
1142 light.ambient_color = vtk_light.GetAmbientColor()
1143 light.diffuse_color = vtk_light.GetDiffuseColor()
1144 light.specular_color = vtk_light.GetSpecularColor()
1145 light.intensity = vtk_light.GetIntensity()
1146 light.on = vtk_light.GetSwitch()
1147 light.positional = vtk_light.GetPositional()
1148 light.exponent = vtk_light.GetExponent()
1149 light.cone_angle = vtk_light.GetConeAngle()
1150 light.attenuation_values = vtk_light.GetAttenuationValues()
1151 trans = vtk_light.GetTransformMatrix()
1152 light.transform_matrix = trans
1153 light.shadow_attenuation = vtk_light.GetShadowAttenuation()
1154
1155 return light
1156
1157 def show_actor(self):
1158 """Show an actor for a spotlight that depicts the geometry of the beam.
1159
1160 For a directional light or a positional light with
1161 :py:attr:`cone_angle` of at least 90 degrees the method
1162 doesn't do anything. If the light is changed so that it
1163 becomes a spotlight, this method has to be called again for
1164 the actor to show. To hide the actor see :func:`hide_actor`.
1165
1166 Examples
1167 --------
1168 Create a scene containing a cube lit with a cyan spotlight and
1169 visualize the light using an actor.
1170
1171 >>> import pyvista as pv
1172 >>> pl = pv.Plotter()
1173 >>> _ = pl.add_mesh(pv.Cube(), color='white')
1174 >>> for light in pl.renderer.lights:
1175 ... light.intensity /= 5
1176 >>> spotlight = pv.Light(position=(-1, 1, 1), color='cyan')
1177 >>> spotlight.positional = True
1178 >>> spotlight.cone_angle = 20
1179 >>> spotlight.intensity = 10
1180 >>> spotlight.exponent = 40
1181 >>> spotlight.show_actor()
1182 >>> pl.add_light(spotlight)
1183 >>> pl.show()
1184
1185 """
1186 if not self.positional or self.cone_angle >= 90:
1187 return
1188 self.actor.VisibilityOn() # type: ignore[union-attr]
1189
1190 def hide_actor(self):
1191 """Hide the actor for a positional light that depicts the geometry of the beam.
1192
1193 For a directional light the function doesn't do anything.
1194
1195 Examples
1196 --------
1197 >>> import pyvista as pv
1198 >>> light = pv.Light()
1199 >>> light.hide_actor()
1200
1201 """
1202 if not self.positional:
1203 return
1204 self.actor.VisibilityOff() # type: ignore[union-attr]
1205
1206 @property
1207 def renderers(self): # numpydoc ignore=RT01
1208 """Return the renderers associated with this light."""
1209 return self._renderers
1210
1211 def add_renderer(self, renderer):
1212 """Attach a renderer to this light.
1213
1214 Parameters
1215 ----------
1216 renderer : :vtk:`vtkRenderer`
1217 Renderer.
1218
1219 """
1220 # quick check to avoid adding twice
1221 if renderer not in self.renderers:
1222 self.renderers.append(renderer)
1223
1224 # verify that the renderer has the light actor if applicable
1225 self._check_actor()