****************************************************************************
*                                                                          *
* IMG* Image Processing Library Manual                                     *
* Version 1.1 (Nov 1994)                                                   *
* Copyright (C) 1994 Simon A.J. Winder                                     *
*                                                                          *
****************************************************************************

This document describes the data structures and function calls that
can be used with the image processing library.

Include File
============

You should use the following header when writing programs that use
calls to the image library:

#include "image.h"

Compilation
===========

Compile your files with:

gcc file.c -I$IMGSTAR/LibSrc -L$IMGSTAR/LibSrc -limg -lm
or
gcc file.c $IMGSTAR/LibSrc/libimg.a -I$IMGSTAR/LibSrc -lm

Here, $IMGSTAR is the full path to the ImgStar directory.

-------------------------------------------------------------------------------
Image Value Types
=================

The following typedefs are used to provide for a number of different image
formats. These are the types of image "values" (pixels).

typedef unsigned char byte;
typedef byte it_bit;
typedef byte it_byte;
typedef long it_long;
typedef float it_float;
typedef double it_double;
typedef struct {byte r,g,b;} it_rgb;
typedef struct {float Re,Im;} it_complex;
typedef struct {float rad,ang;} it_polar;

These are represented by the following preprocessor symbols:

IT_NONE      None of the above.
IT_BIT       Bit image (pbm).
IT_BYTE      Grey level image (pgm).
IT_LONG      Long word image.
IT_FLOAT     Float image.
IT_DOUBLE    Double floating point image.
IT_RGB       Red, green and blue image (ppm).
IT_COMPLEX   Complex image.
IT_POLAR     Polar image.

-------------------------------------------------------------------------------
Image Structure
===============

The image structure is defined as:

typedef struct {
  int width,height;		Size of image.
  int valid_x,valid_y;		Top left corner of valid region.
  int valid_width,valid_height;	Size of valid region.
  double min_value,max_value;	Range of values.
  int mode;			Mode of creation/destruction.
  int type;			Type of image (one of the above names)
  void **field;			Pointer to 2D field of values.
} it_image;


-------------------------------------------------------------------------------
Image Creation and Destruction Functions
========================================

it_image *i_create_image(int width,int height,int type,int mode)
	width	Width of image to make.
	height	Height of image to make.
	type	Type of image.
	mode	Mode of creation.

This function creates an it_image structure and allocates memory for a
2D data field of the specified width and height. This field is
initialised to zero. The field entry in the image structure points to
an array of pointers to image rows. Each row pointer points to the
start of the pixel data for each row. The type parameter specifies the
image pixel value type and should be one of the symbols IT_BIT,
IT_BYTE etc. The mode can be either IM_CONTIG in which case the array
is guarenteed to be one block of contiguous values, or IM_FRAGMENT
when the rows of field values are not necessarily memory
contiguous. The it_image structure members are all set to default
values by a call to this function. In particular, the valid region is
set to be the entire image and the min and max value entries are
zeroed. Returns pointer to new image structure on success or NULL if
not enough memory was available.

void i_destroy_image(it_image *image)
	image	Pointer to image structure.

This function frees all storage used by the specified image. This image
was created by a call to i_create_image.

void i_set_valid_region(it_image *image,int x,int y,int width,int height)
	image	Pointer to image structure.
	x	top left x coordinate of valid region
	y	top left y coordinate of valid region
	width	width of valid region
	height	height of valid region

This function sets the valid region stored in the image structure. It
checks the values given and always stores a sensible region.

void i_set_min_max_values(it_image *image,double min,double max)
	image	Pointer to image structure.
	min	minimum value
	max	maximum value

This function sets the min and max value fields of the image structure.
The values are swapped if the min>max.

-------------------------------------------------------------------------------
Functions and Macros for Accessing Image Values
===============================================

int i_get_bit_value(it_image *image,int x,int y)
int im_get_bit_value(it_image *image,int x,int y)
	image	Pointer to image structure.
	x	X coordinate of bit to extract.
	y	Y coordinate of bit to extract.

This function extracts a bit value from an image with type it_bit.
Bits are stored in a packed format. Returns 1 or 0. The macro version,
im_get_bit_value is faster but evaluates x twice.

void i_put_bit_value(it_image *image,int x,int y,int value)
void im_put_bit_value(it_image *image,int x,int y,int value)
	image	Pointer to image structure.
	x	X coordinate of bit to alter.
	y	Y coordinate of bit to alter.
	value	value to set bit to.

This function sets or clears a bit value in an image with type it_bit.
Bits are stored in a packed format. If value is non-zero, the bit is
set to 1. The macro version im_put_bit_value is faster but evaluates x
twice.

it_byte    im_byte_value(it_image *image,int x,int y)
it_long    im_long_value(it_image *image,int x,int y)
it_float   im_float_value(it_image *image,int x,int y)
it_double  im_double_value(it_image *image,int x,int y)
it_rgb     im_rgb_value(it_image *image,int x,int y)
it_complex im_complex_value(it_image *image,int x,int y)
it_polar   im_polar_value(it_image *image,int x,int y)
	image	Pointer to image structure.
	x	X coordinate of value.
	y	Y coordinate of value.

The above macros refer to the image values at a particular x and y
coordinate for the relevant type of image and allow reading or writing
to the image array.

it_byte    *im_byte_row(it_image *image,int y)
it_long    *im_long_row(it_image *image,int y)
it_float   *im_float_row(it_image *image,int y)
it_double  *im_double_row(it_image *image,int y)
it_rgb     *im_rgb_row(it_image *image,int y)
it_complex *im_complex_row(it_image *image,int y)
it_polar   *im_polar_row(it_image *image,int y)
	image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1) if the two pixels are the same colour. (i.e.
they have the same rgb values)

void im_set_rgb(it_rgb *pix,int r,int g,int b)
	pix	pointer to rgb pixel.
	r,g,b	values to set pixel to.

This macro sets an rgb pixel to the colour given.

double im_luminance(it_rgb *pix)
	pix	pointer to rgb pixel.

This macro returns the luminance value for the rgb pixel given. It uses
the formula: L = 0.299*r + 0.587*g + 0.114*b.

-------------------------------------------------------------------------------
Image File Functions
====================

void i_write_image_file(FILE *fp,it_image *image,int mode)
	fp	file pointer open for writing.
	image	pointer to image structure.
	mode	mode of writing.

This function writes the given image in a standard format to the
specified file pointer. The type of image is found from the type
member of the image structure. This must be one of the supported image
types. The mode parameter dictates whether the image is written in a
binary or ascii format. Note that binary images containing floating
point numbers are machine dependent. Valid image	Pointer to image structure.
	y	Y coordinate of value.

The above macros return the image row pointers for the relevant type
of image and allow a pointer to be set to the start of an image row.

it_byte    **im_byte_field(it_image *image)
it_long    **im_long_field(it_image *image)
it_float   **im_float_field(it_image *image)
it_double  **im_double_field(it_image *image)
it_rgb     **im_rgb_field(it_image *image)
it_complex **im_complex_field(it_image *image)
it_polar   **im_polar_field(it_image *image)
	image	Pointer to image structure.

The above macros return the image field pointer for the relevant type
of image.

-------------------------------------------------------------------------------
Miscellaneous Types and Macros
==============================

XY coordinate structure:
typedef struct {
  int x;
  int y;
} it_point;

int im_rgb_equal(it_rgb *pix1,it_rgb *pix2)
	pix1	pointer to rgb pixel 1
	pix2	pointer to rgb pixel 2

This macro returns true (1)