The Recognition Process

Optical tablature recognition (OTR) means the extraction of a machine readable tablature encoding from bitmap images of historic lute tablature prints. This process typically consists of the following steps:

Preprocessing:

Includes image enhancement techniques (like smoothing or skew correction) and staff line removal, which is necessary for a proper symbol segmentation.

Segmentation:

Separation of the individual tablature symbols.

Classification:

Identification of the individual tablature symbols.

Postprocessing:

Although the classification step yields the symbol type, this information needs further semantic interpretation, because the musical meaning depends on the local position of a symbol on the score and its neighbouring smybols. The resulting musical meaning is encoded in some way and given out as the result of the recognition process.

Some methods for these steps are supplied in this toolkit, some are already part of the core gamera distribution as shown in the following table:

Recognition step	Provided by
Smoothing, Picture removal	OTR toolkit
Skew correction, Staff line removal	OTR toolkit (uses the MusicStaves toolkit)
Segmentation	Gamera: CC analysis
Classification	Gamera: kNN classifier
Semantic interpretation, music code output	OTR toolkit

Provided Components

The toolkit consists of two python modules, some plugin image functions and some end user applications.

The modules are

• otr_staff for staff detection and removal. Basically this is a wrapper around the MusicStaves toolkit. See the developer's manual for details how to choose a particular staff removal algorithm.
• german_page for page layout analysis of German lute tablature
• otr_glyph for tablature symbol interpretation of French and Italian lute tablature
• german_glyph for tablature symbol interpretation of German lute tablature

The plugins are for preprocessing image enhancement and are documented in the plugin reference.

The end user applications are

• a GUI for starting an interactive training session for tablature symbols
• otr_recognize and otr_german_recognize for automatic recognition of a tablature image
• otr_prepare for only doing selected preprocessing steps on a tablature image

Limitations

Due to the basic concept of isolated symbol classification, this toolkit yields reasonable results only for tablature prints with movable types, but not for engraved prints or manuscripts.

The following additional restrictions limit its use further:

• symbols spanning more than one chord (eg. slurs) are not supported
• grid style flags are currently only supported for German lute tablature, but not for Frecnh and Italian tablature

Prerequisites

First you will need a working installation of Gamera 3.x. See the Gamera website for details. It is strongly recommended that you use a recent version, preferably from SVN.

Second you will need a working installation of the Gamera MusicStaves toolkit. Download the latest file release from its website and follow the installation instructions in its documentation.

If you want to generate the documentation, you will need two additional third-party Python libraries:

• docutils (version 0.3 or later) for handling reStructuredText documents.
• SilverCity (version 0.9 or later) for colorizing source code.

Building and Installing

To build and install this toolkit on Linux or MacOS X, go to the base directory of the toolkit distribution and run the setup.py script as follows:

# 1) compile
python setup.py build

# 2) install (requires root privilegue => sudo)
sudo python setup.py install

To do the same on MS Windows, open an Msys shell, go to the base directory of the toolkit distribution and run the setup.py script as follows:

# 1) compile (Msys uses slashes as directory separator)
/c/Python25/python.exe setup.py build --compiler=mingw32 bdist_wininst

# 2) install ('*' depends on the toolkit and python version)
start dist/otr-*.exe

Note that the standalone scripts are installed into /usr/bin on Linux, but into /System/Library/Frameworks/Python.framework/Versions/2.3/bin on MacOS X. As the latter directory is not in the standard search path, you could either add it to your search path, or install the scripts additionally into /usr/bin on MacOS X with:

# install scripts into standard path (MacOS X only)
sudo python setup.py install_scripts -d /usr/bin

On MS Windows, the scripts are installed into C:\Python2.5\Scripts. To make the scripts startable form the DOS os Msys shell, you should add this directory to your search path.

To regenerate the documentation, go to the doc directory and run the gendoc.py script. The output will be placed in the doc/html/ directory. The contents of this directory can be placed on a webserver for convenient viewing.

Installing without root privileges

The above installation with python setup.py install will install the toolkit system wide and thus requires root privileges. If you do not have root access (Linux) or are no sudoer (MacOS X), you can install the OTR toolkit into your home directory. Note however that this also requires that gamera is installed into your home directory. It is currently not possibole to install gamera globally and only toolkits locally.

Here are the steps to install both gamera and the OTR toolkit into ~/python:

# install gamera locally
mkdir ~/python
python setup.py install --prefix=~/python

# build and install the OTR toolkit locally
export CFLAGS=-I~/python/include/python2.5/gamera
python setup.py build
python setup.py install --prefix=~/python

Moreover you should set the following environment variables in your ~/.profile:

# search path for python modules
export PYTHONPATH=~/python/lib/python

# search path for executables (eg. gamera_gui)
export PATH=~/python/bin:$PATH

Uninstallation

The installation uses the Python distutils, which do not support uninstallation on Linux and MacOS X. Thus you need to remove the installed files manually:

• the installed Python library files of the toolkit
• the installed standalone scripts

On MS Windows, you can use the uninstaller from "System Settings/Software".