Lights¶
The pyvista.Light
class adds additional functionality and a pythonic API
to the vtk.vtkLight
class. pyvista.Plotter
objects come with a default
set of lights that work well in most cases, but in many situations a more hands-on
access to lighting is necessary.
Brief Example¶
Create a red spotlight that shines on the origin.
import pyvista as pv
from pyvista import examples
light = pv.Light(position=(-1, 1, 1), color='red')
light.positional = True
Create a scene without lighting and add our light to it manually.
plotter = pv.Plotter(lighting='none')
mesh = examples.download_bunny()
mesh.rotate_x(90)
mesh.rotate_z(180)
plotter.add_mesh(mesh, specular=1.0, diffuse=0.7, smooth_shading=True)
plotter.add_light(light)
plotter.show(screenshot='ominous_bunny.png')

For detailed examples please see Lighting.
Light API¶
pyvista.Light
instances come in three types: headlights, camera lights, and
scene lights. Headlights always shine along the camera’s axis, camera lights
have a fixed position with respect to the camera, and scene lights are positioned
with respect to the scene, such that moving around the camera doesn’t affect the
lighting of the scene.
Lights have a position
and a focal_point
that define the
axis of the light. The meaning of these depends on the type of the light. The
color of the light can be set according to ambient, diffuse and specular components.
The brightness can be set with the intensity
property, and the writable
on
property specifies whether the light is switched on.
Lights can be either directional (meaning an infinitely distant point source) or
positional
. Positional lights have additional properties that describe
the geometry and the spatial distribution of the light. The cone_angle
and exponent
properties define the shape of the light beam and the
angular distribution of the light’s intensity within that beam. The fading of the
light with distance can be customized with the attenuation_values
property.
Positional lights can also make use of an actor that represents the shape and color
of the light using a wireframe, see show_actor()
.
Positional lights with a cone_angle
of less than 90 degrees are known as
spotlights. Spotlights are unidirectional and they make full use of beam shaping
properties, namely exponent
and attenuation. Non-spotlight positional
lights, however, act like point sources located in the real-world position of the
light, shining in all directions of space. They display attenuation with distance
from the source, but their beam is isotropic in space. In contrast, directional
lights act as infinitely distant point sources, so they are unidirectional but they do
not attenuate.
API reference¶
-
class
pyvista.
Light
(position=None, focal_point=None, color=None, light_type='scene light')¶ Light class.
- Parameters
position (list or tuple, optional) – The position of the light. The interpretation of the position depends on the type of the light and whether the light has a transformation matrix. See also the
position
property.focal_point (list or tuple, optional) – The focal point of the light. The interpretation of the focal point depends on the type of the light and whether the light has a transformation matrix. See also the
focal_point
property.color (string or 3-length sequence, optional) – The color of the light. The ambient, diffuse and specular colors will all be set to this color on creation.
light_type (string or int, optional) –
The type of the light. If a string, one of
'headlight'
,'camera light'
or'scene light'
. If an int, one of 1, 2 or 3, respectively. The class constantsLight.HEADLIGHT
,Light.CAMERA_LIGHT
andLight.SCENE_LIGHT
are also available, respectively.A headlight is attached to the camera, looking at its focal point along the axis of the camera. A camera light also moves with the camera, but it can occupy a general position with respect to it. A scene light is stationary with respect to the scene, as it does not follow the camera. This is the default.
Examples
Create a light at (10, 10, 10) and set its diffuse color to red.
>>> import pyvista as pv >>> light = pv.Light(position=(10, 10, 10)) >>> light.diffuse_color = 1, 0, 0
-
property
ambient_color
¶ Return the ambient color of the light.
When setting, the color must be a 3-length sequence or a string. For example:
color='white'
color='w'
color=[1, 1, 1]
color='#FFFFFF'
Examples
Create a light and set its ambient color to red.
>>> import pyvista as pv >>> light = pv.Light() >>> light.ambient_color = 'red'
-
property
attenuation_values
¶ Return the quadratic attenuation constants.
The values are 3-length sequences which specify the constant, linear and quadratic constants in this order. These parameters only have an effect for positional lights.
Attenuation refers to the dampening of a beam of light as it gets further away from the point source. The three constants describe three different profiles for dampening with distance. A larger attenuation constant corresponds to more rapid decay with distance.
Examples
Plot three cubes lit by two lights with different attenuation profiles. The blue light has slower linear attenuation, the green one has quadratic attenuation that makes it decay faster. Note that there are no shadow effects included so each box gets lit by both lights.
>>> import pyvista as pv >>> plotter = pv.Plotter(lighting='none') >>> for offset in 1, 2.5, 4: ... _ = plotter.add_mesh(pv.Cube(center=(offset, offset, 0)), color='white') ... >>> colors = ['b', 'g'] >>> all_attenuations = [(0, 0.1, 0), (0, 0, 0.1)] >>> centers = [(0, 1, 0), (1, 0, 0)] >>> for color, attenuation_constants, center in zip(colors, all_attenuations, centers): ... light = pv.Light(position=center, color=color) ... light.focal_point = (1 + center[0], 1 + center[1], 0) ... light.cone_angle = 90 ... light.positional = True ... light.attenuation_values = attenuation_constants ... plotter.add_light(light) ... >>> plotter.view_vector((-1, -1, 1)) >>> plotter.show()
-
property
cone_angle
¶ Return the cone angle of a positional light.
The angle is in degrees and is measured between the axis of the cone and an extremal ray of the cone. A value smaller than 90 has spot lighting effects, anything equal to and above 90 is just a positional light, i.e. a spherical point source.
Regarding the angular distribution of the light, the cone angle merely truncates the beam, the shape of which is defined by the
exponent
. If the cone angle is at least 90 degrees then there is no angular dependence.If the light’s cone angle is increased to 90 degrees or above, its actor (if previousy shown) is automatically hidden.
Examples
Plot three planes lit by three spotlights with varying cone angles. Use a large exponent to cause a visible angular variation of the intensity of the beams.
>>> import pyvista as pv >>> plotter = pv.Plotter(lighting='none') >>> for offset, angle in zip([0, 1.5, 3], [70, 30, 20]): ... _ = plotter.add_mesh(pv.Plane((offset, 0, 0)), color='white') ... light = pv.Light(position=(offset, 0, 1), focal_point=(offset, 0, 0)) ... light.exponent = 15 ... light.positional = True ... light.cone_angle = angle ... plotter.add_light(light) ... >>> plotter.view_xy() >>> plotter.show()
-
copy
(deep=True)¶ Return a shallow or a deep copy of the light.
The only mutable attribute of
Light
objects is the transformation matrix (if it exists). Thus asking for a shallow copy merely implies that the returned light and the original share the transformation matrix instance.- Parameters
deep (bool) – Whether to return a deep copy rather than a shallow one. Default
True
.
Examples
Create a light and check that it shares a transformation matrix with its shallow copy.
>>> import pyvista as pv >>> light = pv.Light() >>> light.transform_matrix = [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]] >>> shallow_copied = light.copy(deep=False) >>> shallow_copied == light True >>> shallow_copied.transform_matrix is light.transform_matrix True
-
property
diffuse_color
¶ Return the diffuse color of the light.
When setting, the color must be a 3-length sequence or a string. For example:
color='white'
color='w'
color=[1, 1, 1]
color='#FFFFFF'
Examples
Create a light and set its diffuse color to blue.
>>> import pyvista as pv >>> light = pv.Light() >>> light.diffuse_color = (0, 0, 1)
-
property
exponent
¶ Return the exponent of the cosine used for spotlights.
With a spotlight (a positional light with cone angle less than 90 degrees) the shape of the light beam within the light cone varies with the angle from the light’s axis, and the variation of the intensity depends as the cosine of this angle raised to an exponent, which is 1 by default. Increasing the exponent makes the beam sharper (more focused around the axis), decreasing it spreads the beam out.
Note that since the angular dependence defined by this property and the truncation performed by the
cone_angle
are independent, for spotlights with narrow beams (smallcone_angle
) it is harder to see the angular variation of the intensity, and a lot higher exponent might be necessary to visibly impact the angular distribution of the beam.Examples
Plot three planes lit by three spotlights with exponents of 1, 2 and 5. The one with the lowest exponent has the broadest beam.
>>> import pyvista as pv >>> plotter = pv.Plotter(lighting='none') >>> for offset, exponent in zip([0, 1.5, 3], [1, 2, 5]): ... _ = plotter.add_mesh(pv.Plane((offset, 0, 0)), color='white') ... light = pv.Light(position=(offset, 0, 0.1), focal_point=(offset, 0, 0)) ... light.exponent = exponent ... light.positional = True ... light.cone_angle = 80 ... plotter.add_light(light) ... >>> plotter.view_xy() >>> plotter.show()
-
property
focal_point
¶ Return the focal point of the light.
Note: the focal point is defined in the coordinate space indicated by the light’s transformation matrix (if it exists). To get the light’s world space focal point, use the (read-only)
world_focal_point
property.Examples
Create a light at (10, 10, 10) shining at (0, 0, 1).
>>> import pyvista as pv >>> light = pv.Light(position=(10, 10, 10)) >>> light.focal_point = (0, 0, 1)
-
classmethod
from_vtk
(vtk_light)¶ Create a light from a
vtk.vtkLight
, resulting in a copy.- Parameters
vtk_light (vtk.vtkLight) – The
vtk.vtkLight
to be copied.
-
hide_actor
()¶ Hide the actor for a positional light that depicts the geometry of the beam.
For a directional light the function doesn’t do anything.
-
property
intensity
¶ Return the brightness of the light (between 0 and 1).
Examples
Light the two sides of a cube with lights of different brightness.
>>> import pyvista as pv >>> plotter = pv.Plotter(lighting='none') >>> _ = plotter.add_mesh(pv.Cube(), color='cyan') >>> light_bright = pv.Light(position=(3, 0, 0), light_type='scene light') >>> light_dim = pv.Light(position=(0, 3, 0), light_type='scene light') >>> light_dim.intensity = 0.5 >>> for light in light_bright, light_dim: ... light.positional = True ... plotter.add_light(light) ... >>> plotter.show()
-
property
is_camera_light
¶ Return whether the light is a camera light.
Examples
Verify that four out of five lights of the default light kit are camera lights.
>>> import pyvista as pv >>> plotter = pv.Plotter() >>> lights = plotter.renderer.lights >>> [light.is_camera_light for light in lights] [False, True, True, True, True]
-
property
is_headlight
¶ Return whether the light is a headlight.
Examples
Verify that the first light of the default light kit is a headlight.
>>> import pyvista as pv >>> plotter = pv.Plotter() >>> lights = plotter.renderer.lights >>> [light.is_headlight for light in lights] [True, False, False, False, False]
-
property
is_scene_light
¶ Return whether the light is a scene light.
Examples
Verify that none of the lights of the default light kit are scene lights.
>>> import pyvista as pv >>> plotter = pv.Plotter() >>> lights = plotter.renderer.lights >>> [light.is_scene_light for light in lights] [False, False, False, False, False]
-
property
light_type
¶ Return the light type.
The default light type is a scene light which lives in world coordinate space.
A headlight is attached to the camera and always points at the camera’s focal point.
A camera light also moves with the camera, but it can have an arbitrary relative position to the camera. Camera lights are defined in a coordinate space where the camera is located at (0, 0, 1), looking towards (0, 0, 0) at a distance of 1, with up being (0, 1, 0). Camera lights use the transform matrix to establish this space, i.e. they have a fixed
position
with respect to the camera, and moving the camera only affects theworld_position
via changes in thetransform_matrix
(and the same goes for the focal point).The property returns class constant values from an enum:
Light.HEADLIGHT == 1
Light.CAMERA_LIGHT == 2
Light.SCENE_LIGHT == 3
Examples
Check the type of lights for the first two lights of the default light kit of plotters.
>>> import pyvista as pv >>> plotter = pv.Plotter() >>> lights = plotter.renderer.lights[:2] >>> [light.light_type for light in lights] [<LightType.HEADLIGHT: 1>, <LightType.CAMERA_LIGHT: 2>]
Change the light type of the default light kit’s headlight to a scene light.
>>> import pyvista as pv >>> plotter = pv.Plotter() >>> lights = plotter.renderer.lights[:2] >>> lights[0].light_type = pv.Light.SCENE_LIGHT >>> [light.light_type for light in lights] [<LightType.SCENE_LIGHT: 3>, <LightType.CAMERA_LIGHT: 2>]
-
property
on
¶ Return whether the light is on.
This corresponds to the Switch state of the
vtk.vtkLight
class.Examples
Create a light, check if it’s on by default, and turn it off.
>>> import pyvista as pv >>> light = pv.Light() >>> light.on True >>> light.on = False
-
property
position
¶ Return the position of the light.
Note: the position is defined in the coordinate space indicated by the light’s transformation matrix (if it exists). To get the light’s world space position, use the (read-only)
world_position
property.Examples
Create a light positioned at (10, 10, 10) after initialization, and note how the position is unaffected by a non-trivial transform matrix.
>>> import numpy as np >>> import pyvista as pv >>> light = pv.Light() >>> light.position = (10, 10, 10) >>> # set a "random" transformation matrix >>> light.transform_matrix = np.arange(4 * 4).reshape(4, 4) >>> light.position (10.0, 10.0, 10.0)
-
property
positional
¶ Return whether the light is positional.
The default is a directional light, i.e. an infinitely distant point source. A positional light with a cone angle of at least 90 degrees acts like a spherical point source. A positional light with a cone angle that is less than 90 degrees is known as a spotlight.
Attenuation and cone angles are only used for positional lights. The
exponent
property is only used for spotlights. Positional lights with a cone angle of at least 90 degrees don’t show angular dependence of their beams, but they display attenuation.If the light is changed to directional, its actor (if previousy shown) is automatically hidden.
Examples
Create a spotlight shining on the origin.
>>> import pyvista as pv >>> light = pv.Light(position=(1, 1, 1)) >>> light.positional = True >>> light.cone_angle = 30
-
set_camera_light
()¶ Set the light to be a camera light.
A camera light moves with the camera, but it can have an arbitrary relative position to the camera. Camera lights are defined in a coordinate space where the camera is located at (0, 0, 1), looking towards (0, 0, 0) at a distance of 1, with up being (0, 1, 0). Camera lights use the transformation matrix to establish this space. Calling this method will reset the light’s transformation matrix.
-
set_direction_angle
(elev, azim)¶ Set the position and focal point of a directional light.
The light is switched to directional (non-positional). The focal point is set to the origin. The position is defined in terms of an elevation and an azimuthal angle, both in degrees.
Note that the equivalent
vtk.vtkLight.SetDirectionAngle()
method uses a surprising coordinate system where the (x’, y’, z’) axes of the method correspond to the (z, x, y) axes of the renderer. This method reimplements the functionality in a way that elev is the conventional elevation and azim is the conventional azimuth. In particular:elev = 0, azim = 0 is the +x direction
elev = 0, azim = 90 is the +y direction
elev = 90, azim = 0 is the +z direction
- Parameters
elev (float) – The elevation of the directional light.
azim (float) – The azimuthal angle of the directional light.
Examples
Create a light that shines on the origin from a 30-degree elevation in the xz plane.
>>> import pyvista as pv >>> light = pv.Light() >>> light.set_direction_angle(30, 0)
-
set_headlight
()¶ Set the light to be a headlight.
Headlights are fixed to the camera and always point to the focal point of the camera. Calling this method will reset the light’s transformation matrix.
-
set_scene_light
()¶ Set the light to be a scene light.
Scene lights are stationary with respect to the scene. Calling this method will reset the light’s transformation matrix.
-
show_actor
()¶ Show an actor for a spotlight that depicts the geometry of the beam.
For a directional light or a positional light with
cone_angle
of at least 90 degrees the method doesn’t do anything. If the light is changed so that it becomes a spotlight, this method has to be called again for the actor to show. To hide the actor seehide_actor()
.Examples
Create a scene containing a cube lit with a cyan spotlight and visualize the light using an actor.
>>> import pyvista as pv >>> plotter = pv.Plotter() >>> _ = plotter.add_mesh(pv.Cube(), color='white') >>> for light in plotter.renderer.lights: ... light.intensity /= 5 ... >>> spotlight = pv.Light(position=(-1, 1, 1), color='cyan') >>> spotlight.positional = True >>> spotlight.cone_angle = 20 >>> spotlight.intensity = 10 >>> spotlight.exponent = 40 >>> spotlight.show_actor() >>> plotter.add_light(spotlight) >>> plotter.show()
-
property
specular_color
¶ Return the specular color of the light.
When setting, the color must be a 3-length sequence or a string. For example:
color='white'
color='w'
color=[1, 1, 1]
color='#FFFFFF'
Examples
Create a light and set its specular color to bright green.
>>> import pyvista as pv >>> light = pv.Light() >>> light.specular_color = '#00FF00'
-
switch_off
()¶ Switch off the light.
Examples
Create a light and switch it off.
>>> import pyvista as pv >>> light = pv.Light() >>> light.switch_off()
-
switch_on
()¶ Switch on the light.
Examples
Create a light, switch it off and switch it back on again.
>>> import pyvista as pv >>> light = pv.Light() >>> light.on = False >>> light.switch_on()
-
property
transform_matrix
¶ Return the transformation matrix of the light (if any).
The transformation matrix is
None
by default, and it is stored as avtk.vtkMatrix4x4
object when set. If set, the light’s parameters (position and focal point) are transformed by the matrix before being rendered. See also theworld_position
andworld_focal_point
read-only properties that can differ fromposition
andfocal_point
, respectively.The 4-by-4 transformation matrix is a tool to encode a general linear transformation and a translation (an affine transform). The 3-by-3 principal submatrix (the top left corner of the matrix) encodes a three-dimensional linear transformation (e.g. some rotation around the origin). The top three elements in the last column of the matrix encode a three-dimensional translation. The last row of the matrix is redundant.
Examples
Create a light with a transformation matrix that corresponds to a 90-degree rotation around the z axis and a shift by (0, 0, -1), and check that the light’s position transforms as expected.
>>> import numpy as np >>> import pyvista as pv >>> light = pv.Light(position=(1, 0, 3)) >>> trans = np.zeros((4, 4)) >>> trans[:-1, :-1] = [[0, -1, 0], [1, 0, 0], [0, 0, 1]] >>> trans[:-1, -1] = [0, 0, -1] >>> light.transform_matrix = trans >>> light.position (1.0, 0.0, 3.0) >>> light.world_position (0.0, 1.0, 2.0)
-
property
world_focal_point
¶ Return the world space focal point of the light.
The world space focal point is the
focal_point
property transformed by the light’s transform matrix if it exists. The value of this read-only property corresponds to thevtk.vtkLight.GetTransformedFocalPoint()
method.Examples
Create a light with a transformation matrix that corresponds to a 90-degree rotation around the z axis and a shift by (0, 0, -1), and check that the light’s focal point transforms as expected.
>>> import numpy as np >>> import pyvista as pv >>> light = pv.Light(focal_point=(1, 0, 3)) >>> trans = np.zeros((4, 4)) >>> trans[:-1, :-1] = [[0, -1, 0], [1, 0, 0], [0, 0, 1]] >>> trans[:-1, -1] = [0, 0, -1] >>> light.transform_matrix = trans >>> light.focal_point (1.0, 0.0, 3.0) >>> light.world_focal_point (0.0, 1.0, 2.0)
-
property
world_position
¶ Return the world space position of the light.
The world space position is the
position
property transformed by the light’s transform matrix if it exists. The value of this read-only property corresponds to thevtk.vtkLight.GetTransformedPosition()
method.Examples
Create a light with a transformation matrix that corresponds to a 90-degree rotation around the z axis and a shift by (0, 0, -1), and check that the light’s position transforms as expected.
>>> import numpy as np >>> import pyvista as pv >>> light = pv.Light(position=(1, 0, 3)) >>> trans = np.zeros((4, 4)) >>> trans[:-1, :-1] = [[0, -1, 0], [1, 0, 0], [0, 0, 1]] >>> trans[:-1, -1] = [0, 0, -1] >>> light.transform_matrix = trans >>> light.position (1.0, 0.0, 3.0) >>> light.world_position (0.0, 1.0, 2.0)