[ Bristol CS | Index ]

IPLIB Users Guide

Introduction

This is a brief guide to using the Image Processing LIBrary. The library consists of a small number of C functions written specifically for the image processing laboratory sessions. To use the library you will need to include the library header file in your programs, viz

\#include "/usr/local/course/csadc/iplib/iplib.h"

and link in the library when compiling your programs, ie for solaris machines:

gcc -o myprog myprog.c /usr/local/course/csadc/iplib/iplib.a -lm

or for linux machines:

gcc -o myprog myprog.c /usr/local/course/csadc/iplib/ipliblinux.a -lm

Note that you must also link in the maths library using -lm. You can use the library on both Faculty and Departmental machines.

You can download your own copy of all the source files in a gzipped tar file.

Philosophy and Format

The library is designed to ease your path to doing some real image processing, ie to get hands-on experience of writing code which actually carries out image processing operations. It provides you with three types of functions:

I/O functions which allow you to write and read images to and from files.
Allocation functions which allow you to allocate memory for `images' whose elements are of a given data type, eg bytes, reals, complex, etc.
A few special functions such a 2-D fft (these are being added all the time).

The library makes use of the `pgm' and `ppm' (raw) image formats and all images are written out and read in as either `pgm' or `ppm' images. The pgm format is used to store 8-bit grey level images and the ppm format is used to store 24-bit RGB images. Details of the formats are attached. The functions available in the library are summarised below.

Library Functions

unsigned char **readpgm(char filename, int width, int *height)

readpgm() reads a pgm image from the file filename and returns the image as a 2-D unsigned char array of size (*width) x (*height). The integers pointed to by width and height are set to the width and height of the image.

writepgm(unsigned char **imageptr, int width, int height, char *filename)

writepgm() writes the image in the 2-D array of unsigned chars pointed to by imageptr into the file filename as a pgm image. The integers width and height are the number of columns and rows, respectively, in the image.

unsigned char ***readppm(char filename, int width, int *height)

readppm() reads a ppm image from the file filename and returns the image as a 3-D unsigned char array of size (*width) x (*height) x 3. The integers pointed to by width and height are set to the width and height of the image. If a is the array returned, then a[i][j][0], a[i][j][1], and a[i][j][2] contain the red, green and blue values of pixel i,j.

writeppm(unsigned char ***imageptr, int width, int height, char *filename)

writeppm() writes the rgb image in the 3-D array of unsigned chars pointed to by imageptr into the file filename as a ppm image. The integers width and height are the number of columns and rows, respectively, in the image.

unsigned char **uchar_array(int width, int height)

uchar_array() allocates and returns a pointer to a 2-D unsigned char array of size width x height .

float **float_array(int width, int height)

float_array() allocates and returns a pointer to a 2-D float array of size width x height.

unsigned char ***uchar_array3D(int width, int height)

uchar_array3D() allocates and returns a pointer to a 3-D unsigned char array of size width x height x 3.

float ***float_array3D(int width, int height)

float_array3D() allocates and returns a pointer to a 3-D float array of size width x height x 3.

complex **complex_array(int width, int height)

complex_array() allocates and returns a pointer to a 2-D array of elements of type complex of size width x height.

complex ***complex_array3D(int width, int height)

complex_array3D() allocates and returns a pointer to a 3-D array of elements of type complex of size width x height x 3.

free_uchar_array(unsigned char ptr, int height)
free_float_array(unsigned char ptr, int height)
free_uchar_array3D(unsigned char ptr, int height, int width)
free_float_array3D(unsigned char ptr, int height, int width)
complex_array(complex ptr, int height)
complex_array3D(complex *ptr, int height, int width)

These functions release memory previously allocated by their corresponmding allocation functions, where the allocated array is pointed to by ptr. The array has height rows.

complex fft2d(complex p, int width, int height, int inv)

For inv==0, this function returns the 2-D fast Fourier transform of the complex array p of size width x height. For inv==1, the inverse FFT is returned.

float gasdev()

Returns normally distributed random variable with zero mean and unit variance

int getcalpars(char filename, CalPars data)

getcalpars() assigns stereo calibration data to `data' read from the calibration text file `filename'. The type CalPars is a structure containing the extrinsic and intrinsic parameters of the stereo system, ie:

typedef struct cpars { float R[3][3]; float T[3]; CamPars leftcam; CamPars rightcam; } CalPars;

typedef struct cam { float f; float sx,sy; float ox,oy; } CamPars;

Used for the stereo correspondence assignment of COMS30121.

Example

The following program illustrates the use of some of the library functions. It does the following

Reads in the pgm image stored in the file with filename given by argv[1].
Transfers the image to a float array.
Stores the square of each pixel value in a new float array.
Scales the float array to values in the range 0-255 and stores them in an array of unsigned chars.
Writes out the array of unsigned chars as a pgm image to a file with filename given by argv[2]}.

Note that when each type of array is no longer needed the memory space it occupied is released using the appropriate `free' function.

#include < math.h> #include < stdio.h> #include "/usr/local/course/csadc/iplib/iplib.h" main(int argc, char **argv) { struct complex **cim,**dftim; unsigned char **ucim; float **fim1,**fim2,maxvalue; int height,width,i,j; ucim=readpgm(argv[1],&width,&height); fim1=float_array(width,height); for(i=0;i< height;i++) for(j=0;j< width;j++) fim1[i][j] = ucim[i][j]; free_uchar_array(ucim,height); fim2=float_array(width,height); maxvalue=0.0; for(i=0;i< height;i++) { for(j=0;j< width;j++) { fim2[i][j]=fim1[i][j]*fim1[i][j]; if(fim2[i][j]>maxvalue) maxvalue=fim2[i][j]; } } free_float_array(fim1,height); ucim=uchar_array(width,height); for(i=0;i< height;i++) for(j=0;j< width;j++) ucim[i][j]=(unsigned char)(255.0*fim2[i][j]/maxvalue+0.5); free_float_array(fim2,height); writepgm(ucim,width,height,argv[2]);