Plotter.set_environment_texture

Plotter.set_environment_texture#

Plotter.set_environment_texture(
texture,
is_srgb=False,
resample: bool | float | None = None,
rotation: TypeAliasForwardRef('pyvista.RotationLike') | None = None,
show_background=True,
) → None[source]#

Set the environment texture used for image based lighting.

This texture is supposed to represent the scene background. If it is not a cubemap, the texture is supposed to represent an equirectangular projection. If used with raytracing backends, the texture must be an equirectangular projection and must be constructed with a valid vtkImageData.

Parameters:
texturepyvista.Texture

Texture.

is_srgbbool, default: False

If the texture is in sRGB color space, set the color flag on the texture or set this parameter to True. Textures are assumed to be in linear color space by default.

resamplebool | float, optional

Resample the environment texture. Set this to a float to set the sampling rate explicitly or set to True to down-sample the texture to 1/16 of its original resolution. By default, the theme value for resample_environment_texture is used, which is False for the standard theme.

Down-sampling the texture can substantially improve performance for some environments, for example, headless setups or if GPU support is limited.

Note

This will resample the texture used for image-based lighting only, for example, the texture used for rendering reflective surfaces. It does not resample the background texture.

Added in version 0.45.

Changed in version 0.48: Resampling now uses linear interpolation with anti-aliasing instead of nearest-neighbor, which gives smoother results for continuous environment textures.

Changed in version 0.49: The image-based lighting textures are down-sampled at the same rate: the specular prefilter integrates fewer samples per texel, and for cube map textures the diffuse irradiance map shrinks as well. Both are clamped between a floor and their default size, so a very low rate stops making them cheaper. Only a single rate is accepted; a sequence of per-axis rates raises ValueError.

rotationRotationLike, optional

Rotation to apply to the environment texture for image-based lighting and the background texture. Accepts any 3x3 numpy.ndarray, vtkMatrix3x3, or SciPy Rotation. Requires VTK >= 9.6.

Added in version 0.48.

show_backgroundbool, default: True

Whether to also show the environment texture as the renderer background. Set this to False to keep image-based lighting enabled while using a solid or gradient background instead.

Added in version 0.48.

Examples#

Download Python source code | Download Jupyter notebook

Add a skybox cubemap as an environment texture and show that the lighting from the texture is mapped on to a sphere dataset. Note how even when disabling the default 'light kit', the scene lighting will still be mapped onto the actor.

>>> from pyvista import examples
>>> import pyvista as pv
>>> pl = pv.Plotter(lighting=None)
>>> cubemap = examples.download_sky_box_cube_map()
>>> _ = pl.add_mesh(pv.Sphere(), pbr=True, metallic=0.9, roughness=0.4)
>>> pl.set_environment_texture(cubemap)
>>> pl.camera_position = 'xy'
>>> pl.show()
../../../_images/pyvista-Plotter-set_environment_texture-a498491b04f6bc2b_00_00.png