snapshot3d {rgl}

Export screenshot

Description

Saves the screenshot to a file.

Usage

rgl.snapshot( filename, fmt = "png", top = TRUE )
snapshot3d( filename = tempfile(fileext = ".png"), 
            fmt = "png", top = TRUE,
            ..., scene, width = NULL, height = NULL,
            webshot = as.logical(Sys.getenv("RGL_USE_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 and a Chrome browser. If no suitable browser is found, snapshot3d() will revert to rgl.snapshot(). To override the automatic search, set environment variable CHROMOTE_CHROME to the path to a suitable browser.

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, but they are usually slower to produce, sometimes drastically so.

Set the environment variable RGL_USE_WEBSHOT to "FALSE" if you want rgl.snapshot to be used by default.

See Also

movie3d, view3d

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

## Not run: 

#
# create animation
#

shade3d(oh3d(), color = "red")
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)

## End(Not run)