Name

Synopsis

Description

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 CW]image->xsize, CW]image->ysize, and CW]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 CW]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 CW]image->name (holds the string that is usually the same as the actual image filename), CW]image->colormap (defines whether the image is a series of intensity values, or color lookup table indices, or an actual colormap), CW]image->max (the maximum intensity stored in the image), and CW]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 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;
        /* 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);
                }
            }
        }

Bugs

Table of Contents

• Name
• Synopsis
• Description
• Opening and Closing an Image File
• Reading and Writing an Image File
• Miscellaneous Functions
• An Example
• Bugs