Minimal User Manual

Needed environment

Besides the executable file (either omr-gui.exe or omr-cli.exe), OptiMusic needs two environment files, that are searched for in the same directory as the executable files :

omr.ini : This is the application definition file, organized by sections. To ease the mapping, the section name is the name of the related Ada package. The only section you really need to edit is the [Omr.Ops] section which defines two keywords 'Sharpeye' and 'Sequencer' that you must set respectively to the full paths of the SharpEye and sequencer programs if you want to be able to launch them from within OptiMusic.
history.dat : This is a binary file that records the shapes learned so far by Optimusic. The file is opaque, you can read or update it only through the OptiMusic program.

GUI Interface

You launch the gui interface by :

omr-gui [bitmap.bmp]

Main menu

File	Classical actions for opening a bitmap file, and exiting the application. The most recent files can be selected directly here.
View	The display zoom can be selected from 1/8 to 8 times the original bitmap size. Other options allow to fit the zoom ratio according to the current window size so that either the full width, or the full height or the full page is entirely visible.
Step	This is simply the sequential list of all processing steps. It's always possible to go back to a previous step (provided that this step is not temporarily disabled).
Output	Three kinds of file output are available : The SharpEye format, to generate the '.mro' file and potentially launch SharpEye program on it (that's a way to get a NIFF output). An XML format, to generate the '.xml' file and potentially launch the simple ScoreTree java program on it. This output is still in works, even the DTD is still evolving. Use it at your own risks! The MIDI format, to generate the '.mid' file and potentially launch a MIDI sequencer on it.
Tool	This is a set of miscellaneous actions, meant for developer's use rather than basic user's use : Reload the 'omr.ini' file. Right after a manual modification of the file with a text editor, this allows its reloading so as to use immediately the new values without restarting OptiMusic. Set Colors. Similarly, the various shape colors are defined in the omr.ini file, and can be immediately taken into account. The display can switch between displaying the various LAG sections or the various item meanings (the default). The current content of the sheet picture can be dumped to the standard output with a variable level of details. The resulting score can be written to the standard output, in SharpEye format. The meaning of alll items can be reset to unknown, so as to allow a new recognition action. Checks can be manually loaded, dumped and stored (note that they are automatically loaded when triggered by the evaluation steps. The item menu is just a way to force these actions, for example to force a re-loading of original shape definitions). Please refer to the section dedicated to the management of check definitions later in this file.
Help	This is today limited to an 'about' box.

Selections

Selection can be made using different methods :

Defining a rubber-band box with the left button of the mouse together with a shift key defines a bitmap region whose display is then zoomed to a maximum size, limited only by the current window size. The focus is kept on the center of the bitmap region. This is the preferred way to zoom in on any specific part of the sheet picture.
Defining a rubber-band box with the left button of the mouse together with a control key selects all the items that lie entirely within the defined region.
Defining a rubber-band box with the right button of the mouse achieves the same goal : it selects all the items that lie entirely within the defined region.
Clicking on an item with the right button of the mouse selects that item.
Clicking outside an item with the right button of the mouse selects the underlying measure, provided that the processing steps have reached at least the stave and measure identification (i.e. the "Score Bar step" or later).

Note : if a whole glyph (with all its stems and leaves) is located within the rubber-band box, the glyph as a whole is selected. If several items are located in the box, then a brand new compound, which contains those items, is built on-the-fly. In other words, to specifically select a given leaf, point that leaf with the right button, and conversely if you want to designate the whole glyph, use the rubber-band approach, but make sure that you are not including parts of others glyphs at the same time.

Popup Menus

Popup menus are linked to contextual actions, and the menu activated depends on the current selection :

Selection	Possible Actions
Bitmap Region	Zoom definition (no menu)
Item	- Dump the item - Dump the item signature (the n-dimension vector used in shape recognition) - Colorize the item lag or colorize the item meaning - Assign a shape to the item (and thus train the program) If you have assigned "Super" privileges to yourself using the application 'omr.ini' file, then you can access the additional actions, that run a single action on a given (selected) item. Remember, these additional actions are meant for the software developer, rather than for an end-user, so be careful ... : - Chop the glyph - Detect item ledgers - Evaluate the item for shape recognition - Look around the item for a suitable aggregation - Try to segment a bar (or a flag) in the item
Compound	- Dump the compound - Assign a shape to the compound (and thus train the program)
Measure	- Dump the measure as a score part, using SharpEye format to the standard output - Assign an instrument (aka Midi program) to the containing stave (Acoustic Grand Piano, Nylon Guitar, etc...)

MIDI Playing

This activity is trigged from the upper right panel, using the Play / Stop button. You can even go directly use the Play button, it will first check and launch if necessary the preliminary recognition steps, before actually beginning to play the recognized music.

The tempo can be adjusted using the scroll-bar.

Finally, you can decide to use a kind of "Stereo effect", where the various staves of a system are dispatched spatially, the top stave on the right-most side and the bottom stave on the left-most side. This helps differentiate between the various channels, for example left and right hand for a piano score.

Checks Definition

If we except a few hard-coded plugin functions (see file sheet.checks.plugins) all shapes can be interactively and gradually learned by OptiMusic. The current reference is held by the companion file named history.dat. A version of this data is provided in the archive to let you run OptiMusic right out of the box on a sheet image of your own. Note that you can update this reference by removing and/or adding new definitions. You can also completely discard the provided data (just delete the history.dat file) and build your own progressively, I did this several times. Here is how the reference data is used :

The history data contains one section for each bitmap file on which a data accumulation has been explicitly asked for. You can get a readable dump of the current data by using the 'Dump Check History' in the Tools menu. Each section provides for each of the encountered shapes in the related bitmap file :

The related population, i.e. the number of items of this shape in the given bitmap file,
The resulting mask, built with the min and max values of each dimension (weight, height, width, ...) of the shape,
The resulting grid, built as the average of the grids of the given shape population.

The reference model, as used by the recognition process, is obtained simply by 'adding' the data across the various bitmap files, in just the same way a bitmap data is obtained by 'adding' the data across the various items encountered in this bitmap with the same shape. By default, the reference model is first built dynamically, by reading the content of history.dat.

Then, there are two ways to update the reference data :

One is to manually assign a shape to a given selected item. Doing so modifies both the shape mask (if the newly assigned item shape does not fit entirely within the existing mask) and the shape grid (remember that the grid is the average value of all items for this shape, so we are adding one element to the existing population). This impact on reference data is usable immediately in the current OptiMusic session, but is not saved on disk. To save such modifications, you have to work at the file level, as described in the next bullet.
Another way is to handle the bitmap file as a whole using the Tools menu. This time, the granularity is no longer at the element level but at the bitmap file level as a whole. You can 'add' (accumulate the data from) a bitmap file, using the 'Cumulate Data' item, and you can remove a bitmap file, using the 'Purge Check History' item. My advice is to ask for data accumulation only when you are confident with the items recognized so far in the current bitmap, otherwise you will corrupt the reference data definitions. If such a corruption happens however, you can always modify manually the wrong meaning assignments in the bitmap and ask for data accumulation when you are done. Don't forget to save your updated data (you'll be reminded if you exit OptiMusic before explicitly storing the updated data using the 'Store Checks' item).

At any time, a readable dump of the current reference model can be obtained by using the 'Dump Check Model' in the Tools menu.

A last point : we don't keep track of the original bitmap file from which the data was accumulated. We keep only a digest of the bitmap (using the classical MD5 algorithm) and thus we are always able to recognize a bitmap, even when accessed through different file paths! Thus there is no problem when repeatedly accumulating data from the same bitmap file, since the data related to this bitmap is simply retrieved and overwritten.

CLI interface

If you are interested only in the recognition engine, you can simply use the command-line interface with the following syntax :

omr-cli bitmap.bmp [step]

The first parameter is the name of the bitmap file.

The second (and optional) parameter is the name of the target step. This step can be any of the following names (the character cases are not relevant) and designates the same steps as described in the GUI interface :

Load, Frame, Glyph, Symbol, Chop, Ledger, Eval, Segment_Flag, Segment_Bar,
Bar, Translate, Annotate, Consistency,
Layout, Sharpeye, XML, Scoretree, Midi, Sequencer.

If no step name is provided, the 'Midi' step is assumed, so a MIDI file is written.

File updated on Friday 29-Dec-2000 16:56