Last modified: February 17, 2010
Editor: | Christoph Dalitz |
---|---|
Version: | 1.1.2 |
See the project home page for general information and file releases or the SourceForge project page for access to CVS.
The aim of the Psaltiki Recognition Toolkit is to recognize historic prints of contemporary psaltic notation, a neumatic notation system for Byzantine music developed in the 19th century in Constantinople.
This toolkit provides
It is based on and requires the Gamera framework for document analysis and recognition.
Optical Psaltiki Recognition means the extraction of a machine readable encoding from bitmap images of historic Psaltiki prints. This process typically consists of the following steps:
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, Copy border removal, Skew correction, Psaltiki toolkit Segmentation Gamera: CC analysis Classification Gamera: kNN classifier Semantic interpretation, music code output Psaltiki toolkit
The toolkit consists of Gamera plugin image functions and some end user applications.
The plugins are for preprocessing like image enhancement and are documented in the plugin reference.
The end user applications are
This documentation is for those, who want to use the toolkit for Psaltiki recognition, but are not interested in extending its capabilities beyond the adaption to specific neume symbols.
This documentation is for those who want to use the toolkit as a library for writing custom recognition scripts. Moreover it describes some common tweaks like the generation of a different output encoding.
Developer's manual: describes how to extend the toolkit
The following installation instructions describe how to install the toolkit from the sources, eg. from a curren cvs snapshot. They should work for any Unix like operating system (MacOS X, Linux, Solaris, FreeBSD, ...). On Windows they require that Mingw32 is installed. Alternatively you can use the binary installers from the project home page; these however are restricted to specific versions of Python and wxPython.
You will need a working installation of Gamera 3.x. See the Gamera website for details.
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) or pygments for colorizing source code.
Note
It is generally not necessary to generate the documentation because it is included in file releases of the toolkit.
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 # a) on MacOS X sudo python setup.py install # b) on Linux su root -c setup.py install
Command 1) compiles the toolkit from the sources and command 2) installs it. As the latter requires root privilegue, you need to use sudo (vanilla MacOS X configuration) or su root -c (vanilla Linux configuration).
On Windows you must run the following commands from the Msys shell prompt instead:
# 1) compile python setup.py build --compiler=mingw32 # 2) build an installer and run it python setup.py build --compiler=mingw32 bdist_wininst dist/psaltiki4gamera-X.X.X-win32.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
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.
Note
Before building the documentation you must install the toolkit. Otherwise gendoc.py will not find the plugin documentation.
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 Psaltiki toolkit into your home directory. Note however that this also requires that gamera is installed into your home directory. It is currently not possible to install gamera globally and only toolkits locally.
Here are the steps to install both gamera and the Psaltiki toolkit into ~/python:
# install gamera locally mkdir ~/python python setup.py install --prefix=~/python # build and install the Psaltiki toolkit locally export CFLAGS=-I~/python/include/python2.3/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
The installation uses the Python distutils, which do not support uninstallation on Linux or MacOS X. Thus you need to remove the installed files manually:
On Windows, you can use the uninstaller from "System Settings/Software".
All python library files of this toolkit are installed into the gamera/toolkits/psaltiki 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/psaltiki
- Debian Linux: /usr/lib/python2.3/site-packages/gamera/toolkits/psaltiki
The standalone scripts are installed into /usr/bin (linux) or /System/Library/Frameworks/Python.framework/Versions/2.3/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:
- psaltiki_recognize.py
This toolkit is a collaborative work of
- Christoph Dalitz (Hochschule Niederrhein, Krefeld, Germany)
- Georgios Michalakis (Association Stoudion, Poitiers, France)
- Christine Pranzas (Hochschule Niederrhein, Krefeld, Germany)