Lute Tablature Recognition Toolkit for Gamera

Last modified: March 20, 2013


Editor:Christoph Dalitz and Thomas Karsten

Use the project home page for access to file releases of this toolkit.


The aim of the Lute Tablature Recognition Toolkit is to help building tablature recognition systems. Even though it can be used as is, it is not a closed box document recognition system, but a collection of modules fulfilling individual tasks of the recognition process. Thus it makes it easy to create recognition systems for a wide variety of tablature prints. The toolkits works both for staff based tablature types like French or Italian lute tablature, as well as for the staffless German lute tablature.

This toolkit provides

It is based on and requires the Gamera framework for document analysis and recognition.

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:

Includes image enhancement techniques (like smoothing or skew correction) and staff line removal, which is necessary for a proper symbol segmentation.
Separation of the individual tablature symbols.
Identification of the individual tablature symbols.
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


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

User's Manual

This documentation is for those, who want to use the toolkit for tablature recognition, but are not interested in extending its capabilities beyond the adaption to specific tablature symbols.

Developer's Manual

This documentation is for those who want to extend the functionality of the OTR toolkit. It is far from complete, but some common tweaks are documented, eg. the choice of a different staff removal algorithm or the generation of output encodings other than abc.


This toolkit has only been tested on Linux and MacOS X. The following installation instructions should work for any Unix like operating system (MacOS X, Linux, Solaris, FreeBSD, ...) and for MS Windows from the Msys shell that comes with Mingw32.


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.


It is generally not necessary to generate the documentation because it is included in file releases of the toolkit.

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 script as follows:

# 1) compile
python build

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

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

# 1) compile (Msys uses slashes as directory separator)
/c/Python25/python.exe 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 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 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.


Before building the documentation you must install the toolkit. Otherwise will not find the plugin documentation.

Installing without root privileges

The above installation with python 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 install --prefix=~/python

# build and install the OTR toolkit locally
export CFLAGS=-I~/python/include/python2.5/gamera
python build
python 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


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".

Python Library Files

All python library files of this toolkit are installed into the gamera/toolkits/otr subdirectory of the Python library folder. Thus it is sufficient to remove this directory for an uninstallation.

Where the python library folder is depends on your system and python version. Here are the folders that you need to remove on MacOS X and Debian Linux ("2.5" stands for the python version; replace it with your actual version):

  • MacOS X: /Library/Python/2.5/gamera/toolkits/otr
  • Debian Linux: /usr/lib/python2.5/site-packages/gamera/toolkits/otr

Standalone Scripts

The standalone scripts are installed into /usr/bin (linux) or /System/Library/Frameworks/Python.framework/Versions/2.5/bin (MacOS X), unless you have explicitly chosen a different location with the options --prefix or --home during installation.

For an uninstall, remove the following scripts: