# windows/png: BMP, JPEG, PNG and TIFF graphics devices

## 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. 

Unknown resolutions in BMP files are 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. 




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