CONTENTS

0. THE LICENCE

1. DAG MATCHER LIBRARY AND THE SHAPE MATCHER APPLICATION

2. EXTERNAL LIBRARIES

3. FINDING HELP FOR THE SHAPE MATCHER (SM)

4. IMAGE TYPES

5. HOW TO ADD YOUR OWN HIERARCHICAL STRUCTURE (ie, DAG) CLASS

6. THE DATABASE DESIGN

_______________________________________________________________________________________

0. THE LICENCE

   You must agree with the software licence in Licence.txt before reading, modifying or
compiling any of the files provided in this project. 

If you find the code useful, please drop me a line at dmac@cs.toronto.edu and tell us what
you are using it for. In addition, we would appreciate if you share with us any useful 
modification that you make to the code and that you think might be useful to other people. 
For example, bug fixes or adaptations to make the code compile under different systems 
are welcome. Of course, extensions to the current functionality and performance optimizations 
are more than welcome.

_______________________________________________________________________________________

1. THE DAG MATCHER LIBRARY AND THE SHAPE MATCHER APPLICATION

The current version of the "DAG matcher library" and
the "ShapeMatcher application" have been successfully compiled on FedoraCode 5 with gcc 4.1
and on Windows XP with Visual C++ Express and the Windows SDK (which are both free).

To build the project, you simply need to run "make" and all the dependent libraries
and source code will be compiled. Nevertheless, things aren't entirely
perfect so you must make sure that the following variables are set in the environment:

Path to the LEDA library (both Linux and Windows)

eg, in linux and cshell

    setenv LEDAROOT /pkgs/LEDA/LEDA-5.1-complete-FC4_i386-g++-4.0.2-std


NOTE: you can use old versions of LEDA (eg, 4.3 or 4.4). If you do, read dagmatcher/LEDA_issues.h

NOTE2: if you don't know what LEDA is, read Section 2 before continuing.

1.1. BUILDING THE CODE 

Before compiling, you must make sure that the variables ARCH={Linux, Windows} 
and MODE={Release,Debug} are set correctly. To do that, open the file common.mk and 
set their values. Then, simply run make at the level of the project's root directory. 
i.e.,

> make

As you can see, both Linux and Windows systems need to have "make" in their path. While 
this is the norm in Linux, it is not so in Windows, where you usually have "nmake" 
(which is also required to compile the project in Windows). 
Since chances are that you won't have make around in Windows, we included the package 
pkgs/UnxUpdates.zip that has it. You will need to unzip this package and set the PATH 
variable accordingly.

Final note: The files in the directory VC are use for debugging the code using Visual Studio. 
You do not need to do anything with those files unless you want to debug the code under Windows. 
If you need that, make sure that you first compile the code from the command line using 
"make MODE=Debug" (which, due to the bug described above, means to go and modify common.mk so 
that MODE=Debug).

_______________________________________________________________________________________

2. EXTERNAL LIBRARIES NEEDED TO COMPILE THE CODE

The only library that is not open source and consequently, that we
cannot distribute with the code is LEDA (Library for Efficient Data
Types). You will have to obtain it in order to compile the code. Find out more at:

  * LEDA documentation: http://www.algorithmic-solutions.com/

And on-line help for this library can be found at:

  * LEDA documentation: http://www.algorithmic-solutions.com/leda_guide/Index.html


There is a free version of LEDA for students and also a trial version. Both versions are free
but are hardcoded to work several times more slowly than the commercial version. They are about 
10 times slower (or more). If you use one of them, you'll notice that the indexing and matching
steps are considerably slower than running the binaries compiled with the commercial version.

The following libraries are included in the package you have
downloaded but you may still want to know where they come from:

  * Flux-based skeleton computation algorithm: Kaleem Siddiqi, 
    http://www.cim.mcgill.ca/~shape/shockgraph/shockgraph.tar.gz

  * A-star-Fast-Marching-Method-based skeleton computation algorithm: Alex Telea, 
    http://www.win.tue.nl/~alext/

  * Newmat Matrix library: http://ideas.uqam.ca/ideas/data/Softwares/codccplusnewmat.html

  * The SR-tree library: http://research.nii.ac.jp/~katayama/homepage/research/srtree/ 
  
  * CImg: http://cimg.sourceforge.net/
  
  * tools/connected.h: http://people.csail.mit.edu/rahimi/connected/


A very old version of the code's documentation is included within the code. You can buid 
a newer one in latex or html form using Doxigen. Ff you want to do that, you can get 
Doxigen from  

  * (NOT INCLUDED) Generator of documentation: http://www.stack.nl/~dimitri/doxygen/

The Doxigen configuration file for this project can be found under the /doc directory.


_______________________________________________________________________________________

3. FINDING HELP FOR THE SHAPE MATCHER (SM)

Run "./Bin/Release/sm -h" for help. Also, simply run "./Bin/Release/sm" to get a list of 
the command-line options and their default values.

_______________________________________________________________________________________

4. IMAGE TYPES

You can find example images to test the ShapeMatcher in the Images directory. The code
has been only tested with ppm and pgm images, but it "may" work with bmp, tif and jpg 
images too.

_______________________________________________________________________________________

5. HOW TO ADD YOUR OWN HIERARCHICAL STRUCTURE (ie, DAG) CLASS

Read /doc/how_to.pdf

If you want a very quick "how to" just read the EXAMPLE, which is the
last section in the document.


_______________________________________________________________________________________

6. THE DATABASE DESIGN

The NOT very up-to-date documentation for the DAG database design can be found at

/doc/db_design.pdf

_______________________________________________________________________________________
