Project Structure

An Audiveris project gathers all OMR information related to a given Book, including its contained Sheet instances.

This project can be stored to disk as a project file and reloaded later. The project file is merely the result of the XML marshalling of a book and its sheets, so there is no logical difference in the project structure in memory and on disk.

The internal project structure is specific to Audiveris software, but it is not opaque and is meant for public access, either via Audiveris API or by direct extraction of project XML fragments.

Project file

An Audiveris project file (a file with a ".omr" extension) is dedicated to one Book hierarchy.

It is nothing more than a Zip archive whose content can be easily browsed (and even modified -- at your own risk!...) via any Zip reader or editor.

For your information, here below is the result of unzipping this "Dichterliebe01.omr" example file into a dedicated folder.
(NOTA: This is for illustration purpose only. You never have to do this since Audiveris accesses a project file as a Zip system and thus performs compression/expansion transparently on-the-fly)

$ tree Dichterliebe01
Dichterliebe01
├── book.xml
├── sheet#1
│   ├── BINARY.png
│   └── sheet#1.xml
└── sheet#2
    ├── BINARY.png
    └── sheet#2.xml

As you can see, we have in this .omr archive example:

• A single book.xml file
• One sheet#N subfolder for each sheet in the book, which here contains:
  • A BINARY.png file
  • A sheet#N.xmlfile

Beyond this small example, here below are all the possible file kinds:

File Name	Content
book.xml	Skeleton of book hierarchy
sheet#N/	Specific folder for sheet #N
sheet#N/BINARY.png	Black and white image of sheet #N
sheet#N/GRAY.png	Gray image of sheet #N
sheet#N/HEAD_SPOTS.png	Head spots image for sheet #N
sheet#N/sheet#N.xml	OMR details for sheet #N

You may have noticed two files that did not appear in our small example, namely GRAY.png and HEAD_SPOTS.png:

• GRAY.png image is built from the sheet original input image (which may be a colored image, perhaps with an alpha channel) and results in pixel gray values.
  The BINARY step processes this gray image to produce the black and white BINARY.png image, which is needed by all subsequent steps. By default, the gray image is then discarded.
  One case where the GRAY.png image would still be useful is when the user would want to modify the image geometry, typically by rotating or de-warping -- features not yet provided as of this writing. In that case, quality would be better preserved when operating on gray rather than binary image.
• HEAD_SPOTS.png image is a temporary information carried over from BEAMS step to HEADS step. It takes advantage of the image processing performed during the BEAMS step to provide the image areas (spots) where black heads are likely to be recognized.
  This image is discarded at the end of HEADS step.

Memory constraint

To be able to handle books with more than a few sheets, Audiveris keeps book top data in memory, while sheet "details" are loaded only when they are really needed.

In terms of project file, this means that the book.xml part is kept in memory until the book is closed, while the various sheet#N/BINARY.png and sheet#N/sheet#N.xml are loaded on demand.

So, the physical and logical containments are implemented as follows: (see Containers section)

• A Book does not directly contain Sheet instances but only a sequence of SheetStub instances (or Stub for short) with a one-to-one relationship between SheetStub and Sheet.
• In a similar manner, a Score actually contains PageRef instances which refer to Page instances.

In the following class diagram, physical entities are displayed in blue, and logical entities in yellow.

On the left side, the book.xml artifact represents the content of the book.xml part within an Audiveris project file, and is kept in memory. Note that the Score and PageRef instances can exist only when GRID step has been reached on (some sheets of) the book.

On the right side, the sheet#N.xml artifact represents one sheet (perhaps among others), pointed to from book.xml, and is not necessarily in memory.
[NOTA: Just to avoid endless clashes with Java predefined System class, we have chosen SystemInfo as the class name to represent a music system]