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, then create a scene without lighting and add our light to it manually.

import pyvista as pv
from pyvista import examples
light = pv.Light(position=(-1, 1, 1), color='red')
light.positional = True

import pyvista as pv
from pyvista import examples
plotter = pv.Plotter(lighting='none')
plotter.background_color = 'white'
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()

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.

Shadows¶

With directed lights, it is possible to create complex lighting scenarios. For example, you can position a light directly above an actor (in this case, a sphere), to create a shadow directly below it.

The following example uses a positional light to create an eclipse-like shadow below a sphere by controlling the cone angle and exponent values of the light.

import pyvista as pv

plotter = pv.Plotter(lighting=None, window_size=(800, 800))

# create a top down light
light = pv.Light(position=(0, 0, 3), show_actor=True, positional=True,
                 cone_angle=30, exponent=20, intensity=1.5)
plotter.add_light(light)

# add a sphere to the plotter
sphere = pv.Sphere(radius=0.3, center=(0, 0, 1))
plotter.add_mesh(sphere, ambient=0.2, diffuse=0.5, specular=0.8,
                 specular_power=30, smooth_shading=True,
                 color='dodgerblue')

# add the grid
grid = pv.Plane(i_size=4, j_size=4)
plotter.add_mesh(grid, ambient=0, diffuse=0.5, specular=0.8, color='white')

# setup and show the plotter
plotter.enable_shadows()
plotter.set_background('darkgrey')
plotter.show()

Note

VTK has known issues when rendering shadows on certain window sizes. Be prepared to experiment with the window_size parameter.

API reference¶

class pyvista.Light(position=None, focal_point=None, color=None, light_type='scene light', intensity=None, positional=None, cone_angle=None, show_actor=False, exponent=None, shadow_attenuation=None, attenuation_values=None)¶

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 constants Light.HEADLIGHT, Light.CAMERA_LIGHT and Light.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.
intensity (float, optional) – The brightness of the light (between 0 and 1).
positional (bool, optional) –
Set if 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.
cone_angle (float, optional) – Cone angle of a positional light in degrees.
show_actor (bool, optional) – Show an actor for a spotlight that depicts the geometry of the beam.
exponent (float, optional) – The exponent of the cosine used for spotlights. See also the exponent property.
shadow_attenuation (float, optional) –
The value of shadow attenuation.

By default a light will be completely blocked when in shadow. By setting this value to less than 1.0 you can control how much light is attenuated when in shadow. Note that changing the attenuation_values of the light can make it pass through objects even if its shadow attenuation is 1.
attenuation_values (sequence, optional) –
Quadratic attenuation constants.

The values are a 3-length sequence which specifies the constant, linear and quadratic constants in this order. These parameters only have an effect for positional lights.

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

Create a positional light at (0, 0, 3) with a cone angle of 30, exponent of 20, and a visible actor.

>>> light = pv.Light(position=(0, 0, 3), show_actor=True,
...                  positional=True, cone_angle=30, exponent=20)

add_renderer(renderer)¶: Attach a renderer to this light.

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))
>>> cpos = 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()
>>> cpos = 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 (small cone_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()
>>> cpos = 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)
...
>>> cpos = 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 the world_position via changes in the transform_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 previously 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

property renderers¶: Return the renderers associated with this light.

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.

property shadow_attenuation¶

Return the value of shadow attenuation.

By default a light will be completely blocked when in shadow. By setting this value to less than 1.0 you can control how much light is attenuated when in shadow. Note that changing the attenuation_values of the light can make it pass through objects even if its shadow attenuation is 1.

Examples

Set the shadow attenuation to 0.5

>>> import pyvista as pv
>>> light = pv.Light()
>>> light.shadow_attenuation = 0.5
>>> light.shadow_attenuation
0.5

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 see hide_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)
>>> cpos = 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 a vtk.vtkMatrix4x4 object when set. If set, the light’s parameters (position and focal point) are transformed by the matrix before being rendered. See also the world_position and world_focal_point read-only properties that can differ from position and focal_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 the vtk.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 the vtk.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)