Add orca_serve R6 class for bulk image exporting

Author: cpsievert

DESCRIPTION

@@ -44,7 +44,8 @@ Imports:
     crosstalk,
     purrr,
     data.table,
-    promises
+    promises,
+    R6
 Suggests:
     MASS,
     maps,

R/imports.R

@@ -6,7 +6,7 @@
 #' @importFrom tidyr unnest
 #' @importFrom viridisLite viridis
 #' @importFrom jsonlite toJSON fromJSON
-#' @importFrom httr GET POST PATCH content config add_headers stop_for_status
+#' @importFrom httr GET POST PATCH content config add_headers stop_for_status warn_for_status
 #' @importFrom htmlwidgets createWidget sizingPolicy saveWidget onRender prependContent
 #' @importFrom lazyeval f_eval is_formula all_dots is_lang f_new
 #' @importFrom tibble as_tibble

R/orca.R

@@ -22,6 +22,7 @@
 #' hang during image generating are skipped.
 #' @export
 #' @author Carson Sievert
+#' @seealso [orca_serve]
 #' @examples
 #' 
 #' \dontrun{
@@ -35,13 +36,7 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
                  parallel_limit = NULL, verbose = FALSE, debug = FALSE, 
                  safe = FALSE) {
 
-  if (Sys.which("orca") == "") {
-    stop(
-      "The orca command-line utility is required to use the `orca()` function.\n\n",
-      "Follow the installation instructions here -- https://github.com/plotly/orca#installation",
-      call. = FALSE
-    )
-  }
+  orca_available()
 
   b <- plotly_build(p)
 
@@ -68,8 +63,156 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
   if (!is.null(parallel_limit)) args <- c(args, "--parallel-limit", parallel_limit)
   if (!is.null(tryNULL(mapbox_token()))) args <- c(args, "--mapbox-access-token", mapbox_token())
   if (isTRUE(mathjax)) args <- c(args, "--mathjax", file.path(mathjax_path(), "MathJax.js"))
-     
+  
   # TODO: point to local topojson? Should this only work if plot_geo(standalone = TRUE)?
   try_library("processx", "orca")
   invisible(processx::run("orca", args, echo = TRUE, spinner = TRUE))
 }
+
+#' Orca image export server
+#' 
+#' @description Compared to [orca], [orca_serve] is more efficient at exporting many plotly 
+#' graphs because the former must startup/shutdown an external process for every image. 
+#' The server (background) process is launched upon initialization of a [orca_serve] class 
+#' (i.e., when the `new()` method is called). The `export()` method accepts any valid plotly 
+#' object as input and spits out an image file to disk. To kill the background server process, 
+#' use `close()`.
+#' 
+#' @section Constructor:
+#' 
+#' \code{orca_serve$new(port = 5151)}
+#' 
+#' \describe{
+#'   \item{\code{port}}{Sets the server's port number.}
+#'   \item{\code{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]).
+#'   }
+#'   \item{\code{safe}}{
+#'     Turns on safe mode: where figures likely to make browser window hang during image generating are skipped.
+#'   }
+#'   \item{\code{request_limit}}{
+#'     Sets a request limit that makes orca exit when reached.
+#'   }
+#'   \item{\code{keep_alive}}{
+#'     Turn on keep alive mode where orca will (try to) relaunch server if process unexpectedly exits.
+#'   }
+#'   \item{\code{window_max_number}}{
+#'     Sets maximum number of browser windows the server can keep open at a given time.
+#'   }
+#'   \item{\code{quiet}}{Suppress all logging info.}
+#'   \item{\code{debug}}{Starts app in debug mode.}
+#' }
+#' 
+#' @export
+#' @author Carson Sievert
+#' @seealso [orca]
+#' @examples 
+#' 
+#' \dontrun{
+#' # launch the server
+#' server <- orca_serve$new()
+#' 
+#' # 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")
+#' }
+#' 
+orca_serve <- R6::R6Class(
+  "orcaServe",
+  public = list(
+    process = NULL,
+    port = NULL,
+    
+    initialize = function(port = 5151, mathjax = FALSE, safe = FALSE, request_limit = NULL,
+                          keep_alive = TRUE, window_max_number = NULL, quiet = FALSE, 
+                          debug = FALSE, ...) {
+      
+      # make sure we have the required infrastructure
+      orca_available()
+      try_library("processx", "orca")
+      
+      # use main bundle since any plot can be thrown at the server
+      plotlyjs <- plotlyMainBundle()
+      plotlyjs_file <- file.path(plotlyjs$src$file, plotlyjs$script)
+      
+      args <- c(
+        "serve",
+        "-p", port,
+        "--plotly", plotlyjs_file,
+        if (safe) "--safe-mode",
+        if (orca_version() >= "1.1.1") "--graph-only",
+        if (keep_alive) "--keep-alive",
+        if (debug) "--debug",
+        if (quiet) "--quiet"
+      )
+      
+      if (!is.null(request_limit))
+        args <- c(args, "--request-limit", request_limit)
+      
+      if (!is.null(window_max_number))
+        args <- c(args, "--window-max-number", window_max_number)
+      
+      if (!is.null(tryNULL(mapbox_token()))) 
+        args <- c(args, "--mapbox-access-token", mapbox_token())
+      
+      if (isTRUE(mathjax)) 
+        args <- c(args, "--mathjax", file.path(mathjax_path(), "MathJax.js"))
+      
+      self$process <- processx::process$new("orca", args, ...)
+      self$port <- port
+    },
+    export = function(p, file = "plot.png", format = tools::file_ext(file), width = 1000, height = 500) {
+      
+      # request/response model works similarly to plotly_IMAGE()
+      bod <- list(
+        figure = plotly_build(p)$x[c("data", "layout")],
+        format = format,
+        width = width,
+        height = height,
+        scale = scale
+      )
+      res <- httr::POST(
+        paste0("http://localhost:", self$port), 
+        body = to_JSON(bod)
+      )
+      httr::stop_for_status(res)
+      httr::warn_for_status(res)
+      con <- httr::content(res, as = "raw")
+      writeBin(con, file)
+    },
+    close = function() {
+      self$process$kill()
+    }
+  )
+)
+
+orca_available <- function() {
+  if (Sys.which("orca") == "") {
+    stop(
+      "The orca command-line utility is required for this functionality.\n\n",
+      "Please follow the installation instructions here -- https://github.com/plotly/orca#installation",
+      call. = FALSE
+    )
+  }
+  
+  TRUE
+}
+
+orca_version <- function() {
+  orca_available()
+  as.package_version(system("orca --version", intern = TRUE))
+}