Save Plotly charts as static images — write

Writes Plotly charts to static image files in SVG and optionally additional formats (EPS, PDF, PNG, PS, and/or WebP) using plotly::kaleido().

In contrast to plotly::save_image(), this function

allows to export multiple plotly objects in a single kaleido session to multiple output formats in one go.
allows to tweak the exported SVG images to be responsive.
allows to crop unused space around the exported images.
allows to add padding around the exported images.

Usage

write_img(
  plots,
  dir = ".",
  formats = "pdf",
  width = NULL,
  height = NULL,
  scale = NULL,
  responsive = TRUE,
  crop = TRUE,
  padding = c(0L, 10L, 0L, 10L),
  show_progress = TRUE
)

Arguments

plots

Charts to export. A named list of plotly objects. Names are used as output filenames (excl. filetype extension).

dir

Path to the directory of the exported files. A character scalar.

formats

Additional image file formats to export to besides the default SVG format. Zero or more of "png", "webp", "pdf", "eps" and "ps".

width

Width of the exported image in layout pixels. If scale is 1, this will also be the width of the exported image in physical pixels. A numeric vector that is recycled to the length of plots, or NULL.

height

Height of the exported image in layout pixels. If scale is 1, this will also be the height of the exported image in physical pixels. A numeric vector that is recycled to the length of plots, or NULL.

scale

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. A numeric vector that is recycled to the length of plots, or NULL.

responsive

Whether or not to modify the SVG image to become responsive when inlined into HTML by setting its width and height property to "100%". A logical vector, recycled to the length of plots.

crop

Whether or not to crop unused space around the generated image. Note that this has no effect on formats = c("eps", "ps") – EPS images are always cropped while cropping PS images is not supported. A logical vector, recycled to the length of plots.

padding

Padding to leave after cropping unused space around the generated image. Either a single numeric vector, or a list of numeric vectors. Each vector must be of length 1–4:

When one value is specified, it applies the same padding to all four sides.
When two values are specified, the first padding applies to the top and bottom, the second to the left and right.
When three values are specified, the first padding applies to the top, the second to the right and left, the third to the bottom.
When four values are specified, the paddings apply to the top, right, bottom, and left in that order (clockwise).

For formats = "pdf", the values are in bp ("big points"), for all other formats in pixels. Only relevant if crop = TRUE. Note that padding has no effect on formats = "eps", i.e. EPS images are always fully cropped.

show_progress

Whether or not to output progress indication.

Value

The paths to the generated SVG files, invisibly.

Details

PNG and WebP images are completely based on the resulting SVG image, while EPS, PDF and PS are built from an intermediate SVG representation (before viewbox-based SVG cropping is applied). Accordingly, results of the different output formats might differ.

It's recommended to rely on SVG images wherever possible and fall back to PDF images where necessary (e.g. in LaTeX documents) since these two vector image formats provide the best visual results. EPS and PS images should be avoided if possible due to their shortcomings in cropping and padding.

Examples

if (FALSE) {
plotly::plot_ly(data = mtcars,
                type = "scatter",
                mode = "markers",
                x = ~mpg,
                y = ~hp) |>
  list("mtcars_mpg_by_hp" = _) |>
  plotlee::write_img(formats = c("pdf", "png"))}