README.md

MuSAK Annotations

This package provides a tool for analysing the annotations produced by the MuSAK system.

Installation

1. Ensure GHC and cabal-install are installed. Either install the Haskell Platform, or for Debian and deriatives, try:

    $ sudo apt-get install ghc cabal-install
   

2. Ensure that libGD is installed, including the include files. On Debian and derivatives, try:

    $ sudo apt-get install libgd-dev
   

3. Clone the repository:

    $ git clone [email protected]:transforming-musicology/musak-shapes.git
   

4. Create a Cabal sandbox and install the dependencies in it:

    $ cd musak-shapes
    $ cabal sandbox init
    $ cabal configure --enable-tests
    $ cabal install --only-dependencies
   

5. Build:

    $ cabal build
    $ cabal test
   

Usage

The tools provided in this package are intended to be used with the annotation data generated by the MuSAK system. Some data from this system is available to T-Mus project members from the Hearing Wagner experiment.

1. Ensure git-annex is installed.

2. Retrieve the Hearing Wagner data repository:

    $ git clone ssh://[email protected]/~/data/hw-data.git
   

3. Retrieve some annotations and page images:

    $ cd hw-data
    $ git annex get Rh/annotations Rh/score
   

4. To dump all the segmented shapes from every page:

    $ cabal run musak-annotations -- dump-shapes -a "/path/to/hw-data/Rh/annotations/*.csv"
   

   If you use globs or multiple file names for the argument, you need to quote them.

5. To draw the shapes on the score pages:

    $ cabal run musak-annotations -- overlay-shapes -a "/path/to/hw-data/Rh/annotations/*.csv" -s "/path/to/hw-data/Rh/score/*.jpg"
   

   If you use globs or multiple file names for the arguments, you need to quote them.

   However, this command pairs up the list of files in its two arguments and draws the shapes from a page onto the corresponding score image. The existing filenames in the score pages are fine because their lexicographic ordering is sensible. However the annotation CSV files have un-padded numerical components in their file names. You could fix this by adding some symlinks with sensible names, e.g.:

    $ cabal update
    $ cabal install unix-compat
    $ cd /path/to/hw-data/Rh/annotations/
    $ ghci
    λ: :m Text.Printf
    λ: :m + System.PosixCompat.Files
    λ: sequence_ $ map (\n -> createSymbolicLink ("Rhpage" ++ (show (n+1)) ++ ".csv") ("Rh-" ++ (printf "%04d" n) ++ ".csv")) [1..252]
   

   And then execute musak-annotations overlay-shapes with suitable globs:

    $ cabal run musak-annotations -- overlay-shapes -a "/path/to/hw-data/Rh/annotations/Rh-*.csv" -s "/path/to/hw-data/Rh/score/Rh-*.jpg"
   

The example commands above using cabal to call the executable. Once built, you can copy the executable from dist/build/musak-annotations/musak-annotations to somewhere on your PATH for more convenient (and faster, by avoiding the cabal start up and build check) usage. If you're calling the executable directly, you don't need the bare -- before the command. There is also a cabal install command which would put the executable (and Haskell library) in some default location in your home directory. However, there's no corresponding "uninstall".

Future

The next phase of this software will be to implement some shape distance measures and then cluster the shapes by similarity.

License

Copyright (C) 2015, 2016 Richard Lewis

Author: [email protected]

musak-annotations 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, either version 3 of the License, or (at your option) any later version.

musak-annotations is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with musak-annotations. If not, see http://www.gnu.org/licenses/.