RGB(4)RGB(4)NAMErgb - Silicon Graphics rgb image file format
SYNOPSIS
#include <gl/image.h>
DESCRIPTION
IRIS image files are used to store 1,2 and 3 dimensional arrays of pixel
values that contain either 1 or 2 bytes per pixel. Pixel values are
signed integers that cover the range 0..255 or -32768..32767 (i.e. 1 or 2
bytes). Image files are currently used to store rgb screen dumps, black
and white images, color index images, as well as colormaps.
The image library provides tools to manipulate these files. To include
the image library place the token -limage on the compile line for your
program. Also, be sure to include image.h from /usr/include/gl in any
source files that use these routines. The following routines provide a
procedural interface to image files:
Opening and Closing an Image File
IMAGE *iopen(file, mode [, type, dim, xsize, ysize, zsize]) char *file;
register char *mode; unsigned int type, dim, xsize, ysize, zsize;
Opens an image file for reading or writing and returns a pointer to IMAGE
in the same style as the UNIX standard i/o library. A return value of 0
means the function failed to successfully open the file that was named.
To open an image file for reading, iopen should be called with 2
arguments, the name of the image file to open and a mode of "r". The
dimensions of the image may be determined by referencing image->xsize,
image->ysize, and image->zsize, where image is the value returned by
iopen. xsize and ysize are defined in terms of pixels while zsize
describes the number of channels (i.e. layers) the image contains.
The value of image->dim indicates whether the image is just a single row
(one dimensional) or is an array of rows (two dimensional) or is an array
of 2 dimensional images (three dimensional).
An rgb image can be thought of as a set of three 2 dimensional images.
Sometimes this is referred to as a 3 channel image. An rgb color image
consists of 3 channels (one channel each for the red green and blue
components of the image) and is represented as a three dimensional image
that is xsize by ysize by 3. A black and white image has one channel and
is represented as a two dimensional image that is xsize by ysize.
Other information may be found in image->name (holds the string that is
usually the same as the actual image filename), image->colormap (defines
whether the image is a series of intensity values, or color lookup table
Page 1
RGB(4)RGB(4)
indices, or an actual colormap), image->max (the maximum intensity stored
in the image), and image->min (the minimum intensity stored in the
image).
To open an image file for writing, iopen should be called with 7
arguments, the name of the image file to open, and a mode of "w",
followed by the type, the number of dimensions and the xsize, ysize and
zsize of the image. The type indicates how many bytes are stored per
pixel value, and whether the image file should be run-length encoded.
Type may be given as RLE(1), RLE(2), VERBATIM(1), or VERBATIM(2). Run-
length encoded (RLE) image files are more efficiently stored than
verbatim files where no compression algorithm is used. 1 or 2 in the
above specifies how many bytes are used for each pixel in a colormap
image, or for each channel in an rgb image. RLE(2) or VERBATIM(2) is
used to store color index images that contain 12 bits per pixel. RLE(1)
is the recommended default for rgb and black and white images.
iclose(image) register IMAGE *image;
Closes an image file that was open for reading or writing. All output is
flushed to the output file, and the output file is closed.
Reading and Writing an Image File
The following functions allow pixels to be transferred to and from an
image file. These functions provide an interface to an image file that
is independent of whether the image file happens to be run length
encoded, and independent of whether it maintains 1 or 2 bytes per pixel.
putrow(image,buffer,y,z) register IMAGE *image; unsigned short *buffer;
unsigned y, z;
Writes a row of pixels to the specified image file. The buffer should be
an array of shorts that contain the pixel values of a colormap image or
one of the 3 channels of an rgb image. If the image file maintains
only one byte per pixel, then the values passed in the buffer should be
in the range 0..255. The row of the image to be written is given by y,
while z selects which channel of the image to write to. The first
channel of the image is channel 0. A black and white image will have
only 1 channel while rgb images have 3 channels. In an rgb image,
channel 0 is used to store red while channel 1 stores green, and channel
2 stores blue pixel data. The y argument should be greater than or equal
to zero and less than the ysize of the image. The rows of the image file
may be written in any order. getrow(image,buffer,y,z) register IMAGE
*image; unsigned short *buffer; register unsigned int y, z;
Reads a row of pixels from the specified image file. The buffer should
be an array of shorts to receive pixel values of a colormap image or one
of the 3 channels of an rgb image. The row of the image to be read is
Page 2
RGB(4)RGB(4)
given by y, while z selects which channel of the image to read from. The
first channel of a image is channel 0. A black and white image will have
only 1 channel, while an rgb image will have 3. The y argument should be
greater than or equal to zero and less than the ysize of the image. The
rows of the image file may be read in any order.
Miscellaneous Functions isetname(image,name) IMAGE *image; char *name;
Copies the character string name into the name field of the image file.
NOTE: handling names when processing two files together is not well
supported and is not encouraged. isetcolormap(image,colormap) IMAGE
*image; int colormap;
Tells ipaste and some printing utilities whether the pixel values should
be interpreted as color-index pixels or intensities. A gray scale image
consists of one channel of intensities, while an rgb image has three
independent channels of pixel intensities, one channel for each red,
green and blue intensities. The argument colormap may be one of
following three values: CM_NORMAL is the default indicating that the
pixels are intensity values. 0 is black and a value of 255 in the image
is white. Black and white images and rgb images are stored with
CM_NORMAL. CM_SCREEN indicates that the pixels were copied from the
screen and must be transformed by a color map to be meaningful.
Colormaps can also be stored in image files. CM_COLORMAP means that the
pixels in the image file represent a color map
An Example
The following example shows how to open an image file and read its
contents. More examples may be found in
/usr/people/4Dgifts/iristools/imgtools.
/*
* readimage - Read an image file and print its pixel values.
*
* To compile: cc readimage.c -o readimage -limage
*
* Paul Haeberli - 1991
*/
#include <gl/image.h>
main(argc,argv)
int argc;
char **argv;
{
IMAGE *image;
int x, y, z;
short *rbuf, *gbuf, *bbuf;
Page 3
RGB(4)RGB(4)
/* print usage message */
if( argc<2 ) {
fprintf(stderr,"usage: readimage infile0);
exit(1);
}
/* open the image file */
if( (image=iopen(argv[1],"r")) == NULL ) {
fprintf(stderr,"readimage: can't open input file %s0,argv[1]);
exit(1);
}
/* print a little info about the image */
printf("Image x and y size in pixels: %d
%d0,image->xsize,image->ysize);
printf("Image zsize in channels: %d0,image->zsize);
printf("Image pixel min and max: %d %d0,image->min,image-max);
/* allocate buffers for image data */
rbuf = (short *)malloc(image->xsize*sizeof(short));
gbuf = (short *)malloc(image->xsize*sizeof(short));
bbuf = (short *)malloc(image->xsize*sizeof(short));
/* check to see if the image is B/W or RGB */
if(image->zsize == 1) {
printf("This is a black and write image0);
for(y=0; y<image->ysize; y++) {
getrow(image,rbuf,y,0);
printf("row %d: ",y);
for(x=0; x<image->xsize; x++)
printf("%d |",rbuf[x]);
printf("0);
}
} else if(image->zsize >= 3) { /* if the image has alpha zsize is 4 */
printf("This is a rgb image0);
for(y=0; y<image->ysize; y++) {
getrow(image,rbuf,y,0);
getrow(image,gbuf,y,1);
getrow(image,bbuf,y,2);
printf("row %d: ",y);
for(x=0; x<image->xsize; x++)
printf("%d %d %d |",rbuf[x],gbuf[x],bbuf[x]);
printf("0);
}
}
}
Page 4
RGB(4)RGB(4)BUGS
There are too many video image file formats.
Page 5
