Reads an image from a file

Description

Reads an image from a file of any file format. The formats PBM, PGM, PPM and RGB format are read by built-in methods. The JPEG format is read utilizing the rimage package. Other formats such as GIF and PNG requires an external image converter to convert the unknown image format into the PPM format.

Usage

BitmapImage$read(filename, path=NULL, format=NULL, ...)

Arguments

About the RGB format

If the file is of RGB format, either the width or the height must be specified since the RGB format does not include the dimensions of the image. The RGB file format is a very simple file format that contains no imformation about the width and the height of the image. Each triplet (R,G,B) of (8-bit) bytes in the file, starting from the first byte, represents one pixel. The first byte in the triple R, is the intensity of the pixel in the red channel. The range of R is [0, 255]. Similarily, the second and third byte, G and B, are the green and the blue intensities. Hence, the length of the image file, is three times the size of the image, i.e. the width times the height in pixels.

Specifying an image converter for unknown file formats

An external image converter is specified by the imageConverter option. It can either be a character string, which is the interpreted as the path to a external image convert program to be called by the system() with the first argument being the input file and the second argument the temporary output file with extension ".ppm". The software is expected to output a PPM image. Example:

options(imageConverter="C:/Program Files/ImageMagick/bin/convert").

If a function is given, it must accept three character string arguments, the input file, the output file and the optional format specification. The format specification is currently set to "png" and is currently to used. In the future this third argument makes it possible to generate gray scale (PGM) or monochrome (PBM) images too (not only colored as the PPM format). Using a function provides more access to software specific options. Example:

      imageMagickConvert <- function(srcfile, destfile, format) {
        cmd <- "\"C:/Program Files/ImageMagick/bin/convert\""
        system(paste(cmd, srcfile, destfile))
      }
      options(imageConverter=imageMagickConvert)

We suggest you to add these settings in your ~/.Rprofile file and also to use the ImageMagick's convert program, which is available for many platforms, is used. See http://www.imagemagick.org/ for more information.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For writing the image to file in RGB format see *write(). For more information see BitmapImage. For an external image converter see ImageMagick (http://www.imagemagick.org/), which is free and available for many differt platforms.

Examples

   # Read the images 'logosm.ppm' of size 51x38.
   logo <- BitmapImage$read("logosm.ppm", path=system.file("images", package="R.image"))
   image(logo)

   if (require(rimage)) {
     logo <- BitmapImage$read("logosm.jpg", path=system.file("images", package="R.image"))
     image(logo)
   }

   ## Not run: 
   # Example using an external image converter for unsupported image formats
   options(imageConverter="C:/Program Files/ImageMagick/bin/convert")
   logo <- BitmapImage$read("logosm.jpg", path=system.file("images", package="R.image"))
   image(logo)
   
## End(Not run)