png                package:grDevices                R Documentation

_B_M_P, _J_P_E_G, _P_N_G _a_n_d _T_I_F_F _g_r_a_p_h_i_c_s _d_e_v_i_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Graphics devices for JPEG, PNG or TIFF format bitmap files.

_U_s_a_g_e:

     bmp(filename = "Rplot%03d.bmp",
         width = 480, height = 480, units = "px",
         pointsize = 12, bg = "white", res = NA, ...,
         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, ...,
          type = c("cairo", "Xlib", "quartz"), antialias)

     png(filename = "Rplot%03d.png",
         width = 480, height = 480, units = "px",
         pointsize = 12, bg = "white",  res = NA, ...,
         type = c("cairo", "Xlib", "cairo1", "quartz"), antialias)

     tiff(filename = "Rplot%03d.tiff",
          width = 480, height = 480, units = "px", pointsize = 12,
          compression = c("none", "rle", "lzw", "jpeg", "zip"),
          bg = "white", res = NA,  ...,
          type = c("cairo", "Xlib", "quartz"), antialias)

_A_r_g_u_m_e_n_t_s:

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 'PATH_MAX'
          characters long, and may be truncated if not. See
          'postscript' for further details.)  Tilde expansion is
          performed where supported by the platform.

   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' dpi.

      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 dpi which will be recorded in the
          bitmap file, if a positive integer.  Also used for 'units'
          other than the default, and to convert points to pixels.

     ...: for 'type = "Xlib"' only, additional arguments to the
          underlying 'X11' device, such as 'gamma' and 'fonts'.

    type: character string, one of '"Xlib"' or '"quartz"' (some Mac OS
          X builds) or '"cairo"' or (deprecated) '"cairo1"'.  The
          latter two will only be available if the system was compiled
          with support for cairo - otherwise '"Xlib"' will be used. 
          The default is set by 'getOption("bitmapType")' - the 'out of
          the box' default is '"quartz"' or '"cairo"' where available,
          otherwise '"Xlib"'.

antialias: for 'type = "cairo"', giving the type of anti-aliasing (if
          any) to be used.  See 'X11'.  The default is set by
          'X11.options'.

_D_e_t_a_i_l_s:

     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 'tiff' is
     lossless and stores RGB (and alpha where appropriate) values
     uncompressed-such files are widely accepted, which is their main
     virtue over PNG.

     'png' supports transparent backgrounds: use 'bg = "transparent"'. 
     Not all PNG viewers render files with transparency correctly. 
     When transparency is in use in the 'type = "Xlib"' variant a very
     light grey is used as the background and so appear as transparent
     if used in the plot. This allows opaque white to be used, as in
     the example.  The 'type = "cairo"' and 'type = "cairo1"' variants
     allows semi-transparent colours, including on a transparent or
     semi-transparent background.

     'tiff(type = "cairo")' supports semi-transparent colours,
     including on a transparent or semi-transparent background.

     R can be compiled without support for each of these devices: this
     will be reported if you attempt to use them on a system where they
     are not supported.  For 'type = "Xlib"' they may not be usable
     unless the X11 display is available to the owner of the R process.
     'type = "cairo"' requires cairo 1.2 or later.  'type = "quartz"'
     uses the 'quartz' device and so is only available where that is
     (on some Mac OS X) builds.  It is at present experimental.

     By default no resolution is recorded in the file.  Viewers will
     often assume a nominal resolution of 72dpi when none is recorded. 
     As resolutions in PNG files are recorded in pixels/metre, the
     reported dpi value will be changed slightly.

     For graphics parameters that make use of dimensions in inches
     (including font sizes in points) the resolution used is 'res' (or
     72dpi if unset).

     'png' will 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 RGBA
     file if 'type = "cairo"' and non-opaque colours are used).

     The deprecated 'png(type = "cairo1")' uses cairo directly to
     output the file - the resolution is not recorded and the PNG
     format used is chosen by cairo (and undocumented - it is currently
     32-bit RGBA, that is with an alpha channel whether used or not). 
     It where included for use on platforms with cairo 1.0 (where 'type
     = "cairo"' is not available).

_V_a_l_u_e:

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

_W_a_r_n_i_n_g_s:

     Note that by default the 'width' and 'height' 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.

_C_o_n_v_e_n_t_i_o_n_s:

     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' dpi.

        *  The default font family is Helvetica.

        *  Line widths in 1/96 inch, minimum one pixel for 'type =
           "Xlib"', 0.01 for 'type = "cairo"'.

        *  For 'type = "Xlib"' circle radii are in pixels with minimum
           one.

        *  Colours are interpreted by the viewing application.

     For 'type = "quartz"' see the help for 'quartz'.

_N_o_t_e:

     For 'type = "Xlib"' these devices are based on the 'X11' device. 
     The colour model used will be that set up by 'X11.options' at the
     time the first Xlib-based devices was opened (or the first after
     all such devices have been closed).

_A_u_t_h_o_r(_s):

     Guido Masarotto and Brian Ripley

_S_e_e _A_l_s_o:

     'Devices', 'dev.print'

     'capabilities' to see if these devices are supported by this build
     of R, and if 'type = "cairo"' is supported.

     'bitmap' provides an alternative way to generate PNG and JPEG
     plots that does not depend on accessing the X11 display but does
     depend on having GhostScript installed.  (Devices 'GDD' in CRAN
     package 'GDD' and 'CairoJPEG' / 'CairoPNG' in CRAN package 'Cairo'
     are further alternatives using several other additional pieces of
     software.)

_E_x_a_m_p_l_e_s:

     ## these examples will work only if the devices are available
     ## and either cairo or an X11 display is available.

     ## 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()

     ## will make myplot1.jpeg and myplot2.jpeg
     jpeg(file="myplot%d.jpeg")
     example(rect)
     dev.off()

