rgb(4)                                                   rgb(4)





NAME
       rgb - Silicon Graphics rgb image file format

SYNOPSIS
       #include <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 rou-
       tines.  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  argu-
              ments,  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  dimen-
              sional)  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.  Some-
              times 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  compo-
              nents 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 rep-
              resented 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->col-
              ormap (defines whether the image is a  series  of
              intensity  values, or color lookup table 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 algo-
              rithm 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 chan-
              nel 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 argu-
              ment  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 col-
       ormap;
              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 indi-
              cates 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
       There are too many video image file formats.



                              1994                       rgb(4)
