| % File src/library/grDevices/man/unix/png.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{png} |
| \alias{png} |
| \alias{jpeg} |
| \alias{tiff} |
| \alias{bmp} |
| \title{BMP, JPEG, PNG and TIFF graphics devices} |
| \description{ |
| Graphics devices for BMP, JPEG, PNG and TIFF format bitmap files. |
| } |
| \usage{ |
| bmp(filename = "Rplot\%03d.bmp", |
| width = 480, height = 480, units = "px", pointsize = 12, |
| bg = "white", res = NA, \dots, |
| type = c("cairo", "Xlib", "quartz"), antialias) |
| |
| jpeg(filename = "Rplot\%03d.jpeg", |
| width = 480, height = 480, units = "px", pointsize = 12, |
| quality = 75, |
| bg = "white", res = NA, \dots, |
| type = c("cairo", "Xlib", "quartz"), antialias) |
| |
| png(filename = "Rplot\%03d.png", |
| width = 480, height = 480, units = "px", pointsize = 12, |
| bg = "white", res = NA, \dots, |
| type = c("cairo", "cairo-png", "Xlib", "quartz"), antialias) |
| |
| tiff(filename = "Rplot\%03d.tiff", |
| width = 480, height = 480, units = "px", pointsize = 12, |
| compression = c("none", "rle", "lzw", "jpeg", "zip", "lzw+p", "zip+p"), |
| bg = "white", res = NA, \dots, |
| type = c("cairo", "Xlib", "quartz"), antialias) |
| } |
| \arguments{ |
| \item{filename}{the name of the output file. |
| The page number is substituted if a C integer format is included in |
| the character string, as in the default. (The result must be less |
| than \code{PATH_MAX} characters long, and may be truncated if not. |
| See \code{\link{postscript}} for further details.) Tilde expansion |
| is performed where supported by the platform.} |
| \item{width}{the width of the device.} |
| \item{height}{the height of the device.} |
| \item{units}{The units in which \code{height} and \code{width} are |
| given. Can be \code{px} (pixels, the default), \code{in} (inches), |
| \code{cm} or \code{mm}.} |
| \item{pointsize}{the default pointsize of plotted text, interpreted as |
| big points (1/72 inch) at \code{res} ppi.} |
| \item{bg}{the initial background colour: can be overridden by setting |
| par("bg").} |
| \item{quality}{the \sQuote{quality} of the JPEG image, as a |
| percentage. Smaller values will give more compression but also more |
| degradation of the image.} |
| \item{compression}{the type of compression to be used. Ignored for |
| \code{type = "quartz"}.} |
| \item{res}{The nominal resolution in ppi which will be recorded in the |
| bitmap file, if a positive integer. Also used for \code{units} |
| other than the default, and to convert points to pixels.} |
| \item{\dots}{for \code{type = "Xlib"} only, additional arguments to |
| the underlying \code{\link{X11}} device such as \code{fonts} or |
| \code{family}. |
| |
| For types \code{"cairo"} and \code{"quartz"}, the \code{family} |
| argument can be supplied. See the \sQuote{Cairo fonts} |
| section in the help for \code{\link{X11}}.} |
| |
| \item{type}{character string, one of \code{"Xlib"} or \code{"quartz"} |
| (some macOS builds) or \code{"cairo"}. The latter will only be |
| available if the system was compiled with support for cairo -- |
| otherwise \code{"Xlib"} will be used. The default is set by |
| \code{\link{getOption}("bitmapType")} -- the \sQuote{out of the box} |
| default is \code{"quartz"} or \code{"cairo"} where available, |
| otherwise \code{"Xlib"}.} |
| |
| \item{antialias}{for \code{type = "cairo"}, giving the type of |
| anti-aliasing (if any) to be used for fonts and lines (but not |
| fills). See \code{\link{X11}}. The default is set by |
| \code{\link{X11.options}}. Also for \code{type = "quartz"}, where |
| antialiasing is used unless \code{antialias = "none"}.} |
| } |
| \details{ |
| Plots in PNG and JPEG format can easily be converted to many other |
| bitmap formats, and both can be displayed in modern web |
| browsers. The PNG format is lossless and is best for line |
| diagrams and blocks of colour. The JPEG format is lossy, |
| but may be useful for image plots, for example. BMP is a standard |
| format on Windows. TIFF is a meta-format: the default format written |
| by \code{tiff} is lossless and stores RGB (and alpha where |
| appropriate) values uncompressed---such files are widely accepted, |
| which is their main virtue over PNG. |
| |
| \code{png} supports transparent backgrounds: use \code{bg = |
| "transparent"}. (Not all PNG viewers render files with transparency |
| correctly.) When transparency is in use in the \code{type = "Xlib"} |
| variant a very light grey is used as the background and so appears as |
| transparent if used in the plot. This allows opaque white to be used, |
| as in the example. The \code{type = "cairo"}, \code{type = |
| "cairo-png"} and \code{type = "quartz"} variants allow |
| semi-transparent colours, including on a transparent or |
| semi-transparent background. |
| |
| \code{tiff} with types \code{"cairo"} and \code{"quartz"} supports |
| semi-transparent colours, including on a transparent or |
| semi-transparent background. Compression type \code{"zip"} is |
| \sQuote{deflate (Adobe-style)}. Compression types \code{"lzw+p"} and |
| \code{"zip+p"} use horizontal differencing (\sQuote{differencing |
| predictor}, section 14 of the TIFF specification) in combination with |
| the compression method, which is effective for continuous-tone images, |
| especially colour ones. |
| |
| \R can be compiled without support for some or all of the types for |
| each of these devices: this will be reported if you attempt to use |
| them on a system where they are not supported. For \code{type = |
| "Xlib"} they may not be usable unless the X11 display is available to |
| the owner of the \R process. \code{type = "cairo"} requires cairo 1.2 |
| or later. \code{type = "quartz"} uses the \code{\link{quartz}} device |
| and so is only available where that is (on some macOS builds: see |
| \code{\link{capabilities}("aqua")}). |
| |
| By default no resolution is recorded in the file, except for BMP. |
| Viewers will often assume a nominal resolution of 72 ppi when none is |
| recorded. As resolutions in PNG files are recorded in pixels/metre, |
| the reported ppi value will be changed slightly. |
| |
| For graphics parameters that make use of dimensions in inches |
| (including font sizes in points) the resolution used is \code{res} (or |
| 72 ppi if unset). |
| |
| \code{png} will normally use a palette if there are less than 256 |
| colours on the page, and record a 24-bit RGB file otherwise (or a |
| 32-bit ARGB file if \code{type = "cairo"} and non-opaque colours are |
| used). However, \code{type = "cairo-png"} uses cairographics' PNG |
| backend which will never use a palette and normally creates a larger |
| 32-bit ARGB file---this may work better for specialist uses with |
| semi-transparent colours. |
| |
| Quartz-produced PNG and TIFF plots with a transparent background are |
| recorded with a dark grey matte which will show up in some viewers, |
| including \command{Preview} on macOS. |
| |
| Unknown resolutions in BMP files are recorded as 72 ppi. |
| } |
| |
| \value{ |
| A plot device is opened: nothing is returned to the \R interpreter. |
| } |
| |
| \section{Warnings}{ |
| Note that by default the \code{width} and \code{height} values are in |
| pixels not inches. A warning will be issued if both are less than 20. |
| |
| If you plot more than one page on one of these devices and do not |
| include something like \code{\%d} for the sequence number in |
| \code{file}, the file will contain the last page plotted. |
| } |
| |
| \section{Differences between OSes}{ |
| These functions are interfaces to three or more different underlying |
| devices. |
| \itemize{ |
| \item On Windows, devices based on plotting to a hidden screen using |
| Windows' GDI calls. |
| |
| \item On platforms with support for X11, plotting to a hidden X11 |
| display. |
| |
| \item On macOS when working at the console and when \R is |
| compiled with suitable support, using Apple's Quartz plotting |
| system. |
| |
| \item Where support has been compiled in for cairographics, plotting |
| on cairo surfaces. This may use the native platform support for |
| fonts, or it may use \code{fontconfig} to support a wide range of |
| font formats. |
| } |
| Inevitably there will be differences between the options supported and |
| output produced. Perhaps the most important are support for |
| antialiased fonts and semi-transparent colours: the best results are |
| likely to be obtained with the cairo- or Quartz-based devices where |
| available. |
| |
| The default extensions are \file{.jpg} and \file{.tif} on Windows, and |
| \file{.jpeg} and \file{.tiff} elsewhere. |
| } |
| |
| \note{ |
| For \code{type = "Xlib"} these devices are based on the \code{\link{X11}} |
| device. The colour model used will be that set up by |
| \code{X11.options} at the time the first Xlib-based devices was opened |
| (or the first after all such devices have been closed). |
| } |
| |
| \author{Guido Masarotto and Brian Ripley} |
| |
| \references{ |
| The PNG specification, \url{http://www.w3.org/TR/PNG/}. |
| |
| The TIFF specification, |
| \url{https://www.iso.org/standard/34342.html}. |
| See also \url{https://en.wikipedia.org/wiki/TIFF}. |
| %% no longer works: |
| %% \url{https://partners.adobe.com/public/developer/tiff/}. |
| } |
| \seealso{ |
| \code{\link{Devices}}, \code{\link{dev.print}} |
| |
| \code{\link{capabilities}} to see if these devices are |
| supported by this build of \R, and if \code{type = "cairo"} is supported. |
| |
| \code{\link{bitmap}} provides an alternative way to generate plots in many |
| bitmap formats that does not depend on accessing the X11 display but does |
| depend on having GhostScript installed. |
| } |
| |
| \section{Conventions}{ |
| This section describes the implementation of the conventions for |
| graphics devices set out in the \dQuote{R Internals Manual}. |
| |
| \itemize{ |
| \item The default device size is in pixels. |
| \item Font sizes are in big points interpreted at \code{res} ppi. |
| \item The default font family is Helvetica. |
| \item Line widths in 1/96 inch (interpreted at \code{res} ppi), |
| minimum one pixel for \code{type = "Xlib"}, 0.01 for \code{type = |
| "cairo"}. |
| \item For \code{type = "Xlib"} circle radii are in pixels with |
| minimum one. |
| \item Colours are interpreted by the viewing application. |
| } |
| |
| For \code{type = "quartz"} see the help for \code{\link{quartz}}. |
| } |
| |
| \examples{ |
| ## these examples will work only if the devices are available |
| ## and cairo or an X11 display or a macOS display is available. |
| |
| ## copy current plot to a (large) PNG file |
| \dontrun{dev.print(png, file = "myplot.png", width = 1024, height = 768)} |
| \donttest{ |
| png(file = "myplot.png", bg = "transparent") |
| plot(1:10) |
| rect(1, 5, 3, 7, col = "white") |
| dev.off() |
| |
| ## will make myplot1.jpeg and myplot2.jpeg |
| jpeg(file = "myplot\%d.jpeg") |
| example(rect) |
| dev.off() |
| }} |
| \keyword{device} |