| Title: | 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. |
| Authors: | Thomas Lin Pedersen [cre, aut] (ORCID: <https://orcid.org/0000-0002-5147-4711>), 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] (ROR: <https://ror.org/03wc8by49>) |
| Maintainer: | Thomas Lin Pedersen <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.5.0.9000 |
| Built: | 2025-11-18 06:59:39 UTC |
| Source: | https://github.com/r-lib/ragg |
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.
agg_capture( width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bg)agg_capture( width=480, height=480, units="px", pointsize=12, background="white", res=72, scaling=1, snap_rect=TRUE, bg)
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 |
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.
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))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))
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.
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)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)
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 |
Smoothing is only applied if ragg has been compiled against a jpeglibrary that supports smoothing.
file <- tempfile(fileext = '.jpeg')agg_jpeg(file, quality = 50)plot(sin, -pi, 2*pi)dev.off()file<- tempfile(fileext='.jpeg')agg_jpeg(file, quality=50)plot(sin,-pi,2*pi)dev.off()
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.
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)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)
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 |
file <- tempfile(fileext = '.png')agg_png(file)plot(sin, -pi, 2*pi)dev.off()file<- tempfile(fileext='.png')agg_png(file)plot(sin,-pi,2*pi)dev.off()
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.
agg_ppm( filename = "Rplot%03d.ppm", width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bg)agg_ppm( filename="Rplot%03d.ppm", width=480, height=480, units="px", pointsize=12, background="white", res=72, scaling=1, snap_rect=TRUE, bg)
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 |
file <- tempfile(fileext = '.ppm')agg_ppm(file)plot(sin, -pi, 2*pi)dev.off()file<- tempfile(fileext='.ppm')agg_ppm(file)plot(sin,-pi,2*pi)dev.off()
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.
agg_record( width = 480, height = 480, units = "px", pointsize = 12, background = "white", res = 72, scaling = 1, snap_rect = TRUE, bg)agg_record( width=480, height=480, units="px", pointsize=12, background="white", res=72, scaling=1, snap_rect=TRUE, bg)
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 |
# 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()# 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()
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.
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)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)
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 |
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.
'jpeg' compression is only available if ragg is compiled with aversion oflibtiff where jpeg support has been turned on.
file <- tempfile(fileext = '.tiff')# Use jpeg compressionagg_tiff(file, compression = 'lzw+p')plot(sin, -pi, 2*pi)dev.off()file<- tempfile(fileext='.tiff')# Use jpeg compressionagg_tiff(file, compression='lzw+p')plot(sin,-pi,2*pi)dev.off()
The WebP format is a raster image format that provides improved lossless (andlossy) compression for images on the web. Transparency is supported.
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)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)
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 |
file <- tempfile(fileext = '.webp')agg_webp(file)plot(sin, -pi, 2*pi)dev.off()file<- tempfile(fileext='.webp')agg_webp(file)plot(sin,-pi,2*pi)dev.off()
The WebP format is a raster image format that provides improved lossless (andlossy) compression for images on the web. Transparency is supported.
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)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)
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 |
agg_webp() for static WebP images
## 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)## Not run:file<- tempfile(fileext='.webp')agg_webp_anim(file, delay=100, loop=0)for(iin1:10){ plot(sin(1:100+ i/10), type='l', ylim= c(-1,1)) dev.flush()}dev.off()## End(Not run)