
DESCRIPTION 
-----------

This is a little package containing code
for edges extraction based on the following
publication (among others):
 *   "Recursive filtering and edge tracking: two primary tools
      for 3-D edge detection", O. Monga, R. Deriche,
     G. Malandain and J.-P. Cocquerez, Image and Vision
     Computing 4:9, pp 203-214, August 1991.
 *   "Recursively Implementing The Gaussian and Its Derivatives",
     R. Deriche, International Conference On Image Processing,
     pp 263-267, Singapore, September 1992. Also INRIA research
     report.

It should be only use it for research purposes with no commercialization
interests. You are not allowed to distribute it outside your laboratory.
The authors thank you to mention them in forthcoming related publications.

CONTENTS
--------

This package should contain the following directories

src/: source and header files

     recline.[c,h]: recursive filtering of a line (a 1D array)
     recbuffer.[c,h]: recursive filtering of a buffer (a [1,2,3]D array)
                      according that the filtering is separable
     extrema.[c,h]: extraction of 2D or 3D edges
                   main (most important) functions are:
                   Extract_Gradient_Maxima_2D()
                   Extract_Gradient_Maxima_3D()
     convert.[c.h]: conversion between buffers of different types
     connexe.[c.h]: connected components extraction, may be used for
                    hysteresis thresholding, to count and label
                    connected components. Design of other tools
                    (as components containing seeds, or holes filling)
                    should be really easy.
     typedefs.h: some common definitions
     iopnm.[c.h]: home made I/O routines for PBM/PGM/PPM raw images
     test-edges.c: a test program to show how to use the main functions
     test-edges-pnm.c: a test program to extract edges in PBM/PGM/PPM raw images
     test-hyster-pnm.c: a test program to perform hysteresis thresholding
                        in PBM/PGM/PPM raw images

     images/: some test images *.data (data without headers) to be processed 
              with test-edges

              square64x64.data: a 64^2 2D synthetical image (unsigned char)
              disk64x64x64.data: a 64^3 3D synthetical image (unsigned char)
              mri64x64x64.data: a 64^3 3D medical image (unsigned char)
              *.extrema are the ground truth outputs (the ones I obtained at INRIA
              with the same test program).
              *.tmp are the output you will obtain.

              greg-rmn.pgm, mona.pgm: two PBM/PGM/PPM raw images
	                              (me and mona :-)
             to be processed with test-edges-pnm, example:
              %%% test-edges-pnm mona.pgm mona-edges.pgm
              will generate edges of the image mona.pgm

html/: a html documentation generated by c2man from the src/*.h files
       in addition you will find index.html 

latex/: a tex documentation generated by c2man from the src/*.h files
	in addition you will find main.tex main.dvi main.ps

HOW TO USE IT
-------------

go into the src directory and compile the code:

% cd src
% make

then (if everything is ok) you can reproduce the example from the web page 
     http://www-sop.inria.fr/epidaure/personnel/malandain/segment/edges.html
i.e.

% test-edges-pnm images/greg-rmn.pgm greg-rmn.ext

test-edges-pnm works on 2D pgm image, you can use your favorite image 
format converter to convert your 2D images into that format.
Otherwise, you may have a look on http://www.imagemagick.org/ or get xv
to convert them manually (cf http://www.trilon.com/xv/),
or you may try to build your own converter (see pgm.5 for the description
for the format).

This package has been designed to be used in some image processing library,
thus one should look at test-edges.c to see how to call the different
functions (especially in 3D).





Gregoire Malandain
gregoire.malandain@inria.fr
