diff --git a/NAMESPACE b/NAMESPACE index 381958839d..eb46d4c658 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -170,6 +170,7 @@ export(remove_typedarray_polyfill) export(rename) export(rename_) export(renderPlotly) +export(save_image) export(schema) export(select) export(select_) diff --git a/NEWS.md b/NEWS.md index 619b797338..9cd9d6e545 100644 --- a/NEWS.md +++ b/NEWS.md @@ -10,7 +10,7 @@ ## 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) +* Added new functions for static image exporting via the [kaleido python package](https://github.com/plotly/Kaleido), namely `save_image()` and `kaleido()`. See `help(save_image, package = "plotly")` for installation info and example usage. (#1971) ## Improvements diff --git a/R/kaleido.R b/R/kaleido.R index 5ac8127cb4..d03daa62c9 100644 --- a/R/kaleido.R +++ b/R/kaleido.R @@ -1,9 +1,9 @@ -#' Static image exporting via kaleido +#' Save plot as a static image #' #' 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). +#' method for converting R plots into static images. `save_image()` provides a convenience wrapper around `kaleido()$transform()`. #' #' @section Installation: #' @@ -19,20 +19,19 @@ #' ``` #' #' @param ... not currently used. +#' @param p a plot object. +#' @param file a file path with a suitable file extension (png, jpg, jpeg, +#' webp, svg, or pdf). +#' @param 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. +#' @param 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. #' @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. +#' @return For `save_image()`, the generated `file`. For `kaleido()`, an environment that contains: +#' * `transform()`: a function to convert plots objects into static images. This function has the same signature (i.e., arguments) as `save_image()` #' * `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` @@ -41,15 +40,30 @@ #' @examples #' #' \dontrun{ -#' scope <- kaleido() +#' # Save a single image +#' p <- plot_ly(x = 1:10) #' tmp <- tempfile(fileext = ".png") -#' scope$transform(plot_ly(x = 1:10), tmp) +#' save_image(p, tmp) #' file.show(tmp) +#' +#' # Efficiently save multiple images +#' scope <- kaleido() +#' for (i in 1:5) { +#' scope$transform(p, tmp) +#' } #' # Remove and garbage collect to remove #' # R/Python objects and shutdown subprocesses #' rm(scope); gc() #' } #' +save_image <- function(p, file, ..., width = NULL, height = NULL, scale = NULL) { + kaleido()$transform( + p, file, ..., width = width, height = height, scale = scale + ) +} + +#' @rdname save_image +#' @export kaleido <- function(...) { if (!rlang::is_installed("reticulate")) { stop("`kaleido()` requires the reticulate package.") @@ -74,7 +88,7 @@ kaleido <- function(...) { 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) { + 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 @@ -95,6 +109,8 @@ kaleido <- function(...) { reticulate::py_run_string( sprintf("open('%s', 'wb').write(%s)", file, transform_cmd) ) + + invisible(file) }, # Shutdown the kaleido subprocesses # https://github.com/plotly/Kaleido/blob/586be5c/repos/kaleido/py/kaleido/scopes/base.py#L71-L72 diff --git a/man/kaleido.Rd b/man/save_image.Rd similarity index 60% rename from man/kaleido.Rd rename to man/save_image.Rd index 40f733ec18..06a0e2596d 100644 --- a/man/kaleido.Rd +++ b/man/save_image.Rd @@ -1,31 +1,35 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/kaleido.R -\name{kaleido} +\name{save_image} +\alias{save_image} \alias{kaleido} -\title{Static image exporting via kaleido} +\title{Save plot as a static image} \usage{ +save_image(p, file, ..., width = NULL, height = NULL, scale = NULL) + kaleido(...) } \arguments{ +\item{p}{a plot object.} + +\item{file}{a file path with a suitable file extension (png, jpg, jpeg, +webp, svg, or pdf).} + \item{...}{not currently used.} + +\item{width, height}{The width/height of the exported image in layout +pixels. If \code{scale} is 1, this will also be the width/height of the exported +image in physical pixels.} + +\item{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.} } \value{ -an environment which contains: +For \code{save_image()}, the generated \code{file}. For \code{kaleido()}, an environment that contains: \itemize{ -\item \code{transform()}: a function to convert plots objects into static images, -with the following arguments: -\itemize{ -\item \code{p}: a plot object. -\item \code{file}: a file path with a suitable file extension (png, jpg, jpeg, -webp, svg, or pdf). -\item \code{width}, \code{height}: The width/height of the exported image in layout -pixels. If \code{scale} is 1, this will also be the width/height of the -exported image in physical pixels. -\item \code{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. -} +\item \code{transform()}: a function to convert plots objects into static images. This function has the same signature (i.e., arguments) as \code{save_image()} \item \code{shutdown()}: a function for shutting down any currently running subprocesses that were launched via \code{transform()} \item \code{scope}: a reference to the underlying \code{kaleido.scopes.plotly.PlotlyScope} @@ -36,7 +40,7 @@ subprocess and/or configure other details such as URL to plotly.js, MathJax, etc \description{ Static image exporting via \href{https://github.com/plotly/Kaleido/}{the kaleido python package}. \code{kaleido()} imports kaleido into a \pkg{reticulate}d Python session and returns a \verb{$transform()} -method for converting R plots into static images (see examples below). +method for converting R plots into static images. \code{save_image()} provides a convenience wrapper around \code{kaleido()$transform()}. } \section{Installation}{ @@ -52,10 +56,17 @@ reticulate::use_miniconda('r-reticulate') \examples{ \dontrun{ - scope <- kaleido() + # Save a single image + p <- plot_ly(x = 1:10) tmp <- tempfile(fileext = ".png") - scope$transform(plot_ly(x = 1:10), tmp) + save_image(p, tmp) file.show(tmp) + + # Efficiently save multiple images + scope <- kaleido() + for (i in 1:5) { + scope$transform(p, tmp) + } # Remove and garbage collect to remove # R/Python objects and shutdown subprocesses rm(scope); gc()