Lets-Plot-Kotlin/org.jetbrains.letsPlot.export/ggsave

ggsave

fun ggsave(plot: Figure, filename: String, scale: Number? = null, dpi: Number? = null, path: String? = null, w: Number? = null, h: Number? = null, unit: String? = null): String

Exports plot to a file. Supported formats: SVG, HTML, PNG, JPEG, and TIFF. Note: in some configurations raster formats might not be supported.

If path is not specified, the output file will be saved in ${user.dir}/lets-plot-images.

Notes

Large plot dimensions without units require explicit unit specification. When w or h value exceeds 20 without specifying units (e.g., ggsave(p, 300, 400)), we ask to specify units explicitly: ggsave(p, 300, 400, unit="px") or ggsave(p, 3, 4, unit="in").

The output format is inferred from the file extension.

For PNG, JPEG, and TIFF:

  • If w, h, unit, and dpi are all specified:

    • The plot's pixel size (default or set via ggsize()) is ignored.

    • The output size is computed from the given dimensions and DPI.

      • The plot is resized to fit the specified w x h area, which may affect the layout.

  • If only dpi is specified:

    • The plot's pixel size (default or set via ggsize()) is converted to inches assuming the standard display PPI of 96 PPI.

    • The output size is computed from this size and dpi.

      • The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.

      • Useful for printing - the plot will appear nearly the same size as on screen.

  • If w and h are not specified:

    • The scale parameter is used to determine the output size.

      • The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.

      • Useful for generating high-resolution images suitable for publication.

For SVG:

  • If w, h, and unit are specified:

    • The plot's pixel size (default or set via ggsize()) is ignored.

    • The output size is set from the given values.

For HTML:

  • If w and h are specified:

    • The plot's pixel size (default or set via ggsize()) is ignored.

    • The output size is determined directly from the specified w and h, which are treated as pixel values.

Examples

Return

Absolute pathname of the created file.

Parameters

plot

Plot to export.

filename

Name of the file. Must include an extension matching one of the supported formats: .svg, .html/.htm, .png, .jpeg/.jpg, or .tiff/.tif

scale

Scaling factor (only for raster formats). Default: 2.0

w

Width of the output image in units.

h

Height of the output image in units.

unit

Unit of the output image. One of: "in", "cm", "mm", "px". Only applicable when exporting to SVG, PNG, JPG, or TIFF. For HTML, the unit is always "px" (pixels). Default: "px" (pixels) for SVG, "in" (inches) for the raster formats (PNG, JPG, and TIFF).

dpi

Resolution in dots per inch. Only applicable when exporting to the raster formats: PNG, JPG, or TIFF. The default value depends on the unit:

  • for "px" it is 96 (output image will have the same pixel size as w and h values)

  • for physical units ("in", "cm", "mm") it is 300.

path

Path to a directory to save image files in. Default: ${user.dir}/lets-plot-images