| Type: | Package |
| Title: | Graphic Devices Based on AGG |
| Version: | 1.5.0 |
| Maintainer: | Thomas Lin Pedersen <thomas.pedersen@posit.co> |
| Description: | Anti-Grain Geometry (AGG) is a high-quality and high-performance 2D drawing library. The 'ragg' package provides a set of graphic devices based on AGG to use as alternative to the raster devices provided through the 'grDevices' package. |
| License: | MIT + file LICENSE |
| URL: | https://ragg.r-lib.org,https://github.com/r-lib/ragg |
| BugReports: | https://github.com/r-lib/ragg/issues |
| Imports: | systemfonts (≥ 1.0.3), textshaping (≥ 0.3.0) |
| Suggests: | covr, graphics, grid, testthat (≥ 3.0.0) |
| LinkingTo: | systemfonts, textshaping |
| Config/build/compilation-database: | true |
| Config/Needs/website: | ggplot2, devoid, magick, bench, tidyr, ggridges,hexbin, sessioninfo, pkgdown, tidyverse/tidytemplate |
| Config/testthat/edition: | 3 |
| Config/usethis/last-upkeep: | 2025-04-25 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| SystemRequirements: | freetype2, libpng, libtiff, libjpeg, libwebp,libwebpmux |
| NeedsCompilation: | yes |
| Packaged: | 2025-09-02 06:41:57 UTC; thomas |
| Author: | Thomas Lin Pedersen [cre, aut], Maxim Shemanarev [aut, cph] (Author of AGG), Tony Juricic [ctb, cph] (Contributor to AGG), Milan Marusinec [ctb, cph] (Contributor to AGG), Spencer Garrett [ctb] (Contributor to AGG), Posit Software, PBC [cph, fnd] |
| Repository: | CRAN |
| Date/Publication: | 2025-09-02 07:20:02 UTC |
ragg: Graphic Devices Based on AGG
Description
Anti-Grain Geometry (AGG) is a high-quality and high-performance 2D drawing library. The 'ragg' package provides a set of graphic devices based on AGG to use as alternative to the raster devices provided through the 'grDevices' package.
Author(s)
Maintainer: Thomas Lin Pedersenthomas.pedersen@posit.co (ORCID)
Authors:
Maxim Shemanarev (Author of AGG) [copyright holder]
Other contributors:
Tony Juricictonygeek@yahoo.com (Contributor to AGG) [contributor, copyright holder]
Milan Marusinecmilan@marusinec.sk (Contributor to AGG) [contributor, copyright holder]
Spencer Garrett (Contributor to AGG) [contributor]
Posit Software, PBC (03wc8by49) [copyright holder, funder]
See Also
Useful links:
Report bugs athttps://github.com/r-lib/ragg/issues
Draw to a buffer that can be accessed directly
Description
Usually the point of using a graphic device is to create a file or show thegraphic on the screen. A few times we need the image data for furtherprocessing in R, and instead of writing it to a file and then reading it backinto R theagg_capture() device lets you get the image data directly fromthe buffer. In contrast to the other devices this device returns a function,that when called will return the current state of the buffer.
Usage
agg_capture( width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bg)Arguments
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
bg | Same as |
Value
A function that when called returns the current state of the buffer.The return value of the function depends on thenative argument. IfFALSE(default) the return value is amatrix of colour values and ifTRUE thereturn value is anativeRaster object.
Examples
cap <- agg_capture()plot(1:10, 1:10)# Get the plot as a matrixraster <- cap()# Get the plot as a nativeRasterraster_n <- cap(native = TRUE)dev.off()# Look at the outputplot(as.raster(raster))Draw to a JPEG file
Description
The JPEG file format is a lossy compressed file format developed inparticular for digital photography. The format is not particularlywell-suited for line drawings and text of the type normally associated withstatistical plots as the compression algorithm creates noticable artefacts.It is, however, great for saving image data, e.g. heightmaps etc. Thus, forstandard plots, it would be better to useagg_png(), but for plots thatincludes a high degree of raster image rendering this device will result insmaller plots with very little quality degradation.
Usage
agg_jpeg( filename = "Rplot%03d.jpeg", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, quality = 75, smoothing = FALSE, method = "slow", bg)Arguments
filename | The name of the file. Follows the same semantics as the filenaming in |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
quality | An integer between |
smoothing | A smoothing factor to apply before compression, from |
method | The compression algorithm to use. Either |
bg | Same as |
Note
Smoothing is only applied if ragg has been compiled against a jpeglibrary that supports smoothing.
Examples
file <- tempfile(fileext = '.jpeg')agg_jpeg(file, quality = 50)plot(sin, -pi, 2*pi)dev.off()Draw to a PNG file
Description
The PNG (Portable Network Graphic) format is one of the most ubiquitoustoday, due to its versatiliityand widespread support. It supports transparency as well as both 8 and 16 bitcolour. The device uses default compression and filtering and will not use acolour palette as this is less useful for antialiased data. This means thatit might be possible to compress the resulting image even more if size is ofconcern (though the defaults are often very good). In contrast togrDevices::png() the date and time will not be written to the file, meaningthat similar plot code will produce identical files (a good feature if usedwith version control). It will, however, write in the dimensions of the imagebased on theres argument.
Usage
agg_png( filename = "Rplot%03d.png", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bitsize = 8, bg)Arguments
filename | The name of the file. Follows the same semantics as the filenaming in |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
bitsize | Should the device record colour as 8 or 16bit |
bg | Same as |
Examples
file <- tempfile(fileext = '.png')agg_png(file)plot(sin, -pi, 2*pi)dev.off()Draw to a PPM file
Description
The PPM (Portable Pixel Map) format defines one of the simplest storageformats available forimage data. It is basically a raw 8bit RGB stream with a few bytes ofinformation in the start. It goes without saying, that this file format ishorribly inefficient and should only be used if you want to play around witha simple file format, or need a file-based image stream.
Usage
agg_ppm( filename = "Rplot%03d.ppm", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bg)Arguments
filename | The name of the file. Follows the same semantics as the filenaming in |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
bg | Same as |
Examples
file <- tempfile(fileext = '.ppm')agg_ppm(file)plot(sin, -pi, 2*pi)dev.off()Capture drawing instructions without rendering
Description
While the point of a graphics device is usually to render the graphics, thereare a few situations where you are instead interested in only capturing theinstructions required to render the graphics. While all graphics devices canbe retrofitted for that usingdev.control(), they would still render totheir internal buffer even if you are only interested in the recordedinstructions, thus adding a performance penalty.agg_record() is a devicethat does no rendering whatsoever, but has recording turned on by defaultmaking it a no-overhead solution for plot recording.
Usage
agg_record( width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bg)Arguments
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
bg | Same as |
Examples
# Capture drawing instructionsagg_record()plot(1:10, 1:10)rec <- recordPlot()dev.off()# Replay these on another devicefile <- tempfile(fileext = '.png')agg_png(file)replayPlot(rec)dev.off()Draw to a PNG file, modifying transparency on the fly
Description
The graphic engine in R only supports 8bit colours. This is for the most partfine, as 8bit gives all the fidelity needed for most graphing needs. However,this may become a limitation if you need to plot thousands of verytranslucent shapes on top of each other. 8bit only afford a minimum of 1/255alpha, which may end up accumulating to fully opaque at some point. Thisdevice allows you to create a 16bit device that modifies the alpha level ofall incomming colours by a fixed multiplier, thus allowing for much moretranslucent colours. The device will only modify transparent colour, so ifyou pass in an opaque colour it will be left unchanged.
Usage
agg_supertransparent( filename = "Rplot%03d.png", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, alpha_mod = 1, bg)Arguments
filename | The name of the file. Follows the same semantics as the filenaming in |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
alpha_mod | A numeric between 0 and 1 that will be multiplied to thealpha channel of all transparent colours |
bg | Same as |
Draw to a TIFF file
Description
The TIFF (Tagged Image File Format) format is a very versatile raster imagestorage format that supports 8 and 16bit colour mode, true transparency, aswell as a range of other features not relevant to drawing from R (e.g.support for different colour spaces). The storage mode of the image data isnot fixed and different compression modes are possible, in contrast to PNGsone-approach-fits-all. The default (uncompressed) will result in much largerfiles than PNG, and in general PNG is a better format for many of the graphictypes produced in R. Still, TIFF has its purposes and sometimes this fileformat is explicetly requested.
Usage
agg_tiff( filename = "Rplot%03d.tiff", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, compression = "none", bitsize = 8, bg)Arguments
filename | The name of the file. Follows the same semantics as the filenaming in |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
compression | The compression type to use for the image data. Thestandard options from the |
bitsize | Should the device record colour as 8 or 16bit |
bg | Same as |
Transparency
TIFF have support for true transparency, meaning that the pixel colour isstored in pre-multiplied form. This is in contrast to pixels being stored inplain format, where the alpha values more function as a mask. The utility ofthis is not always that important, but it is one of the benefits of TIFF overPNG so it should be noted.
Note
'jpeg' compression is only available if ragg is compiled with aversion oflibtiff where jpeg support has been turned on.
Examples
file <- tempfile(fileext = '.tiff')# Use jpeg compressionagg_tiff(file, compression = 'lzw+p')plot(sin, -pi, 2*pi)dev.off()Draw to a WebP file
Description
The WebP format is a raster image format that provides improved lossless (andlossy) compression for images on the web. Transparency is supported.
Usage
agg_webp( filename = "Rplot%03d.webp", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, lossy = FALSE, quality = 80, bg)Arguments
filename | The name of the file. Follows the same semantics as the filenaming in |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
lossy | Use lossy compression. Default is |
quality | An integer between |
bg | Same as |
Examples
file <- tempfile(fileext = '.webp')agg_webp(file)plot(sin, -pi, 2*pi)dev.off()Draw an animation to a WebP file
Description
The WebP format is a raster image format that provides improved lossless (andlossy) compression for images on the web. Transparency is supported.
Usage
agg_webp_anim( filename = "Ranim.webp", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, lossy = FALSE, quality = 80, delay = 100L, loop = 0L, bg)Arguments
filename | The name of the file. This function does not perform pagenumber substitution as the other devices since it cannot produce multiplepages. |
width,height | The dimensions of the device |
units | The unit |
pointsize | The default pointsize of the device in pt. This will ingeneral not have any effect on grid graphics (including ggplot2) as textsize is always set explicitly there. |
background | The background colour of the device |
res | The resolution of the device. This setting will govern how devicedimensions given in inches, centimeters, or millimeters will be convertedto pixels. Further, it will be used to scale text sizes and linewidths |
scaling | A scaling factor to apply to the rendered line width and textsize. Useful for getting the right dimensions at the resolution that youneed. If e.g. you need to render a plot at 4000x3000 pixels for it to fitinto a layout, but you find that the result appears to small, you canincrease the |
snap_rect | Should axis-aligned rectangles drawn with only fill snap tothe pixel grid. This will prevent anti-aliasing artifacts when tworectangles are touching at their border. |
lossy | Use lossy compression. Default is |
quality | An integer between |
delay | Per-frame delay in milliseconds (single integer) |
loop | Number of loops (0 = infinite) |
bg | Same as |
See Also
agg_webp() for static WebP images
Examples
## Not run: file <- tempfile(fileext = '.webp')agg_webp_anim(file, delay = 100, loop = 0)for(i in 1:10) { plot(sin(1:100 + i/10), type = 'l', ylim = c(-1, 1)) dev.flush()}dev.off()## End(Not run)Objects exported from other packages
Description
These objects are imported from other packages. Follow the linksbelow to see their documentation.
- systemfonts
- textshaping