Add kaleido() for static image exporting

.github/workflows/R-CMD-check.yaml

@@ -72,35 +72,33 @@ jobs:
           key: ${{ matrix.config.os }}-${{ steps.install-r.outputs.installed-r-version }}-1-${{ hashFiles('.github/r-depends.rds') }}
           restore-keys: ${{ matrix.config.os }}-${{ steps.install-r.outputs.installed-r-version }}-1-
 
-      - name: Install system dependencies
+      - name: Install Linux sysdeps
         if: runner.os == 'Linux'
         run: |
           pak::local_system_requirements(execute = TRUE)
           pak::pkg_system_requirements("rcmdcheck", execute = TRUE)
         shell: Rscript {0}
-
-      - uses: actions/setup-node@v1
-        with:
-          node-version: ${{ matrix.config.node }}
-
-      - name: Install orca
-        if: matrix.config.visual_tests == true
-        run: npm install -g [email protected] orca
-        shell: bash
-
-      - name: Install phantomjs
-        if: matrix.config.shinytest == true
-        run: |
-          pak::pak("shinytest")
-          shinytest::installDependencies()
-          pak::pak()
-        shell: Rscript {0}
-
+
       - name: Install dependencies
         run: |
-          pak::local_install_dev_deps(upgrade = TRUE)
+          if (Sys.info()[['sysname']] == 'Darwin') options(pkgType = 'mac.binary')
+          pak::local_install_dev_deps(upgrade = FALSE)
           pak::pkg_install("rcmdcheck")
         shell: Rscript {0}
+
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+
+      - name: Install kaleido
+        if: matrix.config.visual_tests == true
+        run: |
+          sudo chown -R $UID $CONDA # https://github.com/nextstrain/conda/issues/5
+          Rscript -e "reticulate::install_miniconda()"
+          Rscript -e "reticulate::conda_install('r-reticulate', 'python-kaleido')"
+          Rscript -e "reticulate::conda_install('r-reticulate', 'plotly', channel = 'plotly')"
+          Rscript -e "reticulate::use_miniconda('r-reticulate')"
 
       - name: Session info
         run: |
@@ -109,10 +107,17 @@ jobs:
           sessioninfo::session_info(pkgs, include_base = TRUE)
         shell: Rscript {0}
 
+      - name: Install shinytest deps
+        if: matrix.config.shinytest == true
+        run: |
+          Rscript -e 'shinytest::installDependencies()'
+          R CMD install .
+        shell: bash
+
         # Run test() before R CMD check since, for some reason, rcmdcheck::rcmdcheck() skips vdiffr tests
       - name: Run Tests
         run: |
-          options(crayon.enabled = TRUE)
+          options(crayon.enabled = TRUE, testthat.progress.max_fails=1000)
           if (!require(devtools)) pak::pak("devtools")
           if (!require(reshape2)) pak::pak("reshape2")
           res <- devtools::test()

DESCRIPTION

@@ -67,13 +67,15 @@ Suggests:
     dendextend,
     maptools,
     rgeos,
+    sf,
     png,
     IRdisplay,
     processx,
     plotlyGeoAssets,
     forcats,
     palmerpenguins,
-    rversions
+    rversions,
+    reticulate
 LazyData: true
 RoxygenNote: 7.1.1
 Encoding: UTF-8

NAMESPACE

@@ -34,6 +34,7 @@ S3method(print,api)
 S3method(print,api_grid)
 S3method(print,api_grid_local)
 S3method(print,api_plot)
+S3method(print,kaleidoScope)
 S3method(print,plotly_data)
 S3method(to_basic,GeomAbline)
 S3method(to_basic,GeomAnnotationMap)
@@ -136,6 +137,7 @@ export(hide_guides)
 export(hide_legend)
 export(highlight)
 export(highlight_key)
+export(kaleido)
 export(knit_print.api_grid)
 export(knit_print.api_grid_local)
 export(knit_print.api_plot)
@@ -260,6 +262,7 @@ importFrom(tidyr,unnest)
 importFrom(tools,file_ext)
 importFrom(tools,file_path_sans_ext)
 importFrom(utils,browseURL)
+importFrom(utils,capture.output)
 importFrom(utils,data)
 importFrom(utils,file.edit)
 importFrom(utils,getFromNamespace)

NEWS.md

