README FILE for thin.c, linker5.c, gluer5.c
		Author: Fabio Cozman (fgcozman@cs)

** This file provides basic information for using the line linker code.     **
** If you plan to use this software, please notify fgcozman@cs.cmu.edu, so  **
** that you can be reached for fixes, patches or new versions.              **

** Throughout this document, paths are abbreviated. A file that is in       **
** the documentation directory is referred to as /doc/XXX. A file that      **
** is in the source directory is referred to as /src/XXX.                   **
** In the Carnegie Mellon VASC environment, the documentation directory     **
** is /usr/vasc/local/pkg/img_utils/doc/gil2lines and  the source           **
** directory is /usr/vasc/local/pkg/img_utils/src/gil2lines                 **

 * The gil2lines package is free software; you can 
 * redistribute it and/or modify it under the terms of the GNU General 
 * Public License as published by the Free Software Foundation, provided
 * that this notice and the name of the author appear in all copies.
 * If you're using the software, please notify fgcozman@cs.cmu.edu so
 * that you can receive updates and patches.
 * The gil2lines package is distributed "as is", in the 
 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even the 
 * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
 * See the GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with the gil2lines package. If not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

** Now, some real stuff:						    **

The file /src/gil-general.c contains a set of functions that will be 
modified (presumably) by the user: the function error (which is called 
everytime the linker finds an unrecoverable error, and image-related
functions fg_i_clrimg, fg_i_putpixel, fg_i_igetpixel, fg_i_line, etc...

Definitions and prototypes for /src/general.c are contained in /src/general.h.
The idea is that, if you want to use an image library other than GIL,
you just enlarge general.h and rewrite gil-general.c. 
Currently there are defines and prototypes in general.h
that allow compilation with AVS structures and GIL structures.

Currently the error function simply
prints a message and exits; you may try something fancier by rewriting
/src/general.c. Keep in mind that if error is called, that is because you're
approaching a core dump.

The thinning program is in thin.c; it is not well documented but its
use should be obvious from the code.

The real linker is in /src/linker5.c and /src/gluer5.c.

There is a lot of information about program internals in the beginning
of linker5.c; here the purpose is simply to highlight which functions 
seems to be most important to get started. 
Before reading this, it is a good idea to get used to the
general behavior of the linker; experiment
a bit with the gil2lines program. In order to get documentation about
gil2lines, start with its man pages. There is also documentation in the
vasc-help facility.

Here is how to use the line linker code:

1) What must be declared in the caller program

The caller must declare three images, here named image_in, image_lines and
	image_chains. 
The type of these images is FG_Image (defined in general.h). 
	You can change it if you are using some library other than GIL.
Image_in receives the image that is to be processed. This image
	must contain only edgels (background is assumed to be zero; 
	edgels can assume any non-zero value). Image_in is left untouched by
	the linker.
Image_lines and image_chains are the output images.
Image_lines will contain, at any pixel, the label of the pixel.
	A pixel may be labelled zero (in which case it is background),
	or a positive number (in which case it belongs to a chain),
	or a negative number (in which case it belongs to a connection).
	See the definitions of chain and connection in the beginning of
	the file /src/linker5.c; you can also see it in the documentation
	file /doc/gil2lines.ps.
	The absolute value of the label is the index of the chain (in
	the Chain structure) or connection (in the Connection structure).
Image_chains will contain, at each non-zero pixel, the chain-code of the
	pixel, so that chains can be followed easily. The chain-codes are
	a bit non-standard in that they indicate, in a single byte, all 
	possible directions that can be followed from a particular pixel,
	and not only a single direction. The description of the chain-code
	is given in the beginning of the file /src/linker5.c. There are
	functions in /src/linker5.c that can provide easy handling of
	the chain-codes: for example, functions that discover the first
	direction that can be followed from a chain code, or discover
	how many directions can be followed, or give all the directions
	that can be followed from a given pixel. Notice that a direction
	is an integer that indicates NORTH, SOUTH, EAST, WEST, NORTH_WEST,
	NORTH_EAST, SOUTH_EAST, SOUTH_WEST. The relation between the numbers
	and the directions is defined in /src/linker5.h. 

