--------------------------------------------------------------------------
  Label Graph Tools v.0.2.1

  Copyright (c) 2012-2013, R. Zanibbi, H. Mouchere
  *Contact information is provided at the bottom of the file.
--------------------------------------------------------------------------

:: License :: 

	These tools are provided in the framework of the ICDAR 2013 CROHME
	competition 'as is' without any guarantee of suitability for non-research
	use.  No commercial use is permitted. The tools are being distributed under
	a Creative Commons license (please see the LICENSE file, and the directory
	cc_license contains a file detailing the specifics of the license).

:: Requirements ::

	Perl (with LibXML), python 2.6/2.7 and TXL (www.txl.ca) are required to run
	the tools included.  LgEval (distributed separately) is also required for
	some of the converter programs. Scripts are written in perl and 
	bash. GraphViz (in particular, 'dot') is needed for graph visualization.

----------------------------------
  INSTALLATION  
----------------------------------

Make sure that CROHMELibDir and LgEvalDir are defined in
your shell enviroment, e.g. by including:
	
	export LgEvalDir=<path_to_LgEval>
	export CROHMELibDir=<path_to_CROHMELib>       		
	export PATH=$PATH:$CROHMELibDir/bin:$LgEvalDir/bin
 
in your .bashrc file (the initialization file for bash shell). The PATH
alteration will add the tools to your search path. 

To avoid warnings about stack sizes from TXL, use the following (using sudo/
as super or root user) from the bash command line:

	ulimit -s 16384

this increases the maximum call stack size for the shell.

----------------------------
  Graph Files (CSV files)
----------------------------

Graphs are represented by lists of node ids, and edge pairs over node ids, with
which one or more labels may be associated. Examples may be found in the tests/
subdirectory.

----------------------------
  Scripts 
----------------------------

Scripts in bin/ are used to call the applications listed below
more conveniently. Call a script without arguments to obtain a description
and instructions on how to use the program.

evaluate
	Main evaluation script for label graphs. For CROHME 2013 this is set
	up to automatically produce metric files, differences, result summaries,
	and visualizations of recognition errors (requires GraphViz). Program
	produces evaluation results given a directory of output files and
	a corresponding directory of ground truth files.

lg2dot
	Create .dot and .pdf output for a label graph, or visualize the
	difference between two label graphs. Different graph types may be
	produced (requires GraphViz).

lg2mml
	Create MathML output from a label graph (requires CROHMELib)

lgfilter
	Removes non-tree edges from a label graph (e.g. to obtain symbol
	layout trees from fully-inherited DAG graphs for math notation)

lg2lgtree
	Converts a directory of label graphs using lgfilter (i.e. producing
	trees as output), writing the output files to another directory.

----------------------------
  Applications
----------------------------

All programs are written in Python (2.x compatible), aside 
from inkML2lg.pl (which is written in Perl). The following
files are located in the src/ directory.

python src/evallg.py

	Used to compute metrics for label graph files. Can
	be run over a pair of files, or in batch mode.
	Metrics are written to <infile>.m, and differences between
	pairs of graphs are written to <infile>.diff.
	
	NOTE: If a node is absent in one of the graphs, it will
	be inserted as 'ABSENT' in the other graph, with an edge
	labeled ('ABSENT',1.0) between the ABSENT node and every 
	other node in the graph. See Lg.matchAbsent() in the file 
	lg.py.

python src/metricDist.py

	Used to select a metric from a CSV file (.m) produced by the
	'evallg' program. Useful for producing histograms.

python src/sumMetric.py

	Takes a metric (.m) file produced by evallg, and presents
	some summary statistics for collected metrics.

python src/sumDiff.py

	Takes a difference (.diff) file produced by evallg, and presents
	confusion matrices for node labels and edge labels.
	Output is in CSV or HTML.

python src/lg2dot.py

	Convert a graph to .dot format (which can then be rendered
	using the 'dot' program from GraphViz). Differences between
	a pair of graphs may also be visualized for:
		- Bipartite label graph(s)
		- Segmentation graph(s)
		- DAG(s) represention of label graph
		- Tree-based representation of label graph (e.g. a 
		  symbol layout tree/SRT for a mathematical expression)

python src/lg2txt.py [also see translate directory]

	Convert a graph to a string encoding, e.g. LaTeX. A symbol and structure
	mapping may be defined in an accompanying .csv file, such
	as translate/symbolMap.csv. A MathML conversion (for CROHME 2013)
	is provided, in translate/mathMLMap.csv.

----------------------------
  Supporting Source Files
----------------------------
src/lg.py  
	defines the label graph class, along with key
	transformations and functions to collect comparison/evaluation
 	metrics. Also defines methods to print graphs and
 	write graphs to file.

src/lgio.py
	operations to output evaluation metrics.

--------------------------------
  Contact
--------------------------------

Harold Mouchère
harold.mouchere@univ-nantes.fr
University of Nantes, France

Richard Zanibbi
rlaz@cs.rit.edu
Rochester Institute of Technology, USA