Plotter.screenshot

Plotter.screenshot#

Take screenshot at current camera position.

Parameters:

filenamestr | Path | io.BytesIO, optional

Location to write image to. If None, no image is written.

transparent_backgroundbool | ‘straight’ | ‘premultiplied’, optional

Whether to make the background transparent. The default is looked up on the plotter’s theme.

False returns an opaque RGB image.
True returns an RGBA image with a transparent background. Anti-aliased edges and translucent surfaces keep the color of the background they were blended with.
'straight' returns an RGBA image with straight (unassociated) alpha and the background color removed, which is what image viewers, web browsers, PNG files, and PIL expect. Use it for images that are saved or shown.
'premultiplied' returns an RGBA image whose colors are already multiplied by alpha (associated alpha) and contain no background color. Use it for compositing software and formats that expect colors multiplied by alpha, or to filter the image further without halos.

'straight' and 'premultiplied' render the scene once more over a black background and then restore the background. Fully transparent pixels are (0, 0, 0, 0). FXAA anti-aliasing is not applied, since it does not smooth the alpha channel.

Added in version 0.50: The 'straight' and 'premultiplied' options.

Changed in version 0.50: Other values raise a ValueError.

return_imgbool, default: True

If True, a numpy.ndarray of the image will be returned.

window_sizesequence[int], optional

Set the plotter’s size to this (width, height) before taking the screenshot.

scaleint, optional

Set the factor to scale the window size to make a higher resolution image. If None this will use the image_scale property on this plotter which defaults to one.

renderbool, default: True

Render the scene before reading the image so that it reflects every change since the last render. The first screenshot of a plotter always renders.

Added in version 0.50.

Returns:

numpy.ndarray

Array containing pixel RGB and alpha. Sized:

[Window height x Window width x 3] if transparent_background is set to False.
[Window height x Window width x 4] otherwise.

None

If return_img is False.

Examples#

Download Python source code | Download Jupyter notebook

>>> import pyvista as pv
>>> sphere = pv.Sphere()
>>> pl = pv.Plotter(off_screen=True)
>>> actor = pl.add_mesh(sphere)
>>> pl.screenshot('screenshot.png')

Take a screenshot with a transparent background and remove the background color from the anti-aliased edges of the sphere, which makes the image suitable for placing over any background.

>>> image = pl.screenshot(transparent_background='straight')

Take a screenshot of an opaque sphere and a translucent cube with each transparent_background option.

>>> import pyvista as pv
>>> pl = pv.Plotter(off_screen=True, window_size=[150, 150])
>>> sphere = pv.Sphere(center=(-0.3, 0, 0))
>>> _ = pl.add_mesh(sphere, color='navy', lighting=False)
>>> cube = pv.Cube(center=(0.3, 0, 0))
>>> _ = pl.add_mesh(cube, color='crimson', opacity=0.5, lighting=False)
>>> pl.view_xy()
>>> images = {
...     str(option): pv.Texture(
...         pl.screenshot(transparent_background=option)
...     ).to_image()
...     for option in [False, True, 'straight', 'premultiplied']
... }

Compare the images over a black background. With True, the white background color shows as a light halo around the sphere and lightens the cube. 'straight' has neither. 'premultiplied' is for software that expects colors multiplied by alpha, and looks darker when shown as straight alpha.

>>> pv.plot_compare(
...     images,
...     rgba=True,
...     background='black',
...     label_kwargs={'color': 'darkorange'},
...     border_color='gray',
...     border_width=6,
...     lighting=False,
...     show_axes=False,
...     cpos='xy',
...     zoom='tight',
... )