The user must also declare two structures that will receive all data:

Elements *chains;
Elements *connections;

Definitions of these types (and all other types) can be found in 
/src/linker5.h. Brief explanations about the types can be found in the 
beginning of /src/linker5.c.

The structure Elements is basically an all-purpose vector; you must
tell the size of the vector to be allocated. The initialization can
be done with function initialize_chains_connections:

void initialize_chains_connections(Elements *chains, Elements *connections,
                                   int max_elements);

2) Which functions the caller calls

At this point, you are ready to use the linker.  The linker does a least
squares fit of chains that are merged and segmented used the Akaike
Information Criterion. General information about the theory behind the linker
can be found in /doc/gil2lines.ps.

The linker works in two steps; the first step is performed by the
function linking:

void linking(FG_Image *image_in, FG_Image *image_out, FG_Image *image_chains,
             FG_Subimage bounds,
             Elements *chains, Elements *connections,
             float variance_of_pixel, int significance_level_break_lines)

This function will fill the structures chains and connections with the results
of the first step.
 
In a sense, line linking has already been performed
at this point; all that will be done in the second step is to analyze
adjacent chains (for possible merging) and analyze small gaps between
nearby chains (for possible merging).
Also, image_out and image_chains are ready to use and are not touched
in the second step. The second step is performed by the function glue_chains:

void glue_chains(FG_Image *image_in, FG_Image *image_out,
                 FG_Image *image_chains, FG_Subimage bounds,
                 Elements *chains, Elements *connections,
                 float variance_of_pixel, int size_exploration)

3) Some interesting auxiliary functions

Linking is finished; chains and connections contain all relevant information.
You can use them arbitrarily, but there are some functions that
are ready to use for printing: 

int print_chain(Elements *chains, int number_chain, int verbose);
void print_chain_simple(Chain *temp_chain);
void print_filter_chain(FilterChain *filtered_chain);
void print_line(Line *line);
int print_connection(Elements *connections,
                     int number_connection, int verbose);
void print_connection_simple(Connection *temp_connection);
void print_element(Element *temp_element);

Also, there are some function that allow you to handle the somewhat 
cumbersome chain-codes. Notice that the chain-codes generated by
the linker are not common ones; the chain-code of a pixel will indicate 
ALL neighbors of this pixel. The functions are:

int give_direction(int i1, int j1, int i2, int j2);
int query_number_bits(int binary_number);
int query_chain_connection(int chain_code);
int first_available_direction_in_chain_code(int chain_code);
int all_available_directions_in_chain_code(int chain_code,
                                           int buf_directions[8]);
int invert_direction(int direction);
There is a function that allows you to free a whole Elements, either
hains or connections:
void free_elements(Elements *vector_elements);

4) The FilterChain hack

Finally, you may consider that the Chain structure is too cumbersome,
since it contains too much information (including linked lists, etc).
There is a simplified version of the Chain structure, called FilterChain,
which is much easier to handle and contains almost the same information.
You generate a vector of FilterChain structures from chains by doing this:

a) Declare
	Elements *filter_chains;

b) Initialize filter_chains; for example:
	filter_chains->total = 0;
	filter_chains->max = max_elements;
	filter_chains->elements = 
	   (Element *)malloc( (filter_chains->max) * sizeof(Element) );

c) Use the function filter_all_chains to translate chains into
   filter_chains:
	void filter_all_chains(Elements *chains, Elements *filter_chains);

d) Use filter_chains any way you like. To free it, use 
   free_elements(filter_chains).


 Suggestions for improvement of this document are more than welcome.
	If you think that there is some part of this text 
	that is obscure, tell me; if you catch some error, let me know.
	Be happy.

			Fabio Cozman