Caltech Interface Tools: README
This is the README file for the Caltech Interface Tools (CIT), which is freeware that includes complete source code and training data for on-line hand-written character recognition, as well as other tools for constructing interfaces. The code is written in C++ and Tcl, and is intended primarily for Unix and Linux platforms. The latest version of the software will always be available at the caltech site.

This README file contains many links to the software, documentation, and other supporting files that are included with the distribution. All such links will work properly when this README file is located in the CIT directory that is created by unpacking the CIT tar file (see below). For convenience, this README file is included in the distribution, so a copy will be placed in the CIT directory for you when you unpack the tar file.

System Requirements
Building and running this software requires the following:

  • gzip, the Gnu file compression/decompression utility.

  • Gnu make (henceforth referred to as gmake).

  • A C++ compiler (such as g++, the Gnu C++ compiler).

  • Tcl/Tk version 8.0 or higher.
How to Build
The Makefile that is supplied should automatically build all the system components and tools. The variables defined in the file PlatformConfig may need to be modified for your system, but you should not need to modify the makefile itself. Here are the steps to follow to build the system:

  1. gzip -d CIT.tar.gz     decompress the distribution

  2. tar -xvf CIT.tar     unpack the tar file

  3. cd CIT     go to the newly-created directory

  4. Modify variables in PlatformConfig if necessary.

  5. gmake     start the build
If you encounter problems with the build, you will likely need to make additional changes to PlatformConfig.
How to Run
The makefile will place all executable programs in the CIT/bin directory, which also contails all the tcl files. To run the trivial test program called test_recognizer, type

   cd CIT
   bin/test_recognizer data

Consult the source code CIT/src/rec/test_recognizer.C to see how to write a C++ program that uses the recognizer.

To run the Train program, type

   bin/Train -d data -f fonts

Please see CIT/doc/Train.txt for instructions on the use of both Train and PostTrain. To list all the command line options for the programs, type

   bin/Train -h
   bin/PostTrain -h

To see the software versions and the versions of the training data that the programs expect, type

   bin/Train -v
   bin/PostTrain -v

Additional Documentation
In the CIT/doc directory you will find the following additional files:

  • Fonts.txt describes how typefaces are encoded. These typefaces are only useful in conjunction with morphing -- they have no connection whatsoever with the process of recognition.

  • Release.txt describes the changes that have been made to the software, and when the various releases were made.

  • Train.txt describes how to use Train and PostTrain to experiment with the recognizer, and to create personalized writing samples.
Important Source Files
Here are a few of the most important source files. If you want to understand how the code works, you should start with these:

  • include/rec/Recognizer.h defines the base class for all recognizers.

  • include/rec/Features.h defines the data structures for representing features associated with hand-drawn shapes.

  • include/rec/FeatureRecognizer.h defines a specific recognizer that works by representing hand-drawn shapes as points in a "feature space", and then performing nearest-neighbor searches.

  • include/util/Multiline.h defines a collection of 2d polylines; a polyline is a sequence of 2D points defining a connected chain of line segments. Multilines are used to encode the strokes drawn by the user as well as built-in stroke fonts. Multilines are the common currency among many of the modules.

  • bin/train.tcl is the main Tcl script, which defines the user-interface for the Train program. This, and all the other Tcl scripts, are used solely for creating and testing the training data. When you build a new interface using the recognizer, you will not need these.
Reporting Bugs
If you encounter any problems building or running this software, please send email to Jim Arvo (arvo@cs.caltech.edu). Comments, suggestions, and (above all) improvements to the code are most welcome. Every effort will be made to incorporate and distribute extensions and improvements contributed by others.
Copyright
This software is free; you may use it however you wish. To make the terms and conditions explicit, the following copyright notice has been included in all source files:
    "This program 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. See http://www.fsf.org/copyleft/gpl.html

    This program is distributed in the hope that it will be useful, but WITHOUT EXPRESS OR IMPLIED WARRANTY of merchantability or fitness for any particular purpose. See the GNU General Public License for more details."

If you modify and redistribute the software, we ask that you please retain this notice (or an equivalent one) in the modified source code so that others can continue to use it and modify it.
Contributors to this Software

  • Jim Arvo

  • Xavier Fan

  • Vladimir Fedorov

  • Yuanshan Guo

  • Kevin Novins

  • Steve Smithies

 
 
This file was last updated on August 31, 2000, by Jim Arvo.