Instructions

Single- and Multi-Page Modes

Neon supports loading a single page of a manuscript or multiple pages, with different requirements for each. Single page mode associates an image file, typically a PNG, with a single MEI file corresponding to the page. Multi page mode instead associates multiple MEI files with multiple canvases present in a IIIF manifest.

These modes load automatically depending on what is provided to Neon. After Neon starts, there are minimal differences between these two modes. Neon gets the information it needs using a Neon Manifest. Typically this does not need to be manually generated.

Using Neon

Viewer Mode

Upon successfully loading, Neon is in viewer mode. Viewer mode displays the source image or images with rendered MEI above. The MEI cannot be modified in this mode, but various visualization tools are available.

To the left is a view panel, which will contain the source image(s) and any rendered MEI. In multi-page mode, the view panel is the diva.js viewer. To the right is a display panel.

View Panel

The view panel has interactive features in viewer mode.

• Info Box - Mousing over a neume, custos, or clef will open an info box below the display panel. This will provide the pitch of the element, if applicable, or the staff line it appears on.
  • For neumes, Neon will attempt to determine the shape of the neume via its contour.
  • For clefs, Neon will report whether it is a C or F clef.
• Panning - The user can move the image and rendered MEI in all four directions.
  • In single-page mode, holding the Shift key, clicking, and dragging will result in panning.
  • In multi-page mode, scrolling will result in panning. Note that holding shift and scrolling vertically will cause horizontal scrolling.
• Zooming - The user can zoom in or out on the contents of the view panel.
  • In single-page mode, this can be done by holding the Shift key and scrolling or by using the + and - keys. There is also a zoom slider in the display panel.
  • In multi-page mode, this can be done by double clicking on the contents to zoom in. Zooming out can be done by holding the Ctrl key and double clicking. There are also zoom in and zoom out buttons near the top left of the diva.js viewer.

Display Panel

The display panel consists of various tools and options to aid in visualization, as well as a report on the status of the MEI file of the active page. The active page is whatever page occupies most of the view panel in multi-page mode. In single-page mode, it is always the one page.

• Zoom Slider - The zoom slider allows the user to scale the image between 25% and 400% its original size. There is also a zoom button that resets the zoom to 100% and snaps the image to center.
  • The zoom slider is only present in single-page mode.
• Opacity Sliders - Two opacity sliders are present to control to opacity of the background image(s) and the rendered MEI file(s). Opacity ranges from 0% to 100% and the buttons reset opacity to 100% for their respective slider.
  • The "Glyph Opacity" button and slider control the opacity of the rendered MEI.
  • The "Image Opacity" button and slider control the opacity of the background image(s).
• Display Text - When checked, lyrics from the MEI file are rendered (if available). For more information, see information on lyrics.
• Display Text BBoxes - When checked, bounding boxes for text will be rendered in the view panel. For more information, see information on lyrics.
• Display Info - When checked, the Info Box is visible below any panels on the right side of the screen. Otherwise no mouseover info is displayed.
• Highlight - A dropdown menu allowing the user to highlight different musical elements in different colors. This is based on how elements are grouped in the MEI file. While looking pretty and helping distinguish the MEI from the background, it is also extremely useful for verifying that each element is logically part of the correct system, grouping, etc.
• MEI Validation - If the active page has an associated MEI file, xml.js is used to validate the loaded MEI file against the MEI 4.0.0 schema. If validation fails, clicking on "INVALID" will download a log of the errors found in the file.

Edit and Insert Modes

Edit mode can be entered from viewer mode by clicking the "Edit Mode" button in the upper left corner of the screen. This will result in a few immediate changes:

• Two new panels — the insert panel and the edit panel — appear below the display panel.
• The "Edit Mode" button is replaced by a "File" dropdown menu with various options.
  • See the File Menu Actions section for more information.

These layout changes will remain the same in both edit mode and insert mode. After leaving viewer mode, it cannot be re-entered without reloading Neon. All the features of viewer mode remain present.

Differentiating Edit and Insert Modes

The edit and insert panels let the user know what mode Neon is in after leaving viewer mode. In edit mode, the heading of the edit panel is tinted red and the text is bolded. In insert mode, the heading of the insert panel is tinted red and the text is bolded.

Insert Panel

