Annotations

This file accompanies the page image file to provide relevant annotations, notably information about the page itself and its contained symbols.

Formatted content

We use a specific XML format as described below.

Element names begin with an uppercase letter and use camel-shaped names,
attribute names are all lowercase, with dash separator if needed.

Annotations element is the root element.

• version attribute provides a "major.minor" value, meant to cope with format evolutions.

• complete attribute is an optional boolean to indicate if all valid symbols are described in the Annotations structure. This impacts the potential generation of "none" symbols in the empty areas, because if complete is absent or false, no "none" symbol can be generated (the so-called empty areas are not safe).

• Source element provides information about how the annotations were built. Right now, it is a free text element, for example: "Musescore 2.06".

• Page element gathers global page information:

  • Image sub-element is a reference to the related image file. It is formatted as a URL, either relative (which can be as basic as a simple file name) or absolute (to allow access to some remote location).
    Remark: if ever we need to specify a specific page number in a multi-page image file, we could add a number attribute within the Image element, as an integer value starting at 1.
  • Size sub-element defines the page dimension in pixels (using integer values).
    • w attribute for page width,
    • h attribute for page height.

• Symbol element exists for each symbol contained in the page:

  • interline attribute provides the interline float value of the related staff (this is the vertical distance in pixels between two staff lines, from center to center). Interline value is mandatory to normalize the symbol.
  • id is an optional integer attribute that uniquely identifies the symbol instance in the containing page (it allows to refer back to the symbol, typically to debug classifier training).
  • shape attribute provides the name of the symbol shape, like "noteheadBlack" or "accidentalNatural". The list of possible names is defined by OmrShape Java class.
  • scale is an optional float attribute to provide a scaling value (generally significantly smaller than 1). This allows to specify that the symbol at hand has a size significantly different (smaller) than one would expect solely from shape and interline informations. For certain shape families (clef, head, flag) this scale attribute can be used to indicate a "small" variant of the shape.
  • Bounds sub-element provides the symbol bounding box, a rectangle defined with respect to origin chosen at page top-left corner point. Bounds attributes are specified as float values to allow a precise symbol re-scaling to any predefined interline value.
    • x attribute for symbol top left abscissa,
    • y attribute for symbol top left ordinate,
    • w attribute for symbol width,
    • h attribute for symbol height.

  Note on float values: all float values (interline, scale, bounds) are defined with a maximum of 3 digits after the dot.

  Symbol nesting: a Symbol element can contain nested Symbol elements, to indicate a nesting relationship. For example a repeatRight symbol is composed of 4 nested symbols: 2 repeatDot symbols + 1 barlineSingle symbol + 1 barlineHeavy symbol. Such information could thus appear as the following fragment:

   <Symbol interline="14" shape="repeatRight">
        <Bounds x="1705" y="2758" w="30" h="62"/>
        <Symbol interline="14" shape="repeatDot">
            <Bounds x="1705" y="2778" w="7" h="8"/>
        </Symbol>
        <Symbol interline="14" shape="repeatDot">
            <Bounds x="1706" y="2794" w="7" h="7"/>
        </Symbol>
        <Symbol interline="14" shape="barlineSingle">
            <Bounds x="1719" y="2758" w="3" h="62"/>
        </Symbol>
        <Symbol interline="14" shape="barlineHeavy">
            <Bounds x="1725" y="2758" w="10" h="62"/>
        </Symbol>
    </Symbol>

Shape names

Java class OmrShape defines the enumeration list of all currently supported shape names. The list is based on a subset of SMuFL specifications. We took the precise symbol names used by SMuFL, with a few additions (e.g. for key signature items).

For the time being, OmrShape refers only to so-called "fixed-shape symbols", that is symbols that don't vary in size, once normalized by a predefined interline value. This excludes the "varying-shape" symbols, such as: beams, slurs, endings, brackets, barline connectors, etc, (although we included brace symbol).

For example, a barline symbol, vertically defined by one staff limits, is a fixed-shape symbol and is, by the way, already part of OmrShape. However, a "barline connector", which is the portion going from the bottom line of a staff to the top line of the next staff below, and which often appears in multi-staff systems, is a varying-shape symbol.

NOTA: Annotations file is allowed to contain symbols with a name not referred by OmrShape. Such symbols will simply be ignored by the programs (such as classifier training) which work only on fixed-shape symbols, but may be duly processed by other programs (perhaps interested by such symbols as full key signatures, slurs, etc).

It is thus important that OMR Dataset, as a reference, remain as open as possible to future uses. We just ask that the SMuFL name be used if it already exists.

Example excerpt

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Annotations version="1.0">
    <Source>MuseScore 2.06</Source>
    <Page>
        <Image>mops-1.png</Image>
        <Size w="1191" h="1683"/>
    </Page>
    <Symbol interline="10" shape="accidentalSharp">
        <Bounds x="264" y="227" w="11" h="30"/>
    </Symbol>
    <Symbol interline="10" shape="accidentalFlat">
        <Bounds x="227" y="213" w="9" h="25"/>
    </Symbol>
    <Symbol interline="10" shape="accidentalNatural">
        <Bounds x="199" y="216" w="7" h="31"/>
    </Symbol>
    <Symbol interline="10" shape="stem">
        <Bounds x="901" y="243" w="1" h="57"/>
    </Symbol>
    <Symbol interline="10" shape="stem">
        <Bounds x="845" y="243" w="1" h="32"/>
    </Symbol>
        ...
        ...
        ...
    <Symbol interline="10" shape="keySharp">
        <Bounds x="94" y="412" w="11" h="30"/>
    </Symbol>
    <Symbol interline="10" shape="keySharp">
        <Bounds x="104" y="426" w="11" h="30"/>
    </Symbol>
    <Symbol interline="10" shape="keySharp">
        <Bounds x="688" y="222" w="11" h="30"/>
    </Symbol>
    <Symbol interline="10" shape="keySharp">
        <Bounds x="698" y="237" w="11" h="30"/>
    </Symbol>
        ...
        ...
        ...
    <Symbol interline="10" shape="articTenutoBelow">
        <Bounds x="376" y="271" w="12" h="2"/>
    </Symbol>
    <Symbol interline="10" shape="articStaccatissimoAbove">
        <Bounds x="282" y="216" w="4" h="11"/>
    </Symbol>
        ...
        ...
        ...
    <Symbol interline="10" shape="flag8thUp">
        <Bounds x="342" y="223" w="10" h="30"/>
    </Symbol>
    <Symbol interline="10" shape="flag8thDown">
        <Bounds x="209" y="238" w="12" h="29"/>
    </Symbol>
    <Symbol interline="10" shape="augmentationDot">
        <Bounds x="862" y="239" w="5" h="5"/>
    </Symbol>
    <Symbol interline="10" shape="augmentationDot">
        <Bounds x="178" y="239" w="5" h="5"/>
    </Symbol>
</Annotations>