"""
Plotter Lighting Systems
~~~~~~~~~~~~~~~~~~~~~~~~

The :class:`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


###############################################################################
# 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()


###############################################################################
# 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()

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


###############################################################################
# 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')
plotter.add_mesh(mesh, color='white')
light = pv.Light()
light.set_direction_angle(30, 0)
plotter.add_light(light)
plotter.show()

[((28, 10, 28, 22), 'pyvista.Plotter', 'pv.Plotter', ({}, {}), '()', True, 'import pyvista as pv\n'), ((32, 0, 32, 33), 'pyvista.plotting._ALL_PLOTTERS.clear', 'pv.plotting._ALL_PLOTTERS.clear', ({}, {}), '()', True, 'import pyvista as pv\n'), ((41, 10, 41, 22), 'pyvista.Plotter', 'pv.Plotter', ({}, {}), '()', True, 'import pyvista as pv\n'), ((55, 10, 55, 45), 'pyvista.Plotter', 'pv.Plotter', (), '', True, 'import pyvista as pv\n'), ((62, 10, 62, 45), 'pyvista.Plotter', 'pv.Plotter', (), '', True, 'import pyvista as pv\n'), ((66, 0, 66, 33), 'pyvista.plotting._ALL_PLOTTERS.clear', 'pv.plotting._ALL_PLOTTERS.clear', ({}, {}), '()', True, 'import pyvista as pv\n'), ((80, 10, 80, 37), 'pyvista.Plotter', 'pv.Plotter', (), '', True, 'import pyvista as pv\n'), ((82, 8, 82, 18), 'pyvista.Light', 'pv.Light', ({}, {}), '()', True, 'import pyvista as pv\n'), ((40, 7, 40, 36), 'pyvista.examples.download_st_helens', 'examples.download_st_helens', ({}, {}), '()', False, 'from pyvista import examples\n')]