Title: | R Graphics Device using Cairo Graphics Library for Creating High-Quality Bitmap (PNG, JPEG, TIFF), Vector (PDF, SVG, PostScript) and Display (X11 and Win32) Output |
---|---|
Description: | R graphics device using cairographics library that can be used to create high-quality vector (PDF, PostScript and SVG) and bitmap output (PNG,JPEG,TIFF), and high-quality rendering in displays (X11 and Win32). Since it uses the same back-end for all output, copying across formats is WYSIWYG. Files are created without the dependence on X11 or other external programs. This device supports alpha channel (semi-transparent drawing) and resulting images can contain transparent and semi-transparent regions. It is ideal for use in server environments (file output) and as a replacement for other devices that don't have Cairo's capabilities such as alpha support or anti-aliasing. Backends are modular such that any subset of backends is supported. |
Authors: | Simon Urbanek [aut, cre, cph] (https://urbanek.org, <https://orcid.org/0000-0003-2297-1732>), Jeffrey Horner [aut] |
Maintainer: | Simon Urbanek <[email protected]> |
License: | GPL-2 | GPL-3 |
Version: | 1.2-0 |
Built: | 2024-10-25 05:47:30 UTC |
Source: | https://github.com/s-u/cairo |
Cairo
initializes a new graphics device that uses the cairo
graphics library for rendering. The current implementation produces
high-quality PNG, JPEG, TIFF bitmap files, high resolution PDF files
with embedded fonts, SVG graphics and PostScript files. It also
provides X11 and Windows interactive graphics devices. Unlike other
devices it supports all graphics features including alpha blending,
anti-aliasing etc.
CairoX11
, CairoPNG
, CairoPDF
, CairoPS
and
CairoSVG
are convenience wrappers of Cairo
that take the
same arguments as the corresponding device it replaces such as
X11
, png
, pdf
, etc. Use of the Cairo
function is encouraged as it is more flexible than the wrappers.
Cairo(width = 640, height = 480, file="", type="png", pointsize=12, bg = "transparent", canvas = "white", units = "px", dpi = "auto", ...) CairoX11(display=Sys.getenv("DISPLAY"), width = 7, height = 7, pointsize = 12, gamma = getOption("gamma"), bg = "transparent", canvas = "white", xpos = NA, ypos = NA, ...) CairoPNG(filename = "Rplot%03d.png", width = 480, height = 480, pointsize = 12, bg = "white", res = NA, ...) CairoJPEG(filename = "Rplot%03d.jpeg", width = 480, height = 480, pointsize = 12, quality = 75, bg = "white", res = NA, ...) CairoTIFF(filename = "Rplot%03d.tiff", width = 480, height = 480, pointsize = 12, bg = "white", res = NA, ...) CairoPDF(file = ifelse(onefile, "Rplots.pdf","Rplot%03d.pdf"), width = 6, height = 6, onefile = TRUE, family = "Helvetica", title = "R Graphics Output", fonts = NULL, paper = "special", encoding, bg, fg, pointsize, pagecentre, ...) CairoSVG(file = ifelse(onefile, "Rplots.svg", "Rplot%03d.svg"), width = 6, height = 6, onefile = TRUE, bg = "transparent", pointsize = 12, ...) CairoWin(width = 7, height = 7, pointsize = 12, record = getOption("graphics.record"), rescale = c("R", "fit", "fixed"), xpinch, ypinch, bg = "transparent", canvas = "white", gamma = getOption("gamma"), xpos = NA, ypos = NA, buffered = getOption("windowsBuffered"), restoreConsole = FALSE, ...) CairoPS(file = ifelse(onefile, "Rplots.ps", "Rplot%03d.ps"), onefile = TRUE, family, title = "R Graphics Output", fonts = NULL, encoding, bg, fg, width, height, horizontal, pointsize, paper, pagecentre, print.it, command, colormodel)
Cairo(width = 640, height = 480, file="", type="png", pointsize=12, bg = "transparent", canvas = "white", units = "px", dpi = "auto", ...) CairoX11(display=Sys.getenv("DISPLAY"), width = 7, height = 7, pointsize = 12, gamma = getOption("gamma"), bg = "transparent", canvas = "white", xpos = NA, ypos = NA, ...) CairoPNG(filename = "Rplot%03d.png", width = 480, height = 480, pointsize = 12, bg = "white", res = NA, ...) CairoJPEG(filename = "Rplot%03d.jpeg", width = 480, height = 480, pointsize = 12, quality = 75, bg = "white", res = NA, ...) CairoTIFF(filename = "Rplot%03d.tiff", width = 480, height = 480, pointsize = 12, bg = "white", res = NA, ...) CairoPDF(file = ifelse(onefile, "Rplots.pdf","Rplot%03d.pdf"), width = 6, height = 6, onefile = TRUE, family = "Helvetica", title = "R Graphics Output", fonts = NULL, paper = "special", encoding, bg, fg, pointsize, pagecentre, ...) CairoSVG(file = ifelse(onefile, "Rplots.svg", "Rplot%03d.svg"), width = 6, height = 6, onefile = TRUE, bg = "transparent", pointsize = 12, ...) CairoWin(width = 7, height = 7, pointsize = 12, record = getOption("graphics.record"), rescale = c("R", "fit", "fixed"), xpinch, ypinch, bg = "transparent", canvas = "white", gamma = getOption("gamma"), xpos = NA, ypos = NA, buffered = getOption("windowsBuffered"), restoreConsole = FALSE, ...) CairoPS(file = ifelse(onefile, "Rplots.ps", "Rplot%03d.ps"), onefile = TRUE, family, title = "R Graphics Output", fonts = NULL, encoding, bg, fg, width, height, horizontal, pointsize, paper, pagecentre, print.it, command, colormodel)
width |
width of the plot area (also see |
height |
height of the plot area (also see |
file |
name of the file to be created or connection to write
to. Only PDF, PS and PNG types support connections. For X11
type |
type |
output type. This version of Cario supports "png", "jpeg"
and "tiff" bitmaps (png/tiff with transparent background), "pdf"
PDF-file with embedded fonts, "svg" SVG-file, "ps" PostScript-file,
"x11" X11 interactive window and "win" Windows graphics.
A special type "raster" creates an image back-end that produces no
actual output file but can be used in conjunction with any of
|
pointsize |
initial text size (in points). |
canvas |
canvas color (must be opaque). The canvas is only used by devices that display graphics on a screen and the canvas is only visible only if bg is transparent. |
bg |
plot background color (can include alpha-component or be transparent alltogether). |
units |
units for of the |
dpi |
DPI used for the conversion of units to pixels. If set to
|
... |
additional backend specific parameters (e.g. The PDF back-end supports following additional arguments:
All parameters
listed below are defined by the other devices are are used by
the wrappers to make it easier replace other devices by
|
display |
X11 display, see |
gamma |
gamma correction |
xpos |
see |
ypos |
see |
filename |
same as |
res |
resolution in ppi, see |
quality |
quality of the jpeg, see |
onefile |
logical: if true (the default) allow multiple
figures in one file (see |
family |
font family, see |
title |
see |
fonts |
see |
paper |
see |
encoding |
see |
fg |
see |
pagecentre |
see |
record |
Windows-specific, ignored on unix |
rescale |
Windows-specific, ignored on unix |
xpinch |
Windows-specific, ignored on unix |
ypinch |
Windows-specific, ignored on unix |
buffered |
Windows-specific, ignored on unix |
restoreConsole |
Windows-specific, ignored on unix |
horizontal |
see |
print.it |
see |
command |
see |
colormodel |
see |
The (invisible) return value is NULL if the device couldn't be created
or a Cairo
object if successful. The vaule of the object is the
device number.
The X11 backend is quite slow. The reason is the cairographics implementation of the backend, so we can't do much about it. It should be possible to drop cairographics' Xlib backend entirely and use image backend copied into an X11 window instead. We may try that in future releases.
TrueType (and OpenType) fonts are supported when this package is compiled against a cairo graphics library configured with FreeType and Fontconfig support. Therefore make sure have a cairo graphics library with all bells and whistles to get a good result.
R math symbols are supported, but require a TrueType "Symbol" font accessible to Cairo under that name.
# very simple KDE Cairo(600, 600, file="plot.png", type="png", bg="white") plot(rnorm(4000),rnorm(4000),col="#ff000018",pch=19,cex=2) # semi-transparent red dev.off() # creates a file "plot.png" with the above plot # you can use any Cairo backend and get the same result # vector, bitmap or on-screen CairoPDF("plot.pdf", 6, 6, bg="transparent") data(iris) attach(iris) plot(Petal.Length, rep(-0.03,length(Species)), xlim=c(1,7), ylim=c(0,1.7), xlab="Petal.Length", ylab="Density", pch=21, cex=1.5, col="#00000001", main = "Iris (yet again)", bg=c("#ff000020","#00ff0020","#0000ff20")[unclass(Species)]) for (i in 1:3) polygon(density(Petal.Length[unclass(Species)==i],bw=0.2), col=c("#ff000040","#00ff0040","#0000ff40")[i]) dev.off() ## remove the example files if not in an interactive session if (!interactive()) unlink(c("plot.png","plot.pdf"))
# very simple KDE Cairo(600, 600, file="plot.png", type="png", bg="white") plot(rnorm(4000),rnorm(4000),col="#ff000018",pch=19,cex=2) # semi-transparent red dev.off() # creates a file "plot.png" with the above plot # you can use any Cairo backend and get the same result # vector, bitmap or on-screen CairoPDF("plot.pdf", 6, 6, bg="transparent") data(iris) attach(iris) plot(Petal.Length, rep(-0.03,length(Species)), xlim=c(1,7), ylim=c(0,1.7), xlab="Petal.Length", ylab="Density", pch=21, cex=1.5, col="#00000001", main = "Iris (yet again)", bg=c("#ff000020","#00ff0020","#0000ff20")[unclass(Species)]) for (i in 1:3) polygon(density(Petal.Length[unclass(Species)==i],bw=0.2), col=c("#ff000040","#00ff0040","#0000ff40")[i]) dev.off() ## remove the example files if not in an interactive session if (!interactive()) unlink(c("plot.png","plot.pdf"))
Cairo.capabilities
returns a logical vector describing the
capabilities of this particular Cairo build.
Cairo.capabilities()
Cairo.capabilities()
The Cairo
package provides multiple back-ends, such as images
(PNG, JPEG, TIFF), vector graphics (PDF, PostScript, SVG) or displays
(X11, Windows). However, not all systems support all back-ends. The
Cairo.capabilities
function returns a logical vector showing
which capabilities are supported in this particular Cairo build.
Note that the capabilities depend both on the libraries available in the system as well as the compiled-in modules in cairo graphics.
Cairo.capture
is essentially the same as
dev.capture(native=TRUE)
with the exception that it works where
dev.capture
doesn't such as onSave
callbacks.
Cairo.snapshot
is very similar to recordPlot
except it
also allows to retrieve the last snapshot.
Cairo.capture(device = dev.cur()) Cairo.snapshot(device = dev.cur(), last=FALSE)
Cairo.capture(device = dev.cur()) Cairo.snapshot(device = dev.cur(), last=FALSE)
device |
device number or an object of the class |
last |
logical, if |
Cairo.capture
: object of the class nativeRaster
.
Cairo.snapshot
: object of the class recordedplot
.
Simon Urbanek
Cairo.onSave
set the onSave
callback which allows R code
to be run when Cairo finalizes a page (either due to a new page being
created or by the device being closed). The callback expects
function(device, page)
where device
will be the device
number and page
is the currently finished page number (starting
at 1).
Cairo.onSave(device = dev.cur(), onSave)
Cairo.onSave(device = dev.cur(), onSave)
device |
device number or |
onSave |
function that will replace the current callback or
|
The old callback being replaced or NULL
if there was none.
The function onSave
will be evaluated in the global environment
and no error checking is done, so you must make sure to catch errors,
otherwise the behavior is undefined (and may included crashing R or
other bad things).
Simon Urbanek
if (require(png, quietly=TRUE)) { dev <- Cairo(800, 600, type='raster') Cairo.onSave(dev, function(dev, page) .GlobalEnv$png <- writePNG(Cairo.capture(dev)) ) plot(1:10, col=2) dev.off() str(png) }
if (require(png, quietly=TRUE)) { dev <- Cairo(800, 600, type='raster') Cairo.onSave(dev, function(dev, page) .GlobalEnv$png <- writePNG(Cairo.capture(dev)) ) plot(1:10, col=2) dev.off() str(png) }
Cairo.serial
returns an integer that is increased with every
plotting operation on the device. This allows user code to determine
whether any new content has been added to the device since it was last
checked.
Cairo.serial(device = dev.cur())
Cairo.serial(device = dev.cur())
device |
device number or an object of the class |
Integer value.
The integer value overflows to 0 at 2^31. Typically only equality should be checked and for such it is extremely unlikely that the state has changed yet the serial value is the same due to overflow.
Simon Urbanek
CairoFontMatch
searches for fonts based on a fontconfig pattern.
CairoFontMatch(fontpattern="Helvetica",sort=FALSE,verbose=FALSE)
CairoFontMatch(fontpattern="Helvetica",sort=FALSE,verbose=FALSE)
fontpattern |
character; a fontconfig pattern. |
sort |
logical; if 'FALSE', display only the best matching font for the pattern. If 'TRUE', display a sorted list of best matching fonts. |
verbose |
logical; if 'FALSE', display the family, style, and file property for the pattern. if 'TRUE', display the canonical font pattern for each match. |
This function displays a list of one or more fonts matching the supplied fontconfig pattern. sort='FALSE' displays the font that Cairo will use for the supplied pattern, while sort='TRUE' displays a sorted list of best matching fonts. The simplest fontconfig pattern matching all installed fonts is ":". Here's what CairoFontMatch(":") displays on this system:
1. family: "Bitstream Vera Sans", style: "Roman", file: "/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf"
verbose='FALSE' displays the font properties 'family', 'style', and 'file', while verbose='TRUE' will display the canonical font pattern, displaying all properties known for the font (output of CairoFontMatch(":",verbose=TRUE)):
1. family: "Bitstream Vera Sans", style: "Roman", file: "/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf" "Bitstream Vera Sans-12:familylang=en:style=Roman:stylelang=en:slant=0:weight=80:width=100:pixelsize=12.5:foundry=bitstream:hintstyle=3:hinting=True:verticallayout=False:autohint=False:globaladvance=True:index=0:outline=True:scalable=True:dpi=75:rgba=1:scale=1:fontversion=131072:fontformat=TrueType:embeddedbitmap=True:decorative=False"
A simple approach to selecting a font starts with calling CairoFontMatch(":",sort=TRUE) to list all available fonts. Next, the user will choose a font from the list and call CairoFontMatch("FamilyName:style=PreferredStyle",sort=TRUE) substituting "FamilyName" and "PreferredStyle" with the desired values. If only one font is found, then the user has found the fontconfig pattern that will select the desired font. Otherwise, the user will call CairoFontMatch with verbose=TRUE to determine other properties to add to the pattern to attain the desired font, for instance the fontformat.
The following excerpt is from the fontconfig user's manual (http://fontconfig.org/) and better describes the fontconfig pattern definition:
"Fontconfig provides a textual representation for patterns that the library can both accept and generate. The representation is in three parts, first a list of family names, second a list of point sizes and finally a list of additional properties:
<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
Values in a list are separated with commas. The name needn't include either families or point sizes; they can be elided. In addition, there are symbolic constants that simultaneously indicate both a name and a value. Here are some examples:
Font Pattern Meaning ---------------------------------------------------------- Times-12 12 point Times Roman Times-12:bold 12 point Times Bold Courier:italic Courier Italic in the default size Monospace:matrix=1 .1 0 1 The users preferred monospace font with artificial obliquing
The '\', '-', ':' and ',' characters in family names must be preceeded by a '\' character to avoid having them misinterpreted. Similarly, values containing '\', '=', '_', ':' and ',' must also have them preceeded by a '\' character. The '\' characters are stripped out of the family name and values as the font name is read."
This function is only available when the Cairo graphics library is configured with FreeType and FontConfig support.
CairoFonts
initializes the fonts used for Cairo graphics devices.
CairoFonts( regular="Helvetica:style=Regular", bold="Helvetica:style=Bold", italic="Helvetica:style=Italic", bolditalic="Helvetica:style=Bold Italic,BoldItalic", symbol="Symbol", usePUA=TRUE )
CairoFonts( regular="Helvetica:style=Regular", bold="Helvetica:style=Bold", italic="Helvetica:style=Italic", bolditalic="Helvetica:style=Bold Italic,BoldItalic", symbol="Symbol", usePUA=TRUE )
regular |
character; fontconfig pattern for the 'plain text' font. |
bold |
character; fontconfig pattern for the 'bold face' font. |
italic |
character; fontconfig pattern for the 'italic' font. |
bolditalic |
character; fontconfig pattern for the 'bold italic' font. |
symbol |
character; fontconfig pattern for the 'symbol' font. |
usePUA |
logical; if |
This function sets the fonts for Cairo graphics devices globally; previously opened Cairo graphics devices will also use these fonts. The argument names correspond to the five values of the graphical parameter 'font', i.e. regular is 1, bold is 2, italic is 3, etc.
For an explanation of fontconfig patterns, see CairoFontMatch
.
This function is only available when the cairo graphics library is configured with FreeType and Fontcofig support.
R math symbols are supported, but require a "Symbol" font with
the Adobe Symbol Encoding unless usePUA=FALSE
is used
(available in R 4.0.0 or higher only).
## Not run: # # The following fontconfig patterns define the free truetype fonts # available in the debian package 'ttf-freefont'. # # Freesans is very similar to Helvetica CairoFonts( regular="FreeSans:style=Medium", bold="FreeSans:style=Bold", italic="FreeSans:style=Oblique", bolditalic="FreeSans:style=BoldOblique" ) ## End(Not run)
## Not run: # # The following fontconfig patterns define the free truetype fonts # available in the debian package 'ttf-freefont'. # # Freesans is very similar to Helvetica CairoFonts( regular="FreeSans:style=Medium", bold="FreeSans:style=Bold", italic="FreeSans:style=Oblique", bolditalic="FreeSans:style=BoldOblique" ) ## End(Not run)