The insert panel provides access to the various kinds of musical elements that can be inserted into the active page. Clicking on the image of one of these elements will cause Neon to enter insert mode. In insert mode, the selected insert element is inserted where the user clicks on the view panel. The musical elements that can be inserted are grouped into tabs:

• Primitive Elements
  • Allows insertion of neume components (punctum, virga, inclinatum), clefs (C, F), and custos.
  • The element is inserted centered around where the user clicks and snaps to the nearest pitch position of the system.
  • For clefs, the element is inserted to the nearest line where the user clicks.
• Groupings
  • Allows insertion of common grouped neumes.
  • The grouping is inserted with the first neume component centered on where the user clicks.
• System
  • Allows the insertion of a new system.
  • The system is inserted in-order (by left-to-right and top-to-bottom ordering).
  • This insert action requires two clicks: the first click selects the upper left corner of the new system, and the second click selects the lower right corner of the system.

Every type of insert action except system will not cause Neon to exit insert mode. In all cases, a user can leave insert mode and enter edit mode by:

• Pressing the Escape key on the keyboard;
• Clicking outside of the view panel and the insert panel; or
• Clicking on the "Return to Edit Mode" button below the edit panel.

Edit Panel

The edit panel contains buttons to control what to select by. Note that clefs and custos can be selected when selecting by syllable, neume, or neume component. For more information on selecting, see the selection section.

• Syllable - Select by the <syllable> tag in MEI.
• Neume - Select by the <neume> tag in MEI.
• Neume Component - Select by the <nc> tag in MEI.
• Staff - Select by the <staff> tag in MEI.
• BBox - Select by Text Bounding Box, tied to the <syl> tag in MEI.
  • Only visible when Display Text BBoxes is checked. See Text Viewing and Editing

Selecting Elements

Musical elements can be selected in one of four ways: syllable, neume, neume component, or staff. Selected elements are highlighted in red. Elements can only be selected in edit mode.

Whenever any selection is made, extra actions will appear below the edit panel. A "Delete" button will always appear, which deletes the selected elements. Other actions are made available if they are applicable given the selection made.

The user can select elements in two ways: by clicking or by dragging. Clicking directly on a glyph of an element that can be selected will naturally select it. To continue selecting multiple elements, a user can either hold the Ctrl key (on Windows or Linux) or the Command key (on Mac OS) and click on the other elements to select.

Dragging involves clicking on the background, holding, and moving the mouse to draw a box around the musical elements to select. If any part of an element is contained in the box it will be selected.

Context Options

Context options are made available below the edit panel when certain elements are selected. For information on making selections, see the edit panel and selecting elements. The options are specific to what the user is selecting by. In all cases, the selection can be deleted.

• Syllable
  • If one syllable is selected, the option is given to ungroup such that each neume in the syllable becomes its own syllable in the staff.
  • If two or more syllables on the same staff are selected, the option is given to merge the neumes in each syllable into an single syllable.
• Neume
  • If one neume is selected, the options to change the grouping and ungroup are given.
    • Changing the grouping means changing the contour and number of neume components in the neume to match the selected neume grouping.
    • Ungrouping the neume means to separate the neume components of the neume into separate neumes.
  • If two or more neumes in the same staff are selected, the option is given to group the neumes into a single syllable.
• Neume Component
  • If one neume component is selected, the option is given to change the head shape of the neume component to be either a punctum, inclinatum, or virga.
  • If two neume components are selected that are part of the same neume and the second neume component is of a lower pitch than the first, the option is given to toggle the components being a ligature.
  • If two or more neume components are selected that are part of the same syllable, the option is given to group the neume components into a single neume.
• Staff
  • If a single staff is selected, the option is given to split the staff into two staves and to resize the staff.
    • Clicking the "Split" button begins the process of splitting a staff. Then clicking on the staff where the staff should be split on the y-axis will cause the staff to become two staves where each new staff logically contains the elements on it.
    • The staff can be resized using the black box surrounding the staff. Clicking and dragging on any of the sides will cause the bounding box of the staff to change. The graphic will not be updated until the user releases the button.
  • If two staves are selected that are roughly in the same y-position, the option is given to merge the staves into a single staff containing all the elements previously in the separate staves.
• Clef
  • If a single clef is selected, the option is given to change the shape of it to be either a C clef or an F clef. The pitches of the neume components that follow will update automatically.

Note that there are no context options for a selected custos.

Grouping

