Saves the screenshot to a file.

rgl.snapshot( filename, fmt = "png", top = TRUE )
snapshot3d( filename = tempfile(fileext = ".png"),
fmt = "png", top = TRUE,
..., scene, width = NULL, height = NULL,
webshot = TRUE)

## Arguments

filename

path to file to save.

fmt

image export format, currently supported: png. Ignored if webshot = TRUE.

top

whether to call rgl.bringtotop. Ignored if webshot = TRUE.

...

arguments to pass to webshot2::webshot

scene

an optional result of scene3d or rglwidget to plot

width, height

optional specifications of output size in pixels

webshot

Use the webshot2 package to take the snapshot

## Details

rgl.snapshot() is a low-level function that copies the current RGL window from the screen. Users should use snapshot3d() instead; it is more flexible, and (if webshot2 is installed) can take images even if no window is showing, and they can be larger than the physical screen.

Animations can be created in a loop modifying the scene and saving each screenshot to a file. Various graphics programs (e.g. ImageMagick) can put these together into a single animation. (See movie3d or the example below.)

## Value

These functions are mainly called for the side effects. The filename of the saved file is returned invisibly.

## Note

When rgl.useNULL() is TRUE, only webshot = TRUE will produce a snapshot. It requires the webshot2 package, which as of this writing is not available on CRAN; to install it, use remotes::install_github("rstudio/webshot2")

rgl.snapshot works by taking an image from the displayed window on-screen. On some systems, the snapshot will include content from other windows if they cover the active RGL window. Setting top = TRUE (the default) will use rgl.bringtotop before the snapshot to avoid this.

There are likely limits to how large width and height can be set based on the display hardware; if these are exceeded the results are undefined. A typical result is that the snapshot will still be made but at a smaller size.

There are slight differences between the displays with webshot = TRUE and webshot = FALSE, as the former are rendered using WebGL while the latter are rendered using OpenGL. Often the webshot = TRUE displays have better quality.

movie3d, rgl.viewpoint

## Examples

if (interactive() && !in_pkgdown_example()) {
saveopts <- options(rgl.useNULL = TRUE)
plot3d(matrix(rnorm(300), ncol = 3, dimnames = list(NULL, c("x", "y", "z"))),
col = "red")
options(saveopts)
browseURL(snapshot3d())
}

if (FALSE) {

#
# create animation
#

rgl.bringtotop()
view3d(0, 20)

olddir <- setwd(tempdir())
for (i in 1:45) {
view3d(i, 20)
filename <- paste("pic", formatC(i, digits = 1, flag = "0"), ".png", sep = "")
snapshot3d(filename)
}
## Now run ImageMagick in tempdir().  Use 'convert' instead of 'magick'
## if you have an older version of ImageMagick:
##    magick -delay 10 *.png -loop 0 pic.gif
setwd(olddir)
}