caTools (version 1.2)

GIF: Read and Write Images in GIF format

Description

Read and write files in GIF format. Files can contain single images or multiple frames. Multi-frame images are saved as animated GIF's.

Usage

read.gif(filename, frame=0, flip=FALSE, verbose=FALSE) 
write.gif(image, filename, col=NULL, scale=c("smart", "never", "always"), 
    transparent=NULL, comment=NULL, delay=0, flip=FALSE, interlace=FALSE)

Arguments

filename

Character string with name of the file. In case of read.gif URL's are also allowed.

image

Data to be saved as GIF file. Can be a 2D matrix or 3D array. Allowed formats in order of preference:

• array of integers in [0:255] range - this is format required by GIF file, and unlessscale='always', numbers will

frame

Request specific frame from multiframe (i.e., animated) GIF file. By default all frames are read from the file (frame=0). Setting frame=1 will ensure that output is always a 2D matrix containing the first frame

col

Color palette definitions such as that generated by rainbow, heat.colors or similar functions. Usually palette will c

scale

There are three approaches to rescaling the data to required [0, 255] integer range:

• "smart" - Data is fitted to [0:255] range, only if it falls outside of it. Also, ifimageis an array of doubles in range [0, 1] than

delay

In case of 3D arrays the data will be stored as animated GIF, and delay controls speed of the animation. It is number of hundredths (1/100) of a second of delay between frames.

comment

Comments in text format are allowed in GIF files. Few file viewers can access them.

flip

By default data is stored in the same orientation as data displayed by print function: row 1 is on top, image x-axis corresponds to columns and y-axis corresponds to rows. However function <

transparent

Optional color number to be shown as transparent. Has to be an integer in [0:255] range. NA's in the image will be set to transparent.

interlace

GIF files allow image rows to be interlaced, or reordered in such a way as to allow viewer to display image using 4 passes, making image sharper with each pass. Irrelevant feature on fast computers.

verbose

Display details sections encountered while reading GIF file.

Value

• Function write.gif does not return anything. Function read.gif returns a list with following fields:
• image
  matrix or 3D array of integers in [0:255] range.
• col
  color palette definitions with number of colors ranging from 1 to 256. In case when frame=0 only the first (usually global) color-map (palette) is returned.
• comment
  Comments imbedded in GIF File
• transparent
  color number corresponding to transparent color. If none was stated than NULL, otherwise an integer in [0:255] range. In order for image to display transparent colors correctly one should use y$col[y$transparent+1] = NA.

concept

• GIF
• image file
• animation

Details

Palettes often contain continuous colors, such that swapping palettes or rescaling of the image date does not affect image apperance in a drastic way. However, when working with non-continuous color-maps one should always provide image in [0:255] integer range (and set scale="never"), in order to prevent scaling. If NA or other infinite numbers are found in the image by write.gif, they will be converted to numbers given by transparent. If transparent color is not provided than it will be created, possibly after reshretching. There are some GIF files not fully supported by read.gif function:

• "Plain Text Extension" is not supported, and will be ignored.
• Multi-frame files with unique settings for each frame have to be read frame by frame. Possible settings include: frames with different sizes, frames using local color maps and frames using individual transparency colors.

References

Ziv, J., Lempel, A. (1977) An Universal Algorithm for Sequential Data Compression, IEEE Transactions on Information Theory, May 1977. Copy of official file format description http://www.danbbs.dk/%7Edino/whirlgif/gif89.html Nicely explained file format description http://semmix.pl/color/exgraf/eeg11.htm Christoph Hohmann code and documentation of encoding algorithm http://members.aol.com/rf21exe/gif.htm Michael A, Mayer code http://www.danbbs.dk/%7Edino/whirlgif/gifcode.html Discussion of GIF file legal status can be found in http://www.cloanto.com/users/mcb/19950127giflzw.html. Interesting page on one way of doing animations in R (with help of outside calls) can be found at http://pinard.progiciels-bpi.ca/plaisirs/animations/index.html.

