****************************************************************************
*                                                                          *
* 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 modes are IF_ASCII and
IF_BINARY. Some image types are written in standard formats (known by
programs such as XV): IT_BIT as pbm, IT_BYTE as pgm and IT_RGB as ppm.
All the other image types are written in an internal format which
includes the valid region information and min and max values image
fields. Many images can be written to one output stream because
i_read_image_file (below) can read them back in separately. XV cannot
load multiple images in this way.

it_image *i_read_image_file(FILE *fp,int types,int mode)
	fp	file pointer open for reading.
	types	allowed image types.
	mode	image creation mode.

This function reads an image written by the i_write_image_file
function and creates a suitable image structure. The function will
only allow files of the specified type to be loaded. The types
parameter is made by or-ing together IT_BIT, IT_BYTE etc., to indicate
which images you are interested in. If the incoming data format is one
of these, then the image will be created and loaded, otherwise the
function returns NULL. The mode parameter specifies whether memory for
the image is allocated contiguously (IM_CONTIG) or in fragments
(IM_FRAGMENT). The function returns NULL if loading fails or not
enough memory could be allocated. The type of image loaded can be
determined from the type field of the image structure. This function
will load standard pbm, pgm and ppm images, but note that for pgm and
ppm, grey or colour values may be silently scaled to lie in the range
0-255.

int i_save_image(char *name,int seq_num,it_image *image,int mode)
	name	filename
	seq_num	sequence number of filename
	image	image to save
	mode	binary or ascii saving mode (as before)

This function saves an image to a file in the same way that
i_write_image_file saves images exceps that it opens and closes the
stream for you. The filename is constructed in the following way. If
seq_num = -1 then the file is saved to the name given. This name may
be a full path name, including UNIX tilde referencing e.g.
~/foobar/file.pgm or ~fred/file.ppm. Such references will be
auto-expanded. If the sequence number is > -1 then it is inserted in
the file name before the final dot (if present) using a three figure
format to give the file a sequence number. For example if the filename
is ~fred/file.ppm and seq_num=4 then, as an example (which depends
upon your system) the image may be saved as
/net/homes/maths/fred/file004.ppm This function returns 1 if there was
a problem in saving otherwise it returns 0.

it_image *i_load_image(char *name,int seq_num,int types,int mode)
	name	filename
	seq_num	sequence number of filename
	types	allowed image types.
	mode	image creation mode.

This function loads images in the same manner as i_read_image_file,
except the file is opened and closed for you using the same interface
as i_save_image. Returns NULL on failure to open, create or load the
image.

FILE *i_open_file(char *name,int seq_num,char *mode)
	name	filename
	seq_num	sequence number of filename
	mode	fopen mode

This function opens a file stream using the fopen mode given ("r", "w"
etc.). The filename convention is the same as for the i_save_image
function above including tilde expansion. Returns NULL on failure.

char *i_parse_filename(char *name,int seq_num)
	name	filename
	seq_num	sequence number of filename

This function returns the constructed filename that would be used by
i_save_image or associated functions as described above. The memory
used to return the filename is dynamically allocated and must be freed
after use by calling free. Returns NULL on failure.

void i_error(char *message)
	message 	message to print.

This function prints the error message given to stderr using a
standard format.

-------------------------------------------------------------------------------
Histogram Structures
====================

The histogram structure is defined as:

typedef struct {
  int maxcolours;
  int numcolours;
  it_hist_entry *hash_col[IM_HIST_HASHSIZE];
  it_hist_entry *hist_list;
} it_hist;

Histogram functions take and return pointers to such a structure. The
data stored within the dynamically allocated array hist_list is made
up of structures of type it_hist_entry:

typedef struct _it_hist_entry {
  it_rgb colour;
  int index;
  long count;
  struct _it_hist_entry *next_col;
} it_hist_entry;

The hash_col[] and next_col entries are used in implementing the
colour hash search implementation.

-------------------------------------------------------------------------------
Histogram Functions 
===================

it_hist *i_create_histogram(int maxcolours)
	maxcolours	Maximum histogram size.

This function allocates memory for a histogram with the number of
different colour entries specified and returns a pointer to the
histogram structure or NULL if there is not enough memory.

void i_destroy_histogram(it_hist *hist)
	hist	pointer to the histogram structure.

This function frees the storage associated with the histogram pointed
to by hist.

it_hist_entry *i_add_histogram_entry(it_hist *hist,it_rgb *colour)
	hist	pointer to the histogram structure.
	colour	pointer to a colour structure.

This function adds a new colour to the histogram. If the colour
pointed to by colour is not present in the histogram, a new entry is
added at the next index position and the numcolours field in the
it_hist structure is incremented. If the colour is already present,
its associated count field is incremented. This function returns a
pointer to the relevant entry in the histogram, or NULL if the maximum
number of colours would be exceeded by creating a new entry. The count
field in the it_hist_entry structure will be equal to one if the
colour has been newly created.

it_hist_entry *i_lookup_histogram_index(it_hist *hist,int index)
	hist	pointer to the histogram structure.
	index	index into existing histogram colours.

This function returns a pointer to the histogram entry with the
desired index, or NULL if the index was out of range. Index numbers
start from zero for the first colour entry and increment with each new
colour.

it_hist_entry *i_lookup_histogram_colour(it_hist *hist,it_rgb *colour)
	hist	pointer to the histogram structure.
	colour	pointer to a colour structure.

This function returns a pointer to the histogram entry with the
desired colour, or NULL if the colour is not present within the
histogram.

-------------------------------------------------------------------------------
Histogram Macro
===============

it_rgb *im_histogram_colour(it_hist_entry *entry)
	entry	pointer to histogram entry.

This macro returns a pointer to the colour structure stored in the
given histogram entry.

