How to use Pixel.js
This tutorial focuses on how to use Pixel.js in order to create ground truth.
For installation guidance, visit the Installation Guide.
For development guidance, visit the Developer's Guide or open an issue.
If you do decide to follow this tutorial, you must not skip any steps as each sub-section depends on the completion of the previous sub-section.
In this Tutorial, we will use 3 example PNG files that each contain either notes, staff lines, or text. We will upload them onto Pixel.js and we will correct a few mis-classified pixels on the manuscript Salzinnes, CDN-Hsmu M2149.L4. These 3 PNG files are the output of Calvo's machine learning pixel classification algorithm.
Make sure that when Diva.js is loaded, the Salzinnes manuscript is rendered on the page. The title should be displayed at the top center of the page.
Before continuing, be sure to download the three PNG files we will use: PNG Files.
To download them, click on each image name to navigate to the download page for each image.
Now, click on the download button.
Scroll through the Salzinnes manuscript until you see the page with the code QA L-3 R. It should be the 5th page. This is the page we will edit in this tutorial.
Now that you have chosen the page you wish to edit by navigating to it, click on the black square icon at the top of the chosen page in the manuscript in order to activate the Pixel.js plugin (see gif below).
Note that once activated, only the page on which you have activated the plugin will respond to the plugin functionalities. If you wish to edit another page in the manuscript, you must refresh the web page and start again.
A tutorial appears by default when activating the plugin. This pop-up tutorial serves as a reminder of tools that can be found in Pixel.js without taking you through the steps of correcting a specific page. In other words, the pop-up tutorial is not as complete. It is recommended for first-time users to follow the wiki Tutorial (this current one) in order to experience the recommended workflow.
Due to the size of different screens, it is possible that you have trouble scrolling down to the toolbox. If not already done, it is recommended that you turn on your scroll bars.
What causes this problem is the fact that when scrolling with your mouse inside the Diva.js viewport, it is the manuscript within Diva.js that will be scrolled. In order to scroll the web page itself, you need to position your mouse outside of the viewport or simply use the scroll bars themselves.
Notice how the mouse is positioned in the following .gif:
Each layer in Pixel.js represents a category, such as notes or staff lines. When images are uploaded onto a layer, all active pixels in the image will be converted into a single colour.
In this tutorial, we will upload 3 image files onto 3 separate layers.
The more layers there are, the more demanding Pixel.js becomes to the browser. Depending on your browser's speed, Pixel.js' performance may drop as more layers are created. For this reason, it is recommended to only create layers that are needed.
For the purpose of this tutorial, create 2 more layers for a total of 3 layers.
This can be done by pressing on the Create New Layer button or by pressing the keys ctrl + N.
Select the layer you would like to import the image into and press on Import Image. Navigate to the directory in which you have downloaded the 3 files from the pre-tutorial sub-section and select a file to import.
Repeat the same steps for the two remaining layers until all 3 files have been uploaded onto Pixel.js, each on a separate layer.
Note: the colours on your screen may be different from the colours in the .gif.
Once the images are uploaded onto their respective layer, you may want to rename the layers to reflect the category they now represent. In order to do so, double-click on a layer and type in the new layer name.
Press Enter or click outside the layers to save the layer name.
You may want the colours to be more opaque or the background to be less visible. To do so, click on the triangle found on the left of each layer in the toolbox in order to show the layer options. Once the opacity slider is displayed, you can click on the triangle again to hide it.
Once you find an opacity level that you are comfortable with, you are ready to start correcting the misclassified pixels.
Zooming
Use the zooming buttons at the top left above the viewport to zoom into the page. The greater the zoom, the greater the precision as details will be more easily seen. Diva.js currently limits zooming to 6 levels. For an even greater zoom, you may choose to use browser zoom. Press on ctrl/cmd + + to zoom in and ctrl/cmd + - to zoom out.
Grab Tool
Once you are zoomed in, press on G to select the grab tool (you can also choose to click on the grab tool in the toolbox). Now, you can click and drag anywhere on the manuscript to move around.
Find a spot on the manuscript that has a few misclassified pixels to start working. As you can see below, some notes have blue pixels while they are supposed to be on the red layer. The algorithm clearly made a mistake. To correct it, you would have to remove the misclassified pixels from the blue layer and add them to the red layer since only the red layer should contain pixels that represent notes/glyphs.
Note: the colours on your screen are most likely different. This is fine. You can still complete this tutorial.
The select tool (press S to select the select tool) allows you to re-classify pixels from one layer to another.
First, select the layer that contains the mis-classified pixels. In this case, the Text layer has pixels that need to be moved to the Glyphs layer. This situation means you should select the Text layer. Click on the layer to select it, or press on its hotkey, in this case, 1. The hotkeys can be found by hovering the mouse over the layer and waiting for a small message to appear.
Now, simply press the left mouse button anywhere on the manuscript and drag to create the rectangular selection area. Release the mouse button to finalize the selection. You want to select the area that contains the misclassified pixels.
You can now cut the pixels out of the selected area by pressing ctrl/cmd + X.
Now, select the layer you want to paste the pixels to. In this case, it is the Glyphs layer (hotkey: 2).
Press on ctrl/cmd + V to paste the pixels to the newly selected layer.
The results should look similar to this:
Three tools allow you to manually add or remove pixels from a layer.
In the toolbox, you can find the Brush tool and the Erase tool. These two tools allow you to free-form draw on the selected layer.
The third option is using the rectangle tool.
For a detailed description of how these tools work, consult the Tools Page.
5.3.1. Fix obvious mistakes
Use the rectangle tool's left and right mouse button presses to add and remove pixels to large regions containing missing or extra pixels.
5.3.2. Fill in detailed missing pixels
Use the brush tool to fill in missing pixels. Control the size of the brush that you want by holding down the right mouse button on the manuscript page and dragging right and left. The left mouse button paints.
5.3.3. Remove pixels in tricky areas
Use the erase tool with the brush tool to trace an accurate contour of tricky glyphs or text.
5.3.4. Straight lines
For painting straight lines and perfect squares, try pressing the shift key and using the rectangle, brush and erase tools. See what happens!
Click and drag on layers to drop them over other layers. The layers respect top-down priority.
The hotkeys to bring a selected layer up is ctrl/cmd + ].
To bring a selected layer down, use ctrl/cmd + [.
You can mute (press m to toggle on/off) or hide (hold h to turn off, release to turn on) layers if you only wish to see certain layers on the screen.
Once you are ready to save your work, you can select one of the three export options. For details on the difference between each export option, please consult this page: Export Options.
In this tutorial, we are only interested by the Export as PNG button.
You may want to continue working on your current project at a later time. To do so, you may export the layers of your choice to then re-import them into pixel and continue working.
Make sure you remember where the exported files are located!