Musical elements can be grouped and ungrouped as described in the section on context options based on MEI tag. The hierarchy of tags where grouping is applicable is:

Staff > Layer > Syllable > Neume > Neume Component

Elements can be grouped generally speaking if the following requirements are satisfied:

• The elements are of the same type (e.g. all the elements are neumes); and
• The parent element of the parent element of the elements is the same element (e.g. the elements are neumes and are in the same layer).

These requirements exist to ensure there are no assumptions made in Neon about how the user wants the resulting group to be. For example if two neume components in two different syllables were grouped, it would be ambiguous if the new neume should be part of the first syllable, the second syllable, or a new third syllable. If the neume components were part of the same syllable, as is required by Neon, this ambiguity is avoided.

Notifications

Notifications may sometimes appear in the upper left corner of the screen. They will give the user information on if the user is in insert mode or regular edit mode. It will also notify the user about the results of actions performed (see below). Notifications will disappear after 5 seconds or immediately if clicked by the user.

Text Viewing and Editing

You can view and edit the text and text bounding boxes in Neon. In MEI a <syllable> element can have a <syl> child, which can contain text and can have facsimile (coordinates) information. If an MEI file is loaded into Neon where some of the <syllable>s dont have <syl> children, verovio will populate the syllables with syl children without text. Similarly, if a <syl> element doesn't have facsimile information verovio will automatically generate a bounding box for the syl.

Text

By clicking Display Text in the display panel, a box in the bottom right will appear with the text from the current MEI page. If an empty <syl> element was generated for a syllable, its text is represented by the ◊ symbol. By mousing over the text, the syllable (and bounding box) associated with the text will be highlighted in the viewer.

While in edit mode, you can edit text by clicking on it. A box will appear to type in the new text value.

Bounding Boxes

By clicking Display Text BBoxes in the display panel, the bounding boxes for the text of each syllable will appear in the Neon viewer.

While displaying the bounding boxes and in edit mode, you can click the BBox button in the Edit Panel. The bounding boxes have many of the same editing features as the neumes and staves. These include:

• Clicking to select a bounding box. This will highlight it and any neume associated with it in red
• Clicking and dragging the bounding box to a new location. This works in exactly the same way as with neumes and staves
• Resizing the bounding box. This works in the same way as resizing staves: when you select a bounding box, a black rectangle will appear surrounding it. Click and drag the edges of this rectangle to resize the bounding box.
• Selecting multiple bounding boxes by clicking at some point in the background and dragging to draw a box around the bounding boxes to select. When selecting multiple bounding boxes you can move them but not resize them.

Bounding boxes and grouping/ungrouping

Grouping and ungrouping syllables affects their <syl> children (since a <syllable> can have at most one <syl> child) which means that it also affects their bounding boxes.

When grouping two syllables together their bounding boxes will be merged into one, which will be the smallest rectangle to comprise the full area of both of the original boxes. In other words, the grouped bounding box will comprise both of the originals and any space in between them.

When ungrouping a syllable into two new ones, a new bounding box with an arbitrary size and position will be created for the new syllable that is created.

"Inserting" bounding boxes

There is no way in Neon to actually insert a new bounding box in way that you insert neumes. This is because bounding boxes are really just the coordinate values of the MEI <syl> element, which can't exist without a <syllable> parent. Having a <syllable> without any neumes doesn't make any sense, so a bounding box needs to be associated to some neumes in order to exist. This also means that there's no way to change which neumes/syllable a bounding box is associated with.

Instead, you should use the dragging, resizing, and grouping functions. Here are some example use cases where you might want to insert or re-associate a bounding box:

• If a bounding box is associated with the wrong syllables, the bounding box should be moved and resized to the correct text.
• If a piece of text doesn't have a bounding box, find the bounding box that is associated with the neumes associated with that piece of text and drag/resize it to the correct position.
• If there are more actual syllables in the text than bounding boxes, then ungroup the appropriate syllable and drag/resize the newly created bounding box to the piece of text.

File Menu Actions

• Save - Save the changes made so far. This first attempts to update the MEI files from the server it fetched them from. If this fails, it will track the changes of the file locally. For more information, see the page on Neon manifests.
• Save and Export File - Saves the changes made so far and downloads a Neon manifest file reflecting all the changes made.
• Download MEI - Downloads the MEI file for the active page.
• Revert Revert to the originally uploaded file, discarding any changes. The page will automatically refresh.