|
| 1 | +#' Static image export via orca |
| 2 | +#' |
| 3 | +#' The function makes a system call to the orca command-line utility, |
| 4 | +#' see the installation instructions [here](https://github.com/plotly/orca#installation) |
| 5 | +#' |
| 6 | +#' @param p a plotly object. |
| 7 | +#' @param file output filename. |
| 8 | +#' @param format the output format (png, jpeg, webp, svg, pdf, eps). |
| 9 | +#' @param scale Sets the image scale. Applies to all output images. |
| 10 | +#' @param width Sets the image width. If not set, defaults to `layout.width` value. |
| 11 | +#' Applies to all output images. |
| 12 | +#' @param height Sets the image height. If not set, defaults to `layout.height` value. |
| 13 | +#' Applies to all output images. |
| 14 | +#' @param mathjax whether or not to specify a path to mathjax (required to export LaTeX characters). |
| 15 | +#' This should 'just work' in RStudio, but outside RStudio, you may have to set |
| 16 | +#' the PLOTLY_MATHJAX_PATH environment variable to the location of MathJax. |
| 17 | +#' @param parallel_limit Sets the limit of parallel tasks run. |
| 18 | +#' @param verbose Turn on verbose logging on stdout. |
| 19 | +#' @param debug Starts app in debug mode and turn on verbose logs on stdout. |
| 20 | +#' @param safe Turns on safe mode: where figures likely to make browser window |
| 21 | +#' hang during image generating are skipped. |
| 22 | +#' @export |
| 23 | +#' @author Carson Sievert |
| 24 | +#' @examples |
| 25 | +#' |
| 26 | +#' \dontrun{ |
| 27 | +#' p <- plot_ly(z = ~volcano) %>% add_surface() |
| 28 | +#' orca(p, "surface-plot.png") |
| 29 | +#' orca(p, "surface-plot.svg") |
| 30 | +#' orca(p, "surface-plot.pdf") |
| 31 | +#' } |
| 32 | +#' |
| 33 | + |
| 34 | +orca <- function(p, file = "plot.png", format = tools::file_ext(file), |
| 35 | + scale = NULL, width = NULL, height = NULL, mathjax = FALSE, |
| 36 | + parallel_limit = NULL, verbose = FALSE, debug = FALSE, |
| 37 | + safe = FALSE) { |
| 38 | + |
| 39 | + if (Sys.which("orca") == "") { |
| 40 | + stop( |
| 41 | + "The orca command-line utility is required to use the `orca()` function.\n\n", |
| 42 | + "Follow the installation instructions here -- https://github.com/plotly/orca#installation", |
| 43 | + call. = FALSE |
| 44 | + ) |
| 45 | + } |
| 46 | + |
| 47 | + b <- plotly_build(p) |
| 48 | + |
| 49 | + # find the relevant plotly.js bundle |
| 50 | + plotlyjs <- plotlyjsBundle(b) |
| 51 | + plotlyjs_file <- file.path(plotlyjs$src$file, plotlyjs$script) |
| 52 | + |
| 53 | + args <- c( |
| 54 | + "graph", to_JSON(b$x[c("data", "layout")]), |
| 55 | + "-o", file, |
| 56 | + "--format", format, |
| 57 | + "--plotlyjs", plotlyjs_file, |
| 58 | + if (debug) "--debug", |
| 59 | + if (verbose) "--verbose", |
| 60 | + if (safe) "--safe-mode" |
| 61 | + ) |
| 62 | + |
| 63 | + if (!is.null(scale)) args <- c(args, "--scale", scale) |
| 64 | + if (!is.null(width)) args <- c(args, "--width", width) |
| 65 | + if (!is.null(height)) args <- c(args, "--height", height) |
| 66 | + if (!is.null(parallel_limit)) args <- c(args, "--parallel-limit", parallel_limit) |
| 67 | + if (!is.na(mapbox_token())) args <- c(args, "--mapbox-access-token", mapbox_token()) |
| 68 | + if (isTRUE(mathjax)) args <- c(args, "--mathjax", mathjax_path()) |
| 69 | + |
| 70 | + # TODO: point to local topojson? Should this only work if plot_geo(standalone = TRUE)? |
| 71 | + try_library("processx", "orca") |
| 72 | + invisible(processx::run("orca", args, echo = TRUE, spinner = TRUE)) |
| 73 | +} |
| 74 | + |
| 75 | + |
| 76 | +mathjax_path <- function() { |
| 77 | + if (is_rstudio()) { |
| 78 | + try_library("rmarkdown", "orca") |
| 79 | + return(getFromNamespace("pandoc_mathjax_local_path", "rmarkdown")()) |
| 80 | + } |
| 81 | + path <- Sys.getenv("PLOTLY_MATHJAX_PATH", Sys.getenv("RMARKDOWN_MATHJAX_PATH", NA)) |
| 82 | + if (!is.na(path)) return(normalizePath(path, mustWork = TRUE)) |
| 83 | + stop( |
| 84 | + "Please set either the RMARKDOWN_MATHJAX_PATH or PLOTLY_MATHJAX_PATH ", |
| 85 | + "environment variable to the location of MathJax. ", |
| 86 | + "On Linux systems you can also install MathJax using your system package manager.", |
| 87 | + call. = FALSE |
| 88 | + ) |
| 89 | +} |
0 commit comments