<jupyter_start><jupyter_text>Beam ShapeThe default directional lights are infinitely distant point sources, for whichthe only geometric customization option is the choice of beam direction definedby the light's position and focal point. Positional lights, however, have moreoptions for beam customization.Consider two hemispheres:<jupyter_code># sphinx_gallery_thumbnail_number = 5
import pyvista as pv
plotter = pv.Plotter()

hemi = pv.Sphere().clip()
hemi.translate((-1, 0, 0))
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

hemi = hemi.copy()
hemi.rotate_z(180)
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

plotter.show()<jupyter_output><empty_output><jupyter_text>We can see that the default lighting does a very good job of articulating theshape of the hemispheres.Let's shine a directional light on them, positioned between the hemispheres andoriented along their centers:<jupyter_code>plotter = pv.Plotter(lighting='none')

hemi = pv.Sphere().clip()
hemi.translate((-1, 0, 0))
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

hemi = hemi.copy()
hemi.rotate_z(180)
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

light = pv.Light(position=(0, 0, 0), focal_point=(-1, 0, 0))
plotter.add_light(light)

plotter.show()<jupyter_output><empty_output><jupyter_text>Both hemispheres have their surface lit on the side that faces the light.This is consistent with the point source positioned at infinity, directed fromthe light's nominal position toward the focal point.Now let's change the light to a positional light (but not a spotlight):<jupyter_code>plotter = pv.Plotter(lighting='none')

hemi = pv.Sphere().clip()
hemi.translate((-1, 0, 0))
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

hemi = hemi.copy()
hemi.rotate_z(180)
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

light = pv.Light(position=(0, 0, 0), focal_point=(-1, 0, 0))
light.positional = True
light.cone_angle = 90
plotter.add_light(light)

plotter.show()<jupyter_output><empty_output><jupyter_text>Now the inner surface of both hemispheres is lit. A positional light with acone angle of 90 degrees (or more) acts as a point source located at thelight's nominal position. It could still display attenuation, see the`ref_attenuation_example` example.Switching to a spotlight (i.e. a positional light with a cone angle lessthan 90 degrees) will enable beam shaping using the :py:attr:`exponent`property. Let's put our hemispheres side by side for this, and put a light inthe center of each: one spotlight, one merely positional.<jupyter_code>plotter = pv.Plotter(lighting='none')

hemi = pv.Sphere().clip()
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

offset = 1.5
hemi = hemi.copy()
hemi.translate((0, offset, 0))
plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

# non-spot positional light in the center of the first hemisphere
light = pv.Light(position=(0, 0, 0), focal_point=(-1, 0, 0))
light.positional = True
light.cone_angle = 90
# add attenuation to reduce cross-talk between the lights
light.attenuation_values = (0, 0, 2)
plotter.add_light(light)

# spotlight in the center of the second hemisphere
light = pv.Light(position=(0, offset, 0), focal_point=(-1, offset, 0))
light.positional = True
light.cone_angle = 89.9
# add attenuation to reduce cross-talk between the lights
light.attenuation_values = (0, 0, 2)
plotter.add_light(light)

plotter.show()<jupyter_output><empty_output><jupyter_text>Even though the two lights only differ by a fraction of a degree in cone angle,the beam shaping effect enabled for spotlights causes a marked difference inthe result.Once we have a spotlight we can change its :py:attr:`exponent` to make the beamshape sharper or broader. Three spotlights with varying sharpness:<jupyter_code>plotter = pv.Plotter(lighting='none')
hemi_template = pv.Sphere().clip()

centers = [(0, 0, 0), (0, 1.5, 0), (0, 1.5*0.5, 1.5*3**0.5/2)]
exponents = [1, 0.3, 5]

for center, exponent in zip(centers, exponents):
    hemi = hemi_template.copy()
    hemi.translate(center)
    plotter.add_mesh(hemi, color='cyan', smooth_shading=True)

    # spotlight in the center of the hemisphere, shining into it
    focal_point = center[0] - 1, center[1], center[2]
    light = pv.Light(position=center, focal_point=focal_point)
    light.positional = True
    light.cone_angle = 89.9
    light.exponent = exponent
    # add attenuation to reduce cross-talk between the lights
    light.attenuation_values = (0, 0, 2)
    plotter.add_light(light)

plotter.show()<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.11091664843579085, 'fraction_numerical': 0.02056442791511704, 'mean_word_length': 5.7533234859675035, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '5', 'dir': 'jupyter-structured-clean-dedup', 'id': '321122', 'license': 'MIT', 'n_tokens_mistral': 1640, 'n_tokens_neox': 1503, 'n_words': 465, 'path': 'locale/examples/04-lights/beam_shape.ipynb', 'repo_name': 'tkoyama010/pyvista-doc-translations', 'size': '4571'}