-------------------------------------------------------------------------------
Colourmap Structures
====================

typedef struct {
  int maxindex;
  it_cmap_entry *hash_col[IM_CMAP_HASHSIZE];
  it_cmap_entry *cmap_list;
} it_cmap;

typedef struct _it_cmap_entry {
  it_rgb colour;
  struct _it_cmap_entry *next_col;
} it_cmap_entry;

-------------------------------------------------------------------------------
Colourmap Functions
===================

it_cmap *i_create_colourmap(int maxsize)
	maxsize		maximum number of entries.

This function creates a hashed colourmap of the specified size and
returns a pointer to the structure it_cmap, or NULL if not enough
memory was available.

void i_destroy_colourmap(it_cmap *colourmap)
	colourmap	pointer to the colourmap structure.

This function frees the memory allocated to the colourmap.

void i_set_colourmap_entry(it_cmap *colourmap,int index,it_rgb *colour)
	colourmap	pointer to the colourmap structure.
	index		colour index.
	colour		pointer to the colour to be entered.

This Function enters the given colour in the colourmap at the location
referred to by index. Index must be from 0 to maxcolours-1. The function
maintains a hashed connection to the colour allowing lookup by colour or
by index.

int i_lookup_colourmap_colour(it_cmap *colourmap,it_rgb *colour)
	colourmap	pointer to the colourmap structure.
	colour		pointer to the colour to be found.

This function looks up the given colour in the colourmap and returns
the index. If the colour appears more than once, the first occurrence
is returned.  If the colour does not exist, the function returns -1.

it_rgb *i_lookup_colourmap_index(it_cmap *colourmap,int index)
	colourmap	pointer to the colourmap structure.
	index		colour index.

This function looks up the given index in the colourmap and returns
the colour at that index. If the index is out of range, the function
returns NULL.

-------------------------------------------------------------------------------
Image Type Conversion Functions
===============================

The following functions convert between various image types. Both
source and destination images must have been created by the calling
program and must have the same dimensions. These functions return 0 on
success.

int i_byte_to_float(it_image *in,it_image *out)
	in	source byte image
	out	destination float image

int i_byte_to_double(it_image *in,it_image *out)
	in	source byte image
	out	destination doublet image

Direct conversion from byte to float or double images.

int i_float_to_byte(it_image *in,it_image *out)
	in	source float image
	out	destination byte image

int i_double_to_byte(it_image *in,it_image *out)
	in	source double image
	out	destination byte image

Lossy conversion from float or double images to byte format. The
conversion scheme depends on the values stored in min_value and
max_value in the input image structure. If theses are not set then the
images are converted by direct mapping over the range 0 to 255 and are
clipped outside this range. If max>0.0 and min<0.0 then the zero value
is represented by an output value of 128 and a scale factor is applied
to bring the positive and negative excursions of the image values into
the range 0 to 128 to 255. If min and max are both positive or both
negative then the image values in the range min-0 or 0-max (depending
on sign) are scaled and offset to lie in the range 0 to 255.

int i_rgb_to_float(it_image *in,it_image *out_r,it_image *out_g,
		it_image *out_b)
	in	source rgb image
	out_r	destination float image (red)
	out_g	destination float image (green)
	out_b	destination float image (blue)

A singe rgb image is converted into three separate float images
containing red, green and blue pixel data.

-------------------------------------------------------------------------------
Image Processing Functions
==========================

it_image *i_create_operator(int width,int height,double *op)
	width	width of convolution kernel
	height	height of convolution kernel
	op	array of data for kernel

This function creates a width x height image of type IT_DOUBLE
containing data drawn from the 1D array op. This can be used as a
convolution kernel. Returns NULL on failure.

int i_convolve(it_image *in,it_image *out,it_image *kernel)
	in	input image (float format)
	out 	output image (float format)
	kernel	kernel image (double format)

This function convolves an image with the kernel given. Computation
size increases quadratically with kernel size. Pixel values are only
used from within the valid region. The output valid region is smaller
than the input region due to the kernel size. Returns 0 on success.

int i_smooth(it_image *in,it_image *out,double sigma)
	in	input image (float format)
	out 	output image (float format)
	sigma	smoothing factor

This function smooths the input image using a Gaussian smoothing
kernel with space constant sigma (0.2<sigma<10.0). Pixel values are
only used from within the valid region. The output valid region is
smaller than the input region due to the kernel size. The function
returns 0 on success, 1 on failure due to bad parameters and -1 due to
failure to allocate memory.

int i_fourier_transform_1d(it_image *inout,int type)
	inout	input and output image (complex format)
	type	type of transform (forward, backward)

This function carries out the forward or inverse Fourier transform
(type = FFFT or type = IFFT) of the it_complex format image given. The
image is of dimensions: width x 1, where width must be a power of 2.
The first pixel in the frequency domain image is the DC term.
Consecutive pixels are higher positive frequency terms until the term
at x=width/2 which is the +-PI radians per pixel term. The rest of the
pixles are negative frequency terms becoming more positive with x.
Returns 0 on success.

int i_fourier_transform_2d(it_image *inout,int type)
	inout	input and output image (complex format)
	type	type of transform (forward, backward)

This function carries out the forward or inverse Fourier transform
(type = FFFT or type = IFFT) of the it_complex format image given. The
image must be square and have dimensions: size x size, where size must
be a power of 2. The top left pixel in the frequency domain image is
the DC term. Consecutive pixels (rightwards or downwards) are higher
positive frequency terms until the term at x (or y) =size/2 which is
the +-PI radians per pixel term. The rest of the pixels are negative
frequency terms becoming more positive with x (or y). Returns 0 on
success.

-------------------------------------------------------------------------------
