     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

     Introduction
          VIP (Visual Information Processing) is an image processing software
          library that has been developed by the Robotics and Vision Research
          Group in The Department of Computer Science at The University of
          Western Australia.  The system consists of two parts:

          - a library of C functions for manipulating and transforming images
          that can be incorporated in your own programs.

          - a set of stand-alone programs for performing many of the more
          commonly used operations on images.

          The VIP library of image processing functions has been designed to
          enable users to create their own image processing programs very
          quickly and simply using a toolkit of standardized library functions.

          The library includes functions in the following categories
          - image input/output and memory management
          - image type and data format conversion
          - image enhancement and spatial transformations
          - mask operations
          - arithmetic operations
          - image statistics
          - frequency domain transformations
          - camera calibration and 3D data reconstruction
          - vector and matrix manipulation
          - one dimensional edge detection
          - miscellaneous functions

          The VIP image data structure supports a wide variety of image types
          ranging from a basic 8 bit grey level representation through to
          complex valued and colour images.  New image types can be easily added
          without `breaking' the existing software.  An additional feature of
          the VIP image data structure that distinguishes it from other image
          structures is its provision for comprehensive camera calibration data
          and lens distortion parameters.  The VIP system provides support for
          reconstruction of 3D information from images via structured light and
          stereo.

          The VIP System is designed to run under Unix on DEC Alpha, Sun Sparc
          Machines and PC's running LINUX, a subset of VIP is also available to
          run under DOS on a PC.

     History
          The origins of the system go back 1986 when The Computer Science
          Department at The University of Western Australia started to develop
          its library of image processing routines, coining the name `VIP'.  At

                                        - 1 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          about the same time the Automated Sheep Shearing Group in The
          Department of Mechanical Engineering started to develop a vision
          system for the automated measurement of sheep.  Each group devised
          their own, different image data structures, which required conversion
          when they were exchanged between groups. In 1991, with increasing
          collaboration between the two groups, and with each wishing to change
          and enhance the image data structures they were using, a new common
          structure was devised.  The two software libraries were merged and
          considerably enhanced.  However, shortly after this, vision research
          within the Automated Sheep Shearing Group ceased due to changes in
          research directions.  Almost all of the subsequent development has
          been done within The Department of Computer Science.

     Authors
          A number of people have contributed to the system.  The initial work
          on VIP in the Computer Science Department was done by Chris Avis.  The
          Automated Sheep Shearing Group's vision system was developed by Peter
          Kovesi.  Much of the subsequent development in the Department of
          Computer Science has been done by Du Huynh and Peter Kovesi.  Recently
          Carl Fisher standardized the code to ANSI C, placed the system under
          SCCS, cleaned up much of the code and fixed numerous bugs.  He also
          wrote the Motif version of the image displaying program, splash.
          Contributions have also been made to the system by Graham Walker,
          James Trevelyan, James Cooper, Ian Reid, Svetha Venkatesh, Ben Robbins
          and Mike Robins.

     Bugs
          Please report any bugs to:

          or post them to the newsgroup

     Getting Started With VIP
          This section describes how to set up your environment variables to
          give you access to the VIP programs, libraries and on-line manuals.
          Some examples are also provided to help you avoid having to read this
          manual in too much detail at first!

     Setting environment variables
          To gain access to the executable VIP programs add the following to
          your path specification in your .cshrc file

          setenv PATH  "... your existing path...  :/proj/robvis/vip/bin/sunbin"

          Note: If you are working on the DEC alpha you should specify `decbin'
          rather than `sunbin'.

                                        - 2 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          To gain access to the manual entries you need to modify your MANPATH
          setting

          setenv MANPATH "... your existing path...:/proj/robvis/vip/man"

          in your .cshrc or .login file.

     Image formats
          VIP has its own image format, what distinguishes this format from
          others is that it has provision for storing camera calibration and
          lens distortion parameters in the image header.  If you obtain images
          using the programs SNAP using the Videopix on the Sub or PKSNAP on the
          PC on the RobVis lab they will be stored in the VIP format.  VIP image
          files generally have a .im ending.

          Other common image formats that you may have to deal with are GIF,
          TIFF, PPM and PGM.  Conversion utilities exist to convert images
          between most of these formats.

     Image Format Conversion

          To convert an image from VIP to PPM (Portable PixMap) use:
          % vip2ppm  [vip_image_file] [-o ppm_image_file]

          To convert a PPM, PGM or PBM image to VIP format use:
          % pm2vip [pm image_file] [-o vip_image_file]

          To convert from PPM to PGM (Portable Grey Map) use:
          % ppmtopgm PPM_image_name > PGM_image_name

          To convert from TIFF to VIP use:
          %tifftopnm TIFF_image_name > dump
          %pm2vip dump -o VIP_image_name

          To convert a VIP image to or from the Sun raster format use:
          % vip2raster [vip_image_file] [-o raster_image_file]

          % raster2vip [raster_image_file] [-o vip_image_file]

          To work with other image formats the general rule is to convert to PPM
          or PGM and then convert from there to your destination format.  Do a
          `man -k ppm' to find all the conversion utilities that work with PPM.

     How to Display Images

                                        - 3 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          There are a number of image displaying programs: splash, xdisplay, xv
          and surface.  xdisplay and xv are the ones that you will find most
          useful on the monochrome X terminals as they are capable of providing
          a dithered display. You can find some sample images to display in
          /proj/robvis/vip/images.

          % xdisplay <vipimage_name>
          The xdisplay program converts your VIP image into ppm format and uses
          the xv utility to display your image.  Click on the right mouse button
          with the cursor in the image to get a control panel.  The `4x3' button
          will give you a more natural display as camera pixels have an aspect
          ratio of about 4x3 but the display screen has square pixels. Clicking
          on the `coledit' button will bring up another control panel.  Most of
          the controls relate to manipulation of the colour map.  For grey scale
          images the intensity control is of most interest.  This panel allows
          you to graphically manipulate the mapping from input grey levels to
          the displayed grey levels.  By manipulating the mapping you can negate
          the image, threshold it, suppress detail in some sections of the grey
          scale and enhance it in others.

          % xv <image_name>
          xv is an X11 program that displays images in the GIF, PBM, PGM, PPM,
          TIFF, X11 bitmap, JPEG, Sun Rasterfile, and PM formats on 1-, 4-, 6-,
          8-, 16-, 24-, and 32-bit X displays.  xv will also read compressed
          versions of these files.  See the manual entry for more information.

          % splash <vipimage_name>
          Splash only displays VIP images and only runs on colour displays.
          Image display is quite fast, 1D slices through the image can be
          digitised, the lookup table can be interactively adjusted, plus a
          number of other goodies are available.

          % surface <image_name>
          Surface displays VIP images as a 3D surface with interactive control
          over viewing direction.  It can be rather slow when dealing with large
          images.

          See manual entries for more details.

     Some VIP programs to try
          To negate an image use:
          % negim image_name -o output_image

                                        - 4 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          To threshold an image (make it binary black or white) use:
          % thresh image_name -t threshold_value -o output_image
          To obtain a histogram of the occurrence of each intensity value in an
          image use:
          % histogram image_name -o outputfile
          This produces a data file of values.  You can display this using
          gnuplot.

          % gnuplot
          gnuplot> plot "datafile" with lines

          gnuplot is a very handy plotting utility, it is suggested that you
          become familiar with it.

          The histogram plot can be useful in selecting a suitable threshold
          when generating a binary image.

          To histogram equalize (make the histogram of intensity values more
          even, aiding interpretation) an image use:
          % histe image_name -o output_image

     Obtaining hard copy of images
          To obtain a hard copy of your image, use the program, laser.  This
          program converts an image in vip format to postscript.  The output may
          be piped directly to a laser printer or saved in a file for subsequent
          inclusion in a document.

          For example, to obtain a hard copy of an image, sized 16cm x 12cm
          (providing a 4 x 3 aspect ratio of a `square' image), placed in the
          centre of the page, and sending the output to the printer `sp', use:

          % laser image_name -w 16 12 -p ce | lpr -Psp

          See the section on the laser program for more information.

     Writing Programs and Functions that call
          Writing programs and functions that use VIP library functions is easy.
          Three example files are provided on the following pages:

          - A program that reads an image of BYTETYPE and
          thresholds it.  Values in the input image that are below the threshold
          are set to zero (black), values greater than the threshold are set to
          255 (white).  The resulting image is then written to a file.

                                        - 5 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          - A sample makefile for programs that use VIP.

          - A function that performs a homomorphic image enhancing
          filtering operation on an image.  This example illustrates the use of
          a number of different image types.

          To gain access to the VIP functions one simply uses
          #include "vip.h"
          in your source files.

     A Sample Program

          /** threshold.c ------------------------------------------------

          Sample program that illustrates use of the VIP library.

          This program thresholds an image.  Values in the input image that are
          below the threshold are set to zero (black), values greater than the
          threshold are set to 255 (white).

          -------------------------------------------------------------------*/

          #include <stdio.h>
          #include "vip.h"                /* the VIP include file */

          void main(int argc, char *argv[])
          {
              IMAGE  *inimage = NULL, *outimage = NULL;     /* pointers to the images we will use */
              int     rows, cols, row, col;
              int     threshold;

              if (argc != 4) {
                  printf("usage: vipexample in_image threshold  out_image 0);
                  return;
              }

          /* Read the image into memory.  */
              inimage = Read_Image(argv[1]);

          /* Check that we read the data from the file.  Note that if Read_Image
             was unable to read the image it would have produced an error message
             via the function VIP_Error_Msg so the following message is really
             not needed. */
              if (!inimage) {
                  printf("Could not open %s0, argv[1]);
                  return;

                                        - 6 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

              }

          /* Check that it is a BYTETYPE image */
              if(inimage->type != BYTETYPE) {
                  printf("Threshold can only operate on BYTETYPE images0);
                  return;
              }

              threshold = atoi(argv[2]);

              if(threshold < 0 || threshold > 255) {
                  printf("threshold value must be in range 0 - 2550);
                  return;
              }

              rows = inimage->rows;
              cols = inimage->cols;

          /* Allocate space for the output image */
              outimage = Allocate_Image(0, 0, rows, cols, BYTETYPE);

              if (!outimage) {
                  printf("Could not allocate space for output image0);
                  Free_Image(inimage);
                  return;
              }

          /*
               Now do the thresholding
               Note that there is a VIP library function to do this
               and the code below could simply be replaced with:
               outimage = Thresh_Image(inimage, threshold);
          */

              for (row = 0; row < rows; row++) {
                  for (col = 0; col < cols; col++) {
                   if (inimage->i.c[row][col] > threshold)
                          outimage->i.c[row][col] = 255;
                   else
                          outimage->i.c[row][col] = 0;
                  }
              }

          /* Write the image to the file name specified by argv[3] */
              Write_Image(outimage, argv[3]);

          /* Free the memory allocated for images */
              Free_Image(inimage);
              Free_Image(outimage);

                                        - 7 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

              return;
          }

          Note that in this program individual pixels in the input image,
          inimage, which is of BYTETYPE, are referenced using .nf inimage-
          >i.c[row][col].fi The pointer, i, is a union structure and can be
          treated as a pointer to any of the currently supported image data
          types.

          For other types of images one has to specify how the union structure,
          i, should be used.  For example to access the element in the eleventh
          row and ninth column in a LONGTYPE image one would use:
          value = image->i.l[10][8];

          In a FLOATTYPE image one would address pixels using
          value = image->i.f[10][8];

          If the image is of RGBTYPE one would access the colour components
          using:
          redvalue   = image->i.rgb[10][8][0];
          greenvalue = image->i.rgb[10][8][1];
          bluevalue  = image->i.rgb[10][8][2];

          If the image is of COMPLEXTYPE one would use:
          realvalue      = image->i.cx[10][8].r;
          imaginaryvalue = image->i.cx[10][8].i;

          See the section, ``The VIP IMAGE Structure'' for more details.

     A Sample Makefile

          Compiling and linking a program using VIP is illustrated by the
          example makefile listed below.

          Note that you should use the gcc compiler as the VIP system is written
          in ANSI C. (use `setenv CC gcc' in your .cshrc file).

          # Example makefile using VIP

          # First set up directories and pathways.

          VIP_DIR = /proj/robvis/vip
          LIB_PATH = -L$(VIP_DIR)/lib/sunlib  # use declib on the Alpha
          INCLUDE_PATH = -I$(VIP_DIR)/include

                                        - 8 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          # Compiling flags
          fla = -DSUN                     # use -DDEC_ALPHA on the Alpha
          CFLAGS = $(INCLUDEPATH) $(fla)

          # Specify the libraries - we want the VIP and maths libraries
          LIBS = $(LIBPATH) -lvip -lm

          # Now make the program

          yourprog: yourprog.o
                  $(LINK.c) -o yourprog yourprog.o $(LIBS)

          yourprog.o: yourprog.c
                  $(COMPILE.c) yourprog.c

     A Sample Function

          The following function performs a homomorphic filtering operation on
          an image.  This is an image enhancing process that attempts to reduce
          the effects of low frequency lighting variations across an image, yet
          at the same time accentuating high frequency intensity variations to
          highlight the detail (see Gonzalez and Woods {\m ``Digital Image
          Processing''} p. 213 for more detail).  The steps involved in this
          process are:

          - The log of the image is taken.
          - The Fast Fourier Transform is taken.
          - A filter function is constructed that reduces low frequency
          components in the image and magnifies the high frequency ones.
          - The Fourier Transform of the image and the filter are multiplied
          together.
          - The inverse Fourier Transform is taken.
          - The exponential of the image is taken.
          - A percentage of the extremes of the image histogram are truncated.
          - Finally the image values are rescaled to the range 0-255.

          You should note the following:

          - Different image types are accepted and, on some occasions,
          mixed by the VIP functions that are called.  Log_Image is passed a
          BYTETYPE image and returns a FLOATTYPE.  FFT_Image is passed a
          FLOATTYPE image and returns a COMPLEXTYPE.  Multiply_Image is passed
          a COMPLEXTYPE and a FLOATTYPE image and returns a COMPLEXTYPE.  This
          ability to cope with different image types simplifies the construction
          of programs.

                                        - 9 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          - There is no checking between calls to see if the
          previous function call failed.  In general VIP functions check to see
          if an input image is valid (non-NULL pointer and correct ID code).  If
          an input image is not valid the function will report the error and
          exit returning a NULL image pointer. Thus if an error occurs early in
          the sequence one will simply cascade harmlessly (hopefully) through
          the other function calls before terminating.  Not having to embed
          large numbers of error trapping calls in one's code makes it much
          clearer to read.

          - All image pointers are initialised to NULL.  This is important
          defensive programming.  If any image pointer is passed to a function,
          and that pointer has never had any image data assigned to it, the
          receiving function can detect this as its value will be NULL.  Also,
          the function Free_Image does not attempt to free memory if it is
          passed a NULL pointer.  This is important if one is to cascade safely
          through a sequence of function calls if an error occurs as described
          above.

          /*- Homomorphic ------------------------------------------------

          Function to perform homomorphic filtering on an image. An image
          enhancing process that attempts to reduce the effects of low frequency
          lighting variations across an image, yet at the same time accentuating
          high frequency intensity variations to highlight the detail.
          Reference: Gonzalez and Woods "Digital Image Processing" page 213.

          Peter Kovesi  January 1994

          input: image    - input image.
                 LowGain  - gain factor for low frequencies (suggest 0.5).
                 HighGain - gain factor for high frequencies (suggest 2.0).
                 CutOff   - frequency at which transition from LowGain to
                            HighGain occurs (suggest 0.4).
                 order    - order of Butterworth type filter (suggest 1)
                 lHistogramCut - percentage of low end of histogram to
                                 truncate (suggest 1).
                 uHistogramCut - percentage of high end of histogram to
                                 truncate (suggest 5).

          Function returns filtered image.

          ------------------------------------------------------------------*/

                                       - 10 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          IMAGE  *Homomorphic(IMAGE * image, double LowGain, double HighGain,
                      double CutOff, int order, int lHistogramCut, int uHistogramCut)
          {
              IMAGE  *t1 = NULL, *t2 = NULL, *t3 = NULL, *t4 = NULL, *t5 = NULL,
                     *t6 = NULL, *t7 = NULL;
              IMAGE  *outimage = NULL, *filter = NULL;
              int     r, c;

              t1 = Log_Image(image);

              t2 = FFT_Image(t1, 0);
              Free_Image(t1);

              filter = Make_Homomorphic_Filter(t2->rows, t2->cols, CutOff, LowGain,
               HighGain, order);

              t3 = Multiply_Image(t2, filter);
              Free_Image(t2);
              Free_Image(filter);

              t4 = IFFT_Image(t3, 0);
              Free_Image(t3);
              if(!t4) {
                VIP_Error_Msg("Homomorphic: An error occurred during a function call");
                return(NULL);
              }

          /* Extract real part of image */

              t5 = Allocate_Image(0, 0, t4->rows, t4->cols, FLOATTYPE);
              for (r = 0; r < t4->rows; r++)
                  for (c = 0; c < t4->cols; c++)
                      t5->i.f[r][c] = t4->i.cx[r][c].r;

              Free_Image(t4);

              t6 = Exp_Image(t5);
              Free_Image(t5);

          /* Remove outlying values of image by truncating top and lower ends of
          the image histogram by HistogramCut percent */

              t7 = Truncate_Image_Histogram(t6, lHistogramCut, uHistogramCut);
              Free_Image(t6);

              outimage = Float2Byte_Image_X(t7);
              Free_Image(t7);

                                       - 11 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

              if(!outimage)
                VIP_Error_Msg(``Homomorphic: An error occurred during a function call'');

              return (outimage);
          }

     The VIP System in More Detail
     The VIP IMAGE Structure
          Central to any image processing system is the image data structure
          used.  The VIP IMAGE structure supports a wide variety of image types
          ranging from the basic 8 bit grey level representation through to
          complex valued and colour images.  This is achieved by using a union
          structure to point to the actual image data.  This union structure
          consists of pointers to all the different types of image data elements
          that are supported.  As pointers to all data types are the same size
          any number of new pointers to new data types can be added to the image
          pointer union without affecting the existing system.  Thus new image
          types can be added easily without `breaking' the existing code.  When
          accessing image data, simply choosing the appropriate element from the
          image pointer union will result in the correct pointer arithmetic
          occurring.

          An additional feature of the VIP image data structure that
          distinguishes it from other image structures is its provision for
          comprehensive camera calibration data and lens distortion parameters.
          The VIP system provides support for reconstruction of 3D information
          from images via structured light and stereo.

          To aid portability the data structures have been designed to have all
          elements aligned with word boundaries so that the different packing
          characteristics of different machines would not be an issue.  It is
          assumed that binary files are stored in big-endian format (byte
          reversed order), this is the natural format produced by Sun SPARC
          machines.  VIP libraries compiled for little-endian machines (DEC
          Alpha and PC's) will perform byte-reversal of image data when reading
          so that it can be interpreted correctly, and then when writing data
          out, will also perform byte-reversal to ensure consistency of binary
          data files.  Unfortunately this does, of course, involve some loss of
          efficiency.

          The image types currently available under VIP are:

          BYTETYPE An unsigned 8 bit grey level image with values ranging from 0
          to 255.

                                       - 12 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          SHORTTYPE Signed 16 bit grey level image.

          LONGTYPE Signed 32 bit grey level image.

          FLOATTYPE 32 bit floating point valued image.

          DOUBLETYPE 64 bit floating point valued image.

          COMPLEXTYPE Complex valued image, real and imaginary components each
          represented by a 32 bit floating point value.

          RGBTYPE Colour image represented by red, green and blue components,
          each component represented by an 8 bit unsigned values.

          HSITYPE Colour image represented by hue, saturation and intensity
          components, each component represented by an 8 bit unsigned values.

          Where appropriate (and where it makes sense) the VIP image processing
          libraries will in most cases allow different image types to be used
          and/or mixed in a seamless manner.  This discussed in some more detail
          later.

          The VIP image data structure is listed below.  For full details refer
          to the listing vip.h in the vip/include directory.

          /*- Image types ------------------------------------------------------*/

          #define BYTETYPE    1
          #define SHORTTYPE   2
          #define LONGTYPE    3
          #define FLOATTYPE   4
          #define DOUBLETYPE  5
          #define COMPLEXTYPE 6
          #define RGBTYPE     7
          #define HSITYPE     8

          /*-  Data types used to build IMAGE structure  ---------------------*/

          typedef struct {         /* complex number */
              float    r;
              float    i;
          }        COMPLEX;

          typedef unsigned char RGB[4]; /* RGB colour image, red green and blue
                               * stored in an array of 4 bytes for

                                       - 13 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

                               * convenience and efficiency */

          typedef unsigned char HSI[4]; /* Hue, saturation and intensity colour
                                           * image */

          typedef unsigned char *c_array;
          typedef short *s_array;
          typedef long *l_array;
          typedef float *f_array;
          typedef double *d_array;
          typedef COMPLEX *cx_array;
          typedef RGB *rgb_array;
          typedef HSI *hsi_array;

          typedef union imagedata {
              c_array *c;
              s_array *s;
              l_array *l;
              f_array *f;
              d_array *d;
              cx_array *cx;
              rgb_array *rgb;
              hsi_array *hsi;
          }        imagedata;

          /*-  CAMERA structure  --------------------------------------------*/

          typedef struct {
              int      idcode;
              char     version[8];
              int      channel;           /* Channel on PIP board */
              int      gain, offset;      /* Gain and offset for the channel */
              int      uvoffset;          /* UV offset in using calibration matrix
                                           * and lens compensation data */
              int      calibstatus;       /* Flag indicating type of calibration data
                                           * present */
              double   gamma[5];          /* For grey scale correction if needed */
              double   calib_matrix[3][4];/* Calibration matrix */
              double   Ucomp[18];         /* Coeffs of lens compensation polynomial*/
              double   Vcomp[18];         /* Coeffs of lens compensation polynomial*/
          }        CAMERA;

          /*- IMAGE Data Structure --------------------------------------------*/

          typedef struct {

                                       - 14 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

              int      idcode;            /* Code to allow automatic identification*/
              char     version[8];        /* software version No */
              int      type;              /* Data type - char, rgb colour etc */
              int      umin;              /* Image origin coords */
              int      vmin;
              int      rows;
              int      cols;
              double   resolution;
              char     info[80];          /* Space for comments */
              CAMERA   camera;
              long     reserved[3];
              void    *pntr[2];           /* two pointers for attaching other
                                           * structures to the image, or for linking
                                           * sequences of images together */
              union imagedata i;
          }        IMAGE;

          The following table lists how pixel elements in different image types
          are accessed.

          value = image->i.c[row][col];   /* BYTETYPE */
          value = image->i.s[row][col];   /* SHORTTYPE */
          value = image->i.l[row][col];   /* LONGTYPE */
          value = image->i.f[row][col];   /* FLOATTYPE */
          value = image->i.d[row][col];   /* DOUBLETYPE */

          RedValue   = image->i.rgb[row][col][0];  /* RGBTYPE */
          GreenValue = image->i.rgb[row][col][1];
          BlueValue  = image->i.rgb[row][col][2];

          HueValue        = image->i.rgb[row][col][0];  /* HSITYPE */
          SaturationValue = image->i.rgb[row][col][1];
          IntensityValue  = image->i.rgb[row][col][2];

          RealValue      = image->i.cx[10][8].r; /* COMPLEXTYPE */
          ImaginaryValue = image->i.cx[10][8].i;

     Global Variables in VIP
          There are a number of global variables used in the VIP system.  They
          are declared in vipglobals.c which is listed below.

                                       - 15 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          FILE    *VIP_LOG_FILE = NULL;  /* Pointer to log file for data recording*/
          FILE    *VIP_STD_ERR = stderr; /* Error output */
          int      VIP_VERBOSE = 0;      /* flag to turn on or off extra printing of
                                          * data */
          int      VIP_DISPLAY = 0;      /* flag for when one wants to turn
                                          * displaying of images on or off */
          char     VIP_MESSAGE[VIP_MESSAGE_LENGTH];       /* global message variable
                                                           * for passing to X view
                                                           * alert boxes etc */

          double   PLANE[USERPLANEMAX][3][3];     /* Fifty constraint planes, each
                                                   * defined by 3 points. These are
                                                   * used for 3D light stripe
                                                   * reconstruction */

     Conventions
          VIP function names start with capitals, multiple words within a
          function name are separated by underscores and each word starts with a
          capital, eg. Allocate_Image.

          VIP data types and VIP global variables are in capitals.

          All error messages are reported via VIP_Error_Msg (in vipio.c).

          The success or otherwise of the execution of a function is indicated
          by the return of either `OK' (1) or `ERROR' (0).  Functions that
          return addresses return NULL on failure.

          In general VIP functions should check to see if an input image is
          valid (non-NULL pointer and correct ID code).  If an input image is
          not valid the function will report the error and exit returning a NULL
          image pointer. Thus if an error occurs early in a sequence of function
          calls in a program one will simply cascade harmlessly through the
          other function calls before terminating.  The idea here being to avoid
          having to embed large numbers of error trapping calls in one's code,
          thus making it much easier to read.

          Accordingly it is good practice to initialise all image pointers to
          NULL.  If any image pointer is passed to a function, and that pointer
          has never had any image data assigned to it, the receiving function
          can detect this as its value will be NULL.  Also, the function
          Free_Image does not attempt to free memory if it is passed a NULL
          pointer.  This is important if one is to cascade safely through a
          sequence of function calls if an error occurs as described above.

          Any image processing function should not destroy or overwrite its
          input image(s).  The result should be placed in a new image, with the

                                       - 16 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          address of the new image usually being returned by the function.

          Generally, each image processing function contains a series of CASE
          statements, indexed by the image type, containing code to process the
          different types of images available under VIP.  For example a
          thresholding function could operate on BYTETYPE, SHORTTYPE, FLOATTYPE
          and other images using this mechanism.  There is no requirement that
          functions cater for all image types, and in many cases they will only
          support BYTETYPE images.  Each function will test for validity of the
          image type and return an error message if it does not support the
          particular image input type.  It is assumed that as people find
          functions that do not support an image type that they need they will
          add the appropriate code to these functions (and update the
          documentation!).

     Error Reporting
          A flexible system exists for the reporting of errors.  Different types
          of programs have different needs for error reporting.  Command line
          programs simply want messages printed on the screen but windows based
          programs want messages to be displayed in alert boxes.  Both of these
          needs can be accommodated in the VIP system.  As mentioned above the
          success or otherwise of the execution of a function is indicated by
          the return of either `OK' (1) or `ERROR' (0).  Functions that return
          addresses return NULL on failure.  All error messages are reported via
          the function VIP_Error_Msg (in vipio.c).  This function allows error
          messages to be directed to up to three different locations depending
          on the needs of the user.

          The three different (globally accessible) locations are:

          VIP_STD_ERR The default value of this is stderr, but it can be
          assigned to any file pointer.

          VIP_LOG_FILE A file pointer, default value is NULL.

          VIP_MESSAGE A character array.  Error messages are always copied into
          this array (space permitting).

          For standard command line based programs the default configuration
          simply results in error messages being sent to stderr (your screen).

          For an X View or other windows based program it is not appropriate to
          be sending text messages to consoles.  In these situations VIP_STD_ERR
          is set to NULL to suppress the printing of messages.  The array
          VIP_MESSAGE is used instead.  When an error is detected through a zero
          or NULL value returned from a function the current contents of
          VIP_MESSAGE can be passed to an alert box for display.  Multiple error
          messages are concatenated together so that one can trace the source of

                                       - 17 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          any errors.  Once the message has been displayed in an alert box it is
          up to the programmer to ensure that the VIP_MESSAGE array is cleared
          to allow new errors to be reported to it.

          The VIP_LOG_FILE pointer is intended for programs that run
          continuously for an extended period of time, say, on a long sequence
          of images.  In these situations one may wish errors to be recorded
          silently in a log file for later analysis if needed.

     Location of the VIP System Components
          VIP Library :

          DEC Alpha UNIX compatible VIP library :
          /proj/robvis/vip/lib/declib/libvip.a SUN Sparc UNIX compatible VIP
          library : /proj/robvis/vip/lib/sunlib/libvip.a PC     DOS  compatible
          VIP library : /proj/robvis/vip/lib/pclib/libvip.a

          VIP Utilities :

          DEC Alpha UNIX compatible VIP utilities : /proj/robvis/vip/bin/decbin
          (unimplemented) SUN Sparc UNIX compatible VIP library   :
          /proj/robvis/vip/bin/sunbin

          VIP Source Code :

          The source code for the various hardware and software platforms on
          which the VIP System is implemented, is represented by a single set of
          code.

          VIP Library Code   : /proj/robvis/vip/src/lib VIP Utilities Code :
          /proj/robvis/vip/src/vip VIP Include Files  : /proj/robvis/vip/include

          There are additional subsets of VIP related code, designed for
          particular VIP related tasks; these are discussed in the appendix.

          VIP Manuals   :

          VIP Utilities                 : /proj/robvis/vip/man/man1 VIP Library
                            : /proj/robvis/vip/man/man2

     Files
          vip.h

          The VIP include file.

                                       - 18 -         Formatted:  March 16, 2001

     VIP(2)                        VIP Version 4.0                        VIP(2)
     VIP SYSTEM                                                       VIP SYSTEM

                                    February 1994

          vipglobalsfn.h vipglobals.c

          File declaring all global variables used in the VIP system.

          vipiofn.h vipio.c

          General input/output functions, image allocation and freeing,
          conversion between different formats.

          vipspatfn.h vipspat.c

          Collection of basic spatial image processing functions.

          vip1Dfn.h vip1D.c

          Collection of functions for processing one dimensional slices through
          images.

          vipfreqfn.h vipfreq.c

          Collection of frequency based image processing functions.

          vipcomplexfn.h vipcomplex.c

          Functions for manipulating complex numbers.

          vipcalibfn.h vipcalib.c

          Functions supporting 2D/3D image transformations, reconstruction of 3D
          data via structured light and stereo.

          vector.h vectorfn.h vector.c

          An extensive library of vector and matrix manipulation routines.

     SEE ALSO
          vip(2), vipio(2), vipconv(2), viparith(2), vipspat(2), vipstat(2),
          vipfreq(2), vipcalib(2), vipvector(2), vipcomplex(2), vipmisc(2)

                                       - 19 -         Formatted:  March 16, 2001