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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
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: November 14, 2024
