plotly (version 4.9.0)

orca: Static image exporting

Description

Export plotly objects to static images (e.g., pdf, png, jpeg, svg, etc) via the orca command-line utility.

Usage

orca(p, file = "plot.png", format = tools::file_ext(file),
  scale = NULL, width = NULL, height = NULL, mathjax = FALSE,
  parallel_limit = NULL, verbose = FALSE, debug = FALSE,
  safe = FALSE, more_args = NULL, ...)
orca_serve(port = 5151, mathjax = FALSE, safe = FALSE,
  request_limit = NULL, keep_alive = TRUE, window_max_number = NULL,
  quiet = FALSE, debug = FALSE, more_args = NULL, ...)

Arguments

p

a plotly object.

file

output filename.

format

the output format (png, jpeg, webp, svg, pdf, eps).

scale

Sets the image scale. Applies to all output images.

width

Sets the image width. If not set, defaults to layout.width value. Applies to all output images.

height

Sets the image height. If not set, defaults to layout.height value. Applies to all output images.

mathjax

whether or not to include MathJax (required to render TeX). If TRUE, the PLOTLY_MATHJAX_PATH environment variable must be set and point to the location of MathJax (this variable is also used to render TeX in interactive graphs, see config).

parallel_limit

Sets the limit of parallel tasks run.

verbose

Turn on verbose logging on stdout.

debug

Starts app in debug mode and turn on verbose logs on stdout.

safe

Turns on safe mode: where figures likely to make browser window hang during image generating are skipped.

more_args

additional arguments to pass along to system command. This is useful for specifying display and/or electron options, such as --enable-webgl or --disable-gpu.

...

for orca(), additional arguments passed along to processx::run. For orca_serve(), additional arguments passed along to processx::process.

port

Sets the server's port number.

request_limit

Sets a request limit that makes orca exit when reached.

keep_alive

Turn on keep alive mode where orca will (try to) relaunch server if process unexpectedly exits.

window_max_number

Sets maximum number of browser windows the server can keep open at a given time.

quiet

Suppress all logging info.

Methods

The orca_serve() function returns an object with two methods:

export(p, file = "plot.png", format = tools::file_ext(file), scale = NULL, width = NULL, height = NULL)

Export a static image of a plotly graph. Arguments found here are the same as those found in orca()

close()

Close down the orca server and kill the underlying node process.

Fields

The orca_serve() function returns an object with two fields:

port

The port number that the server is listening to.

process

An R6 class for controlling and querying the underlying node process.

Details

The orca() function is designed for exporting one plotly graph whereas orca_serve() is meant for exporting many graphs at once. The former starts and stops an external (nodejs) process everytime it is called whereas the latter starts up a process when called, then returns an export() method for exporting graphs as well as a close() method for stopping the external (background) process.

Examples

# NOT RUN {
# }
# NOT RUN {
# NOTE: in a headless environment, you may need to set `more_args="--enable-webgl"`
# to export webgl correctly
p <- plot_ly(z = ~volcano) %>% add_surface()
orca(p, "surface-plot.svg")

#' # launch the server
server <- orca_serve()

# export as many graphs as you'd like
server$export(qplot(1:10), "test1.pdf")
server$export(plot_ly(x = 1:10, y = 1:10), "test2.pdf")

# the underlying process is exposed as a field, so you
# have full control over the external process
server$process$is_alive()

# convenience method for closing down the server
server$close()

# remove the exported files from disk
unlink("test1.pdf")
unlink("test2.pdf")
# }
# NOT RUN {
# }