orca {plotly} | R Documentation

## 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.

### 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.

### 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.

### Author(s)

Carson Sievert

### Examples

    ## 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")

    ## End(Not run)

[Package plotly version 4.9.0 Index]