
                             DAGMatcher Help


Contents
--------

1. Creating a Database of DAGs

2. Viewing the Database Contents

3. Matching DAGs

4. Need further help or have comments?

5. Clustering using NCuts and MATLAB

_______________________________________________________________________

1. Creating a Database of DAGs

  A database of DAGs (only shockgraphs so far) is created from a set of 
.ppm images. DAGMatcher will process all the images in a directory and 
will extract from the image file name and path the corresponding object 
name and view number.

The input directory is expected to be composed by one subdirectory per 
object model. Each of these directories must contain all the views of 
the object. E.g.

+ ImgDir
	+ Dolphin
		view001.ppm
		view002.ppm
		...
	+ Shark
		view001.ppm
		view002.ppm
		...

  As it can be seen in the example, the name of an object's view must 
be compose by a prefix and the view number. 

To create a database from all the images in /ImgDir, call: 

   dm -c objs.db /ImgDir

  Later, new images can be added by the 'add' command in a similar 
fashion. For example, to add all the views of a new object, call: 

   dm -a objs.db /ImgDir/Monkey

To add two new views to an object, type:

   dm -a objs.db /ImgDir/Shark/view020.ppm /ImgDir/Shark/view021.ppm
_______________________________________________________________________

2. Viewing the Database Contents

  A list of all the objects in the database can be obtained with the 
command line option '-l'.

 This list provides the object ID that is required as a parameter for 
the '-match' option and some other commands. For example, you can see 
and play around with a DAG by calling: 

   dm -v objs.db obj-id1 obj-id2 ...

  This command will open a window containing the requested DAG (one at 
a time). Right-click on one node, and select any of the several options 
that will be displayed. In particular, the 'add node' and 'delete node' 
options will update all the nodes' TSVs, and the set of new values will 
be shown in your xterm window.

  Once you are done, click 'Done' at the window's top right. A new 
window will be opened with the skeleton of the object (in this 
implementation, you'll see the skeleton repeated twice, for some 
technical reasons or laziness if you prefer.)
_______________________________________________________________________

3. Matching DAGs

DAGMatcher allows you to match a set of DAGs against a subset of the 
database. The matching results will display the DAGs of the query and 
the matched views along with their skeletons and matching lines between 
these skeletons (press any key when seen the skeleton window to display 
the matching lines.)

The simplest matching case is to compare one DAG with an entire 
database. E.g.

   dm -m 15 objs.db

where 15 is the DAG id in the database (use '-l' to look up id's). 
It is also possible to use all the models in a database as matching 
queries. E.g.

   dm -m fish.db animals.db

Optionally, a subset of the query database can be defined for matching.

   dm -m fish.db -from 500 -to 1200 animals.db
   
A similarity (MATLAB) matrix for all objects can be created by

   dm -matrix simmat.m models.db

this may be slow if the database is big, since indexing is not used. Options 
-to and -from can be used to fill in only a submatrix.

   dm -matrix simmat.m -from 15 -to 50 models.db
   
where the "missing" entries of the matrix are set to zero (see below for and
example for clustering based on the similarity matrix using NCuts for MATLAB).

3.1 Matching parameters

You can control a number of things in the matching process. For example, 
it is possible to avoid being ask about whether to display the results 
or not (-showResults 0). This is useful when computing large experiments. 
Other parameters are -saveResults, -stats, -matchTau, idxTau, etc.

3.1. Results

  The results for indexing and matching processes are saved in a file 
named resultsNNN.txt. Where NNN is a correlative number generated 
each time a matching is requested.

_______________________________________________________________________

4. Need further help or have comments?

Do not hesitate to email me at dmac@cs.toronto.edu

_______________________________________________________________________

5. Example for clustering based on the similarity matrix returned by dm,
   using NCuts (i.e., graph-theoretical min-cut algorithm) for MATLAB.
   
The MATLAB NCuts code can be downloaded from:

    http://www.cis.upenn.edu/~jshi/software/ 

	
Then, the matrix 'm' returned in the file 'simmat.m' by 

	dm -matrix simmat.m models.db
	
can be used directly for clustering in MATLAB.

In MATLAB, do

simmat;                  % to load matrix m
ncutClustering(m, 5);    % to find 5 clusters


The function ncutClustering() is an example that calls the appropriate 
function from the NCuts code to get a nice coloured figure.

function ncutClustering(W, nbCluster)

% clustering graph in
[NcutDiscrete,NcutEigenvectors,NcutEigenvalues] = ncutW(W,nbCluster);

% display clustering result
cluster_color = ['rgbmyc'];
figure(2);clf;
for j=1:nbCluster,
    id = find(NcutDiscrete(:,j));
	plot(1,id,[cluster_color(j),'s'], 'MarkerFaceColor',cluster_color(j),'MarkerSize',5); hold on;
end
hold off; axis ij;
disp('This is the clustering result');