BMP, JPEG, PNG and TIFF graphics devices

Share:

Description

Graphics devices for BMP, JPEG, PNG and TIFF format bitmap files.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
bmp(filename = "Rplot%03d.bmp",
    width = 480, height = 480, units = "px", pointsize = 12,
    bg = "white", res = NA, family = "", restoreConsole = TRUE,
    type = c("windows", "cairo"), antialias)

jpeg(filename = "Rplot%03d.jpg",
     width = 480, height = 480, units = "px", pointsize = 12,
     quality = 75,
     bg = "white", res = NA, family = "", restoreConsole = TRUE,
     type = c("windows", "cairo"), antialias)

png(filename = "Rplot%03d.png",
    width = 480, height = 480, units = "px", pointsize = 12,
    bg = "white", res = NA, family = "", restoreConsole = TRUE,
    type = c("windows", "cairo", "cairo-png"), antialias)

tiff(filename = "Rplot%03d.tif",
     width = 480, height = 480, units = "px", pointsize = 12,
     compression = c("none", "rle", "lzw", "jpeg", "zip", "lzw+p", "zip+p"),
     bg = "white", res = NA, family = "", restoreConsole = TRUE,
     type = c("windows", "cairo"), antialias)

Arguments

filename

the name of the output file, up to 511 characters. The page number is substituted if a C integer format is included in the character string, as in the default, and tilde-expansion is performed (see path.expand). (The result must be less than 600 characters long. See postscript for further details.)

width

the width of the device.

height

the height of the device.

units

The units in which height and width are given. Can be px (pixels, the default), in (inches), cm or mm.

pointsize

the default pointsize of plotted text, interpreted as big points (1/72 inch) at res ppi.

bg

the initial background colour: can be overridden by setting par("bg").

quality

the ‘quality’ of the JPEG image, as a percentage. Smaller values will give more compression but also more degradation of the image.

compression

the type of compression to be used.

res

The nominal resolution in ppi which will be recorded in the bitmap file, if a positive integer. Also used for units other than the default. If not specified, taken as 72 ppi to set the size of text and line widths.

family

A length-one character vector specifying the default font family. The default means to use the font numbers on the Windows GDI versions and "sans" on the cairographics versions.

restoreConsole

See the ‘Details’ section of windows. For type == "windows" only.

type

Should be plotting be done using Windows GDI or cairographics?

antialias

Length-one character vector.

For allowed values and their effect on fonts with type = "windows" see windows: for that type if the argument is missing the default is taken from windows.options()$bitmap.aa.win.

For allowed values and their effect (on fonts and lines, but not fills) with type = "cairo" see svg.

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. The BMP format is standard on Windows, and supported by most viewers elsewhere. TIFF is a meta-format: the default format written by tiff is lossless and stores RGB values uncompressed—such files are widely accepted, which is their main virtue over PNG.

Windows GDI imposes limits on the size of bitmaps: these are not documented in the SDK and may depend on the version of Windows. It seems that width and height are each limited to 2^15-1. In addition, there are limits on the total number of pixels which depend on the graphics hardware.

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, res ppi (default 72) is assumed.

Both bmp and png will use a palette if there are fewer than 256 colours on the page, and record a 24-bit RGB file otherwise. For the png device, type = "cairo" does the PNG output in the driver and so is compatible with the "windows" type. 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.

png(type = "windows") supports transparent backgrounds on 16-bit (‘High Color’) or better screens: use bg = "transparent". There is also support for semi-transparent colours of lines, fills and text. However, as there is only partial support for transparency in the graphics toolkit used: if there is a transparent background semi-transparent colours are painted onto a slightly off-white background and hence the pixels are opaque.

Not all PNG viewers render files with transparency correctly.

tiff compression types "lzw+p" and "zip+p" use horizontal differencing (‘differencing predictor’, section 14 of the TIFF specification) in combination with the compression method, which is effective for continuous-tone images, especially colour ones.

Prior to R 3.0.3 unknown resolutions in BMP files were sometimes recorded incorrectly: they are now recorded as 72 ppi.

Value

A plot device is opened: nothing is returned to the R interpreter.

Warnings

Note that by default the width and 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 %d for the sequence number in file, the file will contain the last page plotted.

Differences between OSes

These functions are interfaces to three or more different underlying devices.

  • On Windows, devices based on plotting to a hidden screen using Windows' GDI calls.

  • On platforms with support for X11, plotting to a hidden X11 display.

  • On macOS when working at the console and when R is compiled with suitable support, using Apple's Quartz plotting system.

  • 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 fontconfig to support a wide range of font formats. (This was first available on Windows in R 2.14.0.)

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 ‘.jpg’ and ‘.tif’ on Windows, and ‘.jpeg’ and ‘.tiff’ elsewhere.

Conventions

This section describes the implementation of the conventions for graphics devices set out in the “R Internals Manual”.

  • The default device size is in pixels.

  • Font sizes are in big points interpreted at res ppi.

  • The default font family is Arial.

  • Line widths are a multiple of 1/96 inch (interpreted at res ppi), with a minimum of one pixel (type = "windows") or 0.01 (type = "cairo").

  • The minimum radius of a circle is 1 pixel for type = "windows".

  • Colours are interpreted by the viewing application.

Note

The type = "windows" versions of these devices effectively plot on a hidden screen and then copy the image to the required format. This means that they have the same colour handling as the actual screen device, and work best if that is set to a 24-bit or 32-bit colour mode.

For high-quality plots you will probably want antialias = "cleartype" if this is not the default on your Windows system. On the other hand, png(antialias = "none") will give the most compact files

References

The PNG specification, http://www.w3.org/TR/PNG/.

The TIFF specification, including extensions, at https://partners.adobe.com/public/developer/tiff/.

See Also

Devices, dev.print

bitmap provides an alternative way to generate plots in many bitmap formats if GhostScript is available.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
## copy current plot to a (large) PNG file
## Not run: dev.print(png, file = "myplot.png", width = 1024, height = 768)

png(file = "myplot.png", bg = "transparent")
plot(1:10)
rect(1, 5, 3, 7, col = "white")
dev.off()

jpeg(file = "myplot.jpeg")
example(rect)
dev.off()

## End(Not run)

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.