@@ -8,6 +8,10 @@
 
 * `ggplotly()` now uses the `layout.legend.title` (instead of `layout.annotations`) plotly.js API to convert guides for discrete scales. (#1961)
 
+## New Features
+
+* Added new `kaleido()` function for static image exporting via the [kaleido python package](https://github.com/plotly/Kaleido). See `help(kaleido, package = "plotly")` for installation info and example usage. (#1971)
+
 ## Improvements
 
 * `ggplotly()` now better positions axis titles for `facet_wrap()`/`facet_grid()`. (#1975)

R/kaleido.R

@@ -0,0 +1,132 @@
+#' Static image exporting via kaleido
+#' 
+#' Static image exporting via [the kaleido python
+#' package](https://github.com/plotly/Kaleido/). `kaleido()` imports
+#' kaleido into a \pkg{reticulate}d Python session and returns a `$transform()`
+#' method for converting R plots into static images (see examples below).
+#' 
+#' @section Installation:
+#' 
+#' `kaleido()` requires [the kaleido python
+#' package](https://github.com/plotly/Kaleido/) to be usable via the \pkg{reticulate} package. Here is a recommended way to do the installation:
+#' 
+#' ```
+#' install.packages('reticulate')
+#' reticulate::install_miniconda()
+#' reticulate::conda_install('r-reticulate', 'python-kaleido')
+#' reticulate::conda_install('r-reticulate', 'plotly', channel = 'plotly')
+#' reticulate::use_miniconda('r-reticulate')
+#' ```
+#' 
+#' @param ... not currently used.
+#' @export
+#' @return an environment which contains:
+#'   * `transform()`: a function to convert plots objects into static images, 
+#'     with the following arguments:
+#'       * `p`: a plot object.
+#'       * `file`: a file path with a suitable file extension (png, jpg, jpeg, 
+#'         webp, svg, or pdf).
+#'       * `width`, `height`: The width/height of the exported image in layout 
+#'         pixels. If `scale` is 1, this will also be the width/height of the 
+#'         exported image in physical pixels.
+#'       * `scale`: The scale factor to use when exporting the figure. A scale 
+#'         factor larger than 1.0 will increase the image resolution with 
+#'         respect to the figure's layout pixel dimensions. Whereas as
+#'         scale factor of less than 1.0 will decrease the image resolution.
+#'   * `shutdown()`: a function for shutting down any currently running subprocesses 
+#'     that were launched via `transform()`
+#'   * `scope`: a reference to the underlying `kaleido.scopes.plotly.PlotlyScope`
+#'     python object. Modify this object to customize the underlying Chromium
+#'     subprocess and/or configure other details such as URL to plotly.js, MathJax, etc. 
+#' @examples 
+#' 
+#' \dontrun{
+#'   scope <- kaleido()
+#'   tmp <- tempfile(fileext = ".png")
+#'   scope$transform(plot_ly(x = 1:10), tmp)
+#'   file.show(tmp)
+#'   # Remove and garbage collect to remove 
+#'   # R/Python objects and shutdown subprocesses
+#'   rm(scope); gc()
+#' }
+#' 
+kaleido <- function(...) {
+  if (!rlang::is_installed("reticulate")) {
+    stop("`kaleido()` requires the reticulate package.")
+  }
+  if (!reticulate::py_available(initialize = TRUE)) {
+    stop("`kaleido()` requires `reticulate::py_available()`  to be `TRUE`. Do you need to install python?")
+  }
+
+  py <- reticulate::py
+  scope_name <- paste0("scope_", new_id())
+  py[[scope_name]] <- reticulate::import("kaleido")$scopes$plotly$PlotlyScope(
+    plotlyjs = plotlyMainBundlePath()
+  )
+
+  scope <- py[[scope_name]]
+
+  mapbox <- Sys.getenv("MAPBOX_TOKEN", NA)
+  if (!is.na(mapbox)) {
+    scope$mapbox_access_token <- mapbox
+  }
+
+  res <- list2env(list(
+    scope = scope,
+    # https://github.com/plotly/Kaleido/blob/6a46ecae/repos/kaleido/py/kaleido/scopes/plotly.py#L78-L106
+    transform = function(p, file = "figure.png", width = NULL, height = NULL, scale = NULL) {
+      # Perform JSON conversion exactly how the R package would do it
+      # (this is essentially plotly_json(), without the additional unneeded info)
+      # and attach as an attribute on the python scope object
+      scope[["_last_plot"]] <- to_JSON(
+        plotly_build(p)$x[c("data", "layout", "config")]
+      )
+      # On the python side, _last_plot is a string, so use json.loads() to 
+      # convert to dict(). This should be fine since json is a dependency of the
+      # BaseScope() https://github.com/plotly/Kaleido/blob/586be5/repos/kaleido/py/kaleido/scopes/base.py#L2
+      transform_cmd <- sprintf(
+        "%s.transform(sys.modules['json'].loads(%s._last_plot), format='%s', width=%s, height=%s, scale=%s)",
+        scope_name, scope_name, tools::file_ext(file), 
+        reticulate::r_to_py(width), reticulate::r_to_py(height), 
+        reticulate::r_to_py(scale)
+      )
+      # Write the base64 encoded string that transform() returns to disk
+      # https://github.com/plotly/Kaleido/blame/master/README.md#L52
+      reticulate::py_run_string(
+        sprintf("open('%s', 'wb').write(%s)", file, transform_cmd)
+      )
+    },
+    # Shutdown the kaleido subprocesses
+    # https://github.com/plotly/Kaleido/blob/586be5c/repos/kaleido/py/kaleido/scopes/base.py#L71-L72
+    shutdown = function() {
+      reticulate::py_run_string(paste0(scope_name, ".__del__()"))
+    }
+  ))
+
+  # Shutdown subprocesses and delete python scope when 
+  # this object is garbage collected by R
+  reg.finalizer(res, onexit = TRUE, function(x) {
+    x$shutdown()
+    reticulate::py_run_string(paste("del", scope_name))
+  })
+
+  class(res) <- "kaleidoScope"
+  res
+}
+
+
+#' Print method for kaleido
+#' 
+#' S3 method for [kaleido()].
+#' 
+#' @param x a [kaleido()] object.
+#' @param ... currently unused.
+#' @export
+#' @importFrom utils capture.output
+#' @keywords internal
+print.kaleidoScope <- function(x, ...) {
+  args <- formals(x$transform)
+  cat("$transform: function(", paste(names(args), collapse = ", "), ")\n", sep = "")
+  cat("$shutdown: function()\n")
+  cat("$scope: ", utils::capture.output(x$scope))
+}

R/orca.R

@@ -1,13 +1,6 @@
-#' Static image exporting 
+#' Static image exporting via orca
 #' 
-#' Export plotly objects to static images (e.g., pdf, png, jpeg, svg, etc) via the
-#' [orca command-line utility](https://github.com/plotly/orca#installation).
-#' 
-#' 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.
+#' Superseded by [kaleido()].
 #' 
 #' @param p a plotly object.
 #' @param file output filename.
@@ -67,17 +60,14 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
                  parallel_limit = NULL, verbose = FALSE, debug = FALSE, 
                  safe = FALSE, more_args = NULL, ...) {
 
+  .Deprecated("kaleido")
+
   orca_available()
 
   b <- plotly_build(p)
 
   # find the relevant plotly.js bundle
-  plotlyjs <- plotlyjsBundle(b)
-  plotlyjs_path <- file.path(plotlyjs$src$file, plotlyjs$script)
-  # package field means src file path should be relative to pkg dir
-  if (!is.null(plotlyjs$package)) {
-    plotlyjs_path <- system.file(plotlyjs_path, package = plotlyjs$package)
-  }
+  plotlyjs_path <- plotlyMainBundlePath()
 
   tmp <- tempfile(fileext = ".json")
   cat(to_JSON(b$x[c("data", "layout")]), file = tmp)
@@ -141,17 +131,14 @@ orca_serve <- function(port = 5151, mathjax = FALSE, safe = FALSE, request_limit
                        keep_alive = TRUE, window_max_number = NULL, quiet = FALSE, 
                        debug = FALSE, more_args = NULL, ...) {
 
+  .Deprecated("kaleido")
+
   # make sure we have the required infrastructure
   orca_available()
   try_library("processx", "orca_serve")
 
   # use main bundle since any plot can be thrown at the server
-  plotlyjs <- plotlyMainBundle()
-  plotlyjs_path <- file.path(plotlyjs$src$file, plotlyjs$script)
-  # package field means src file path should be relative to pkg dir
-  if (!is.null(plotlyjs$package)) {
-    plotlyjs_path <- system.file(plotlyjs_path, package = plotlyjs$package)
-  }
+  plotlyjs_path <- plotlyMainBundlePath()
 
   args <- c(
     "serve",

R/plotly.R

@@ -487,6 +487,15 @@ plotlyMainBundle <- function() {
   )
 }
 
+plotlyMainBundlePath <- function() {
+  dep <- plotlyMainBundle()
+  path <- file.path(dep$src$file, dep$script)
+  if (!is.null(dep$package)) {
+    path <- system.file(path, package = dep$package)
+  }
+  path
+}
+
 plotlyHtmlwidgetsCSS <- function() {
   htmltools::htmlDependency(
     name = "plotly-htmlwidgets-css",