MusicStaves Toolkit Documentation

Last modified: October 27, 2011


Editor:Christoph Dalitz and Thomas Karsten

Use the SourceForge project page for access to CVS, file releases, etc.


An important preprocessing step in Optical Music Recognition is the removal of staff lines. This toolkit provides methods for removing staff lines from a music image and for querying their positions afterwards.

Apart from the basic functionality, this toolkit also provides

User's Manual

This documentation is for those, who want to use the toolkit for finding and removing stafflines, but are not interested in implementing their own staff removal algorithms.

Developer's Manual

This documentation is for those, who want to implement their own staff removal algorithms for inclusion into this toolkit.


This toolkit has only been tested on Linux and MacOS X. We do not know whether and how this toolkit could be compiled and installed on Windows (although it should be possible in principle).

The following installation instructions should work for any Unix like operating system (MacOS X, Linux, Solaris, FreeBSD, ...).


First you will need a working installation of Gamera. See the Gamera website for details. It is strongly recommended that you use the CVS version rather than the latest stable release.

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.
  • pygments (version 0.6 or later) or SilverCity (version 0.9 or later) for colorizing source code.

Building and Installing

To build and install this toolkit, go to the base directory of the toolkit distribution and run the script as follows:

# 1) compile
python build

# 2) install
#    a) on MacOS X
sudo python install
#    b) on Linux
su root -c install

Command 1) compiles the toolkit from the sources and command 2) installs it into the Python library directory. As the latter requires root privilegue, you need to use sudo (vanilla MacOS X configuration) or su root -c (vanilla Linux configuration).

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 MusicStaves 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 MusicStaves toolkit into ~/python:

# install gamera locally
mkdir ~/python
python install --home=$HOME/python

# build and install the MusicSatves toolkit locally
export CFLAGS=-I$HOME/python/include/python2.3/gamera
python build
python install --home=$HOME/python

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

# search path for python modules
export PYTHONPATH=$HOME/python/lib/python

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


All files of this toolkit are installed into the gamera/toolkits/musicstaves 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 (with python 2.3):

  • MacOS X: /Library/Python/2.3/gamera/toolkits/musicstaves
  • Debian Linux: /usr/lib/python2.3/site-packages/gamera/toolkits/musicstaves