From f5e2d9cf1a468f14422ed6c03c30d7b4ed1dc52c Mon Sep 17 00:00:00 2001 From: Carson Date: Sun, 18 Jul 2021 11:26:59 -0500 Subject: [PATCH 1/2] Add save_image(), a convenience wrapper around kaleido()$transform() --- NAMESPACE | 1 + NEWS.md | 2 +- R/kaleido.R | 51 ++++++++++++++++++++----------- man/{kaleido.Rd => save_image.Rd} | 49 +++++++++++++++++------------ 4 files changed, 64 insertions(+), 39 deletions(-) rename man/{kaleido.Rd => save_image.Rd} (60%) 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..a370e06683 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,18 @@ #' ``` #' #' @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. `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 +39,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 +87,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 +108,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..ef65640b22 100644 --- a/man/kaleido.Rd +++ b/man/save_image.Rd @@ -1,31 +1,33 @@ % 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. \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.} } \value{ -an environment which contains: -\itemize{ -\item \code{transform()}: a function to convert plots objects into static images, -with the following arguments: +For \code{save_image()}, the generated \code{file}. For \code{kaleido()}, an environment that contains: \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 +38,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 +54,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() From 618bb0ccef4bb162a878bfb5a7f9bfaff3045736 Mon Sep 17 00:00:00 2001 From: Carson Date: Sun, 18 Jul 2021 12:04:35 -0500 Subject: [PATCH 2/2] Rd fix --- R/kaleido.R | 3 ++- man/save_image.Rd | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/R/kaleido.R b/R/kaleido.R index a370e06683..d03daa62c9 100644 --- a/R/kaleido.R +++ b/R/kaleido.R @@ -24,7 +24,8 @@ #' 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. `scale`: The scale factor to use when exporting +#' 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. diff --git a/man/save_image.Rd b/man/save_image.Rd index ef65640b22..06a0e2596d 100644 --- a/man/save_image.Rd +++ b/man/save_image.Rd @@ -19,7 +19,9 @@ webp, svg, or pdf).} \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. \code{scale}: The scale factor to use when exporting +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.}