See Also

Displaying of images can be done through functions: image (part of R), image.plot and add.image from fields or plot.im from spatstat package, and possibly many other functions. Displayed image can be saved in GIF, JPEG or PNG format using several different functions: GDD from package GDD, HTMLplot from package R2HTML and functions jpeg and png. Functions for directly reading and writing image files:

• read.pnmandwrite.pnmfrompixmappackage can process PBM, PGM and PPM images (file types supported by ImageMagic software)
• read.ENVIandwrite.ENVIfrom this package can process files in ENVI format. ENVI files can store 2D images and 3D data (multi-frame images), and are supported by most GIS (Geographic Information System) software including free "freelook".
• read.jpegfromrimagepackage can read JPEG files

There are many functions for creating and managing color palettes:

• R provides functions for creating palettes of continuous colors:rainbow,topo.colors,heat.colors,terrain.colors.colors,gray
• tim.colorsin packagefieldscontains palette similar to Matlab's jet palette
• rich.colorsin packagegplotscontains two palettes of continuous colors.
• Functionsbrewer.palfromRColorBrewerpackage andcolorbrewer.palettefromepitoolspackage contain tools for generating palettes
• rgbandhsvcreates palette from RGB or HSV 3-vectors.
• col2rgbtranslates palette colors to RGB 3-vectors.

Examples

# visual comparison between image and plot
write.gif( volcano, "volcano.gif", col=terrain.colors(256), flip=TRUE, 
           scale="always", comment="Maunga Whau Volcano")
y = read.gif("volcano.gif", verbose=TRUE, flip=TRUE)
image(y$image, col=y$col, main=y$comment, asp=1)
# browseURL("file://volcano.gif")  # inspect GIF file on your hard disk

# test reading & writing
col = heat.colors(256) # choose colormap
trn = 222              # set transparent color
com = "Hello World"    # imbed comment in the file
write.gif( volcano, "volcano.gif", col=col, transparent=trn, comment=com)
y = read.gif("volcano.gif")
stopifnot(volcano==y$image, col==y$col, trn==y$transparent, com==y$comment)

# create animated GIF (using image function im a loop is very rough,
# but only way I know of displaying 'animation" in R)
x <- y <- seq(-4*pi, 4*pi, len=200)
r <- sqrt(outer(x^2, y^2, "+"))
image = array(0, c(200, 200, 10))
for(i in 1:10) image[,,i] = cos(r-(2*pi*i/10))/(r^.25)
write.gif(image, "wave.gif", col=rainbow(256))
y = read.gif("wave.gif")
for(i in 1:10) image(y$image[,,i], col=y$col, breaks=(0:256)-0.5, asp=1)
# browseURL("file://wave.gif") # inspect GIF file on your hard disk

# Display interesting images from the web
url = "http://www.ngdc.noaa.gov/seg/cdroms/ged_iib/datasets/b12/gifs/eccnv.gif"
y = read.gif(url, verbose=TRUE, flip=TRUE)
image(y$image, col=y$col, breaks=(0:length(y$col))-0.5, asp=1,
           main="January Potential Evapotranspiration mm/mo")
url = "http://www.ngdc.noaa.gov/seg/cdroms/ged_iib/datasets/b01/gifs/fvvcode.gif"
y = read.gif(url, flip=TRUE)
y$col[y$transparent+1] = NA # mark transparent color in R way
image(y$image, col=y$col[1:87], breaks=(0:87)-0.5, asp=1,
           main="Vegetation Types")
url = "http://talc.geo.umn.edu/people/grads/hasba002/erosion_vids/run2/r2_dems_5fps(8color).gif"
y = read.gif(url, verbose=TRUE, flip=TRUE)
for(i in 2:dim(y$image)[3]) 
  image(y$image[,,i], col=y$col, breaks=(0:length(y$col))-0.5,
            asp=1, main="Erosion in Drainage Basins")

## End(Not run)
file.remove("volcano.gif")
file.remove("wave.gif")