Plotter Lighting Systems

The pyvista.Plotter class comes with three options for the default lighting system:

  • a light kit consisting of a headlight and four camera lights,

  • an illumination system containing three lights arranged around the camera,

  • no lighting.

With meshes that don’t have depth information encoded in their color the importance of an appropriate lighting setup becomes paramount for accurate visualization.

Light kit

The default lighting='light kit' option recreates a lighting setup that corresponds to a vtk.vtkLightKit. We can check what type of lights this lighting comprises:

# sphinx_gallery_thumbnail_number = 3
import pyvista as pv
from pyvista import examples

# default: light kit
plotter = pv.Plotter()
light_types = [light.light_type for light in plotter.renderer.lights]

# Remove from plotters so output is not produced in docs
pv.plotting._ALL_PLOTTERS.clear()

light_types

Out:

[<LightType.HEADLIGHT: 1>, <LightType.CAMERA_LIGHT: 2>, <LightType.CAMERA_LIGHT: 2>, <LightType.CAMERA_LIGHT: 2>, <LightType.CAMERA_LIGHT: 2>]

Add a white terrain to the scene:

mesh = examples.download_st_helens().warp_by_scalar()
plotter = pv.Plotter()
plotter.add_mesh(mesh, color='white')
plotter.show()
plotter builtins

Out:

[(581977.3046422418, 5134123.804642241, 21436.804642241805),
 (562835.0, 5114981.5, 2294.5),
 (0.0, 0.0, 1.0)]

Three-lights illumination

Switching to three-lights illumination gives a different character to the figure, in this case showing less contrast when viewing the mountain from the top, but having more contrast with views closer to the side. This becomes especially clear when exploring the figures interactively.

plotter = pv.Plotter(lighting='three lights')
plotter.add_mesh(mesh, color='white')
plotter.show()
plotter builtins

Out:

[(581977.3046422418, 5134123.804642241, 21436.804642241805),
 (562835.0, 5114981.5, 2294.5),
 (0.0, 0.0, 1.0)]

Again we can check what kind of lights this setting uses:

plotter = pv.Plotter(lighting='three lights')
light_types = [light.light_type for light in plotter.renderer.lights]

# Remove from plotters so output is not produced in docs
pv.plotting._ALL_PLOTTERS.clear()

light_types

Out:

[<LightType.CAMERA_LIGHT: 2>, <LightType.CAMERA_LIGHT: 2>, <LightType.CAMERA_LIGHT: 2>]

Custom lighting

We can introduce our own lighting from scratch by disabling any lighting on plotter initialization. Adding a single scene light to a scene will often result in ominous visuals due to objects having larger regions in shadow.

plotter = pv.Plotter(lighting='none', window_size=(1000, 1000))
plotter.add_mesh(mesh, color='white', smooth_shading=True)
light = pv.Light()
light.set_direction_angle(30, -20)
plotter.add_light(light)
plotter.show()
plotter builtins

Out:

[(581977.3046422418, 5134123.804642241, 21436.804642241805),
 (562835.0, 5114981.5, 2294.5),
 (0.0, 0.0, 1.0)]

Custom lighting with shadows

Here, we enable_shadows to enhance the effect that the lighting angle has. It has a subtle, but realistic effect. Notice the sharp shadows due to the mountaintop.

plotter = pv.Plotter(lighting='none', window_size=(1000, 1000))
plotter.add_mesh(mesh, color='white', smooth_shading=True)
light = pv.Light()
light.set_direction_angle(20, -20)
plotter.add_light(light)
plotter.enable_shadows()
plotter.show()
plotter builtins

Out:

[(581977.3046422418, 5134123.804642241, 21436.804642241805),
 (562835.0, 5114981.5, 2294.5),
 (0.0, 0.0, 1.0)]

Total running time of the script: ( 0 minutes 3.536 seconds)

Gallery generated by Sphinx-Gallery