diff --git a/docs/_config.yml b/docs/_config.yml
index a27763e5a..0b3b90871 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -79,7 +79,7 @@ back_to_top: true
back_to_top_text: "Back to top"
# Footer content appears at the bottom of every page's main content
-footer_content: "Copyright © Audiveris 2023. Distributed under Affero General Public License."
+footer_content: "Copyright © Audiveris 2024. Distributed under Affero General Public License."
# Color scheme currently only supports "dark" or nil (default)
color_scheme: nil
@@ -138,45 +138,61 @@ java_version: 17
tesseract_version: 5.3.1
# File menu paths
-file_input: File → Input
+file_input: File → Input
# Book menu paths
-book_split: Book → Split and merge
-book_parameters: Book → Set book parameters
-book_transcribe: Book → Transcribe book
-book_swap: Book → Swap book sheets
-book_select: Book → Select sheets
-book_export: Book → Export book
-book_stop: Book → Stop book transcription
-book_save: Book → Save book
-book_close: Book → Close book
+book_split: Book → Split and merge
+book_parameters: Book → Set book parameters
+book_transcribe: Book → Transcribe book
+book_swap: Book → Swap book sheets
+book_select: Book → Select sheets
+book_export: Book → Export book
+book_stop: Book → Stop book transcription
+book_save: Book → Save book
+book_close: Book → Close book
# Sheet menu paths
-sheet_repetitive: Sheet → Toggle repetitive input
-sheet_transcribe: Sheet → Transcribe sheet
-sheet_status: Sheet → Current status
-sheet_scaling: Sheet → Set scaling data
-sheet_scale_plots: Sheet → Display scale plots
-sheet_binary: Sheet → Display binary
+sheet_repetitive: Sheet → Toggle repetitive input
+sheet_transcribe: Sheet → Transcribe sheet
+sheet_status: Sheet → Current status
+sheet_scaling: Sheet → Set scaling data
+sheet_scale_plots: Sheet → Display scale plots
+sheet_staves_plots: Sheet → Display staves plots
+sheet_stem_plot: Sheet → Display stem plot
+sheet_binary: Sheet → Display binary
+sheet_nostaff: Sheet → Display no-staff
# View menu paths
-view_jumbos: View → Show jumbo inters
-view_voices: View → Show score voices
-view_errors: View → Show score errors
-view_selections: View → Switch selections
-view_layers: View → Switch layers
-view_slots: View → Show score slots
-view_annotations: View → Show annotations
-view_chords: View → Show chord IDs
-view_parts: View → Show part names
+view_jumbos: View → Show jumbo inters
+view_voices: View → Show score voices
+view_errors: View → Show score errors
+view_selections: View → Switch selections
+view_layers: View → Switch layers
+view_slots: View → Show score slots
+view_annotations: View → Show annotations
+view_chords: View → Show chord IDs
+view_parts: View → Show part names
# Tools menu paths
-tools_train: Tools → Train classifier
-tools_memory: Tools → Memory
-tools_options: Tools → Options
-tools_advanced: Tools → Advanced topics
+tools_train: Tools → Train classifier
+tools_memory: Tools → Memory
+tools_options: Tools → Options
+tools_advanced: Tools → Advanced topics
# Help menu paths
-help_handbook: Help → Handbook
-help_updates: Help → Check for updates
-help_about: Help → About
+help_handbook: Help → Handbook
+help_updates: Help → Check for updates
+help_about: Help → About
+
+# Popup menu paths
+popup_chords: ≡ Chords
+popup_inters: ≡ Inters
+popup_glyphs: ≡ Glyphs
+popup_slot: ≡ Slot N°
+popup_measure: ≡ Measure N°
+popup_staff: ≡ Staff N°
+popup_part: ≡ Part N°
+popup_system: ≡ System N°
+popup_page: ≡ Page N°
+popup_score: ≡ Score N°
+popup_extraction: ≡ Extraction
diff --git a/docs/_pages/advanced/cli.md b/docs/_pages/advanced/cli.md
index 40950e29e..0d60e6f85 100644
--- a/docs/_pages/advanced/cli.md
+++ b/docs/_pages/advanced/cli.md
@@ -4,7 +4,7 @@ title: Command Line Interface
parent: Advanced Features
nav_order: 1
---
-## Command Line Interface
+# Command Line Interface
{: .no_toc }
---
@@ -15,7 +15,7 @@ Table of contents
{:toc}
---
-### Syntax
+## Syntax
Note that any argument beginning with the `@` character is considered as the name of a text file
to be immediately expended _in situ_ (the text file is assumed to contain one argument per line).
@@ -82,30 +82,30 @@ Sheet steps are in order:
PAGE : Connect systems within page
```
-### Arguments
+## Arguments
These are the standard arguments that are listed when the help option is used.
They are presented here in alphabetical order.
-#### -batch
+### -batch
Launches Audiveris without any Graphic User Interface.
-#### -export
+### -export
Exports each book music as a MusicXML file.
-#### -force
+### -force
Forces reprocessing even if target step has already been reached.
This option is effective only when a target step is specified
(see the `-step` option) or the `-transcribe` option is present.
-#### -help
+### -help
Displays the arguments summary as printed above, then exits.
-#### -option KEY=VALUE
+### -option KEY=VALUE
Specifies the value of one application option,
KEY being the qualified name of the option,
@@ -113,7 +113,7 @@ VALUE being the value to assign.
This is the CLI equivalent of the GUI pull-down menu {{ site.tools_options }}.
-#### -output DIRNAME
+### -output DIRNAME
Defines the path to the target output folder, that is the precise folder where all output files
(``.omr``, ``.mxl``, etc) should be stored.
@@ -121,7 +121,7 @@ Defines the path to the target output folder, that is the precise folder where a
if this option is not present, a default output folder is chosen according to the policy described
in [Standard folders](../folders/standard.md) section.
-#### -playlist FILE.XML
+### -playlist FILE.XML
Loads the provided `.xml` file as a playlist.
@@ -133,18 +133,18 @@ If in interactive mode, the loaded playlist is used only to populated and displa
The user can then review and/or edit the playlist and potentially launch the building of
the compound book at a desired location.
-#### -print
+### -print
Exports each book music as a PDF file.
-#### -save
+### -save
Saves each book OMR data to its `.omr` project file as soon as a sheet step is processed
successfully.
This option is effective only in `-batch` mode.
-#### -sheets N M X-Y
+### -sheets N M X-Y
Specifies the IDs of sheets to process.
@@ -158,7 +158,7 @@ If no sheet IDs are specified, all (valid) sheets are concerned.
Sheet IDs apply to all books referenced on the command line.
-#### -step STEPNAME
+### -step STEPNAME
Specifies a sheet target step.
@@ -169,17 +169,17 @@ For any given sheet, if the target step has already been reached, no further pro
However, if the `-force` option is present, this sheet will be reset to BINARY and then processed
again to the target step.
-#### -transcribe
+### -transcribe
Transcribes each book.
-#### `--`
+### `--`
This argument (a double dash: "`--`") is not a real argument _per se_, but merely a delimiter
so that each following argument in the command line is taken as an input file path
(even if this argument begins with a `-` character).
-#### FILENAME
+### FILENAME
Path to one input file.
@@ -188,11 +188,11 @@ as input / output.
For any other extension, the file is considered as an image input file.
-### Advanced Arguments
+## Advanced Arguments
These arguments are made available for the advanced user.
-#### -annotate
+### -annotate
For each book, populates a Zip archive with images and symbol annotations derived from book Inter
instances.
@@ -201,14 +201,14 @@ These annotations are meant to populate a dataset for training future Audiveris
(Page and/or Patch).
-#### -sample
+### -sample
Populates each book sample repository with samples derived from the book Inter instances.
A book-level repository can be later merged into the global Audiveris sample repository in order
to prepare a training of Audiveris 5.x Glyph classifier.
-#### -run CLASS_NAME
+### -run CLASS_NAME
Runs the specified Java class on each valid sheet.
CLASS_NAME must be the fully qualified name of a Java class, which must extend the abstract class
diff --git a/docs/_pages/advanced/improve_input.md b/docs/_pages/advanced/improve_input.md
index 6a23d1370..5c193e92f 100644
--- a/docs/_pages/advanced/improve_input.md
+++ b/docs/_pages/advanced/improve_input.md
@@ -4,7 +4,7 @@ title: Improve Input
parent: Advanced Features
nav_order: 3
---
-## Improve Input
+# Improve Input
{: .no_toc }
Sometimes the base image is of rather bad quality.
@@ -19,13 +19,13 @@ Table of contents
{:toc}
---
-### Using Gimp
+## Using Gimp
[Contribution by Baruch Hoffart]
Here are some possible improvements using Gimp.
-#### Adjust Brightness and Contrast
+### Adjust Brightness and Contrast
The simplest way is to adjust the brightness of an input image.
Although Audiveris has a very good automatic binarization algorithm, sometimes manual adjustment
@@ -40,7 +40,7 @@ Keep the dark parts black, to get an image like this:
-#### Improve Image using Filters
+### Improve Image using Filters
Have a look at the following image: here we have a lot of noise in the lines and in the bars.
The transcriptions will have problem to properly detect the bars in such a case.
@@ -66,7 +66,7 @@ Finally use an "unsharp mask" filter with standard deviation set to about 1.0 to
You see that now the noise is almost completely removed.
-### Enlarging Low Resolution Scans
+## Enlarging Low Resolution Scans
[Contribution by Ram Kromberg]
@@ -85,7 +85,7 @@ It is possible to improve or even entirely overcome such obstacles using super-r
This document will detail an example using free, open-source software that is commonly distributed in Linux distributions. Alternatives for Macintosh and Windows will be mentioned as well.
-#### Software Required
+### Software Required
1. _waifu2x_. For the enlargement.
@@ -99,7 +99,7 @@ This document will detail an example using free, open-source software that is co
4. Audiveris OMR.
-#### Step-by-step
+### Step-by-step
1. In this example we'll be using the [Icelandic national anthem](https://commons.wikimedia.org/wiki/File:Icelandic_national_anthem_sheet_music.gif) as follows:
```bash
@@ -116,7 +116,7 @@ convert "is~.gif" 00.png
waifu2x-ncnn-vulkan -s 4 -i 00.png -o O4.png
```
-#### Notes
+### Notes
1. By default, _waifu2x-ncnn-vulkan_ makes use of the GPU. It is possible to force the use of the CPU with the `-g -1` flag and specify the use of more threads with the `-j` flag. e.g. 4 CPU threads: `waifu2x-ncnn-vulkan -g -1 -j 2:4:4 -s 2 -i 00.png -o 04.png`.
Be advised even low-end GPUs will out-perform the CPU many times over.
diff --git a/docs/_pages/advanced/options.md b/docs/_pages/advanced/options.md
index 5a40ed433..5f082a831 100644
--- a/docs/_pages/advanced/options.md
+++ b/docs/_pages/advanced/options.md
@@ -4,7 +4,7 @@ title: Options
parent: Advanced Features
nav_order: 4
---
-## Options {#options}
+# Options {#options}
{: .no_toc }
There is (or should be) no hard-coded constant in Audiveris code.
@@ -22,7 +22,7 @@ Table of contents
1. TOC
{:toc}
---
-### Dialog
+## Dialog
The display below combines a tree of classes on the left side, and a table on the right side,
where details of the options from the containing classes are available for display and modification.
@@ -61,7 +61,7 @@ number of pixels using the sheet interline scale (42 and 63 on this picture).
value there.
The new value applies immediately.
-### Options Lifecycle
+## Options Lifecycle
The overriding mechanism is defined as follows, from lower to higher priority:
diff --git a/docs/_pages/advanced/plugins.md b/docs/_pages/advanced/plugins.md
index 4ab0453dd..36800d5af 100644
--- a/docs/_pages/advanced/plugins.md
+++ b/docs/_pages/advanced/plugins.md
@@ -4,7 +4,7 @@ title: Plugins
parent: Advanced Features
nav_order: 5
---
-## Plugins {#plugins}
+# Plugins {#plugins}
{: .no_toc }
Many music notation programs, if not all, can import MusicXML files as those exported by Audiveris.
@@ -26,7 +26,7 @@ Table of contents
{:toc}
---
-### Use of Plugins
+## Use of Plugins
Once plugins are correctly configured, we can call an external program by selecting the desired one
in the pull-down `Plugins` menu:
@@ -42,7 +42,7 @@ exists and is up-to-date with the latest score modifications performed manually
and finally launches the proper external program,
providing the path to the exported file as an import argument.
-### Plugins Configuration
+## Plugins Configuration
We can define one or more plugins, by creating a single XML file, named `plugins.xml`,
in [Audiveris configuration folder](../folders/essential.md#config-folder).
diff --git a/docs/_pages/advanced/samples.md b/docs/_pages/advanced/samples.md
index a1cc4bb86..5020ea8cd 100644
--- a/docs/_pages/advanced/samples.md
+++ b/docs/_pages/advanced/samples.md
@@ -4,7 +4,7 @@ title: Samples
parent: Advanced Features
nav_order: 6
---
-## Samples
+# Samples
{: .no_toc :}
This chapter describes how to set up repositories of Glyph samples and how to carefully filter the
@@ -24,7 +24,7 @@ Table of contents
1. TOC
{:toc}
---
-### Initial samples
+## Initial samples
There is an Audiveris Google drive located at
[https://drive.google.com/drive/u/1/folders/0B9_F5tULPk_oeEU0a2Z1U0gwLTg?resourcekey=0-W_yyQcPj9JL9Bc2bKTAtrg](https://drive.google.com/drive/u/1/folders/0B9_F5tULPk_oeEU0a2Z1U0gwLTg?resourcekey=0-W_yyQcPj9JL9Bc2bKTAtrg)
@@ -51,7 +51,7 @@ We will then be able to augment this collection on our own.
We can also download the `images.zip` file which is not mandatory for training, but which will
help us see most samples within their sheet context.
-### Sampling a Sheet or a Book
+## Sampling a Sheet or a Book
After perhaps some manual corrections, when we are really satisfied with all the glyphs recognized
in a given sheet, we can save the sheet data as training samples.
@@ -68,7 +68,7 @@ In say the `foo` book folder, there will be:
It is a good practice to work on one book at a time, and only merge a book repository into the
global repository when the book data has been thoroughly verified and its samples carefully filtered.
-### Sample Repository
+## Sample Repository
The purpose of the Sample Repository dialog is to provide a user interface to visually review some
or all of the various SAMPLES which could be used for training the classifier.
@@ -101,7 +101,7 @@ The repository interface is organized as follows:
* Samples selector
* Sample context
-#### Sample Selection
+### Sample Selection
1. Initially, all panes are empty except the `Sheets` selector which appears populated with
sheets names.
@@ -125,7 +125,7 @@ We can now select the shapes of interest.
panel displays the selected sample in its sheet context.
This can be helpful for visual checking.
-#### Sample Editing
+### Sample Editing
The selected sample can be:
* **Removed** from the repository.
@@ -135,7 +135,7 @@ The selected sample can be:
This is done by clicking on the `Assign to` button in the Sample board or selecting the
`Assign to` item in the sample right-click menu, and then selecting the new shape.
-### Merging Repositories
+## Merging Repositories
When we are satisfied with a book repository we can push its content to the global repository.
diff --git a/docs/_pages/advanced/topics.md b/docs/_pages/advanced/topics.md
index 90a53a518..5cb22c197 100644
--- a/docs/_pages/advanced/topics.md
+++ b/docs/_pages/advanced/topics.md
@@ -4,7 +4,7 @@ title: Advanced Topics
parent: Advanced Features
nav_order: 2
---
-## Advanced Topics
+# Advanced Topics
{: .no_toc }
---
@@ -23,17 +23,17 @@ This is done via the {{ site.tools_advanced }} pull-down menu.
-### Input Step
+## Input Step
This box allows to define which step is automatically trigerred on an input file.
-### Default Plugin
+## Default Plugin
This allows to interactively choose a new default plugin among the declared ones,
since by default the first declared plugin is set as the default one
(See [Plugins](./plugins.md) section).
-### Target output folders
+## Target output folders
{: .d-inline-block }
new in 5.3
{: .label .label-yellow }
@@ -47,14 +47,14 @@ folder, created according to the input file name without its extension.
For further explanation, see section on [Standard folders](../folders/standard.md).
-### Global font ratio
+## Global font ratio
{: .d-inline-block }
new in 5.3
{: .label .label-yellow }
The slider allows to select a larger font size used throughout the application views.
-### Locale
+## Locale
{: .d-inline-block }
new in 5.3
{: .label .label-yellow }
@@ -64,7 +64,7 @@ As of this writing, available locales are:
- **en** (English), the default
- **fr** (French), still partially implemented...
-### Advanced Topics
+## Advanced Topics
Each of these topics can gather several related features.
diff --git a/docs/_pages/advanced/training.md b/docs/_pages/advanced/training.md
index e6c6e71de..f5ea0a6e6 100644
--- a/docs/_pages/advanced/training.md
+++ b/docs/_pages/advanced/training.md
@@ -4,7 +4,7 @@ title: Training
parent: Advanced Features
nav_order: 7
---
-## Training {#training}
+# Training {#training}
{: .no_toc }
Audiveris has the ability to train the underlying Glyph classifier with representative samples.
@@ -32,7 +32,7 @@ Table of contents
{:toc}
---
-### Trainer Dialog {#trainer}
+## Trainer Dialog {#trainer}
This dialog is dedicated to the training of Audiveris basic classifier (a glyph classifier).
It is launched via the pull-down menu {{ site.tools_train }} or, from the global repository,
@@ -55,7 +55,7 @@ There we can set amplitude, learningRate, momentum and maxEpochs parameters.
`Stop` button allows to stop the training before the maxEpochs count has been reached.
-### Validation
+## Validation
There are two data sets available for validation, the train set (of no major interest)
and the test set.
diff --git a/docs/_pages/assets/images/BachInvention5_binary_adaptive.png b/docs/_pages/assets/images/BachInvention5_binary_adaptive.png
new file mode 100644
index 000000000..c9c7cc434
Binary files /dev/null and b/docs/_pages/assets/images/BachInvention5_binary_adaptive.png differ
diff --git a/docs/_pages/assets/images/BachInvention5_binary_global.png b/docs/_pages/assets/images/BachInvention5_binary_global.png
new file mode 100644
index 000000000..a459bc4fd
Binary files /dev/null and b/docs/_pages/assets/images/BachInvention5_binary_global.png differ
diff --git a/docs/_pages/assets/images/BachInvention5_gray.png b/docs/_pages/assets/images/BachInvention5_gray.png
new file mode 100644
index 000000000..aaa16df69
Binary files /dev/null and b/docs/_pages/assets/images/BachInvention5_gray.png differ
diff --git a/docs/_pages/assets/images/Mercy_binary_adaptive.png b/docs/_pages/assets/images/Mercy_binary_adaptive.png
new file mode 100644
index 000000000..7b464eb6e
Binary files /dev/null and b/docs/_pages/assets/images/Mercy_binary_adaptive.png differ
diff --git a/docs/_pages/assets/images/Mercy_binary_global.png b/docs/_pages/assets/images/Mercy_binary_global.png
new file mode 100644
index 000000000..548e3b5ed
Binary files /dev/null and b/docs/_pages/assets/images/Mercy_binary_global.png differ
diff --git a/docs/_pages/assets/images/Mercy_gray.png b/docs/_pages/assets/images/Mercy_gray.png
new file mode 100644
index 000000000..89fcd3ad2
Binary files /dev/null and b/docs/_pages/assets/images/Mercy_gray.png differ
diff --git a/docs/_pages/assets/images/binarization_board.png b/docs/_pages/assets/images/binarization_board.png
deleted file mode 100644
index a4e6dd25f..000000000
Binary files a/docs/_pages/assets/images/binarization_board.png and /dev/null differ
diff --git a/docs/_pages/assets/images/binarization_board_adaptive.png b/docs/_pages/assets/images/binarization_board_adaptive.png
new file mode 100644
index 000000000..df06072e1
Binary files /dev/null and b/docs/_pages/assets/images/binarization_board_adaptive.png differ
diff --git a/docs/_pages/assets/images/binarization_board_global.png b/docs/_pages/assets/images/binarization_board_global.png
new file mode 100644
index 000000000..a90044b44
Binary files /dev/null and b/docs/_pages/assets/images/binarization_board_global.png differ
diff --git a/docs/_pages/assets/images/black_plot.png b/docs/_pages/assets/images/black_plot.png
index 51a10f60e..b2623fa5a 100644
Binary files a/docs/_pages/assets/images/black_plot.png and b/docs/_pages/assets/images/black_plot.png differ
diff --git a/docs/_pages/assets/images/chula_binary.png b/docs/_pages/assets/images/chula_binary.png
new file mode 100644
index 000000000..6d81cfe9b
Binary files /dev/null and b/docs/_pages/assets/images/chula_binary.png differ
diff --git a/docs/_pages/assets/images/chula_data.png b/docs/_pages/assets/images/chula_data.png
new file mode 100644
index 000000000..aa38a62ca
Binary files /dev/null and b/docs/_pages/assets/images/chula_data.png differ
diff --git a/docs/_pages/assets/images/chula_data_output.png b/docs/_pages/assets/images/chula_data_output.png
new file mode 100644
index 000000000..d2ee4a600
Binary files /dev/null and b/docs/_pages/assets/images/chula_data_output.png differ
diff --git a/docs/_pages/assets/images/chula_filaments.png b/docs/_pages/assets/images/chula_filaments.png
new file mode 100644
index 000000000..d0fcc3bf9
Binary files /dev/null and b/docs/_pages/assets/images/chula_filaments.png differ
diff --git a/docs/_pages/assets/images/chula_header.png b/docs/_pages/assets/images/chula_header.png
new file mode 100644
index 000000000..077600ad7
Binary files /dev/null and b/docs/_pages/assets/images/chula_header.png differ
diff --git a/docs/_pages/assets/images/chula_long_hori.png b/docs/_pages/assets/images/chula_long_hori.png
new file mode 100644
index 000000000..821d930fd
Binary files /dev/null and b/docs/_pages/assets/images/chula_long_hori.png differ
diff --git a/docs/_pages/assets/images/chula_long_vert.png b/docs/_pages/assets/images/chula_long_vert.png
new file mode 100644
index 000000000..7f2c38d66
Binary files /dev/null and b/docs/_pages/assets/images/chula_long_vert.png differ
diff --git a/docs/_pages/assets/images/chula_lu_areas.png b/docs/_pages/assets/images/chula_lu_areas.png
new file mode 100644
index 000000000..d0cc3f564
Binary files /dev/null and b/docs/_pages/assets/images/chula_lu_areas.png differ
diff --git a/docs/_pages/assets/images/chula_lu_areas_2.png b/docs/_pages/assets/images/chula_lu_areas_2.png
new file mode 100644
index 000000000..64f125361
Binary files /dev/null and b/docs/_pages/assets/images/chula_lu_areas_2.png differ
diff --git a/docs/_pages/assets/images/chula_nostaff.png b/docs/_pages/assets/images/chula_nostaff.png
new file mode 100644
index 000000000..ca46296f8
Binary files /dev/null and b/docs/_pages/assets/images/chula_nostaff.png differ
diff --git a/docs/_pages/assets/images/chula_short_hori.png b/docs/_pages/assets/images/chula_short_hori.png
new file mode 100644
index 000000000..4b1eee150
Binary files /dev/null and b/docs/_pages/assets/images/chula_short_hori.png differ
diff --git a/docs/_pages/assets/images/chula_staff_plot.png b/docs/_pages/assets/images/chula_staff_plot.png
new file mode 100644
index 000000000..c1c394422
Binary files /dev/null and b/docs/_pages/assets/images/chula_staff_plot.png differ
diff --git a/docs/_pages/assets/images/chula_stems_buffer.png b/docs/_pages/assets/images/chula_stems_buffer.png
new file mode 100644
index 000000000..3161c0b11
Binary files /dev/null and b/docs/_pages/assets/images/chula_stems_buffer.png differ
diff --git a/docs/_pages/assets/images/chula_stems_histo.png b/docs/_pages/assets/images/chula_stems_histo.png
new file mode 100644
index 000000000..842dd2fc6
Binary files /dev/null and b/docs/_pages/assets/images/chula_stems_histo.png differ
diff --git a/docs/_pages/assets/images/coffrets_beam_sections.png b/docs/_pages/assets/images/coffrets_beam_sections.png
new file mode 100644
index 000000000..5e5d55232
Binary files /dev/null and b/docs/_pages/assets/images/coffrets_beam_sections.png differ
diff --git a/docs/_pages/assets/images/coffrets_beam_spots.png b/docs/_pages/assets/images/coffrets_beam_spots.png
new file mode 100644
index 000000000..23f309175
Binary files /dev/null and b/docs/_pages/assets/images/coffrets_beam_spots.png differ
diff --git a/docs/_pages/assets/images/coffrets_beams.png b/docs/_pages/assets/images/coffrets_beams.png
new file mode 100644
index 000000000..1a57dbd18
Binary files /dev/null and b/docs/_pages/assets/images/coffrets_beams.png differ
diff --git a/docs/_pages/assets/images/coffrets_binary.png b/docs/_pages/assets/images/coffrets_binary.png
new file mode 100644
index 000000000..4670764f9
Binary files /dev/null and b/docs/_pages/assets/images/coffrets_binary.png differ
diff --git a/docs/_pages/assets/images/coffrets_double_beam.png b/docs/_pages/assets/images/coffrets_double_beam.png
new file mode 100644
index 000000000..5c7b45e6e
Binary files /dev/null and b/docs/_pages/assets/images/coffrets_double_beam.png differ
diff --git a/docs/_pages/assets/images/coffrets_gray_spots.png b/docs/_pages/assets/images/coffrets_gray_spots.png
new file mode 100644
index 000000000..a72f98d49
Binary files /dev/null and b/docs/_pages/assets/images/coffrets_gray_spots.png differ
diff --git a/docs/_pages/assets/images/combo_plot.png b/docs/_pages/assets/images/combo_plot.png
index 124277caa..f91211422 100644
Binary files a/docs/_pages/assets/images/combo_plot.png and b/docs/_pages/assets/images/combo_plot.png differ
diff --git a/docs/_pages/assets/images/run_heights.png b/docs/_pages/assets/images/run_heights.png
new file mode 100644
index 000000000..f224ce06b
Binary files /dev/null and b/docs/_pages/assets/images/run_heights.png differ
diff --git a/docs/_pages/assets/images/staff_plot.png b/docs/_pages/assets/images/staff_plot.png
index e06e1ff09..eb4c7cff9 100644
Binary files a/docs/_pages/assets/images/staff_plot.png and b/docs/_pages/assets/images/staff_plot.png differ
diff --git a/docs/_pages/assets/images/view_menu.png b/docs/_pages/assets/images/view_menu.png
index 1027a8280..15cb5cf5b 100644
Binary files a/docs/_pages/assets/images/view_menu.png and b/docs/_pages/assets/images/view_menu.png differ
diff --git a/docs/_pages/boards/README.md b/docs/_pages/boards/README.md
index cb17f031d..6f242e3bf 100644
--- a/docs/_pages/boards/README.md
+++ b/docs/_pages/boards/README.md
@@ -2,7 +2,7 @@
layout: default
title: Boards
parent: References
-nav_order: 3
+nav_order: 5
has_children: true
---
# Boards
diff --git a/docs/_pages/boards/binarization.md b/docs/_pages/boards/binarization.md
index 91d7cd017..c115c2d1c 100644
--- a/docs/_pages/boards/binarization.md
+++ b/docs/_pages/boards/binarization.md
@@ -5,31 +5,38 @@ grand_parent: References
parent: Boards
nav_order: 2
---
-## Binarization board
+# Binarization board
{: .no_toc :}
-
+This board, together with the [Pixel board](./pixel.md), is meant to visualize the behavior of the binarization algorithm documented in the [BINARY step](../steps/binary.md).
-This board is meant to visualize the behavior of the `adaptive` binarization algorithm.
-According to the current location, it displays the context information and the resulting threshold
-on pixel level.
+The board is displayed by default in the Gray tab and on demand in the Binary tab.
+Of course, to be effective, the gray image must still be available.
-It is effective only when run on the initial gray image.
+- The pixel board displays the selected _location_ (x, y).
+It can also display the _gray level_ at this location when available.
+- The binarization board always displays the _threshold_ value and the resulting _binary color_.
----
-Table of contents
-{: .no_toc .text-delta }
+## Threshold
+The threshold value to be compared with the gray level at the selected location.
-1. TOC
-{:toc}
----
+## Color
+The resulting color of binarization at the selected location -- either _black_ or _white_.
+
+## Board for the Global filter
+
+
+For the global filter, the threshold value is constant for all pixels in the image.
+
+## Board for the Adaptive filter
+
+
+For the adaptive filter, the threshold value is computed for each location,
+based on the mean and the standard deviation of gray values in location vicinity.
### Mean
-Average value of all pixels read in the vicinity of the selected location.
+The average value of all gray pixels read around the selected location.
### StdDev
-Standard deviation value of all pixels read in the vicinity.
+The standard deviation value of all gray pixels read around the selected location.
-### Threshold
-Computed threshold value based on mean and deviation in vicinity,
-to compare with pixel level at selected location.
diff --git a/docs/_pages/boards/classifier.md b/docs/_pages/boards/classifier.md
index 2c5c7ff8c..37ed4c2ed 100644
--- a/docs/_pages/boards/classifier.md
+++ b/docs/_pages/boards/classifier.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Boards
nav_order: 7
---
-## Basic Classifier board
+# Basic Classifier board
diff --git a/docs/_pages/boards/glyph.md b/docs/_pages/boards/glyph.md
index d800d79b9..8b58ab7f8 100644
--- a/docs/_pages/boards/glyph.md
+++ b/docs/_pages/boards/glyph.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Boards
nav_order: 4
---
-## Glyph board
+# Glyph board
{: .no_toc :}
@@ -18,32 +18,32 @@ Table of contents
{:toc}
---
-### Vip
+## Vip
(input/output)
Flag this entity as VIP, resulting in verbose processing information.
-### Dump
+## Dump
(input)
Dump main entity data into the log window.
-### Id
+## Id
(input/output)
Integer ID of entity.
-### (groups)
+## (groups)
(output)
If any, the group(s) this glyph is part of.
A group is a tag assigned to a glyph, related to the intended usage of the glyph.
For example, `VERTICAL_SEED` is assigned to a glyph considered for the detection of
stem candidates.
-### Weight
+## Weight
(output)
The _normalized_ glyph weight.
The glyph raw weight (number of black pixels it is composed of) is divided by the square of
interline value to provide the interline-normalized weight.
-### Width & Height
+## Width & Height
(output)
The _normalized_ dimension of the glyph bounding box (raw dimension divided by interline value).
diff --git a/docs/_pages/boards/inter.md b/docs/_pages/boards/inter.md
index bb52a3d46..e3154a5b6 100644
--- a/docs/_pages/boards/inter.md
+++ b/docs/_pages/boards/inter.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Boards
nav_order: 5
---
-## Inter board
+# Inter board
{: .no_toc :}
@@ -18,53 +18,53 @@ Table of contents
{:toc}
---
-### Vip
+## Vip
(input/output)
Flag this entity as VIP, resulting in verbose processing information
when entity is involved.
-### Dump
+## Dump
(input)
Dump main entity data into the log window.
-### Id
+## Id
(input/output)
Integer ID of entity.
-### Grade
+## Grade
(output)
The intrinsic grade value assigned to the Inter instance.
Followed by the computed contextual grade, if any.
-### Deassign
+## Deassign
(input)
Button available to manually delete this interpretation.
-### (shape icon)
+## (shape icon)
(output)
If available, the icon related to the Inter shape.
-### Edit
+## Edit
(input/output)
Allows to open an editor of the entity.
-### To Ensemble
+## To Ensemble
Button to navigate to the ensemble if any this entity is part of.
-### (shape name)
+## (shape name)
(output)
Name of the shape assigned to the Inter instance.
-### (word)
+## (word)
(input/output)
For a word inter, the modifiable word textual content.
-### (sentence)
+## (sentence)
(output)
For a sentence inter, the _non-modifiable_ sentence textual content.
Modifications can be performed at word level only.
-### (sentence role)
+## (sentence role)
(input/output)
Role of the sentence (such as Direction, PartName, Rights, Lyrics, ...).
@@ -73,7 +73,7 @@ Role of the sentence (such as Direction, PartName, Rights, Lyrics, ...).
Nota: `Lyrics` is such a specific sentence role that it cannot be changed in an existing Inter.
Instead, a new (lyrics) inter is created automatically.
-### (lyrics)
+## (lyrics)
For a lyrics sentence, the inter board displays additional data:
diff --git a/docs/_pages/boards/pixel.md b/docs/_pages/boards/pixel.md
index fcaa836ca..41599d7e4 100644
--- a/docs/_pages/boards/pixel.md
+++ b/docs/_pages/boards/pixel.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Boards
nav_order: 1
---
-## Pixel board
+# Pixel board
{: .no_toc }
@@ -21,19 +21,19 @@ Table of contents
{:toc}
---
-### Level
+## Level
(output)
Gray value, between 0 and 255, at the (x,y) location.
This field is active only on the initial (gray) image.
It becomes inactive on the binary (black & white) image.
-### X & Y
+## X & Y
(input/output)
The abscissa and ordinate values for the selected location
(either a single point, or the top left corner of a rectangle).
-### Width & Height
+## Width & Height
(input/output)
The width and height values of the selected rectangle.
If both are zero, the rectangle degenerates as a single point.
diff --git a/docs/_pages/boards/section.md b/docs/_pages/boards/section.md
index 1d89e11a3..c9659e3e6 100644
--- a/docs/_pages/boards/section.md
+++ b/docs/_pages/boards/section.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Boards
nav_order: 3
---
-## Section board
+# Section board
{: .no_toc :}
@@ -21,28 +21,28 @@ Table of contents
{:toc}
---
-### Vip
+## Vip
(input/output)
Flag this entity as VIP, resulting in verbose processing information.
-### Dump
+## Dump
(input)
Dump main entity data into the log window.
-### Id
+## Id
(input/output)
Integer ID of entity.
-### Weight
+## Weight
(output)
Number of (black) pixels that compose the section.
-### X & Y
+## X & Y
(output)
Coordinates of top left corner of the section:
* For a horizontal section, this is the left side of the top run.
* For a vertical section, this is the top side of the left run.
-### Width & Height
+## Width & Height
(output)
Width and height of the section bounding box.
diff --git a/docs/_pages/boards/shape.md b/docs/_pages/boards/shape.md
index 631d9094e..19b0d6399 100644
--- a/docs/_pages/boards/shape.md
+++ b/docs/_pages/boards/shape.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Boards
nav_order: 6
---
-## Shape board
+# Shape board
{: .no_toc :}
--
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Top dialog: sets
+## Top dialog: sets
The shape board displays a panel of shape sets.
@@ -27,7 +27,7 @@ In the picture above, we can see:
- Second row: Keys, HeadsAndDot, Markers, Ornaments, Rests, Times, Digits,
Pluckings, Romans, Physicals.
-### Palettes: shapes
+## Palettes: shapes
Clicking on a shape set button replaces the global shape panel by the selected set palette,
for example the ``HeadsAndDot`` palette which adapts to the book at hand:
@@ -48,6 +48,6 @@ location in sheet.
To leave the current palette and return to the global shape set panel,
we press the `ESCAPE` key or click on the ``up`` (▲) button.
-### More recently used
+## More recently used
The shapes most recently assigned (by whatever means) always appear at the top of shape panel,
available for a direct reuse.
diff --git a/docs/_pages/folders/README.md b/docs/_pages/folders/README.md
index 3efd21e29..0a86a889f 100644
--- a/docs/_pages/folders/README.md
+++ b/docs/_pages/folders/README.md
@@ -2,7 +2,7 @@
layout: default
title: Folders
parent: References
-nav_order: 4
+nav_order: 6
has_children: true
---
# Folders
diff --git a/docs/_pages/folders/cached.md b/docs/_pages/folders/cached.md
index d83e11dcf..9e695bd44 100644
--- a/docs/_pages/folders/cached.md
+++ b/docs/_pages/folders/cached.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Folders
nav_order: 3
---
-## Cached folders
+# Cached folders
{: .no_toc :}
---
@@ -16,13 +16,13 @@ Table of contents
{:toc}
---
-### Purpose
+## Purpose
Audiveris uses these locations for persistency of internal information.
These files are **not** meant to be edited, period!
-### GUI folder
+## GUI folder
These are opaque files used for GUI lifecycle (notably last position and size of each window)
- mainFrame.session.xml
@@ -36,7 +36,7 @@ These are opaque files used for GUI lifecycle (notably last position and size of
| **Linux** | ~/audiveris |
| **MacOS** | TODO: !!! **I DON'T KNOW** !!!|
-### Log folder
+## Log folder
Each session of Audiveris application creates in this folder a single global `dateTtime.log` file
that covers all log events of the session.
@@ -48,7 +48,7 @@ that covers all log events of the session.
| **Linux** (choice #2)| $HOME/.cache/AudiverisLtd/audiveris/log |
| **MacOS** | $HOME/Library/AudiverisLtd/audiveris/log |
-### Temp folder
+## Temp folder
It is a temporary storage for various needs, such as saving a snapshot of a score image portion.
diff --git a/docs/_pages/folders/essential.md b/docs/_pages/folders/essential.md
index 256262023..36bf9b793 100644
--- a/docs/_pages/folders/essential.md
+++ b/docs/_pages/folders/essential.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Folders
nav_order: 2
---
-## Essential folders
+# Essential folders
{: .no_toc :}
---
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Purpose
+## Purpose
This is where Audiveris stores user-specific essential parameters:
@@ -24,7 +24,7 @@ Under Windows notably, these are _hidden locations_ by default.
Please do not create or modify these files, unless you are an advanced user and
know what you are doing.
-### Config folder
+## Config folder
Audiveris defines a `CONFIG_FOLDER` for configuration files:
@@ -44,7 +44,7 @@ Precise location of `CONFIG_FOLDER` depends on OS environment:
| **Linux** (choice #2)| $HOME/.config/AudiverisLtd/audiveris |
| **MacOS** | $HOME/Library/Application Support/AudiverisLtd/audiveris |
-### Train folder
+## Train folder
There is a `TRAIN_FOLDER` that can be populated with user-specific training
material and trained model to override default Audiveris model:
diff --git a/docs/_pages/folders/standard.md b/docs/_pages/folders/standard.md
index 82f419ce7..1bb00230f 100644
--- a/docs/_pages/folders/standard.md
+++ b/docs/_pages/folders/standard.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Folders
nav_order: 1
---
-## Standard folders
+# Standard folders
{: .no_toc :}
{: .d-inline-block }
new in 5.3
@@ -18,12 +18,12 @@ Table of contents
{:toc}
---
-### Purpose
+## Purpose
This is where, by default, Audiveris stores all score outputs, such as the `.omr` project
files, the `.pdf` printouts, the `.mxl` MusicXML files, etc.
-### Historical target policy
+## Historical target policy
Before 5.3, Audiveris policy was to gather all outputs of a given input file
in a specific sub-folder, named according to the input radix, created under the base folder.
@@ -73,7 +73,7 @@ this time with CLI option ``-output /path/to/fooBar``, we would get outputs like
...
```
-### Updated target policy
+## Updated target policy
The historical target policy is still the default policy, but additional possibilities
are now provided by Audiveris 5.3.
diff --git a/docs/_pages/handbook.md b/docs/_pages/handbook.md
index 2a221f778..c16f59d40 100644
--- a/docs/_pages/handbook.md
+++ b/docs/_pages/handbook.md
@@ -32,10 +32,15 @@ learning curve for any potential developer.
## Overview
-When questioned about Audiveris, ChatGPT answered:
-> Audiveris is an open source Optical Music Recognition (OMR) software. It is used to scan sheet music and convert it into a machine-readable format, such as MusicXML or MIDI. This allows the music to be edited, played back, and shared digitally.
+When questioned about Audiveris in December 2023, ChatGPT answered:
-Not that bad! But let's try to describe it on our own...
+> Audiveris is an open-source optical music recognition (OMR) software. OMR technology is designed to recognize printed music notation from scanned images or photos and convert it into a digital format that can be edited and played back. Audiveris specifically focuses on converting scanned sheet music into MusicXML format.
+
+> The software is developed in Java and is available for various operating systems, including Windows, macOS, and Linux. It can be used to digitize printed sheet music, making it easier to edit, share, and playback on digital devices.
+
+> If you're interested in using Audiveris, you can find more information, documentation, and download links on the official website or through open-source software repositories. Keep in mind that the information provided here is accurate as of my last knowledge update in January 2022, and there may have been updates or changes since then.
+
+Not that bad at all! But let's try to describe it on our own...
Audiveris is an open source software, published under the
[AGPL](https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License) V3 license.
diff --git a/docs/_pages/install/languages.md b/docs/_pages/install/languages.md
index ad76795ab..68dee05a5 100644
--- a/docs/_pages/install/languages.md
+++ b/docs/_pages/install/languages.md
@@ -4,7 +4,7 @@ title: OCR languages
nav_order: 2
parent: Installation
---
-## OCR languages
+# OCR languages
{: .no_toc }
Audiveris delegates text recognition to Tesseract OCR library.
@@ -24,7 +24,7 @@ Table of contents
{:toc}
---
-### Tesseract as a linked library
+## Tesseract as a linked library
Audiveris calls Tesseract software as a linked binary _library_,
not as a separate executable _program_.
@@ -35,7 +35,7 @@ not as a separate executable _program_.
Audiveris will not interfere with that program.
- However, Tesseract library will need data (language files) which must be provided separately.
-### Data version
+## Data version
Tesseract OCR engine can operate in two different OCR modes
-- the ``legacy`` mode and the new ``LSTM`` mode -- each with its own model.
@@ -46,7 +46,7 @@ The language files downloadable from [Tesseract tessdata] page are meant for Tes
version 4.x and up, each language file containing both ``legacy`` and ``LSTM`` models.
So, these are the language data files that Audiveris requires.
-### Data location
+## Data location
At starting time, Audiveris tries to initialize the Tesseract library with a `tessdata` folder:
1. It first checks the location defined by the `TESSDATA_PREFIX` environment variable.
@@ -80,7 +80,7 @@ about the OCR engine version and OCR tessdata folder:
-### Languages selection
+## Languages selection
At runtime, you can specify which languages should be tried by the OCR software.
This is done via a language specification string, a plus-separated list of language names:
diff --git a/docs/_pages/install/sources.md b/docs/_pages/install/sources.md
index 98c14d475..6f3ffbbe4 100644
--- a/docs/_pages/install/sources.md
+++ b/docs/_pages/install/sources.md
@@ -4,7 +4,7 @@ title: Building from sources
nav_order: 4
parent: Installation
---
-## Building from sources (Windows, MacOS, Linux, ArchLinux)
+# Building from sources (Windows, MacOS, Linux, ArchLinux)
{: .no_toc }
{: .note }
@@ -20,7 +20,7 @@ Table of contents
{:toc}
---
-### Dependencies
+## Dependencies
* [Git][git]: version control system.
@@ -38,7 +38,7 @@ Please check [OCR languages](./languages.md) section.
to handle those specific PDFs that contain vector graphics.
Fortunately, every known Unix-like OS distribution already contains a package for FreeType.
-### Download, build and run
+## Download, build and run
To download the Audiveris project, use the following command in a directory of your choice:
```sh
@@ -87,7 +87,7 @@ gradlew.bat run
Please note that all these commands use **gradle wrapper** (`gradlew`) which, behind the scenes,
takes care of getting and launching the proper gradle version.
-### Alternative run
+## Alternative run
The gradle-based run, as described above, makes sure that all your potential modifications are
compiled before the application is launched.
diff --git a/docs/_pages/main/book_parameters.md b/docs/_pages/main/book_parameters.md
index 993b60dd0..0c8302bab 100644
--- a/docs/_pages/main/book_parameters.md
+++ b/docs/_pages/main/book_parameters.md
@@ -4,7 +4,7 @@ title: Book Parameters
parent: Main Features
nav_order: 5
---
-## Book Parameters
+# Book Parameters
{: .no_toc }
Table of contents
@@ -15,7 +15,7 @@ Table of contents
---
-### Dialog
+## Dialog
The pull-down menu {{ site.book_parameters }} opens a dialog to review and modify
high-level processing parameters.
@@ -25,7 +25,7 @@ two sheets:
-### Scopes
+## Scopes
The dialog is organized in several tabs to describe Default, Book and Sheet's scopes respectively.
In this example, the dialog provides 4 tabs, one for Default, one for Dichterliebe01 book,
@@ -50,7 +50,7 @@ To cancel a value modification, we simply un-check the box on left side.
The line then gets disabled, changing from black to gray, and it now displays the inherited value
in lieu of the overriding value.
-### Lifecycle
+## Lifecycle
All modifications apply only when either the `OK` button or the `Apply` button is pressed,
which actually commits them.
@@ -61,7 +61,7 @@ The `OK` button completes the dialog, while the `Apply` button keeps the dialog
* All the modified **book/sheets** values persist in the book `.omr` project file.
-### Parameters
+## Parameters
* **Binarization** (needs SPECIFIC_ITEMS advanced topic)
We select the kind of filter (_global_ or _adaptive_) which gives the best results for the sheet
diff --git a/docs/_pages/main/book_portions.md b/docs/_pages/main/book_portions.md
index ba0780162..9dbb16d92 100644
--- a/docs/_pages/main/book_portions.md
+++ b/docs/_pages/main/book_portions.md
@@ -5,7 +5,7 @@ parent: Main Features
has_children: true
nav_order: 7
---
-## Book Portions
+# Book Portions
Handling a one-image score is just a matter of one book with one sheet in it.
But handling cases of dozens or hundreds of score images may require more flexible approaches:
diff --git a/docs/_pages/main/book_sheet.md b/docs/_pages/main/book_sheet.md
index 9980881a5..4af1677f0 100644
--- a/docs/_pages/main/book_sheet.md
+++ b/docs/_pages/main/book_sheet.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Main Entities
nav_order: 1
---
-### Book of Sheets
+# Book of Sheets
An image file fed into OMR software contains one or several images.
Typically PDF and TIFF formats support the notion of multi-image files while, for example,
diff --git a/docs/_pages/main/display_modes.md b/docs/_pages/main/display_modes.md
index 32b09af12..8ca3666b8 100644
--- a/docs/_pages/main/display_modes.md
+++ b/docs/_pages/main/display_modes.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Main Window
nav_order: 1
---
-### Data display modes
+# Data display modes
In the sheet panel we can choose between 3 display modes, that are effective in the **Data** tab:
diff --git a/docs/_pages/main/entities.md b/docs/_pages/main/entities.md
index 926ad39ef..3ae82f49d 100644
--- a/docs/_pages/main/entities.md
+++ b/docs/_pages/main/entities.md
@@ -5,7 +5,7 @@ parent: Main Features
nav_order: 2
has_children: true
---
-## Main Entities
+# Main Entities
The purpose is not to describe the full data model of Audiveris, but simply to introduce some
key notions that are used throughout the whole application and that the end-user needs to
diff --git a/docs/_pages/main/entity_colors.md b/docs/_pages/main/entity_colors.md
index b5ceb51f2..c99a46ffa 100644
--- a/docs/_pages/main/entity_colors.md
+++ b/docs/_pages/main/entity_colors.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Main Window
nav_order: 3
---
-### Entity Colors
+# Entity Colors
The sheet window uses different colors to display the entities and the kind of entity that was
recognized:
diff --git a/docs/_pages/main/glyph_inter.md b/docs/_pages/main/glyph_inter.md
index d4a2fb476..eca9f4af3 100644
--- a/docs/_pages/main/glyph_inter.md
+++ b/docs/_pages/main/glyph_inter.md
@@ -5,9 +5,9 @@ grand_parent: Main Features
parent: Main Entities
nav_order: 4
---
-### Glyph vs Inter
+# Glyph vs Inter
-#### Glyph
+## Glyph
A **Glyph** is nothing more than a set of foreground (black) pixels
in a sheet binary image.
@@ -21,7 +21,7 @@ or two staves: does it belong to the upper or the lower system/staff?
These restrictions on Glyph don't apply to glyph interpretations (Inter).
-#### Inter
+## Inter
An interpretation, or **Inter** for short, is precisely meant to formalize any reasonable
interpretation of a glyph.
@@ -43,7 +43,7 @@ This grade is an interpretation _intrinsic_ grade, only based on the glyph at ha
Later, the Inter will generally be assigned a _contextual_ grade, based on the Inter grade
and the supporting relations with other Inter instances nearby.
-#### Typical display example
+## Typical display example
| View | Inter over Glyph |
diff --git a/docs/_pages/main/limitations.md b/docs/_pages/main/limitations.md
index dd35a855d..a47bd80b4 100644
--- a/docs/_pages/main/limitations.md
+++ b/docs/_pages/main/limitations.md
@@ -4,7 +4,7 @@ title: Limitations
parent: Main Features
nav_order: 9
---
-## Limitations
+# Limitations
{: .no_toc }
This section presents the known cases that current Audiveris does not handle properly.
@@ -25,7 +25,7 @@ Table of contents
---
-### Natural signs in key signature
+## Natural signs in key signature
@@ -41,7 +41,7 @@ In this case, we will have to manually enter the correct key (without the natura
Since 5.3, we can manually insert a natural-only key signature, a kind of "cancel key".
See this possibility detailed in the [Naturals section](../ui_tools/key.md#naturals).
-### Key signature change
+## Key signature change
@@ -62,7 +62,7 @@ It is thus harmless for the OMR engine to ignore this warning.
Apart from this courtesy case, the user may have to manually enter the missing key change on every
staff.
-### Opposed Stems
+## Opposed Stems
We can have two head chords with up and down stems that are located in such a way that they seem
to be merged, as follows:
@@ -76,7 +76,7 @@ At the next reduction, this stem will be discarded, and the now isolated heads a
This error can be fixed by manually inserting separate standard stems (and the related heads).
-### ChordName
+## ChordName
Recognition of chord names can still be impeded by the presence of sharp (``♯``) or flat (``♭``)
characters which Tesseract OCR cannot handle correctly.
@@ -87,11 +87,11 @@ signs.
See further description in the [Text Chord Name](../ui_tools/text.md#chord-name) section.
-### Tuplets
+## Tuplets
Tuplets other than triplets and 6-tuplets are not supported, even manually.
-### Roman numeral
+## Roman numeral
Some input files represent chords using Roman numerals.
diff --git a/docs/_pages/main/main_window.md b/docs/_pages/main/main_window.md
index cad15a799..1166f968d 100644
--- a/docs/_pages/main/main_window.md
+++ b/docs/_pages/main/main_window.md
@@ -5,13 +5,13 @@ parent: Main Features
nav_order: 1
has_children: true
---
-## Main Window
+# Main Window
The Audiveris main window is composed of 3 panels:
-### Sheet
+## Sheet
This is the large panel on the left side.
- The **Gray** tab, when available, presents the original image using gray values.
@@ -24,7 +24,7 @@ In this Data tab, the staff lines are drawn as thin lines.
All tabs, except the Data tab, can be manually closed.
Most can be re-opened via the `Sheet` pull-down menu.
-### Boards
+## Boards
The right panel is a vertical set of boards.
They provide information and editing functions.
@@ -32,7 +32,7 @@ They provide information and editing functions.
Only basic boards are displayed by default, others are hidden.
A right click in this column allows hiding or displaying any available board.
-### Events
+## Events
The lower left panel is a log of the main events that occurred so far.
diff --git a/docs/_pages/main/output_formats.md b/docs/_pages/main/output_formats.md
index 8a4b98454..6f94758b7 100644
--- a/docs/_pages/main/output_formats.md
+++ b/docs/_pages/main/output_formats.md
@@ -4,7 +4,7 @@ title: Output Formats
parent: Main Features
nav_order: 8
---
-## Output Formats
+# Output Formats
There are 3 possibilities for output of a transcribed score:
diff --git a/docs/_pages/main/pan_zoom.md b/docs/_pages/main/pan_zoom.md
index 9cfd9399d..5c8f56945 100644
--- a/docs/_pages/main/pan_zoom.md
+++ b/docs/_pages/main/pan_zoom.md
@@ -5,9 +5,9 @@ grand_parent: Main Features
parent: Main Window
nav_order: 2
---
-### Pan and Zoom {#pan-and-zoom}
+# Pan and Zoom {#pan-and-zoom}
-#### Moving {#moving}
+## Moving {#moving}
The sheet image is usually larger than the window where the sheet is displayed.
We can move the display over the sheet using different means:
@@ -21,7 +21,7 @@ We can move the display over the sheet using different means:
* By pressing on one of the 4 arrow keys to move the display in related direction,
* By pressing on one of the 4 arrow keys, while `Shift` is held down, to move pixel by pixel.
-#### Zoom {#zoom}
+## Zoom {#zoom}
It can be adjusted in the range [1:8 to 32:1] by several means:
diff --git a/docs/_pages/main/pipeline.md b/docs/_pages/main/pipeline.md
index 4d1905d78..4a350bc88 100644
--- a/docs/_pages/main/pipeline.md
+++ b/docs/_pages/main/pipeline.md
@@ -5,18 +5,16 @@ parent: Main Features
nav_order: 3
has_children: true
---
-## Pipeline
+# Pipeline
{: .no_toc }
-Table of contents
+---
{: .no_toc .text-delta }
-
1. TOC
{:toc}
-
---
-### Global Book Workflow
+## Global Book Workflow
When working on a book, the Audiveris V5 OMR engine can process any sheet of the book independently of
the others.
Only the final gathering of sheets results, which comparatively is a very fast action,
@@ -39,7 +37,7 @@ To save on memory, especially during long interactive sessions, we can ask Audiv
transparently swap all book sheets to disk (except the current sheet).
This is done via the pull-down menu {{ site.book_swap }}.
-### Sheet Pipeline
+## Sheet Pipeline
The processing of a given sheet by the OMR engine is done via a pipeline of some 20 steps
applied, one after the other, on sheet OMR data.
@@ -48,7 +46,13 @@ Here below is the sheet pipeline sequence, with the main inputs and outputs of e
-### Driving the Pipeline
+{: .note }
+Each of these 20 steps is further detailed in dedicated pages below.
+There is no need to go through all of them in a first reading of this handbook.
+Just keep in mind that the documentation is available and is likely to help
+you understand how each of these steps works.
+
+## Driving the Pipeline
A sheet step is like a mini-batch applied on the sheet data, and this is the smallest increment
that the OMR engine can perform.
@@ -63,7 +67,10 @@ Note that selecting the pull-down menu {{ site.sheet_transcribe }} is just anoth
the pull-down menu `Step → PAGE`.
Beware that we cannot directly move the pipeline backward.
-There are two workarounds:
-* Selecting a target step that has already been performed will, after user confirmation,
- reset the sheet data to its BINARY step, then perform all necessary steps up to the target step.
-* We can abandon the book and reload it from a previously saved version.
+There are two indirect workarounds:
+* We can select a target step that has already been performed:
+ 1. we are first prompted for confirmation,
+ 2. the sheet data is then reset to its initial status
+ -- the gray image if available, otherwise the binary image,
+ 3. and all necessary steps are performed up to the target step.
+* We can also abandon the book and reload it from a previously saved version.
diff --git a/docs/_pages/main/run_section.md b/docs/_pages/main/run_section.md
index d14be9875..f8850ada1 100644
--- a/docs/_pages/main/run_section.md
+++ b/docs/_pages/main/run_section.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Main Entities
nav_order: 3
---
-### Pixels assemblies
+# Pixels assemblies
The ``BINARY`` step transforms the input image into a black and white image.
From this step on, the image will contain only black (foreground) pixels on a white background.
@@ -15,24 +15,24 @@ A (black) pixel is just a black square, of dimension 1 x 1, located at some poin
Depending on what the engine has to process (staff lines, stems, beams, etc),
the same pixels can be viewed through one structure or another.
-### Run
+## Run and RunTable
A horizontal (or vertical) contiguous sequence of pixels of the same color is called a
-horizontal (or vertical) "run".
+horizontal (or vertical) ``Run``.
In the same alignment, such run is followed by a run of the opposite color, and so on,
until the image border is reached.
-A "run table" is a rectangular area, made of sequences of runs, all of the same orientation.
+A ``RunTable`` is a rectangular area, made of sequences of runs, all of the same orientation.
Typically, the whole binarized image can be considered, at the same time, as:
- a table of horizontal runs
- a table of vertical runs
-### Section
+## Section and LAG
It can be interesting to transitively join adjacent (black) runs of the same orientation,
according to some compatibility rules.
-Each such resulting assembly is called a "section".
+Each such resulting assembly is called a ``Section``.
Typical compatibility rules are:
- Maximum difference in run lengths
@@ -40,9 +40,12 @@ Typical compatibility rules are:
- Maximum shift on each run end
- Void rule (no check, except adjacency)
-Sections are gathered into LAGs (**L**inear **A**djacency **G**raphs).
+Sections are gathered into ``LAG``s (**L**inear **A**djacency **G**raphs).
-### Concrete example
+Just like a ``RunTable`` gathers ``Run``s of the same orientation,
+a ``LAG`` gathers ``Section``s of the same orientation.
+
+## Sections example
@@ -57,3 +60,11 @@ with length greater than the maximum line thickness are displayed in pale blue.
2. From the horizontal LAG, the remaining pixels are organized in (horizontal) sections
and displayed in pale red.
+## Filament
+
+A ``Filament`` is a dynamic assembly of sections, long and thin, likely to represent lines.
+
+The engine uses:
+- horizontal filaments to detect staff lines and ledgers alignments,
+- vertical filaments to detect stems and legs of endings.
+
diff --git a/docs/_pages/main/scanning.md b/docs/_pages/main/scanning.md
index 38023a0e8..9f7785c8c 100644
--- a/docs/_pages/main/scanning.md
+++ b/docs/_pages/main/scanning.md
@@ -4,7 +4,7 @@ title: Scanning
parent: Main Features
nav_order: 4
---
-## Scanning of paper scores
+# Scanning of paper scores
Audiveris doesn't support direct scanning because there is still no open-source solution for
cross-platform access to scanning devices from Java projects.
diff --git a/docs/_pages/main/score_page.md b/docs/_pages/main/score_page.md
index 8d15d674c..ae46baba0 100644
--- a/docs/_pages/main/score_page.md
+++ b/docs/_pages/main/score_page.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Main Entities
nav_order: 2
---
-### Score of Pages
+# Score of Pages
Looking at the musical content of a given sheet image, we can observe that staves are often gathered
into systems (in which staves are played in sync), and that a given sheet image generally contains
@@ -20,7 +20,7 @@ In Audiveris, this logical containment is modeled as one instance of **Score** p
(since "Score" is the word used by MusicXML), the score containing a sequence of one or several
**Page** instances.
-#### Example
+## Example
To make these concepts more concrete, let's look at the following diagram of a hypothetical book:
@@ -46,7 +46,7 @@ To summarize, in this book we have 2 scores that span over 3 sheets:
- `Page` #2 from `Sheet` #2, followed by
- Single `Page` #1 from `Sheet` #3
-#### Rules
+## Rules
In the vast majority of cases, there is exactly one page per sheet.
diff --git a/docs/_pages/main/sheet_scale.md b/docs/_pages/main/sheet_scale.md
index 388afc106..4d9d16f98 100644
--- a/docs/_pages/main/sheet_scale.md
+++ b/docs/_pages/main/sheet_scale.md
@@ -4,7 +4,7 @@ title: Sheet Scale
parent: Main Features
nav_order: 6
---
-## Sheet Scale
+# Sheet Scale
{: .no_toc }
Table of contents
@@ -13,7 +13,7 @@ Table of contents
{:toc}
---
-### General scaling
+## General scaling
The behavior of steps like GRID (staves, etc), BEAMS and STEMS depends highly on the accuracy
of scaling data estimated during:
@@ -37,7 +37,7 @@ Here are two examples of such histograms:
- If the sheet contains a significant population of beams, we can observe a second peak
which corresponds to the typical beam thickness (12 pixels in this example).
-### Beam thickness
+## Beam thickness
{: .d-inline-block }
new in 5.3
{: .label .label-yellow }
@@ -54,7 +54,7 @@ and simply make a guess on beam thickness (using say 1/2 of staff interline).
And without a precise thickness estimate, chances are the beams will not be correctly detected
and processed in the sheet.
-#### Manual beam correction
+### Manual beam correction
After the SCALE step, but before the BEAMS step, we can manually modify the beam thickness value
as computed by the OMR engine.
@@ -79,11 +79,11 @@ Initially, all rows appear in gray, and the data values, if any, are displayed o
the modified value must be re-entered.
- We may have to perform the correction manually for each and every sheet in the containing book.
-#### Upfront beam specification
+### Upfront beam specification
A different approach is to provide upfront the OMR engine with a beam thickness specification.
-##### Interactive mode
+#### Interactive mode
We can do this using the {{ site.book_parameters }} pull-down menu:
@@ -109,7 +109,7 @@ It can be used at book and/or sheet levels.
- It is only a *specification*, to be used by any subsequent SCALE step.
Hence, to be effectively applied, the SCALE step must be performed (or reperformed).
-##### Batch mode
+#### Batch mode
When running in batch on a brand new input, we can include this beam specification in the
command line arguments, using an option like:
diff --git a/docs/_pages/main/sheet_selection.md b/docs/_pages/main/sheet_selection.md
index 88e3bf88d..364f08a07 100644
--- a/docs/_pages/main/sheet_selection.md
+++ b/docs/_pages/main/sheet_selection.md
@@ -6,7 +6,7 @@ parent: Book Portions
nav_order: 2
---
-## Sheet Selection
+# Sheet Selection
An action launched at the sheet level processes only that sheet.
An action launched at the book level, processes by default all the (valid) sheets of the book.
diff --git a/docs/_pages/main/sheet_validity.md b/docs/_pages/main/sheet_validity.md
index fe986d698..d801edfa8 100644
--- a/docs/_pages/main/sheet_validity.md
+++ b/docs/_pages/main/sheet_validity.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Book Portions
nav_order: 1
---
-## Sheet Validity
+# Sheet Validity
{: .no_toc }
All images in an input file may not be score images: we can find illustration pages, blank pages, etc.
@@ -39,4 +39,6 @@ But validity is supposed to represent the real status of the sheet from the OMR
we should not use it to include or exclude this sheet for some processing.
A side effect of modifying the validity status of a sheet is to nullify all its OMR data!
-Instead, we should use the sheet selection mechanism or the even more powerful [Split and Merge](./split_merge.md) tool.
+Instead, we should use the sheet selection mechanism or the even more powerful
+[Split and Merge](./split_merge.md) tool
+that can be accessed via the {{ site.book_split }} pull-down menu.
diff --git a/docs/_pages/main/sig.md b/docs/_pages/main/sig.md
index 08669a72a..1fad4387f 100644
--- a/docs/_pages/main/sig.md
+++ b/docs/_pages/main/sig.md
@@ -5,9 +5,9 @@ grand_parent: Main Features
parent: Main Entities
nav_order: 5
---
-### Symbol Interpretation Graph
+# Symbol Interpretation Graph
-#### Relation
+## Relation
A Relation instance formalizes a relationship between a source Inter instance and a (separate)
target Inter instance.
@@ -47,7 +47,7 @@ clef and this key (because the vertical positions of this key are not compatible
-#### SIG
+## SIG
A **S**ymbol **I**nterpretation **G**raph (SIG), is simply a graph with Inter instances as vertices
and Relation instances as edges.
diff --git a/docs/_pages/main/split_merge.md b/docs/_pages/main/split_merge.md
index 29ab53925..b1698245d 100644
--- a/docs/_pages/main/split_merge.md
+++ b/docs/_pages/main/split_merge.md
@@ -6,7 +6,7 @@ parent: Book Portions
nav_order: 3
---
-## Split and Merge
+# Split and Merge
{: .no_toc }
This feature is meant to be the Audiveris "Swiss Army Knife" to configure books, images and sheets.
@@ -19,7 +19,7 @@ Table of contents
{:toc}
---
-### Concepts
+## Concepts
The Split and Merge feature relies on the concept of *"PlayList"* that the user can define, modify,
save/reload, and finally use to build the resulting compound book.
@@ -36,10 +36,10 @@ It can also be written from scratch via a plain text editor
Either way, the PlayList can then be used interactively or in batch to produce a compound book
according to the PlayList content.
-### Use cases
+## Use cases
This section lists typical use cases from the end-user point of view.
-#### 4-hands piano sheet
+### 4-hands piano sheet
The request in issue #220
([Support for 4 hands piano sheet](https://github.com/Audiveris/audiveris/issues/220))
@@ -61,7 +61,7 @@ The easiest way to "split" the single input file into two separate books is to o
Then pressing the `Action` button in each dialog builds the corresponding compound books
`DieToteninsel-primo.omr` and `DieToteninsel-secondo.omr` respectively.
-#### Compound book
+### Compound book
The case is described in issue #129
([Allow to load multiple images into one book](https://github.com/Audiveris/audiveris/issues/129))
@@ -81,7 +81,7 @@ In all these cases, the engine will update the sheets where needed and process t
dependencies (slurs, time-signatures, measure IDs) before building the resulting score(s).
-#### Sheet replacement
+### Sheet replacement
We have seen that sheet addition/removal can be done at any time, regardless of the transcription
process of any sheet.
@@ -105,13 +105,13 @@ In this example, we are using references to `.png` image files.
We could as well prefer references to `.omr` book files, containing the same sheets perhaps
partly transcribed.
-### Dialog
+## Dialog
It is accessed via the {{ site.book_split }} menu item.
The dialog large table, meant for the underlying PlayLists, is initially empty.
-#### Populating the PlayList
+### Populating the PlayList
- If we have a PlayList available somewhere, we can open it via the `Open PlayList...` button
in the upper right corner of the dialog.
@@ -126,7 +126,7 @@ The dialog large table, meant for the underlying PlayLists, is initially empty.
- Similarly, via the `Load files` button, we can load one or several Book or Image files and
their corresponding excerpts will be appended at the bottom of the PlayList.
-#### Legend
+### Legend
- There is one row per excerpt, composed of the container name, the sheets specification string
and the resulting count of sheets as selected in this excerpt.
- A container name ends with `.omr` extension to denote a Book, and with another extension
@@ -140,7 +140,7 @@ The dialog large table, meant for the underlying PlayLists, is initially empty.
with different sheets specifications
-- see the example of [Sheet replacement](#sheet-replacement) above.
-#### Editing the PlayList
+### Editing the PlayList
- We have seen that the sheets specification of any excerpt can be manually edited.
- We can add/include and remove excerpts.
@@ -151,7 +151,7 @@ The dialog large table, meant for the underlying PlayLists, is initially empty.
When satisfied with the PlayList, we can save it for future reload or use it immediately as follows.
-#### Building the result
+### Building the result
The `Action!` button launches the building of the compound book according to the PlayList
current content.
@@ -166,7 +166,7 @@ kept separate from its original "parts".
In other words, any further work made on this compound book will not impact the original "parts".
And similarly, any further work made on any of the original "parts" will not impact the compound book.
-### PlayList format
+## PlayList format
A PlayList can be created or saved as a plain XML file,
- with `` as its root element,
@@ -203,7 +203,7 @@ saved:
```
-### CLI option
+## CLI option
There is a new option available on command line interface: `-playlist ` which allows
loading an `.xml` file as a PlayList, provided that file content is compliant with the PlayList
diff --git a/docs/_pages/main/voice_colors.md b/docs/_pages/main/voice_colors.md
index 7bea0ea11..d47faef9a 100644
--- a/docs/_pages/main/voice_colors.md
+++ b/docs/_pages/main/voice_colors.md
@@ -5,7 +5,7 @@ grand_parent: Main Features
parent: Main Window
nav_order: 4
---
-### Voice Colors
+# Voice Colors
By default, as described in the previous section, each score entity is displayed using a color
determined according to the entity kind:
@@ -30,7 +30,7 @@ Within any given part, voice numbers (and thus colors) are assigned as follows:
* Voices starting on the first staff use numbers 1 through 4,
* Voices starting on the second staff use numbers 5 through 8.
-#### Shared Heads
+## Shared Heads
Note that some note heads can be _shared_ between two chords.
In the example above, this is the case in the last staff, for the starting head of each measure
diff --git a/docs/_pages/menus/README.md b/docs/_pages/menus/README.md
index 46b4852c5..d796cf67e 100644
--- a/docs/_pages/menus/README.md
+++ b/docs/_pages/menus/README.md
@@ -2,7 +2,7 @@
layout: default
title: Pull-down menus
parent: References
-nav_order: 1
+nav_order: 3
has_children: true
---
# Pull-down menus
diff --git a/docs/_pages/menus/book.md b/docs/_pages/menus/book.md
index d6f2e11dc..52cb14cde 100644
--- a/docs/_pages/menus/book.md
+++ b/docs/_pages/menus/book.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 2
---
-## Book menu
+# Book menu
{: .no_toc }
@@ -25,65 +25,72 @@ Table of contents
{:toc}
---
-### Recent Books
+## Recent Books
Open a list of recently saved books.
After selection, the book is opened in the state it was saved.
-### Most recent Book
+## Most recent Book
Open the book most recently closed.
-### Open Books
+## Open Books
Open a dialog box allowing to select a book that has been saved before.
-### Split and Merge
+## Split and Merge
Open a dialog to select and combine inputs from different sources (books, image files).
See [Split and Merge](../main/split_merge.md) section.
-### Set Book Parameters
+## Set Book Parameters
Modify parameters for transcription, at global level, book level and sheets level.
See [Book parameters](../main/book_parameters.md).
-### Reset Book to Gray
+## Reset Book to Gray
Reset all sheets of a book to the initial state, as if it were just loaded as a plain image.
-### Reset Book to Binary
+## Reset Book to Binary
Same as `Reset Book to Gray` above, except that the initial processing of the images
from gray-scale to B&W image is kept.
-### Transcribe Book
+## Transcribe Book
Start the transcription of all sheets of the book.
Transcription is by default performed sheet by sheet.
During processing, the user may start editing sheets that have already been transcribed.
-### Rebuild Scores
+## Stop book transcription
+
+Stop the current book transcription at the next step end.
+
+Stop is achieved in a civilized manner, no data is corrupted.
+If desired, the processing can be relaunched manually.
+
+## Rebuild Scores
Force the rebuilding of scores, out of the processed sheets.
-### Swap Book Sheets
+## Swap Book Sheets
Swap to disk all the sheets of current book (except the current sheet).
This is useful to save memory when working on a book with numerous sheets.
When needed, a swapped sheet is transparently reloaded.
-### Select sheets
+## Select sheets
Select some sheets out of the current book, and limit processing to these sheets.
See [Sheets Selection](../main/sheet_selection.md) section.
-### Print Book
+## Print Book
Save the transcribed book in PDF format, so that it can be printed or saved for further purposes.
The name of the output file is derived from the book name.
@@ -91,11 +98,11 @@ The name of the output file is derived from the book name.
By default, the file is saved into book folder, a (newly created) subdirectory of the base output directory.
But we can modify this policy.
-### Print Book as
+## Print Book as
Same as above, except that we can define the file name and the directory where the file is saved.
-### Export Book
+## Export Book
Export the transcribed score as a MusicXML `.mxl` file for exchange with a notation program.
See [Outputs Formats](../main/output_formats.md).
@@ -103,29 +110,29 @@ See [Outputs Formats](../main/output_formats.md).
By default, the file is saved into book folder, a (newly created) subdirectory of the base output directory.
But we can modify this policy.
-### Export Book as
+## Export Book as
Same as above except that we can define the file name and the directory where the file is saved.
-### Sample Book Symbols
+## Sample Book Symbols
Populate the book sample repository with samples derived from relevant inters of all book sheets.
(needs `SAMPLES` topic, see [Samples section](../advanced/samples.md))
-### Browse Book Repository
+## Browse Book Repository
Open a window to browse, check and filter the samples of book repository.
(needs `SAMPLES` topic, see [Samples section](../advanced/samples.md))
-### Save Book Repository
+## Save Book Repository
Save book sample repository to disk into book folder.
(needs `SAMPLES` topic, see [Samples section](../advanced/samples.md))
-### Annotate Book Symbols
+## Annotate Book Symbols
Populate a Zip archive with images and symbol annotations derived from book Inter instances.
@@ -134,18 +141,18 @@ classifiers (Page and/or Patch).
(needs `ANNOTATIONS` topic)
-### Save Book
+## Save Book
Save the collection of all book sheets with the current state of transcription.
By default, the file is saved into book folder, a (newly created) subdirectory of the base output directory.
But we can modify this policy.
-### Save Book as
+## Save Book as
Same as above except that we can define the file name and the directory where the file is saved.
-### Close Book
+## Close Book
Close the current book and releases all its resources.
diff --git a/docs/_pages/menus/debug.md b/docs/_pages/menus/debug.md
index 839539c7e..fd37059f7 100644
--- a/docs/_pages/menus/debug.md
+++ b/docs/_pages/menus/debug.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 8
---
-## Debug menu
+# Debug menu
{: .no_toc }
@@ -25,7 +25,7 @@ Table of contents
{:toc}
---
-### Browse Book...
+## Browse Book...
@@ -37,14 +37,14 @@ measures, chords, glyphs, inters, etc.
* The right part displays the name and value of each data member of the entity currently selected
in the tree.
-### Clear Log
+## Clear Log
This action clears the events panel (located at bottom of main window).
This is meant for an easier focus on the coming events.
Note this does not impact the output, nor the log file.
-### Dump Event Services
+## Dump Event Services
Dump all UI services connected to the current sheet.
diff --git a/docs/_pages/menus/file.md b/docs/_pages/menus/file.md
index 4a2731eb2..01c9e43ae 100644
--- a/docs/_pages/menus/file.md
+++ b/docs/_pages/menus/file.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 1
---
-## File menu
+# File menu
{: .no_toc }
@@ -18,19 +18,19 @@ Table of contents
{:toc}
---
-### Recent Inputs
+## Recent Inputs
Gives a list of the most recent image input files.
A click on the file name opens the file as source image.
-### Input
+## Input
Opens a dialog box allowing to select the image or pdf-file that shall be transcribed.
The dialog pre-selects the folder from where the last input image file was loaded.
-### Exit
+## Exit
Allows to exit Audiveris application in a civilized manner.
You will first be prompted to save or discard any unsaved modification (book, sample repository).
diff --git a/docs/_pages/menus/help.md b/docs/_pages/menus/help.md
index 7228311e9..ea803e9f9 100644
--- a/docs/_pages/menus/help.md
+++ b/docs/_pages/menus/help.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 9
---
-## Help menu
+# Help menu
{: .no_toc }
@@ -18,19 +18,19 @@ Table of contents
{:toc}
---
-### Handbook
+## Handbook
Open this documentation (user-oriented handbook) from Audiveris program.
-### Wiki
+## Wiki
Open Audiveris Wiki.
-### Web Site
+## Web Site
Open Audiveris organization and contained repositories.
-### About
+## About
Open an "à propos" dialog with information about Audiveris program and main external components
it depends upon (Tesseract OCR, Java, OS, machine architecture).
diff --git a/docs/_pages/menus/plugins.md b/docs/_pages/menus/plugins.md
index 943b1bfa1..497837c4c 100644
--- a/docs/_pages/menus/plugins.md
+++ b/docs/_pages/menus/plugins.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 7
---
-## Plugins menu
+# Plugins menu
diff --git a/docs/_pages/menus/popup.md b/docs/_pages/menus/popup.md
index 598e6cd78..bf6ec1f56 100644
--- a/docs/_pages/menus/popup.md
+++ b/docs/_pages/menus/popup.md
@@ -2,14 +2,15 @@
layout: default
title: Pop-up menu
parent: References
-nav_order: 2
+nav_order: 4
---
-## Pop-up menu
+# Pop-up menu
{: .no_toc }
-This pop-up menu appears via a right-click in sheet view.
+This pop-up menu appears via a mouse right-click in a sheet view,
+and is represented by the ``≡`` symbol in this handbook.
It displays _contextual_ information and actions that depend on the sheet latest processing step,
the current location in sheet view and the selected items if any.
@@ -24,43 +25,44 @@ Table of contents
{:toc}
---
-### Chords
+## Chords
Depending on the chord(s) currently selected, this sub-menu allows to modify their configuration
regarding time slot and voice.
-TBD LINK
-### Inters
+See the chapter on [Chords editing](../ui_tools/chords.md).
+
+## Inters
If at least one Inter instance has been selected, this sub-menu lists the selected Inters,
ordered by decreasing grade.
-It allows to delete Inter instance(s) or relation.
+It also allows to delete Inter instance(s) or relation(s).
-### Glyphs
+## Glyphs
If at least one Glyph instance has been selected, the _compound_ glyph
(dynamically built by merging all selected glyphs) appears in this sub-menu.
It allows to assign a specific shape (via a created Inter) to the selected glyph.
-### Slot #n @offset
-If `RHYTHMS` step has been reached, this sub-menu relates to the closest time-slot in containing
-measure stack.
+## Slot #n @offset
+If the `RHYTHMS` step has been reached, this sub-menu relates to the closest time-slot
+in the containing measure stack.
For this time slot, we can:
-* **Dump chords**: list all chords starting on this slot.
-* **Dump voices**: list all voices with chords starting on this slot.
+* **Dump chords**: list all the chords starting on this slot.
+* **Dump voices**: list all the voices with chords starting on this slot.
-### Measure #n
+## Measure #n
If current location lies within a measure, this sub-menu provides actions upon the selected measure.
-A measure is delimited horizontally by left and right bar-lines and vertically by top and bottom
-staves of the containing part.
+A measure is delimited horizontally by the left and right bar-lines and vertically by
+the top and bottom staves of the containing part.
Depending on which steps have already been performed, we can:
* **Dump stack voices**: for the containing vertical stack of measures, display a kind of strip
with time slots in abscissa and voices in ordinate.
-* **Dump measure voices**: same display but limited to containing measure.
-* **Reprocess rhythm**: force re-computation of rhythm data (slots and voices) in current measure.
-* **Merge on right**: merge current measure with the next measure on right.
+* **Dump measure voices**: same display but limited to the containing measure.
+* **Reprocess rhythm**: force re-computation of rhythm data (slots and voices) in the current measure.
+* **Merge on right**: merge the current measure with the next measure on right.
Example of voices dump:
```
@@ -71,32 +73,32 @@ V 1 |Ch#2325 ==================|Ch#2326 |Ch#2828 |Ch#2327 |1/2
V 5 |Ch#2347 |Ch#2348 |Ch#2349 |Ch#2350 |Ch#2351 =========|1/2
```
-### Staff #n
-This sub-menu appears if current location is within a staff height
+## Staff #n
+This sub-menu appears if the current location is within a staff height
(even beyond staff horizontal limits).
We can edit the whole staff or one of its lines (see [Staff Editing](../ui_tools/staff_editor.md)):
- **Edit staff**: Manual editing of all staff lines as a whole
- **Edit lines**: Manual editing of one staff line in isolation
-We can also display vertical projections of whole staff and of staff header,
-provided that ``PLOTS`` advanced topic has been selected.
+We can also display vertical projections of the whole staff and of the staff header,
+provided that the ``PLOTS`` advanced topic has been selected.
-### Part #n
+## Part #n
Allows to manually assign a logical part to this physical part.
-See section on part [Manual mapping](../specific/logical_parts.md#manual-mapping).
+See the section on part [Manual mapping](../specific/logical_parts.md#manual-mapping).
-### System #n
-If current system is not the last one in sheet, this allows to **Merge with system below**.
+## System #n
+If the current system is not the last one in sheet, this allows to **Merge with system below**.
-### Page #n
-Allows to **Reprocess rhythm**, that is force re-computation of rhythm data for the whole page.
+## Page #n
+Allows to **Reprocess rhythm**, that is to force re-computation of rhythm data for the whole page.
-### Score #n
-Allows to manage logical parts in the containing score.
-See chapter on [logical part management](../specific/logical_parts.md)
+## Score #n
+Allows to manage all the logical parts in the containing score.
+See the chapter on [logical part management](../specific/logical_parts.md)
-### Extraction
+## Extraction
Extracts a rectangular portion (or whole) of the underlying binary image and save it to disk.
This is meant for sharing or further analysis.
diff --git a/docs/_pages/menus/sheet.md b/docs/_pages/menus/sheet.md
index eb36f33bd..d87bb0391 100644
--- a/docs/_pages/menus/sheet.md
+++ b/docs/_pages/menus/sheet.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 3
---
-## Sheet menu
+# Sheet menu
{: .no_toc }
@@ -20,24 +20,24 @@ Table of contents
{:toc}
---
-### Undo
+## Undo
Undo last manual edit step, one at a time.
-### Redo
+## Redo
Redo last undone manual edit step, one at a time.
-### Toggle Repetitive Input
+## Toggle Repetitive Input
Switch on/off a mode where a simple click replicates the last inserted shape at the new mouse location.
This mode is convenient to insert a series of identical symbols, such as heads, at different locations.
-### Transcribe Sheet
+## Transcribe Sheet
Start the transcription of just the active sheet.
-### Current status
+## Current status
Flag the current sheet as either valid or invalid (containing no music information, and thus be ignored during transcription of the book).
@@ -45,11 +45,11 @@ This validity status should not be confused with sheet selection made at book le
- An **invalid** sheet contains no music and thus will always be ignored even if selected at book level.
- A sheet can be dynamically **selected** or not, according to user's desire.
-### Set Scaling Data
+## Set Scaling Data
Display and potentially modify scaling data of current sheet.
-### Display Scale plots
+## Display Scale plots
Display plots of two histograms used for sheet scale retrieval:
* The "black" plot deals with vertical black runs, leading to staff line thickness
@@ -63,7 +63,7 @@ leading to staff interline(s).
(needs ``PLOTS`` advanced topic)
-### Display Stem plot
+## Display Stem plot
Display plot of histogram of stem thickness.
@@ -71,7 +71,7 @@ Display plot of histogram of stem thickness.
(needs ``PLOTS`` advanced topic)
-### Display Staves plots
+## Display Staves plots
@@ -80,21 +80,21 @@ leading to barlines extraction.
(needs ``PLOTS`` advanced topic)
-### Display Gray
+## Display Gray
If still available, display the (initial) gray view tab.
-### Display Binary
+## Display Binary
Open if needed, then select the binary view tab.
-### Display Data
+## Display Data
Select the data view tab.
This central sheet view exists from GRID step onwards and is the only one which cannot be manually
closed.
-### Display NoStaff
+## Display NoStaff
Open if needed, then select the "NoStaff" view tab that shows the transcribed score with
"logically erased" staff lines.
@@ -102,28 +102,28 @@ Open if needed, then select the "NoStaff" view tab that shows the transcribed sc
It's helpful to see the quality of the image that is used for the internal score processing,
because staff line removal can lead to collateral damages in some cases.
-### Display line Glyphs
+## Display line Glyphs
Open the "StaffLineGlyphs" view tab that shows just the "removed" pixels of staff lines.
-### Print Sheet as
+## Print Sheet as
Write the transcribed sheet in PDF format, so that it can be printed or saved for further purposes.
The name of the output file is derived from the book name, followed by "\#" and the sheet number if
the book contains more than one sheet.
-### Export Sheet as
+## Export Sheet as
Same as above except that we can define the file name and the folder where the file is saved.
-### Sample sheet Symbols
+## Sample sheet Symbols
Populate the book sample repository with samples derived from relevant inters of this sheet only.
(needs ``SAMPLES`` advanced topic, see [Samples section](../advanced/samples.md))
-### Annotate sheet Symbols
+## Annotate sheet Symbols
Populate a Zip archive with images and symbol annotations derived from inters of this sheet only.
diff --git a/docs/_pages/menus/step.md b/docs/_pages/menus/step.md
index 5c344458d..e06828328 100644
--- a/docs/_pages/menus/step.md
+++ b/docs/_pages/menus/step.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 4
---
-## Step menu
+# Step menu
diff --git a/docs/_pages/menus/tools.md b/docs/_pages/menus/tools.md
index e86f6d5d5..57981a3f4 100644
--- a/docs/_pages/menus/tools.md
+++ b/docs/_pages/menus/tools.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 6
---
-## Tools menu
+# Tools menu
{: .no_toc }
@@ -18,27 +18,27 @@ Table of contents
{:toc}
---
-### Browse Global repository
+## Browse Global repository
Open a dialog to verify and edit the content of the Global sample repository
(this is _the_ only repository which is used for classifier training).
(needs `SAMPLES` topic)
-### Save Global repository
+## Save Global repository
Saves the Global sample repository to disk.
(needs `SAMPLES` topic)
-### Browse a local repository
+## Browse a local repository
Open a dialog to verify and edit a local (book) sample repository
(generally before merging it into the Global repository).
(needs `SAMPLES` topic)
-### Train Classifier
+## Train Classifier
Open a dialog to launch, monitor and evaluate the training of the glyph classifier.
@@ -46,11 +46,11 @@ See [Training](../advanced/training.md) section.
(needs `SAMPLES` topic)
-### Memory
+## Memory
Displays the used memory in the output window
-### Options
+## Options
Opens the options window.
@@ -63,7 +63,7 @@ A search window allows to search for a string part in the option name or its des
For more details, refer to [Options](../advanced/options.md) section.
-### Advanced Topics
+## Advanced Topics
Opens a dialog with a couple of options concerning the program development only.
diff --git a/docs/_pages/menus/view.md b/docs/_pages/menus/view.md
index 3c9a8f85b..d797981c9 100644
--- a/docs/_pages/menus/view.md
+++ b/docs/_pages/menus/view.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Pull-down menus
nav_order: 5
---
-## View menu
+ View menu
{: .no_toc }
@@ -18,81 +18,86 @@ Table of contents
{:toc}
---
-### Width Fit
+# Width fit
Zoom image to window width.
-### Height Fit
+# Height fit
Zoom image to window height.
-### Display invalid sheets
+# Display invalid sheets
Toggle the display all sheets, even invalid ones.
-### Use transparency
+# Use transparency
Display interpretations in transparency according to the computed probability value.
-### Show score Voice (F8)
+# Show jumbo inters (F7)
+
+Toggle the display of certain shapes (dots by default) with a double size
+to ease their visual checking.
+
+# Show score voices (F8)
Toggle the display of notes and lyrics in colors according to the computed voices
(only in output and mixed layer view).
-### Show score Errors (F9)
+# Show score errors (F9)
Toggle the display of erroneous measures in pink background color.
-### Switch Selections (F11)
+# Switch selections (F11)
Toggles the selection modes between glyph, inter and section.
(needs ``SPECIFIC_VIEWS`` advanced topic)
-### Switch Layers (F12)
+# Switch layers (F12)
Toggle between the 3 different layer views (see [Sheet display modes](../main/display_modes.md)).
-### Show Score Slots
+# Show score slots
Display the detected rhythm analysis (only in output and mixed view).
-### Show Annotations
+# Show annotations
Toggle the display of all system, part, measure and rhythm related annotations
(system ID, part name, measure ID, time slot offset).
-### Show chord IDs
+# Show chord IDs
Toggle the display of every chord ID.
This is convenient to visually map chords between [measure strips](./popup.md#measure-n)
and sheet view.
-### Show part names
+# Show part names
Toggle the display of logical part name for every physical part.
-### Show staff Lines
+# Show staff Lines
Toggle the display of staff lines.
(needs ``SPECIFIC_ITEMS`` advanced topic)
-### Show staff Points
+# Show staff Points
Toggle the display of staff lines defining points, the ones that can be manually edited.
(needs ``SPECIFIC_ITEMS`` advanced topic)
-### Show stick Lines
+# Show stick Lines
Toggle the display of the average line of the selected glyph.
(needs ``SPECIFIC_ITEMS`` advanced topic)
-### Show Attachments
+# Show attachments
Toggle the display of specific attachments.
diff --git a/docs/_pages/outputs/README.md b/docs/_pages/outputs/README.md
index 8a14919a0..fec2c21ad 100644
--- a/docs/_pages/outputs/README.md
+++ b/docs/_pages/outputs/README.md
@@ -2,7 +2,7 @@
layout: default
title: Outputs
parent: References
-nav_order: 5
+nav_order: 7
has_children: true
---
# Outputs
diff --git a/docs/_pages/outputs/log.md b/docs/_pages/outputs/log.md
index 9888d06f2..c9f4ec181 100644
--- a/docs/_pages/outputs/log.md
+++ b/docs/_pages/outputs/log.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Outputs
nav_order: 1
---
-## .log files
+# .log files
{: .no_toc :}
---
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Session global log
+## Session global log
All messages displayed in Audiveris events window during the same session are also written into a
separate log file located in Audiveris log folder (see [Cached Folders](../folders/cached.md)).
@@ -32,7 +32,7 @@ The advanced user can precisely customize the logged information by manually edi
configuration file `logback.xml` located in Audiveris config folder
(see [Essential Folders](../folders/essential.md)).
-### Batch books logs
+## Batch books logs
When running in batch, Audiveris can process hundreds of books in a row.
As mentioned above, this results in one global log file, perhaps a huge one.
diff --git a/docs/_pages/outputs/mxl.md b/docs/_pages/outputs/mxl.md
index c6e704384..a5f79cac0 100644
--- a/docs/_pages/outputs/mxl.md
+++ b/docs/_pages/outputs/mxl.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Outputs
nav_order: 2
---
-## .mxl files
+# .mxl files
{: .no_toc :}
---
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Purpose
+## Purpose
These are zip-compressed files of XML music files formatted according to **MusicXML** specification.
Most, if not all, music editors are able to import / export this kind of file,
@@ -30,7 +30,7 @@ Instead of `.mxl` files, which are compressed XML files, Audiveris can export pl
To do this, we just set the option `org.audiveris.omr.sheet.BookManager.useCompression`
to false.
-### Book level
+## Book level
A **book** export provides:
* Either one separate `.mxl` file for each movement found in the book (this is the default).
* Or a single `.mxl` file for a global `opus` containing the separate movements.
@@ -38,6 +38,6 @@ A **book** export provides:
To make Audiveris use opus, we simply set the option `org.audiveris.omr.sheet.BookManager.useOpus`
to true.
-### Sheet level
+## Sheet level
A **sheet** export provides:
* One separate `.mxl` file for each page found in the sheet.
diff --git a/docs/_pages/outputs/omr.md b/docs/_pages/outputs/omr.md
index f9ce229cc..24df042ff 100644
--- a/docs/_pages/outputs/omr.md
+++ b/docs/_pages/outputs/omr.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Outputs
nav_order: 3
---
-## .omr files
+# .omr files
A `.omr` file is Audiveris project file for a given image(s) input file (book).
@@ -20,7 +20,7 @@ since data can be continuously saved to (and restored from) disk while sheets ar
All other Audiveris outputs derive from this project data.
-### File structure
+## File structure
The internal project structure is specific to Audiveris software but, as opposed to commercial
software, it is not opaque and is meant for public access, either via Audiveris API or by direct
@@ -78,7 +78,7 @@ It takes advantage of the image processing performed during the `BEAMS` step to
image areas (spots) where black heads are likely to be recognized.
This image is discarded at the end of `HEADS` step.
-### Memory constraint
+## 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.
@@ -109,7 +109,7 @@ 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**]
-### Schemas documentation
+## Schemas documentation
We wanted to make `.omr` file as open as possible to let end-users and developers use directly
this file for any purpose compliant with Audiveris AGPL license.
@@ -129,7 +129,7 @@ Since Audiveris 5.3, the Split & Merge feature can accept play-list definitions
Audiveris UI or provided as XML files created by any plain text editor.
Consequently, we provide an additional `.xsd` + `.html` pair, this time for a `playlist.xml` file.
-#### Documentation distribution
+### Documentation distribution
We could not integrate the schemas documentation set into Audiveris HandBook on GitHub Pages.
Please tell us if we are wrong, but we could not use GitHub Pages for two reasons:
@@ -155,7 +155,7 @@ You can simply download and expand this ZIP archive locally, to get an easy acce
The various HTML pieces use links to images stored in the `doc-files` sub-folder.
-#### Documentation generation
+### Documentation generation
If, as a developer, you want to (re-)generate this documentation set on your own, please refer to
[Building Schemas Documentation](https://github.com/Audiveris/audiveris/wiki/Schemas-Documentation)
diff --git a/docs/_pages/outputs/pdf.md b/docs/_pages/outputs/pdf.md
index 2263d2c03..4908b4150 100644
--- a/docs/_pages/outputs/pdf.md
+++ b/docs/_pages/outputs/pdf.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Outputs
nav_order: 4
---
-## .pdf files
+# .pdf files
Audiveris can print out a whole book or a single sheet.
diff --git a/docs/_pages/outputs/zip.md b/docs/_pages/outputs/zip.md
index e2f17a451..f91f410c0 100644
--- a/docs/_pages/outputs/zip.md
+++ b/docs/_pages/outputs/zip.md
@@ -5,7 +5,7 @@ grand_parent: References
parent: Outputs
nav_order: 5
---
-## .zip files
+# .zip files
{: .no_toc :}
---
@@ -16,10 +16,10 @@ Table of contents
{:toc}
---
-### Purpose
+## Purpose
These files are containers mainly used for training material.
-### Book
+## Book
A book folder (let's name it "BOOK") may contain:
@@ -39,7 +39,7 @@ This is just an output of Audiveris 5.x, meant for the future page and patch cla
for 6.x versions.
It provides sheet image and symbol annotations (shape + bounding box) for each recognized inter.
-### Global
+## Global
These files are located in the `TRAIN_FOLDER`.
See section on [Essential folders](../folders/essential.md).
diff --git a/docs/_pages/quick/export.md b/docs/_pages/quick/export.md
index a66808960..2b5db454a 100644
--- a/docs/_pages/quick/export.md
+++ b/docs/_pages/quick/export.md
@@ -4,7 +4,7 @@ title: Export
nav_order: 4
parent: Quick Tour
---
-## Export
+# Export
From the input image, Audiveris OMR engine has gradually built specific information that we
collectively refer to as "_OMR data_".
diff --git a/docs/_pages/quick/launch.md b/docs/_pages/quick/launch.md
index 16ae49a8b..447e772ef 100644
--- a/docs/_pages/quick/launch.md
+++ b/docs/_pages/quick/launch.md
@@ -4,7 +4,7 @@ title: Launch
nav_order: 1
parent: Quick Tour
---
-## Launch
+# Launch
For the sake of simplicity, let's assume we are using Windows OS and have installed Audiveris via
the provided Windows Installer available in the Audiveris
diff --git a/docs/_pages/quick/load.md b/docs/_pages/quick/load.md
index 76f54ca11..7ddd9ae46 100644
--- a/docs/_pages/quick/load.md
+++ b/docs/_pages/quick/load.md
@@ -4,7 +4,7 @@ title: Load
nav_order: 2
parent: Quick Tour
---
-## Load
+# Load
To load an image from disk, we can use the pull-down menu {{ site.file_input }}:
diff --git a/docs/_pages/quick/play.md b/docs/_pages/quick/play.md
index ed081a0d1..603e1c146 100644
--- a/docs/_pages/quick/play.md
+++ b/docs/_pages/quick/play.md
@@ -4,7 +4,7 @@ title: Play
nav_order: 5
parent: Quick Tour
---
-## Play
+# Play
Strictly speaking, this feature is not part of Audiveris, but rather pertains to an
external program (a simple music sequencer or some high-level editor).
diff --git a/docs/_pages/quick/transcribe.md b/docs/_pages/quick/transcribe.md
index 9ed001d22..5be22d3ca 100644
--- a/docs/_pages/quick/transcribe.md
+++ b/docs/_pages/quick/transcribe.md
@@ -4,7 +4,7 @@ title: Transcribe
nav_order: 3
parent: Quick Tour
---
-## Transcribe
+# Transcribe
Transcription is the heart of OMR, the difficult process to infer high-level music information
from low-level graphical data.
diff --git a/docs/_pages/references.md b/docs/_pages/references.md
index c5062577e..d87870b8e 100644
--- a/docs/_pages/references.md
+++ b/docs/_pages/references.md
@@ -3,13 +3,24 @@ layout: default
title: References
nav_order: 7
has_children: true
+has_toc: false
---
# References
-These sections are meant for direct reference only.
+This ``References`` chapter presents a few key topics that are not mandatory for a first reading.
-* Inter editors
-* Pull-down and pop-up menus.
-* UI boards.
-* Folders used according to Operating System.
-* All kinds of output files.
+In each topic, it is meant to be exhaustive and often provides pointers back to
+more specific and detailed sections in the handbook presentation.
+
+Table of contents
+{: .text-delta }
+
+| Topic | Content |
+| :--- | :--- |
+| [Steps internals](./steps/README.md) | Internals of each engine processing step |
+| [Inter editors](./ui_tools/inter_editors.md) | All different editors per Inter kind |
+| [Pull-down menus](./menus/README.md) | All the pull-down menus |
+| [Pop-up menu](./menus/popup.md) | The contextual pop-up menu |
+| [Boards](./boards/README.md) | All the UI boards in right column |
+| [Folders](./folders/README.md) | All the folders used according to the host operating system |
+| [Outputs](./outputs/README.md) | All kinds of output files |
diff --git a/docs/_pages/specific/bar_repeat.md b/docs/_pages/specific/bar_repeat.md
index 0f1f1f1a6..9a691d3dd 100644
--- a/docs/_pages/specific/bar_repeat.md
+++ b/docs/_pages/specific/bar_repeat.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 5
has_children: false
---
-## Bar Repeat
+# Bar Repeat
{: .no_toc }
{: .d-inline-block }
new in 5.3
@@ -21,7 +21,7 @@ Table of contents
{:toc}
---
-### Example
+## Example
@@ -33,7 +33,7 @@ to repeat the previous two measures (#4 and #5).
We could also encounter a four-bar sign, to repeat the four previous measures.
-### Model
+## Model
Since release 5.3, Audiveris OMR engine is able to recognize both:
- The repeat sign itself, with either 1, 2 or 4 slashes.
@@ -42,7 +42,7 @@ It should correspond to the count of slashes in the repeat sign.
-### Editing
+## Editing
If needed, we can manually assign or drag these signs from the shape palette,
using the three symbols available in ``Barlines`` set.
@@ -58,7 +58,7 @@ We can choose a predefined item from the ``Parts`` numbers.
Or pick up the custom ``0`` item and then manually assign the desired value.
-### Output
+## Output
The MusicXML output is correctly populated with these bar repeat signs
and with the content of the repeated measures.
diff --git a/docs/_pages/specific/drums.md b/docs/_pages/specific/drums.md
index 1ac333e0d..b631b72e2 100644
--- a/docs/_pages/specific/drums.md
+++ b/docs/_pages/specific/drums.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 1
has_children: false
---
-## Drums
+# Drums
{: .no_toc }
{: .d-inline-block }
updated for 5.4
@@ -23,7 +23,7 @@ Table of contents
{:toc}
---
-### Example
+## Example
This [Wikipedia article](https://en.wikipedia.org/wiki/Percussion_notation) provides a good
introduction to drum notation.
@@ -42,7 +42,7 @@ Note this handbook contains a [User editing session](../ui_examples/eyes/README.
3. Though not specific to drum notation, we can frequently observe
[multi-measure rests](./multi_rest.md) and [measure-repeat signs](./bar_repeat.md).
-### Mandatory processing switches
+## Mandatory processing switches
To be able to transcribe the example above, we have to set two specific processing book parameters,
available in the dialog {{ site.book_parameters }}, in the section named "Staves",
@@ -55,7 +55,7 @@ In batch mode, we can also set these switches at the command line interface leve
> -option org.audiveris.omr.sheet.ProcessingSwitches.drumNotation=true
-### Additional switches
+## Additional switches
Beside the two mandatory switches, it is worth paying attention to two other lines:
- One is the "**Barline height**", located just above, in the "Scaling specifications".
@@ -73,7 +73,7 @@ It has no concrete impact on the example at hand, because there are other multi-
available for the OMR engine to measure the score interline value.
This switch will get more important when we address the case of [Snippets](./snippets.md).
-### Drum set mapping
+## Drum set mapping
There seems to be no universal specification for drum set mapping, only some recommendations.
This means that, depending on score author, the mapping can be different.
@@ -100,7 +100,7 @@ in theh user ``config`` folder.
- To "nullify" an existing default entry, we simply specify a "``null``" value
for its "``sound``" attribute.
-### Transcription
+## Transcription
Among the examples used when working on drums with Brian, we can recommend the
[Redeye Percussion](https://www.redeyepercussion.com/) site.
@@ -148,7 +148,7 @@ It is organized as follows:
- The last row presents the playing **signs** [^playing_signs] (open, half-open, closed) that can
appear away from heads.
-## Appendix
+# Appendix
Here below is the content of the ``drum-set.xml`` file provided in the Audiveris ``res``
application folder.
diff --git a/docs/_pages/specific/fingering_plucking.md b/docs/_pages/specific/fingering_plucking.md
index 00483d01f..5c30bf35f 100644
--- a/docs/_pages/specific/fingering_plucking.md
+++ b/docs/_pages/specific/fingering_plucking.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 8
has_children: false
---
-## Fingering and Plucking
+# Fingering and Plucking
{: .no_toc }
{: .d-inline-block }
completed in 5.3
@@ -26,21 +26,21 @@ Table of contents
{:toc}
---
-### Example
+## Example
Here is an example with fingering indications (in red squares)
and plucking indications (in green circles):
-### Detection
+## Detection
The OMR engine must be explicitly told to detect these indications.
This can be done via the processing switches in the {{ site.book_parameters }} pull-down menu:
-### Insertion
+## Insertion
Regardless of the switches values, we can always manually assign or drag & drop these
indications from the shape board:
@@ -52,7 +52,7 @@ indications from the shape board:
| Fingerings |  |
| Pluckings |  |
-### Export
+## Export
These indications get exported to MusicXML and are thus visible from MuseScore for example:
diff --git a/docs/_pages/specific/fonts.md b/docs/_pages/specific/fonts.md
index 873be85f8..7156bb2f4 100644
--- a/docs/_pages/specific/fonts.md
+++ b/docs/_pages/specific/fonts.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 2
has_children: false
---
-## Fonts
+# Fonts
{: .no_toc }
{: .d-inline-block }
new in 5.3
@@ -19,7 +19,7 @@ Table of contents
{:toc}
---
-### Music fonts
+## Music fonts
Before 5.3 release, only one music font family was used (**Musical Symbols** font initially,
later replaced by **Bravura** font for SMuFL compliance).
@@ -27,7 +27,7 @@ later replaced by **Bravura** font for SMuFL compliance).
Since 5.3 release, we can tell Audiveris which music font family to use by default,
or for a given book or sheet.
-#### Head symbols
+### Head symbols
This choice is key for **head symbols**, since the OMR engine uses a *template matching* technique to
detect them during the HEADS step.
@@ -53,7 +53,7 @@ especially for all the cross-like shapes.
- Within jazz fonts, Finale Jazz and Jazz Perc differ mainly by their width, and impact
on template matching is more visible on oval-like shapes.
-#### Other symbols
+### Other symbols
For symbols other than head symbols, such as Clef, Flag, etc,
recognition is not based on template matching but on a neural network.
@@ -67,7 +67,7 @@ The reason is the current network needs a glyph to work upon, and there is yet n
a head glyph *reliably*.
[^prototype]
-#### Music fonts hierarchy
+### Music fonts hierarchy
Not all symbols are available in every music font family.
@@ -84,7 +84,7 @@ The current family hierarchy is as follows:[^musical_symbols]
└── Musical Symbols
```
-### Text fonts
+## Text fonts
Texts recognition is less sensitive to font family, compared to music symbols recognition.
The main reason is that Audiveris delegates texts recognition to Tesseract OCR.[^ocr_font]
@@ -99,7 +99,7 @@ Since 5.3 release, we can tell Audiveris which text font family to use among the
Proper choice of text font family will result in a better consistency between the input image
and its displayed transcription.
-### Selection of fonts families
+## Selection of fonts families
In interactive mode, we can use the {{ site.book_parameters }} dialog in its ``Music font``
and ``Text font`` fields:
diff --git a/docs/_pages/specific/logical_parts.md b/docs/_pages/specific/logical_parts.md
index 5e934bdd3..92c6daf61 100644
--- a/docs/_pages/specific/logical_parts.md
+++ b/docs/_pages/specific/logical_parts.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 3
has_children: false
---
-## Logical Parts
+# Logical Parts
{: .no_toc }
{: .d-inline-block }
new in 5.3
@@ -22,7 +22,7 @@ Table of contents
{:toc}
---
-### Definition
+## Definition
A part is generally meant to represent a given music instrument.
It contains one stave, or two staves (piano example), or even 3 staves (organ).
@@ -35,7 +35,7 @@ In many cases, one (physical) part in a system corresponds to another (physical)
following system(s). We refer to this logical sequence as a **logical** part, which represents
the same instrument all along the score.
-### Parts mapping
+## Parts mapping
In some cases, from one system to the next, the system composition in terms of physical parts may vary
as shown in the following example:
@@ -57,11 +57,10 @@ We call this action: "***Part collation***" (into logical parts).
Part collation is automatically triggered at the end of score transcription,
and before any export to MusicXML.
We can also manually trigger parts collation.
-This is done via a right-click in a score area, which opens a pop-up menu as follows:
+This is done via a right-click in a score area, which opens a contextual menu as follows:
-To visualize the current mapping, one easy way is to tick the item ``Show part names``
-in the ``View`` pull-down menu.
+To visualize the current mapping, one easy way is to use the {{ site.view_parts }} pull-down menu.
This results in:
@@ -75,7 +74,7 @@ Each physical part is prefixed with the name of its corresponding logical part.
- (blank) since we have yet no name for this logical part
- PIANO (displayed in small size with a slight vertical offset)
-### Editing of logical parts
+## Editing of logical parts
Still via a right-click in the score area, we can open an editor on logical parts:
@@ -117,7 +116,7 @@ This means that the logicals just saved are now locked (but can be manually unlo
Notice also that the main score window now displays the updated parts names:
-### Unlocked/Locked logicals configuration
+## Unlocked/Locked logicals configuration
The "Parts collation" action works differently according to the unlocked/locked status
of our logicals configuration.
@@ -134,7 +133,7 @@ For each physical part -- not manually mapped -- found in sequence in the score:
2. The physical part is assigned to a compatible logical part
or a warning is displayed for this un-mappable physical part.
-### Mapping algorithm
+## Mapping algorithm
The parts mapping works as follows.
For every physical part checked against a logical part:
@@ -150,7 +149,7 @@ then checking goes bottom-up from the piano part,
and goes top-down for the parts located below the piano part.
- If there is no piano part, checking is done bottom-up.
-### Manual mapping
+## Manual mapping
If the score gets too complex for the OMR engine, we can always fall back
to the manual mapping of any "un-mappable" physical part.
diff --git a/docs/_pages/specific/multi_rest.md b/docs/_pages/specific/multi_rest.md
index 20da8993b..91d984b85 100644
--- a/docs/_pages/specific/multi_rest.md
+++ b/docs/_pages/specific/multi_rest.md
@@ -6,7 +6,7 @@ nav_order: 6
has_children: false
---
-## Multi-Measure Rest
+# Multi-Measure Rest
{: .no_toc }
{: .d-inline-block }
new in 5.3
@@ -22,7 +22,7 @@ Table of contents
{:toc}
---
-### Example
+## Example
It is drawn as a thick horizontal line centered on staff middle line
with serifs at both ends, completed by a time-like number drawn above the staff.
@@ -31,12 +31,12 @@ with serifs at both ends, completed by a time-like number drawn above the staff.
In the example above, we have instances of multiple measure rests, on 5-line and 1-line staves.
-### Model
+## Model
Since release 5.3, with no need for a specific processing switch, these multiple rests are detected
together with the related measure count number.
-### Editing
+## Editing
If not detected, we can still assign or drag a multiple rest item from the shape palette
in its ``Rests`` set:
diff --git a/docs/_pages/specific/octave_shift.md b/docs/_pages/specific/octave_shift.md
index 067733c7d..af5254dd5 100644
--- a/docs/_pages/specific/octave_shift.md
+++ b/docs/_pages/specific/octave_shift.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 4
has_children: false
---
-## Octave Shift
+# Octave Shift
{: .no_toc }
{: .d-inline-block }
new in 5.3
@@ -22,7 +22,7 @@ Table of contents
{:toc}
---
-### Examples
+## Examples
Here is an example of a one-line shift:
@@ -33,7 +33,7 @@ We can consider we have one "logical" shift composed of three "physical" shifts.
-### Recognition
+## Recognition
Automatic recognition of octave shifts by the OMR engine is difficult for various reasons:
- The value is not always just a number to be found in {8, 17, 22} set.
@@ -46,7 +46,7 @@ step by the current classifier, which requires identified glyphs.
-### Model
+## Model
In Audiveris, we have chosen to focus on a simplified model.
@@ -67,9 +67,9 @@ A multi-line (logical) shift is implemented as a vertical sequence of several (p
The OMR engine may recognize just the value portion of an octave shift, but it is then rather
easy for the end-user to edit the line portion.
-### Editing
+## Editing
-#### Location
+### Location
First things first, we need the shift value.
@@ -91,7 +91,7 @@ At drop time, the last staff is kept as the related staff.
-#### Single line editing
+### Single line editing
As usual, a double-click on the shift Inter opens a dedicated editor on it.
@@ -114,7 +114,7 @@ in the system above, the initial shift gets separated in two shifts, one for eac
In these forced cases, the initial one-line shift has evolved to a multiple-line shift.
And it can continue its evolution.
-#### Multiple line editing
+### Multiple line editing
@@ -129,7 +129,7 @@ The picture above represents the current status of a 3-line shift being edited:
Forcing the first line downwards (or the last line upwards) allows to shrink the shift
and reduce the number of lines, potentially down to a single line shift.
-#### End
+### End
Clicking outside any handle completes the current editing.
diff --git a/docs/_pages/specific/snippets.md b/docs/_pages/specific/snippets.md
index f8000a7bd..0b3fe61d1 100644
--- a/docs/_pages/specific/snippets.md
+++ b/docs/_pages/specific/snippets.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 0
has_children: false
---
-## Snippets
+# Snippets
{: .no_toc }
{: .d-inline-block }
new in 5.4
@@ -26,13 +26,13 @@ Table of contents
{:toc}
---
-### Challenges
+## Challenges
Let's have a closer look at this image (By Hyacinth, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=27409005):
-#### Interline
+### Interline
If we naively launch Audiveris on this input image, we almost immediately get this alert message:
@@ -62,7 +62,7 @@ For the sake of completion, here below are the black histogram and the combo his
|The black histogram gives correct values for the typical staff line height (4 pixels) and the typical beam height (16 pixels) |  |
|The combo histogram should give the typical interline value, but provides only erratic values | |
-#### Barline height
+### Barline height
Another consequence of the lack of multi-line staves in the input image concerns the typical
barline height that the engine should expect.
@@ -82,7 +82,7 @@ But let's consider this other example, with a 5-line staff and a 1-line staff:
The typical barline height for the 1-line staff is here the same as for the 5-line staff, that is 4 interlines.
-### Specifications
+## Specifications
Since the engine has no way to guess by itself the needed values of interline and barline height, we have to tell the engine which values to use for the image at hand.
@@ -109,7 +109,7 @@ We have to measure the typical height of a note head or half the typical height
We can do so by drawing a lasso either in the Binary tab, or in the Data tab (once the Pixel board has been opened).
This gives about 31 pixels for our snippet example.
-### Transcription
+## Transcription
Once the book parameters are correctly set, the snippet gets perfectly transcribed.
Here is the final result using the MuseScore plugin:
diff --git a/docs/_pages/specific/tablature.md b/docs/_pages/specific/tablature.md
index 3db79970e..9be8c8aae 100644
--- a/docs/_pages/specific/tablature.md
+++ b/docs/_pages/specific/tablature.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 9
has_children: false
---
-## Tablature
+# Tablature
{: .no_toc }
{: .d-inline-block }
new in 5.3
@@ -22,7 +22,7 @@ Table of contents
{:toc}
---
-### Example
+## Example
@@ -32,7 +32,7 @@ There exist also tablatures for 4-string bass guitar, represented with 4 lines.
While a standard staff would begin with a clef (G, F or C), this tablature staff begins
with a "TAB" indication.
-### Detection
+## Detection
By default, tablatures are not detected.
To enable their detection, we have to explicitly set the processing switches
@@ -45,7 +45,7 @@ Typically a cluster of 5 lines is considered as a "standard" 5-line staff.
If properly enabled, 4- or 6-line clusters are detected as "tablatures" staves.
-### Processing
+## Processing
There is no processing *per se* by the OMR engine.
diff --git a/docs/_pages/specific/tremolo.md b/docs/_pages/specific/tremolo.md
index e70f241f3..f14deec5b 100644
--- a/docs/_pages/specific/tremolo.md
+++ b/docs/_pages/specific/tremolo.md
@@ -5,7 +5,7 @@ parent: Specific Features
nav_order: 7
has_children: false
---
-## Tremolo
+# Tremolo
{: .no_toc }
{: .d-inline-block }
new in 5.3
diff --git a/docs/_pages/steps/README.md b/docs/_pages/steps/README.md
new file mode 100644
index 000000000..94c169938
--- /dev/null
+++ b/docs/_pages/steps/README.md
@@ -0,0 +1,26 @@
+---
+layout: default
+title: Steps internals
+parent: References
+nav_order: 1
+has_children: true
+---
+# Steps internals
+
+All the 20 steps of the OMR engine are presented here in chronological order.
+
+A step presentation is generally organized in:
+- goal
+- inputs
+- outputs
+- main processing operations
+
+Some steps work on the sheet as a whole.
+Other steps work system per system, and can present:
+- sheet-level prolog
+- system-level processing
+- sheet-level epilog
+
+{: .note :}
+This type of documentation is halfway between a user manual (functional) and a developer manual (implementation).
+Reading it is not obligatory, but should help understand step by step how the engine behaves and how to best control it.
\ No newline at end of file
diff --git a/docs/_pages/steps/beams.md b/docs/_pages/steps/beams.md
index bd441d46c..01ab2467a 100644
--- a/docs/_pages/steps/beams.md
+++ b/docs/_pages/steps/beams.md
@@ -1,8 +1,128 @@
---
layout: default
title: BEAMS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 7
---
-### BEAMS step
+# BEAMS step
+{: .no_toc }
+
+The purpose of the ``BEAMS`` step is to detect all beams in a sheet, both standard
+and small beams if any.
+
+As a side effect, it also detects any multi-measure rest found in the sheet.
+
+---
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+
+## Inputs
+
+- The no-staff image
+
+## Outputs
+
+- The beams and beam-hooks candidates
+- The multi-measure rests candidates
+
+## Prolog: retrieval of potential beams glyphs
+
+Geometrically, a beam is a filled parallelogram, rather horizontal, long and thick.
+
+To focus as much as possible on all relevant beam candidates and only them,
+the input data is carefully worked upon.
+
+The engine cleaning actions are as follows:
+
+1. Remove all the staff lines, by taking the no-staff image as input
+1. Remove all stem-like items, by removing any horizontal run whose length is smaller
+than the maximum stem thickness
+1. Smoothen the image to get rid of noise and small holes, by applying a median filter
+followed by a gaussian filter, both using a 3x3 kernel
+1. Highlight the spots whose thickness is close to the beam expected thickness;
+this is the result of a morphological closing operation (a dilation followed by an erosion)
+using a disk-shaped mask whose diameter is the expected beam thickness
+-- the smaller value, when the sheet exhibits two beam thickness values
+
+The resulting cleaned image uses a gray scale.
+All spots with a rather high density of black are interesting for two purposes,
+beams recognition of course but also black heads recognition[^head_spots].
+
+Regarding beam recognition, the prolog final actions are as follows:
+1. Binarize the resulting gray image, using a global threshold
+1. Build all glyphs (spots) from the image runs, using runs connections
+1. Dispatch all spots to their containing systems
+-- any spot located between two systems is dispatched to both
+
+As an example, the images below result from the processing of a score of rather poor-quality.
+Notice that, in the cleaned image, the tiny black or white items have disappeared.
+
+| Legend | Image |
+| :---: | :---: |
+| Binary image |  |
+| Cleaned image |  |
+| Detected glyphs |  |
+
+The ``binary`` tab is always available via the {{ site.sheet_binary }} pull-down menu.
+The two other tabs require specific booleans to be set in the {{ site.tools_options}} menu,
+respectively ``displayGraySpots`` and ``displayBeamSpots``.
+
+## Beams detection
+
+Each individual spot glyph is checked for being a good beam candidate:
+- width
+- mean thickness
+- slope of the glyph center line (least squares approximation)
+
+These very simple criterias help discarding some glyphs
+(displayed in gray in the image above).
+
+At this point, a glyph may represent a beam, or a portion of a beam, or several beams
+stuck together, or a black note head, etc...
+
+For each of the remaining glyphs (displayed in pale blue), the engine builds
+a structure, based on the glyph vertical sections:
+
+| Legend | Image |
+| :---: | :---: |
+| Sections |  |
+
+The structure focuses on the top and bottom lines of the most significant vertical sections
+-- the {{ site.view_selections }} menu allows the display of sections.
+
+These lines are likely to represent the top and bottom borders of the underlying
+individual beams.
+They are checked for straightness and consistent slope.
+
+A thick structure is likely to represent beams stuck one upon the other,
+it is thus split into thinner structures:
+
+| Legend | Image |
+| :---: | :---: |
+| Double beam glyph |  |
+
+The final structures are converted to elementary beams,
+which can be further merged or extended horizontally to full beams and beam hooks Inters.
+
+| Legend | Image |
+| :---: | :---: |
+| Beams inters |  |
+
+At the end of this ``BEAMS`` step, all the created Inters are just candidates.
+In particular, Inters for short beams and beam hooks may still coexist for the same underlying glyph!
+
+These beam Inters are displayed in red: they are still in an *abnormal* status
+becaused they are not yet linked to any stem!
+
+Only the following steps, especially the ``REDUCTION`` step, will allow the engine
+to confirm or discard these candidates.
+
+## Multi-measure rests detection
+
+TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO
+
+[^head_spots]: This is a forward reference to the [``HEADS`` step](./heads.md), since filled black heads are very likely to appear in these spots. A specially binarized version of the cleaned image is thus set aside to be used later by the ``HEADS`` step.
\ No newline at end of file
diff --git a/docs/_pages/steps/binary.md b/docs/_pages/steps/binary.md
index a0f3a7863..fec8ef942 100644
--- a/docs/_pages/steps/binary.md
+++ b/docs/_pages/steps/binary.md
@@ -1,8 +1,129 @@
---
layout: default
title: BINARY step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 2
---
-### BINARY step
+# BINARY step
+{: .no_toc }
+
+Many components of the Audiveris engine are meant to work on a black & white input image.
+In such image, the black pixels compose the foreground and the white pixels the background.
+
+The goal of the BINARY step is to provide this black & white image.
+
+---
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+## Inputs
+
+- The gray image of the sheet
+- The chosen binarization filter -- by default, this is the _adaptive_ filter
+
+## Output
+
+- The black & white image of the sheet
+
+## Processing
+
+The gray value -- a number between 0 and 255 -- of each image pixel is compared with
+a threshold value.
+The result is:
+- black (0) if gray value <= threshold value
+- white (255) if gray value > threshold value
+
+What is this _threshold_ value?
+It depends on the binarization filter used on the sheet image.
+
+Via the {{ site.book_parameters }} pull-down menu, the precise filter and its parameters
+can be defined for the default, book and sheet scopes.
+
+### The GLOBAL filter
+
+This is the older filter.
+
+It provides a single threshold value which is applied globally on every pixel
+of the gray image.
+
+The threshold default value is ``140``, and we can change this value
+via the {{ site.book_parameters }} pull-down menu.
+
+It generally provides good results, except when the input image exhibits different
+illumination values.
+Let's consider the ``BachInvention5.png`` image,
+available in the ``data/examples`` folder of Audiveris.
+
+Here is the bottom part of the gray image:
+
+
+
+Note that the image appears dark on the left and pale on the right.
+If we apply the _global_ filter on it, we get this binary image:
+
+
+
+The following engine steps will miss both the left part and the right part of this system.
+The left part because almost every pixel looks like foreground.
+The right part because several staff lines lack foreground pixels.
+
+In this case, increasing or decreasing the overall threshold value has no point, because it cannot improve both parts at the same time.
+We need something more sensitive to the local environment.
+
+### The ADAPTIVE filter
+
+This is the newer filter.
+
+Instead of being a constant value, a specific threshold value is now computed for every pixel,
+based on its location in the image.
+
+The actual gray value is measured for every pixel in a rectangular neighborhood
+around the current location.
+Based on this population, the engine computes two values:[^threshold_computation]
+- ``mean``: the mean gray value,
+- ``std_dev``: the standard deviation of gray values.
+
+The resulting threshold is then defined according to the following formula:
+> threshold = mean_coeff * mean + std_dev_coeff * std_dev
+
+The parameters are by default ``0.7`` for ``mean_coeff`` and ``0.9`` for ``std_dev_coeff``.
+We can modify them via the {{ site.book_parameters }} pull-down menu.
+
+On the same example, we now get this binary image:
+
+
+Our experience on hundreds of gray images has shown that the adaptive filter gives good results
+and its default parameters are OK.
+Therefore, the _adaptive_ filter has been promoted as the default binarization filter
+for every input...
+
+... until [this discussion](https://github.com/Audiveris/audiveris/discussions/703)
+was recently posted on Audiveris forum.
+Here below is a portion of the gray input image posted in the discussion:
+
+
+
+We can notice that the staff lines, as well as the bar lines, are painted in a pale gray color.
+Here, the pale gray is not a transition between black and white as seen on the other scores.
+
+Applying the standard _adaptive_ filter gives this binary result:
+
+
+
+Here, we must go back to the _global_ filter.
+With a threshold value set to 225, we now obtain this binary result:
+
+
+
+## Binarization board
+
+To observe the binarization behavior, we can use the ``binarization board`` available in the ``Gray`` and ``Binary`` tabs.
+
+It presents the selected filter in action around the current user location.
+
+Please refer to the [Binarization board](../boards/binarization.md) dedicated section.
+
+[^threshold_computation]: The implementation does not use brute force to compute mean and standard deviation around each and every point, but the result is the same.
\ No newline at end of file
diff --git a/docs/_pages/steps/chords.md b/docs/_pages/steps/chords.md
index e72de08e9..e75e41b4a 100644
--- a/docs/_pages/steps/chords.md
+++ b/docs/_pages/steps/chords.md
@@ -1,8 +1,8 @@
---
layout: default
title: CHORDS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 15
---
-### CHORDS step
+# CHORDS step
diff --git a/docs/_pages/steps/cue_beams.md b/docs/_pages/steps/cue_beams.md
index dd621b267..82fe90114 100644
--- a/docs/_pages/steps/cue_beams.md
+++ b/docs/_pages/steps/cue_beams.md
@@ -1,8 +1,8 @@
---
layout: default
title: CUE_BEAMS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 12
---
-### CUE_BEAMS step
+# CUE_BEAMS step
diff --git a/docs/_pages/steps/curves.md b/docs/_pages/steps/curves.md
index d5b4e4f11..5ae362d63 100644
--- a/docs/_pages/steps/curves.md
+++ b/docs/_pages/steps/curves.md
@@ -1,8 +1,8 @@
---
layout: default
title: CURVES step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 16
---
-### CURVES step
+# CURVES step
diff --git a/docs/_pages/steps/grid.md b/docs/_pages/steps/grid.md
index 817d906a5..354479283 100644
--- a/docs/_pages/steps/grid.md
+++ b/docs/_pages/steps/grid.md
@@ -1,8 +1,186 @@
---
layout: default
title: GRID step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 4
---
-### GRID step
+# GRID step
+{: .no_toc }
+
+The purpose of the ``GRID`` step is to retrieve the systems and staves of the sheet.
+
+---
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+## Inputs
+
+- The black & white image
+- The maximum staff line thickness
+- The typical interline value (and the small interline value if any)
+
+## Outputs
+
+- The [LAG](../main/run_section.md#lag) of horizontal [sections](../main/run_section.md#section)
+- The LAG of vertical sections
+- The staff lines organized in staves
+- The global skew of the image
+- For every staff:
+ - the barlines if any
+ - the vertical connectors if any with a staff above or below
+ - the starting brace if any
+ - the starting bracket if any
+- The gathering of staves into systems
+- The no-staff image
+
+## Processing
+
+### Filtering runs and sections
+
+First, all the foreground (black) pixels of the binary image are organized into vertical
+[runs](../main/run_section.md#run).
+
+Then, the engine determines a maximum line thickness, based on the maximum staff line thickness
+provided by the [``SCALE`` step](./scale.md#outputs),
+slightly augmented to cope with potentially thicker ledgers.
+
+Any vertical run which is longer than this maximum staff line thickness cannot be a
+pure portion of a staff line -- it must be a (portion of) crossing object.
+
+Therefore:
+- All "long" vertical runs are set aside into the _vertical LAG_.
+- All remaining pixels are organized in horizontal runs gathered in the _horizontal LAG_.
+
+Then, within each [LAG](../main/run_section.md#lag), adjacent runs are organized into
+[sections](../main/run_section.md#section).
+
+The horizontal sections are further separated between short sections and long sections,
+because the long sections will drive the staff lines detection.
+
+We can visualize this material.
+To do so, we have to use the {{ site.tools_options}} pull-down menu and there
+tick the boolean constant ``displayRuns`` (it is located in class ``LinesRetriever``).
+
+| Content | View |
+| :--- | :---: |
+| Binary image |  |
+| Long vertical sections |  |
+| Short horizontal sections |  |
+| Long horizontal sections |  |
+
+### Long horizontal filaments
+
+From the set of long horizontal sections, the engine gradually builds long and thin
+[filaments](../main/run_section.md#filament)
+which are likely to correspond to long portions of staff lines.
+
+The filaments that are not straight enough are discarded.
+A small set of filaments, the longest ones, are used to compute a global slope of the score image.
+The filaments whose slope diverges from the sheet global slope are discarded.
+
+Then the horizontal filaments are vertically gathered into clusters likely to represent staves.
+Within a cluster:
+- the filaments are expected to be spaced according to a known staff interline
+- the number of filaments must match the possible staff sizes (1-line, 4-line, 5-line or 6-line) as
+defined by the end user via the {{ site.book_parameters }} pull-down menu.
+
+In the end, the remaining clusters are transformed as standard staves, one-line staves or tablatures
+according to their line count.
+
+At this point, the left and right abscissa limits of each staff are defined purely
+via its detected lines.
+
+### Staff vertical projection
+
+Since the engine knows the top line and the bottom line for each staff, it can compute a projection
+of all black pixels located between these two lines onto the x-axis.[^one_line_projection]
+
+Provided we have activated the ``PLOTS`` topic in the {{ site.tools_advanced }} pull-down menu,
+we can visualize this projection:
+- either via the {{ site.sheet_staves_plots}} pull-down menu
+- or via the {{ site.popup_staff }} contextual menu from a staff
+
+
+
+From this projection limited to the staff height, the engine detects peaks which can represent:
+- barlines,
+- half braces,
+- half brackets,
+- as well as long stems, etc.
+
+The slim vertical sections located within a peak are used to build vertical filaments.
+Note that these filaments may extend past the top and/or the bottom of the staff.
+
+If, via the {{ site.tools_options}} pull-down menu, we have ticked the boolean constant
+``displayFilaments``, then a specific ``Filaments`` tab is displayed
+for both horizontal and vertical filaments initial material:
+- The horizontal filaments are in pale red
+- The vertical filaments are in pale blue
+
+| Content | View |
+| :--- | :---: |
+| Initial Filaments |  |
+
+All the peaks in vertical projection are handled as vertices in a common peak graph at sheet level.
+Any vertical alignment detected between a peak in one staff and a peak in the following staff is
+recorded as an edge in the global peak graph.
+
+Each alignment is then checked for the presence of enough foreground pixels between
+the two staff peaks, to detect concrete connections between them.
+
+Any filament which extends beyond the staff top or bottom limits and which is not a connector
+cannot be a barline and is thus discarded.
+
+Based on the detected connections, the engine is now able to gather staves into systems.
+
+### System internal alignments
+
+Within each system, the staff peaks are organized into system-based columns.
+
+The starting column, if any, is used to refine the system and staves left abscissa.
+
+The columns found on the right of the starting column must embrace the whole system height,
+otherwise they are discarded.
+Also, the peaks that extend past the system vertical limits are discarded.
+
+Brace portions and bracket portions are searched on the left of the starting column.
+The presence of braces in left margin drives the gathering of staves into parts.
+
+Finally, Inters are created in each system [SIG](../main/sig.md#sig) for:
+- barlines
+- connectors
+- braces
+- brackets
+
+## Results
+
+At the end of this ``GRID`` step, we can see the ``Data`` tab
+populated with the grid of systems and staves (shown below in physical and logical modes):
+
+| Mode | View |
+| :---: | :---: |
+|  Physical |  |
+|  Logical |  |
+
+Note that some false barlines may persist at the end of the ``GRID`` step.
+They generally get discarded later in the [``REDUCTION`` step](./reduction.md).
+
+### No-staff image
+
+Since the engine knows which precise horizontal sections compose the staff lines,
+it can logically "erase" these sections from the binary source and provide
+what is called the no-staff image.
+
+The no-staff image will be used by several steps down the pipeline.
+
+We can visualize the no-staff image via the {{ site.sheet_nostaff}} pull-down menu:
+
+| Content | View |
+| :---: | :---: |
+| No staff |  |
+
+
+[^one_line_projection]: In the specific case of a 1-line staff, the engine uses a target barline-height defined as a number of interlines (and perhaps modified via the {{ site.book_parameters }} pull-down menu).
\ No newline at end of file
diff --git a/docs/_pages/steps/headers.md b/docs/_pages/steps/headers.md
index f9f40a5ce..4de76b2be 100644
--- a/docs/_pages/steps/headers.md
+++ b/docs/_pages/steps/headers.md
@@ -1,8 +1,149 @@
---
layout: default
title: HEADERS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 5
---
-### HEADERS step
+# HEADERS step
+{: .no_toc }
+
+The ``HEADER`` step detects clef, key and time information at the beginning of every staff.
+
+---
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+## Inputs
+
+- The systems and staves
+- The no-staff image
+
+## Outputs
+
+For every staff:
+- The clef (mandatory)
+- The key signature, if any
+- The time signature, if any
+
+## Processing
+
+The engine can be rather aggressive because of the standardization of the sequence of these
+entities in the header portion of the staff.
+
+Moreover, within the same system, the header components (whether present or absent)
+are vertically aligned in "columns" across the system staves.
+This allows several cross-validations within a multi-staff system:
+- **Clefs**:
+ A clef is mandatory at the beginning of each staff header.
+ It can be different from one staff to the other.
+- **Key signatures**:
+ A key signature can vary (and even be void) from one staff to the other.
+ If present, the alteration slices are aligned across system staves.
+- **Time signatures**:
+ Either a time signature is present and identical in every staff of a system, or there are none.
+
+### Staff-free pixel source
+
+To process each staff header, the engine uses the no-staff image
+-- the binary image where all staff line pixels have been removed,
+made available by the [``GRID`` step](./grid.md#no-staff-image).
+
+With a projection to the x-axis, this allows to detect the blanks between the header components
+and thus limit the region of interest for each of them.
+
+Specifically for the key signature, the projection is also used to detect peaks
+likely to represent "stem-like" portions of sharp or flat signs.
+
+
+
+### Clef candidates
+
+Using the pixels of a rectangular lookup area, the engine extracts all the elementary glyphs
+-- defined as connected black pixels ensembles.
+
+These elementary glyphs, as well as their combinations, are submitted to the glyph classifier,
+to come up with a list of acceptable clef shapes.
+
+There may be several (mutually exclusive) acceptable clefs.
+They are registered in the system SIG and kept for the time being.
+
+### Key candidates
+
+A key signature is a sequence of consistent alterations (all sharps or all flats or none) in a
+predefined order (FCGDAEB for sharps, BEADGCF for flats).
+
+{: .warning }
+In the case of a key signature change, there may be some natural signs to explicitly cancel the
+previous alterations, although this is not mandatory.
+As of this writing, the engine is not able to handle key signatures containing natural signs.
+
+The relative positioning of alterations in a given signature is identical for all clefs (treble,
+alto, tenor, bass) with the only exception of the sharp-based signatures in tenor clef.
+
+Regarding the vertical projection of the staff-free pixels onto the x-axis:
+- Vertically, the projection uses an envelope that can embrace any key signature (under any clef),
+ ranging from two interline values above the staff to one interline value below the staff.
+- Horizontally, the goal is to split the projection into slices, one slice for each alteration item
+ to be extracted.
+
+At the staff level, the engine strategy is as follows:
+1. Find the first significant space right after the clef, it's the space that separates the clef
+ from the next component (key signature or time signature or first note/rest, etc).
+ The next really wide space will mark the end of the key signature area.
+1. Look for projection peaks in the area representing "stem-like" portions
+ (one for the flat shape, two for the sharp shape)
+ Since at this point in time there is no reliable way to choose between flats and sharps,
+ the engine will work in parallel on the two hypotheses (flat-based key vs sharp-based key).
+1. Determine a precise splitting of the projection into vertical regions of interest (slices),
+based on the "stem-like" peaks and the shape hypothesis.
+1. Try to retrieve one good component in each slice,
+ by submitting each glyph compound to the glyph classifier.
+ For the slices left empty, force slice segmentation and perform recognition within the slice only.
+1. Check each item pitch against the pitches sequences imposed by the staff clef candidate(s).
+ In the system SIG, register a support relationship between any compatible clef candidate
+ and key candidate.
+
+And for the systems that contain several staves:
+1. Across all the system staves, align the abscissa offset for each slice.
+1. Check that within any multi-staff _part_, the part staves exhibit the same key signature,
+otherwise select the best one and replicate it in the other staves of the part.
+
+### Time candidates
+
+Since all time signatures must be identical in any vertical "column" of a system,
+the retrieval is made directly from the system level:
+
+1. In the system header area, a "column" of staff areas is defined, right after the key "column"
+if any, otherwise right after the clef "column".
+1. For each staff of the system, knowing the abscissa range for time candidates, three lookup regions are defined:
+ - A rectangle as high as staff height, searched for possible whole time signature shapes
+such as COMMON_TIME, 4/4, 6/8, etc.
+ - A small rectangle centered on the higher staff half, searched for possible numerator shapes
+ - A small rectangle centered on the lower staff half, searched for possible denominator shapes
+1. Not all num/den pairs are possible, the engine restricts them to the commonly used ones.
+1. If, in a staff header, no time signature was found, the search within the current system is abandonned.
+
+## Results
+
+The picture below presents the results of the ``HEADERS`` step on the first system of the ``chula`` input example.
+
+We can see the lookup areas used for:
+- Clef: outer and inner rectangles
+- Key: rectangular slice for each item of this two-sharp key
+- Time: one whole and two half rectangles
+
+
+
+The next picture presents the results on the second system.
+
+Notice that, in the first staff, the projection of the quarter note,
+located right after the key signature area,
+has been searched for a time signature candidate.
+But no time symbol could be recognized there.
+
+Consequently, the header of the second staff was not even considered for a time signature lookup.
+
+
\ No newline at end of file
diff --git a/docs/_pages/steps/heads.md b/docs/_pages/steps/heads.md
index 3cd948a6b..ee33acc62 100644
--- a/docs/_pages/steps/heads.md
+++ b/docs/_pages/steps/heads.md
@@ -1,8 +1,8 @@
---
layout: default
title: HEADS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 9
---
-### HEADS step
+# HEADS step
diff --git a/docs/_pages/steps/ledgers.md b/docs/_pages/steps/ledgers.md
index 4a61fef10..1ee12bcb5 100644
--- a/docs/_pages/steps/ledgers.md
+++ b/docs/_pages/steps/ledgers.md
@@ -1,8 +1,8 @@
---
layout: default
title: LEDGERS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 8
---
-### LEDGERS step
+# LEDGERS step
diff --git a/docs/_pages/steps/links.md b/docs/_pages/steps/links.md
index ea63d10b8..c25c97705 100644
--- a/docs/_pages/steps/links.md
+++ b/docs/_pages/steps/links.md
@@ -1,8 +1,8 @@
---
layout: default
title: LINKS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 18
---
-### LINKS step
+# LINKS step
diff --git a/docs/_pages/steps/load.md b/docs/_pages/steps/load.md
index 4325cfc09..11a4024e5 100644
--- a/docs/_pages/steps/load.md
+++ b/docs/_pages/steps/load.md
@@ -1,8 +1,34 @@
---
layout: default
title: LOAD step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 1
---
-### LOAD step
+# LOAD step
+{: .no_toc }
+
+It is the very first step applied when processing any sheet.
+Its goal is to provide the sheet gray image, whatever the input color model.
+
+## Inputs
+
+- The path to the book input file
+- The sheet number within the book -- 1 by default
+
+## Output
+
+- The gray image of the sheet
+
+## Processing
+
+1. A proper image loader is chosen according to the extension of the input file name
+(``.pdf``, ``.tif``, ``.png``, ``jpg``, etc),
+2. The loader then extracts the input image, based on the sheet number,
+3. The image is discarded if its size is too large,
+4. According to its color model, this initial image is converted to a gray scale of pixels
+-- ranging from 0 for a black pixel to 255 for a white pixel.
+ - The alpha channel if any is discarded,
+ - If RGB channels are provided, the gray value for each pixel is set as
+ the highest value among the 3 RGB values.
+
diff --git a/docs/_pages/steps/measures.md b/docs/_pages/steps/measures.md
index 07de82474..f426fad58 100644
--- a/docs/_pages/steps/measures.md
+++ b/docs/_pages/steps/measures.md
@@ -1,8 +1,8 @@
---
layout: default
title: MEASURES step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 14
---
-### MEASURES step
+# MEASURES step
diff --git a/docs/_pages/steps/page.md b/docs/_pages/steps/page.md
index 6a0d6186d..bd4480baf 100644
--- a/docs/_pages/steps/page.md
+++ b/docs/_pages/steps/page.md
@@ -1,8 +1,8 @@
---
layout: default
title: PAGE step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 20
---
-### PAGE step
+# PAGE step
diff --git a/docs/_pages/steps/reduction.md b/docs/_pages/steps/reduction.md
index 8e2e7c81e..dd8f7fdc6 100644
--- a/docs/_pages/steps/reduction.md
+++ b/docs/_pages/steps/reduction.md
@@ -1,8 +1,8 @@
---
layout: default
title: REDUCTION step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 11
---
-### REDUCTION step
+# REDUCTION step
diff --git a/docs/_pages/steps/rhythms.md b/docs/_pages/steps/rhythms.md
index 677a79f28..c7240f107 100644
--- a/docs/_pages/steps/rhythms.md
+++ b/docs/_pages/steps/rhythms.md
@@ -1,8 +1,8 @@
---
layout: default
title: RHYTHMS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 19
---
-### RHYTHMS step
+# RHYTHMS step
diff --git a/docs/_pages/steps/scale.md b/docs/_pages/steps/scale.md
index df3f0e381..e303e3ffc 100644
--- a/docs/_pages/steps/scale.md
+++ b/docs/_pages/steps/scale.md
@@ -1,8 +1,115 @@
---
layout: default
title: SCALE step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 3
---
-### SCALE step
+# SCALE step
+{: .no_toc }
+
+Music is written on staves composed of one or more horizontal lines
+regularly spaced within the same staff.
+
+Depending on the input image, these lines can vary in thickness and spacing.
+And the dimensions of almost all the music elements to be detected depend on these values.
+
+The purpose of the ``SCALE`` step is to measure this key scaling data for the sheet at hand.
+
+---
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+## Input
+
+The black & white image provided by the [``BINARY`` step](./binary.md).
+
+## Outputs
+
+Most of the scaling items use a tuple of 3 values, specified as a number of pixels:
+- The minimum value
+- The main (most frequent) value
+- The maximum value
+
+1. Mandatory outputs:
+ - Staff line thickness
+ - Staff interline -- the vertical distance between staff lines,
+ measured from line center to line center
+
+2. Optional outputs:
+ - Small staff interline -- when two populations of staves exist in the sheet,
+ this is the vertical spacing for the smaller staves
+ - Beam thickness -- when beams exist in the sheet, this is the measured beam thickness
+ - Small beam thickness -- when two populations of beams exist in the sheet,
+ this is the thickness for the smaller beams.
+
+## Processing
+
+To retrieve the various scale values, the engine inspects every abscissa of the binary image
+for the sequence of vertical runs it contains, alternatively white and black runs.
+
+The picture below was taken when working on the ``chula.png`` image
+found in the ``data/examples`` of Audiveris installation.
+It is a partial view of a column read at a given abscissa,
+with the sequence of white and black runs and the length of each run in pixels:
+
+
+
+With all these vertical run lengths read in the whole image, the engine builds two histograms:
+- The **black** histogram uses the length of every black run,
+- The **combo** histogram tries to use the length of every white run twice
+ 1. combined with the length of the black run **above** if any
+ 2. combined with the length of the black run **below** if any
+
+The final histograms can be viewed via the {{ site.sheet_scale_plots }} pull-down menu
+-- provided we have activated the ``PLOTS`` topic in the {{ site.tools_advanced }} menu.
+
+### Black histogram
+
+
+
+In this plot, we can clearly see two peaks on the length of vertical black runs:
+- a first peak around value 3, this is the typical staff line thickness
+- a second peak around value 12, this is the typical beam thickness
+
+### Combo histogram
+
+
+
+Here we have just one peak around value 21, this is the typical interline value.
+
+### Engine behavior
+
+The engine detects these peaks rather easily, using:
+- a threshold on peak height (for beam thickness in the black histogram)
+- a threshold on the absolute values of derivative before and after the peak
+ (leading to the "HiLo" sequences shown on the plot),
+ to precisely grab the minimum and maximum values around the peak.
+
+In the current example, the output of the ``SCALE`` step can be read in the log as:
+> [chula] Scale{ interline(21,21,22) line(2,3,4) beam(12)}
+
+This simple example represents the most frequent case.
+We can also encounter more complex cases as listed below.
+
+Regarding the _black_ histogram:
+- It may exhibit just one peak, meaning that no significant beam-based runs were detected.
+ The image can in fact contain no beam, but it can also contain too few of them,
+ resulting in no clear peak.
+ In the latter case, the end user may have to explicitly provide the beam thickness to the engine.
+ See this [sheet scale section about beam thickness](../main/sheet_scale.md#beam-thickness).
+- It may exhibit 3 peaks, one for the typical line thickness and the two others
+ for two populations of beams: small and large (standard).
+
+Regarding the _combo_ histogram:
+- It may exhibit 2 peaks, due to the presence of 2 populations of staves in the image,
+one with a smaller interline and one with a larger (standard) interline.
+- It may exhibit no clear peak, or a peak detected far from the expected values
+ -- Audiveris expects an interline value not too far from 20 pixels.
+ - This generally means that the image at hand contains no staff, but perhaps some illustration.
+ The engine will notify the user about a sheet considered as "*invalid*" from the OMR point of view.
+ - This case can also occur when the score contains no multi-line staff,
+ hence there is no physical *inter*-line to measure.
+ See [snippets with only one-line staves](../specific/snippets.md).
diff --git a/docs/_pages/steps/stem_seeds.md b/docs/_pages/steps/stem_seeds.md
index f1fc06588..d0073b55a 100644
--- a/docs/_pages/steps/stem_seeds.md
+++ b/docs/_pages/steps/stem_seeds.md
@@ -1,8 +1,113 @@
---
layout: default
title: STEM_SEEDS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 6
---
-### STEM_SEEDS step
+# STEM_SEEDS step
+{: .no_toc }
+
+A stem is a rather long vertical segment meant to join note heads, perhaps with beams.
+And in a perfect world, any stem could be easily recognized on its own.
+
+But in reality, there may be missing black pixels in the input image,
+perhaps breaking a stem in smaller segments, or damaging the connection between a stem and
+some of its partnering heads and beams.
+
+To cope with this, the engine uses several approaches to gradually detect:
+1. (portions of) stem candidates -- this ``STEM_SEEDS`` step!
+1. beam candidates -- the [``BEAMS`` step](./beams.md)
+1. ledger candidates -- the [``LEDGERS`` step](./ledgers.md)
+1. heads candidates -- the [``HEADS`` step](./heads.md)
+
+and finally to:
+1. determine all full stem candidates joining heads and beams -- the [``STEMS`` step](./stems.md)
+1. filter all the candidates -- the [``REDUCTION`` step](./reduction.md)
+
+---
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+## Input
+
+- The systems and staves
+- The no-staff image
+- The vertical LAG
+- The horizontal LAG (very partially)
+
+## Output
+
+- The typical stem thickness for the sheet
+- The stem seeds as glyphs in the ``VERTICAL_SEED`` group
+
+## Prolog: stem thickness
+
+The user can directly specify a stem thickness value for the sheet at hand
+via the {{ site.sheet_scaling }} pull-down menu.
+
+In the normal case -- that is with no thickness value provided --
+the engine must, as a step prolog, measure the typical stem thickness.
+It does so by crafting an input image suitable for a global stem analysis.
+
+To avoid any pollution brought by lyrics, title or other external entities,
+the engine focuses only on the core staff areas, which is the staff height augmented vertically
+slightly less than one interline above and one interline below.
+
+Within each staff area, the staff lines have been removed, as well as the detected barlines
+and the header components.
+Note that some stems may have been mistaken for barlines candidates
+during the [``GRID`` step](./grid.md);
+this should have a negligible impact on the stem thickness computation.
+
+The result is an input image like this one (still for the ``chula`` example):
+
+
+
+On this input, it is easy to build a histogram of horizontal black runs lengths, as shown below.
+
+We can display this histogram via the {{ site.sheet_stem_plot }} pull-down menu
+-- provided we have activated the ``PLOTS`` topic in the {{ site.tools_advanced }} menu.
+
+
+
+The retrieved peak gives the stem thickness: in our example, the most frequent value is 2 pixels,
+and the maximum value is 3 pixels.
+
+These values are stored in the sheet scaling data.
+Then the rest of step processing is performed system per system.
+
+## System processing
+
+### Vertical filaments
+
+Based on the retrieved (or specified) stem thickness value, the engine can now build vertical
+straight filaments from the vertical sections that are slim enough and long enough.
+
+For now, the engine is only looking for stem *seeds*.
+Hence, it makes no attempt to extend these filaments vertically
+-- this will be done later in the ``STEM`` step.
+
+The filaments can just be thickened with compatible adjacent vertical sections
+and tiny horizontal sections as long as the resulting thickness stays within
+the limit on stem thickness value.
+
+### Checking seeds
+
+Each retrieved filament is further checked to be kept as a stem seed.
+
+The checks concern:
+- slope
+- straightness
+- length
+- cleanliness -- not too many adjacent pixels
+- high black part
+- low white part
+
+The checks are evaluated according to the declared quality of the sheet input
+(synthetic, standard, poor).
+
+The successful candidates are finally registered in the specific ``VERTICAL_SEED``
+group of glyphs, ready to be picked up by the following steps.
\ No newline at end of file
diff --git a/docs/_pages/steps/stems.md b/docs/_pages/steps/stems.md
index 224476337..8292d36ec 100644
--- a/docs/_pages/steps/stems.md
+++ b/docs/_pages/steps/stems.md
@@ -1,8 +1,8 @@
---
layout: default
title: STEMS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 10
---
-### STEMS step
+# STEMS step
diff --git a/docs/_pages/steps/symbols.md b/docs/_pages/steps/symbols.md
index b92d763a7..fa95617ed 100644
--- a/docs/_pages/steps/symbols.md
+++ b/docs/_pages/steps/symbols.md
@@ -1,8 +1,8 @@
---
layout: default
title: SYMBOLS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 17
---
-### SYMBOLS step
+# SYMBOLS step
diff --git a/docs/_pages/steps/texts.md b/docs/_pages/steps/texts.md
index 32d7e7ad8..f6d9c51cb 100644
--- a/docs/_pages/steps/texts.md
+++ b/docs/_pages/steps/texts.md
@@ -1,8 +1,8 @@
---
layout: default
title: TEXTS step
-parent: Pipeline
-grand_parent: Main Features
+parent: Steps internals
+grand_parent: References
nav_order: 13
---
-### TEXTS step
+# TEXTS step
diff --git a/docs/_pages/ui_examples/eyes/README.md b/docs/_pages/ui_examples/eyes/README.md
index a60c3c23b..0ff3d5777 100644
--- a/docs/_pages/ui_examples/eyes/README.md
+++ b/docs/_pages/ui_examples/eyes/README.md
@@ -257,7 +257,7 @@ into the proper location (the needed ledger line gets created automatically)
## Logical parts
-If we naïvely export our work to say MuseScore, we get something that starts like:
+If we naively export our work to say MuseScore, we get something that starts like:
diff --git a/docs/_pages/ui_examples/trinitas/README.md b/docs/_pages/ui_examples/trinitas/README.md
index 280e44945..b342a8dbb 100644
--- a/docs/_pages/ui_examples/trinitas/README.md
+++ b/docs/_pages/ui_examples/trinitas/README.md
@@ -219,8 +219,8 @@ So let's replace all the common-cuts by explicit "4/2" time signatures.
To delete:
- We select the common-cut Inter and press `DEL` key.
- Or we click on the `Deassign` button in the Inter board.
- Or we use the ` → Inters...` contextual menu.
+- Or we click on the `Deassign` button in the Inter board.
+- Or we use the {{ site.popup_inters }} contextual menu.
Inserting a 4/2 signature is more complex, since this is not one of the predefined time signatures:
1. From the Shape palette, we select the "Times" family (the family figured by a 4/4 sign) and
@@ -283,13 +283,13 @@ So, we open the {{ site.book_parameters}} dialog, and:
We don't forget to press the `OK` or `Apply` button to commit the parameters.
-Then, we use the contextual ` → Page #1 → Reprocess rhythm` to update the page.
+Then, we use the contextual `≡ Page #1 → Reprocess rhythm` to update the page.
Measure #4 now looks like this (notice chords #3381 and #2836 are now in the same green voice):
-And ` → Measure #4 → Dump stack voices` dumps its strip as:
+And `≡ Measure #4 → Dump stack voices` dumps its strip as:
```
MeasureStack#4
@@ -464,7 +464,7 @@ This concludes our manual work on Sheet #1, with no rhythm errors left.
## Sheet #2
-We update the rhythm on the whole sheet #2, via ` → Page #1 → Reprocess rhythm`,
+We update the rhythm on the whole sheet #2, via `≡ Page #1 → Reprocess rhythm`,
to benefit from the time signature fix (4/2) made on sheet #1.
Only 3 measures are left in pink, but let's review all measures.
@@ -590,7 +590,7 @@ with custom 4/2 signatures.
The first two measures are OK, but we would like to align their voices in the lower staff.
So, we select the last chord in measure #1 and the first chord in measure #2, and use
-` → Chords → Next in voice` to get:
+the contextual `≡ Chords → Next in voice` to get:
@@ -607,7 +607,8 @@ We select (a head in) the first voice chord in the staff, for example chord #429
-Then in the `Chords` pop-up menu, we select the "Preferred voice" directly for this chord.
+Then in the {{ site.popup_chords }} contextual menu,
+we select the "Preferred voice" directly for this chord.
We can see here that there was no voice assigned ("None").
We select the desired voice number in the menu, that is voice #5 (cyan color).
diff --git a/docs/_pages/ui_foundations/inspection.md b/docs/_pages/ui_foundations/inspection.md
index 239704798..303c2c4d1 100644
--- a/docs/_pages/ui_foundations/inspection.md
+++ b/docs/_pages/ui_foundations/inspection.md
@@ -6,7 +6,7 @@ parent: UI Foundations
nav_order: 3
---
-## Inspection
+# Inspection
{: .no_toc }
In a perfectly transcribed score, all the items would be correctly recognized
@@ -26,7 +26,7 @@ Table of contents
{:toc}
---
-### Measure background
+## Measure background
A pink measure background is the most obvious sign, meant to call user attention to a measure,
as in the following page view which displays two measures (#5P1 and #10P2) with a pink
@@ -56,7 +56,7 @@ Note that, conversely, a measure not detected as abnormal
may still exhibit errors that the OMR engine could not reliably detect.
We'll see examples of these cases that today only the human reader can detect and fix.
-### Colorized voices
+## Colorized voices
@@ -67,7 +67,7 @@ is to visually check the content of every voice.
In the example above, voice 6 which appears in the bottom right corner of the
measure is really suspicious (although the measure is not flagged as _abnormal_).
-### Chords IDs
+## Chords IDs
By default, chord IDs are not displayed in sheet view because they look too invasive.
To set them on, we use the pull-down menu {{ site.view_chords }}.
@@ -77,7 +77,7 @@ into a single chord:
-### Measure strip
+## Measure strip
A right-click within a measure N leads to a measure contextual menu which offers to print out
all voices for the measure at hand.
@@ -86,8 +86,8 @@ For example, let's focus on the measure below:
-` | Measure #N | Dump stack voices` prints a strip for the whole system-high measure stack.
-` | Measure #N | Dump measure voices` prints a strip for just the part-high measure.
+`≡ Measure #N | Dump stack voices` prints a strip for the whole system-high measure stack.
+`≡ Measure #N | Dump measure voices` prints a strip for just the part-high measure.
The latter (limited to one part) is meant for orchestra scores, with lots of parts within each
system, to allow to focus on one part at a time.
@@ -115,7 +115,7 @@ Moreover, Ch#3979 starts at offset 1/2, whereas on the image it starts at offset
Here again there is nothing, from the OMR engine point of view, to flag this measure as abnormal
-- all voices can be computed and all of them complete within the measure time limit.
-### Time slots
+## Time slots
Time slots are not visible in  physical mode.
They are displayed in  combined and
@@ -136,11 +136,11 @@ with no chord aligned with it.
Moreover, chord 4010 at bottom center is not aligned with any slot.
To be more precise, we can investigate the content of each time slot, via a right-click on the slot:
-- ` | Slot #3 | Dump chords` gives
+- `≡ Slot #3 | Dump chords` gives
```
slot#3 start= 1/2 [HeadChordInter{#3979(0.794/0.794) stf:7 slot#3 off:1/2 dur:1/4},HeadChordInter{#4010(0.815/0.815) stf:9 slot#3 off:1/2 dur:1/2}]
```
-- ` | Slot #3 | Dump voices` gives
+- `≡ Slot #3 | Dump voices` gives
```
slot#3 start= 1/2 [V1 Ch#3979 s:7 Dur= 1/4, V5 Ch#4010 s:9 Dur= 1/2]
```
diff --git a/docs/_pages/ui_foundations/principles.md b/docs/_pages/ui_foundations/principles.md
index a85be552a..08327d10f 100644
--- a/docs/_pages/ui_foundations/principles.md
+++ b/docs/_pages/ui_foundations/principles.md
@@ -6,7 +6,7 @@ parent: UI Foundations
nav_order: 1
---
-## Principles
+# Principles
{: .no_toc }
For Audiveris, music is something very graphical, a 2D view of music symbols
diff --git a/docs/_pages/ui_foundations/selection.md b/docs/_pages/ui_foundations/selection.md
index 562bb5a08..b680e9016 100644
--- a/docs/_pages/ui_foundations/selection.md
+++ b/docs/_pages/ui_foundations/selection.md
@@ -6,7 +6,7 @@ parent: UI Foundations
nav_order: 2
---
-## Selection
+# Selection
{: .no_toc }
Table of contents
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Current location
+## Current location
Selection is driven by the current location we are pointing at in the score image.
The location point is displayed as a cross made of 2 red segments, one horizontal and one vertical.
@@ -41,9 +41,9 @@ To precisely **shift** the current location:
* While keeping the `ALT` key pressed (`OPTION` key on MacOS), we use one of the 4 arrow keys
to move the location (point or rectangle) one pixel at a time.
-### Entity selection
+## Entity selection
-#### Selection modes
+### Selection modes
There are 3 selections modes available:
1.  _glyph+inter_ based (the default)
@@ -53,7 +53,7 @@ There are 3 selections modes available:
To switch from one mode to another, we use the toggle menu item {{ site.view_selections }},
click on the related toolbar icon or press the `F11` function key.
-#### Selection means
+### Selection means
The mouse-based selection works as expected, pointing to glyph entities, inter entities,
section entities, according to the current selection mode.
@@ -106,7 +106,7 @@ The images below depict:
| --- | --- | --- |
|  |  |  |
-#### Multi-selection
+### Multi-selection
A left-click in an entity area selects this entity (and deselects the entity previously selected if any).
@@ -130,7 +130,7 @@ shows the bounding box of a compound glyph built from all selected glyphs.
Moreover, an entity changes color when it gets selected (a glyph turns red, an inter turns to
nearly-reverse color, a section turns white).
-#### Member vs Ensemble
+### Member vs Ensemble
Selecting an entity by pointing at it can be ambiguous.
@@ -156,10 +156,10 @@ with the `To Ensemble` button enabled.
Here, we have pressed `To Ensemble` button, and the focus is now on the head chord,
with the "_ChordSyllable_" relation to the lyric item "Ver" below.
-### Container selection
+## Container selection
When clicking with the right mouse button on any location of the sheet image, the sheet
-pop-up menu appears.
+contextual menu appears.
This pop-up displays contextual information
-- such as the selected glyphs, inters, etc, if any --
diff --git a/docs/_pages/ui_tools/README.md b/docs/_pages/ui_tools/README.md
index 2595a67a1..3b842cb81 100644
--- a/docs/_pages/ui_tools/README.md
+++ b/docs/_pages/ui_tools/README.md
@@ -10,7 +10,7 @@ has_children: true
## Interaction with the OMR engine
The OMR engine works as a sequence of 20 sheet steps, a step being a kind of mini-batch.
-You, as an interacting user, can get in only at the end of a step.
+We, as an interacting user, can get in only at the end of a step.
[When a sheet first appears with its Data tab, the OMR engine has already performed the LOAD and
BINARY steps.]
@@ -26,36 +26,37 @@ the OMR engine.
## Tasks
-#### Task sequence
+### Task sequence
-Whenever you modify an entity in some way, this task is recorded as such, perhaps with some
+Whenever we modify an entity in some way, this task is recorded as such, perhaps with some
joint tasks, into a "_task sequence_" which is then performed on the targeted entities.
A task sequence can be pretty large. For example:
-* You can select a dozen inters and ask for the removal of the whole set.
-* You can remove an inter ensemble; this triggers the removal of all the
+* We can select a dozen inters and ask for the removal of the whole set.
+* We can remove an inter ensemble; this triggers the removal of all the
members of the ensemble: words of a sentence, heads of a head-chord, etc.
* Removing the last remaining member of an ensemble also removes the now-empty ensemble.
-A task sequence is _indivisible_, but you can **do** it, **undo** and **redo** it at will,
+A task sequence is _indivisible_, but we can **do** it, **undo** and **redo** it at will,
with no limits.
Only moving the engine forward (or pseudo backward) from one step to another clears the user
task history.
-#### Undo
+### Undo
-Undo cancels the last task sequence (whether it was a do or a redo) with all its consequences.
+The ``Undo`` command cancels the last task sequence (whether it was a do or a redo)
+with all its consequences.
-* Press the **Undo** button  on the tool bar,
+* We press the **Undo** button  on the tool bar,
* Or type `Ctrl+Z` (`Command+Z` for MacOS)
-#### Redo
+### Redo
-Redo re-performs the last un-done task sequence.
+The ``Redo`` command re-performs the last un-done task sequence.
-* Press the **Redo** button  on the tool bar,
+* We press the **Redo** button  on the tool bar,
* Or type `Ctrl+Shift+Z` (`Command+Shift+Z` for MacOS).
## When to interact?
@@ -63,23 +64,24 @@ Redo re-performs the last un-done task sequence.
Most user corrections can be done at the end of a sheet transcription
(at the final `PAGE` step of the engine pipeline).
-Some corrections are more effective at earlier moments; experience will tell you.
+Some corrections are more effective at earlier moments; experience will tell us.
Here are interesting stopping points, presented in chronological order:
* **SCALE** step is an interesting stop if the beams are questionable.
-That is, if you get a message saying that the beam thickness value is just "extrapolated", be careful!
-This tells you that beam-related data could not reach the quorum needed to infer a reliable
+That is, if we get a message saying that the beam thickness value is just "extrapolated",
+we must be careful!
+This tells us that beam-related data could not reach the quorum needed to infer a reliable
thickness value.
-So, measure the actual beam thickness by yourself (using the Pixel Board) and modify the beam scale
-if needed (see the [Sheet scale](../main/sheet_scale.md) section).
+So, let's measure the actual beam thickness on our own (using the Pixel Board) and modify
+the beam scale if needed (see the [Sheet scale](../main/sheet_scale.md) section).
* **GRID** step is where staff lines, then staves and systems are detected.
-Hence, this is the most convenient point to interact if you need to manually modify lines
+Hence, this is the most convenient point to interact if we need to manually modify lines
and staves (see the [Staff editing](./staff_editor.md) section).
* **REDUCTION** step is where all candidate note heads are combined with candidate stems and
-beams and then reduced to come up with reliable notes (this does not include any flag or rest,
-which are addressed later in the SYMBOLS step).
+beams and then reduced to come up with reliable notes
+-- this does not include any flag or rest, which are addressed later in the SYMBOLS step.
It is a key moment in the engine pipeline, because these "reliable" notes will never be called into
question by the following steps.
So much so that their underlying pixels will not be presented to the glyph classifier during the
@@ -99,5 +101,5 @@ be considered as a possible music symbol.
Thus, it is efficient to manually remove text false positives at the end of this TEXT step to let
their pixels be taken into account by the SYMBOLS step.
-* **PAGE** step is where the OMR engine ends on a sheet and where you can observe and correct the
+* **PAGE** step is where the OMR engine ends on a sheet and where we can observe and correct the
final results.
diff --git a/docs/_pages/ui_tools/add_inter.md b/docs/_pages/ui_tools/add_inter.md
index 0a71bb708..f781b72b8 100644
--- a/docs/_pages/ui_tools/add_inter.md
+++ b/docs/_pages/ui_tools/add_inter.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 1
---
-## Inter Addition
+# Inter Addition
{: .no_toc }
In the Audiveris data model, an Inter instance represents an interpretation, that is a candidate
@@ -30,7 +30,7 @@ Table of contents
{:toc}
---
-### Inter from underlying Glyph
+## Inter from underlying Glyph
Inter creation from a glyph is the only case where a glyph is used in Audiveris manual editing.
@@ -52,7 +52,7 @@ target staff:
The target shape can be specified via different means, as follows.
-#### Via the glyph classifier
+### Via the glyph classifier
@@ -80,21 +80,21 @@ For these two cases -- and only for them -- the glyph classifier is not precise
We'll have to explicitly select a more specific target shape, via the glyph pop-up menu
or via the shape palette.
-#### Via the glyphs pop-up-menu
+### Via the glyphs pop-up menu
-Once a glyph has been selected, we use a mouse right click to access the sheet pop-up menu,
-and its `Glyphs` sub-menu.
+Once a glyph has been selected, we use a mouse right click to access
+the {{ site.popup_glyphs }} sheet contextual menu.
Then we navigate through shape sets to our precise target shape.
-#### Via the shape palette
+### Via the shape palette
The shape palette (see next section) allows to assign a shape to the selected glyph.
This is done by a double-click on the desired shape in the palette.
-### The Shape Palette
+## The Shape Palette
The palette offers the ability to choose the desired shape for a selected glyph.
@@ -108,7 +108,7 @@ Nothing can be dragged from this catalog, we must first select a shape set:
-#### Entering a shape set
+### Entering a shape set
Pressing a shape set button replaces the catalog view by a specific palette dedicated to
the selected shape set.
For example, pressing on the ``ClefsAndShifts`` set button gives:
@@ -122,7 +122,7 @@ Within a set, a shape can be:
-#### Selecting target staff
+### Selecting target staff
While we are dragging a shape, we have the freedom to hover where we like.
The last staff we have been hovering over is selected as our current target staff.
@@ -140,7 +140,7 @@ it may get snapped according to staff lines, etc.
We can drop the shape only when a staff target has been selected.
If not, the drag & drop action is abandoned.
-#### Case of compound shapes
+### Case of compound shapes
Note the ``HeadsAndDot`` set now contains four new shapes located at the end.
@@ -158,7 +158,7 @@ Once dropped, such a compound shape is replaced by two separate Inters
We can then later edit each "part" separately, for example to modify the stem length.
And we can add flags to the stem.
-#### Exiting a shape set
+### Exiting a shape set
To leave the specific set palette and go back to the catalog view, we can:
* Click on the "triangle-up" sign located on the left side of the set palette,
@@ -166,7 +166,7 @@ To leave the specific set palette and go back to the catalog view, we can:
* Or press the `ESC` key on the keyboard.
-### Shape cache
+## Shape cache
We can notice, appearing on a line above the shape palette, the list of the most recent shape
buttons we have used so far.
@@ -179,7 +179,7 @@ containing sets.
And if we want to add many Inters of the same shape, we can consider using the
"Repetitive Input" mode below.
-### Repetitive input
+## Repetitive input
If we have numerous Inters of the **same shape** to add in a row, a convenient way is to switch
temporarily to the "_Repetitive Input_" mode.
@@ -210,7 +210,7 @@ Then we set the repetitive mode on again if so desired.
To exit this rather specific mode, we toggle the mode
(via the toolbar icon, the menu item or the shortcut).
-### Relations with other inters
+## Relations with other inters
Key relation(s) with the nearby Inter(s), if any, will be updated automatically as we create
-- or later edit -- the Inter, but only as long as the required geometrical relationships can apply
@@ -218,7 +218,7 @@ Key relation(s) with the nearby Inter(s), if any, will be updated automatically
If the relation constraints are not met, we will have to set the relation manually afterwards.
-### Shortcuts for inter addition
+## Shortcuts for inter addition
In order to make long editing sessions easier, there are a few shortcuts to assign interpretations
without having our hands leave the keyboard.
@@ -240,7 +240,7 @@ position, ready for further use (via double-click, drag & drop or repetitive inp
***
-#### Shortcuts table
+### Shortcuts table
Only sets and shapes that are used rather often are supported.
diff --git a/docs/_pages/ui_tools/add_relation.md b/docs/_pages/ui_tools/add_relation.md
index bb13422a0..8f8716fae 100644
--- a/docs/_pages/ui_tools/add_relation.md
+++ b/docs/_pages/ui_tools/add_relation.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 4
---
-## Relation Addition
+# Relation Addition
{: .no_toc }
---
@@ -27,7 +27,7 @@ We can visually check the relations when we select an Inter.
The name of each relation is also displayed, provided that the current zoom is high enough (>=2).
-### Mandatory vs non-mandatory relations
+## Mandatory vs non-mandatory relations
Depending on the Inter class, an Inter instance may need a relation with another Inter instance.
@@ -64,7 +64,7 @@ An example of a non-mandatory relation is the case of a direction sentence which
have a chord precisely above or below.
For such non-mandatory relations, we have to decide if we set them or not.
-### Linking Inters
+## Linking Inters
Assuming the slur is not linked to the note head, we need to insert the relation between them.
diff --git a/docs/_pages/ui_tools/chords.md b/docs/_pages/ui_tools/chords.md
index 1458d5d01..a7a13415e 100644
--- a/docs/_pages/ui_tools/chords.md
+++ b/docs/_pages/ui_tools/chords.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 12
---
-## Chords
+# Chords
{: .no_toc }
For Audiveris, a _chord_ is a container:
@@ -28,10 +28,10 @@ Table of contents
{:toc}
---
-### Chords menu
+## Chords menu
Below, we have selected two notes as indicated by the arrows: one note head and one rest,
-before opening the pop-up/Chords menu:
+before opening the {{ site.popup_chords }} contextual menu:
@@ -57,11 +57,11 @@ because the list depends on the current status and configuration of the selected
Next, we list all the possible items of the `Chords...` menu.
-### Chord
+## Chord
The gathering of note heads into chords may need some user correction.
-#### Split
+### Split
| One chord? | Two chords? |
| --- | --- |
@@ -73,7 +73,7 @@ In that case, select this chord and use the ``Split`` command.
-#### Merge
+### Merge
Or, just the opposite, we may want to merge these two chords into a single one.
In that case, we select both chords and use the ``Merge`` command.
@@ -84,7 +84,7 @@ to gather whole heads into one chord.
-### Voice
+## Voice
A voice is defined as a sequence of chords (head chords and rest chords) in the same music part.
[^voice_sharing]
@@ -95,7 +95,7 @@ user would expect.
The purpose of these voice actions is to guide the engine in voice building.
-#### Next in Voice
+### Next in Voice
@@ -121,7 +121,7 @@ Also if we want, much later in the process, to cancel this task, we can always g
to selecting the same chords and we'll be offered to **cancel** the task.
Cancelling this action removes the relation (and thus the related guidance).
-#### Same Voice
+### Same Voice
`Same Voice` command is weaker than `Next in Voice` command.
@@ -134,7 +134,7 @@ Note that `Same Voice` (or `Next in Voice`) can be used in the context of rest c
between beam head chords, to "push" these rests into the beam area.
And conversely, `Separate Voice` can be used to "pull" these rests out of the beam area.
-#### Separate Voices
+### Separate Voices
This command imposes the voice algorithm to assign the selected chords to **separate** voices.
@@ -143,7 +143,7 @@ Note this is not exactly the reverse of the `Next in Voice` command
* Without any command, we let the algorithm decide with no guidance.
* With a command (whether it's _next_, _same_ or _separate_), we explicitly guide the algorithm.
-#### Preferred Voice
+### Preferred Voice
Whereas the `Next in Voice`/`Same Voice" and "Separate Voices" commands operate on 2 chords,
by establishing a **dynamic** computing rule from chord A to chord B,
@@ -163,7 +163,7 @@ These are the two cases where this feature can be useful.
But except for these very specific cases, we are advised not to use this feature.
In particular, let's not imagine we could use it to somehow build voice sequences of chords!
-### Time
+## Time
Assigning a chord to the proper time slot is as tricky as voice assignment.
In fact, the time and voice algorithms are tightly coupled.
@@ -171,7 +171,7 @@ In fact, the time and voice algorithms are tightly coupled.
When two chords are rather close horizontally, when should we consider them as part of the same
time slot?
-#### Same Time Slot
+### Same Time Slot
@@ -184,7 +184,7 @@ Experience shows that the most efficient action is generally to grab the set of
that should share the same slot (a rather vertical selection **within the same part**)
and apply the `Same Time Slot` command on the whole set.
-#### Separate Time Slots
+### Separate Time Slots
As opposed to `Same Time Slot`, this command is used to force time separation between two
chords that the engine has considered as adjacent.
diff --git a/docs/_pages/ui_tools/edit_inter.md b/docs/_pages/ui_tools/edit_inter.md
index b30ad9bf1..0ed28bec7 100644
--- a/docs/_pages/ui_tools/edit_inter.md
+++ b/docs/_pages/ui_tools/edit_inter.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 2
---
-## Inter Editing
+# Inter Editing
{: .no_toc }
Since 5.2 release, any Inter -- whether it has been created by the OMR engine,
@@ -26,7 +26,7 @@ Table of contents
{:toc}
---
-### Entering editing mode
+## Entering editing mode
To start editing an Inter, we must first set it into `editing mode`:
- This is most conveniently done by a left double-click on the Inter.
@@ -35,7 +35,7 @@ To start editing an Inter, we must first set it into `editing mode`:
-### Inter handles
+## Inter handles
The Inter being edited now displays a set of one or several handles, depending on the
Inter class.
@@ -72,7 +72,7 @@ These are just two typical examples.
See the [Inter Editors](../ui_tools/inter_editors.md) reference section for a description
of all available Inter editors.
-### Exiting editing mode
+## Exiting editing mode
Finally, to complete the on-going editing, we simply press the `Enter` key or
click on any location other than the Inter handles.
diff --git a/docs/_pages/ui_tools/inter_editors.md b/docs/_pages/ui_tools/inter_editors.md
index e02cab16b..3e15216eb 100644
--- a/docs/_pages/ui_tools/inter_editors.md
+++ b/docs/_pages/ui_tools/inter_editors.md
@@ -2,10 +2,10 @@
layout: default
title: Inter Editors
parent: References
-nav_order: 0
+nav_order: 2
---
-## Inter Editors
+# Inter Editors
{: .no_toc }
This reference chapter gathers the description of all Inter editors variants,
@@ -21,7 +21,7 @@ Table of contents (editors are presented in alphabetical order)
{:toc}
---
-### Default editor
+## Default editor
The default editor applies to every Inter class, for example the augmentation dot class here below,
unless a more specific editor is defined for the Inter class at hand.
@@ -43,7 +43,7 @@ Here, we are currently located too far from the note and the relation disappears
The next sections describe all specific editors, listed in alphabetical order.
-### Barline/Bracket editor
+## Barline/Bracket editor
@@ -55,7 +55,7 @@ Aligned barlines from different staves are often connected by so-called "Connect
The same editor applies to Bracket as well.
-### Brace editor
+## Brace editor
@@ -69,14 +69,14 @@ If you want to extend or reduce the number of staves embraced by a Brace instanc
this must be done **explicitly** by adding or removing a manual Brace.
Please refer to [Part merge](./part.md) section for such Brace usage.
-### Beam editor
+## Beam editor
* Center handle moves the whole beam in any direction.
* A side handle moves the side in any direction, **snapping** the beam side on any stem nearby.
-### Ending editor
+## Ending editor
@@ -84,14 +84,14 @@ Please refer to [Part merge](./part.md) section for such Brace usage.
* A side handle moves the ending side horizontally
(together with its side leg if any)
-### Flag editor
+## Flag editor
The flag editor is another variation of the default editor with its single center handle,
which here can move **only vertically** along the related stem.
-### Head editor
+## Head editor
@@ -102,7 +102,7 @@ The only difference is that the head being moved is snapped:
* **Horizontally** to the stem nearby, if any, on left or right.
Of course, this does not apply to WHOLE or BREVE shapes since these heads use no stem.
-### KeyAlter/Key editor
+## KeyAlter/Key editor
@@ -113,17 +113,17 @@ The key alter editor allows to move **horizontally** one KeyAlter member of the
If the key signature is a whole manual signature (e.g. it has been dropped from the ShapePalette),
then the editor can shift the **whole key** horizontally.
-### Ledger editor
+## Ledger editor
-### Multi-measure rest editor
+## Multi-measure rest editor
See details in [Multi-measure rest section](../specific/multi_rest.md#editing)
-### Octave shift editor
+## Octave shift editor
Single-line editor:
@@ -135,7 +135,7 @@ Multiple-line editor:
See details in [Octave Shift section](../specific/octave_shift.md#editing)
-### Slur editor
+## Slur editor
This is the most complex editor:
@@ -145,7 +145,7 @@ This is the most complex editor:
* Control handles move their underlying control point,
* Middle of control segment moves both control points in any direction.
-### Staff lines editor
+## Staff lines editor
@@ -153,7 +153,7 @@ All the various lines handles in staff are available for individual vertical dra
See Staff Editing [Lines mode](staff_editor.md#lines-mode).
-### Staff global editor
+## Staff global editor
@@ -166,13 +166,13 @@ Handles are located on the staff middle line but they work for all lines as a wh
See Staff Editing [Global mode](staff_editor.md#global-mode).
-### Stem/Arpeggiato/Connector editor
+## Stem/Arpeggiato/Connector editor
The editor applies to Stem as well as Arpeggiato and Connector (of barlines or brackets)
-### TimeHalf/Time editor
+## TimeHalf/Time editor
@@ -186,13 +186,13 @@ If the time signature is a whole signature then is can be shifted horizontally a
Note this applies as well to signatures handled globally, such as a manual custom signature
or even a two-part signature (such as 2/4) if it was recognized globally.
-### Wedge editor
+## Wedge editor
The handle on the lower segment allows to increase or decrease the wedge vertical spread.
-### Word editor
+## Word editor
diff --git a/docs/_pages/ui_tools/key.md b/docs/_pages/ui_tools/key.md
index ea2341ba2..76485e152 100644
--- a/docs/_pages/ui_tools/key.md
+++ b/docs/_pages/ui_tools/key.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 10
---
-## Key Signature
+# Key Signature
{: .no_toc }
A key signature cannot be built or modified incrementally by adding or removing one alteration
@@ -22,7 +22,7 @@ Table of contents
{:toc}
---
-### Flats and Sharps
+## Flats and Sharps
When dragging a "ghost" key from the shape palette, the ghost turns from dark-gray to green
when we enter a staff and, as usual, a thin red segment is drawn from the ghost center to the staff mid line.
@@ -39,7 +39,7 @@ Note the two sharp signs are located on F and C steps respectively, and they can
horizontally until we release the mouse.
Once dropped, we can still set the key into editing mode and again shift the inserted key.
-### Naturals
+## Naturals
As of this writing, the Audiveris OMR engine can recognize all-sharp keys and all-flat keys but
no key with natural signs inserted
diff --git a/docs/_pages/ui_tools/measure.md b/docs/_pages/ui_tools/measure.md
index 3d91b1a58..2a24301d4 100644
--- a/docs/_pages/ui_tools/measure.md
+++ b/docs/_pages/ui_tools/measure.md
@@ -5,11 +5,11 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 9
---
-## Measure Merge
+# Measure Merge
{: .no_toc }
A right-click in any measure stack allows us to merge this measure with the following one
-on the right, via the menu ` → Measure #N → Merge on right`
+on the right, via the contextual menu `≡ Measure #N → Merge on right`
(which is disabled for the last measure of a system).
It is a convenient way to remove all the intermediate barlines, if any, and merge the two
diff --git a/docs/_pages/ui_tools/octave_shift.md b/docs/_pages/ui_tools/octave_shift.md
index fe6095748..8d2051023 100644
--- a/docs/_pages/ui_tools/octave_shift.md
+++ b/docs/_pages/ui_tools/octave_shift.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 15
---
-## Octave Shift
+# Octave Shift
{: .no_toc }
{: .d-inline-block }
New in 5.3
@@ -19,7 +19,7 @@ Table of contents
{:toc}
---
-### Definition
+## Definition
An octave shift looks like this:
@@ -44,7 +44,7 @@ to name a few ones related to ottava.
- And how can the OMR engine determine the related staff of an octave shift?
Using the vertical distance to the closest staff is not reliable enough.
-### Multi-system octave shift
+## Multi-system octave shift
The example at the beginning of this page presented a rather short octave shift,
limited in range to a portion of the physical staff just below it.
@@ -63,7 +63,7 @@ Notice also the other shift located on the lower staff of the second system, or
-### Current status
+## Current status
As of this writing, automatic recognition of octave shifts by the Audiveris engine is very limited:
- The starting glyph (`8`, `15` or `22`) could be recognized,
@@ -82,15 +82,15 @@ above for `alta`, below for `bassa`.
4. Logical octave shifts can cross system breaks but not page breaks.
5. A hook is always present at the end of the last physical octave shift, and only there.
-### Creation
+## Creation
The easiest way to create an octave shift is a drag & drop from the `ClefsAndShifts` family in the
Shape board:
-1. Drag the desired shift symbol
-2. Pay attention to hover over the target staff.
+1. We drag the desired shift symbol
+2. We pay attention to hover over the target staff.
Staff information is sticky:
- The symbol is initially displayed in gray with no hook, then in green when hovering over a staff
- The last hovered staff becomes the current staff, and potential links to staff chords are shown
@@ -100,22 +100,22 @@ Shape board:
| :---: | :---: |
| an `alta` downside hook appears | a `bassa` upside hook appears |
|  | |
-3. Drop the symbol at the desired location (typically the center of the number box) by releasing the mouse.
+3. We drop the symbol at the desired location (typically the center of the number box) by releasing the mouse.
Another way is to select a suitable glyph, which must be limited to the number part
without any suffix:
-1. This will trigger the glyph classifier which may recognize the shape, in which case press
-the proper button in the classifier board.
-2. If not, manually assign the target shape via the pop-up menu or via a double-click in the
+1. This will trigger the glyph classifier which may recognize the shape,
+in which case we just press the proper button in the classifier board.
+2. If not, we can manually assign the target shape via the pop-up menu or via a double-click in the
`ClefsAndShifts` family of the Shape board.
-3. Note you will be prompted for the precise target staff of the created shift.
+3. Note that we will be prompted for the precise target staff of the created shift.
-In both ways, what you have created is just a small octave shift.
-You can now proceed to its precise editing as described in the next section.
+In both ways, what we have created is just a small octave shift.
+We can now proceed to its precise editing as described in the next section.
-### Editing
+## Editing
-The octave shift editor provide up to 3 handles: left, middle and right:
+The octave shift editor provides up to 3 handles: left, middle and right:
- All these handles can move the shift vertically between the current staff and the other staff,
above or below, according to the shift kind alta/bassa.
- Only the left and right handles, when present, can resize the shift line horizontally within
@@ -155,6 +155,6 @@ entity. This applies to creation, editing and removal actions.
And as usual, any of these actions can be undone and redone at will.
-### Removal
+## Removal
The manual removal of any (physical) octave shift means the removal of the whole "logical" octave shift.
diff --git a/docs/_pages/ui_tools/part.md b/docs/_pages/ui_tools/part.md
index 685ece527..ce8a9c083 100644
--- a/docs/_pages/ui_tools/part.md
+++ b/docs/_pages/ui_tools/part.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 8
---
-## Part Merge
+# Part Merge
{: .no_toc }
During the ``GRID`` step, the OMR engine detects staves and assigns exactly one part per staff,
diff --git a/docs/_pages/ui_tools/remove_inter.md b/docs/_pages/ui_tools/remove_inter.md
index 744bec914..7c12447e0 100644
--- a/docs/_pages/ui_tools/remove_inter.md
+++ b/docs/_pages/ui_tools/remove_inter.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 3
---
-## Inter Removal
+# Inter Removal
{: .no_toc }
When one or several Inter instances have been selected, we can remove them as follows:
@@ -15,7 +15,7 @@ When one or several Inter instances have been selected, we can remove them as fo
This applies only for the displayed Inter.
-* The pop-up menu, trigerred by a right click, in its `Inters...` sub-menu, provides an item to
+* The {{ site.popup_inters }} contextual menu provides an item to
remove the selected Inter entities according to their containing system.
diff --git a/docs/_pages/ui_tools/remove_relation.md b/docs/_pages/ui_tools/remove_relation.md
index b50986999..e60d32a07 100644
--- a/docs/_pages/ui_tools/remove_relation.md
+++ b/docs/_pages/ui_tools/remove_relation.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 5
---
-## Relation Removal
+# Relation Removal
{: .no_toc }
---
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Removing a wrong relation
+## Removing a wrong relation
There is no direct way to select Relation instances.
They can be selected only indirectly, via the selection of one of the Inter instances they link.
@@ -28,7 +28,8 @@ In the following example, a sharp sign has been linked to the wrong note head:
To select this relation, we first select the involved sharp sign.
This will result in the picture above.
-Then we use a right-click to display the context pop-up menu, hover on the `Inters...` submenu,
+Then we use a right-click to display the contextual menu {{ site.popup_inters }},
+hover on the `Inters...` submenu,
then on the sharp item to see the `Relations:` list of relations this Inter is involved in.
By clicking on the _AlterHead_ relation, we will be prompted to confirm the removal of this
@@ -45,7 +46,7 @@ configuration below:
-### Implicit relation removal
+## Implicit relation removal
In the precise case above (correcting reference of accidentals), explicit removal of the
relation was not necessary, provided the correct relation is inserted manually.
diff --git a/docs/_pages/ui_tools/shared_head.md b/docs/_pages/ui_tools/shared_head.md
index 9029c730b..f5b2d80dd 100644
--- a/docs/_pages/ui_tools/shared_head.md
+++ b/docs/_pages/ui_tools/shared_head.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 14
---
-## Shared Head
+# Shared Head
{: .no_toc }
---
@@ -16,7 +16,7 @@ Table of contents
{:toc}
---
-### Note head shared by two voices
+## Note head shared by two voices
Generally a note head (filled or void -- except whole and breve notes) is connected to exactly one stem, as in the following example.
@@ -55,7 +55,7 @@ And if voices are colorized, the separation between head 'halves' becomes even m
-### Impact on relations
+## Impact on relations
Playing with relations around note heads, such as the relation with an accidental or with an
augmentation dot, is still possible with shared note heads.
diff --git a/docs/_pages/ui_tools/staff_editor.md b/docs/_pages/ui_tools/staff_editor.md
index e0aa0fcc5..2799d184f 100644
--- a/docs/_pages/ui_tools/staff_editor.md
+++ b/docs/_pages/ui_tools/staff_editor.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 6
---
-## Staff Editing
+# Staff Editing
{: .no_toc }
During the `GRID` step, the OMR engine strives to detect sequences of equally spaced,
@@ -22,8 +22,8 @@ If the engine result is not satisfactory, we can manually correct these staves v
editing, which is provided in two different modes: `Global` mode and `Lines` mode.
The former operates on the staff as a whole, the latter on any line separately.
-To enter staff editing, we right-click within a staff area, in the pop-up menu select the
-`Staff#n...` sub-menu and then select:
+To enter staff editing, we right-click within a staff area, and in the {{ site.popup_staff }}
+contextual menu we select:
- either the `Edit staff` item to edit the staff globally,
- or the `Edit lines` item to edit each staff line individually.
@@ -35,7 +35,7 @@ Table of contents
{:toc}
---
-### Lines mode
+## Lines mode
In this mode, we can modify the different lines of the staff individually.
@@ -76,7 +76,7 @@ The number of handles may vary from line to line, as can be seen in the picture.
This number depends on the "wavyness" of the line detected by the engine.
It has no negative impact on the editing capabilities.
-### Global mode
+## Global mode
In this mode, we can move staff portions vertically and/or horizontally, and in doing so we modify
all staff lines as a whole.
diff --git a/docs/_pages/ui_tools/system.md b/docs/_pages/ui_tools/system.md
index 670bcfcdf..45855013b 100644
--- a/docs/_pages/ui_tools/system.md
+++ b/docs/_pages/ui_tools/system.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 7
---
-## System Merge
+# System Merge
{: .no_toc }
In the Audiveris ``GRID`` step, detected staves are gathered into systems, based on barlines found on
@@ -23,8 +23,8 @@ detection of systems by the OMR engine.
Since the 5.2 release, we can manually fix this problem.
-We point at the upper system portion, and via the right-click pop-up menu, navigate to `System#n ...`
-and click on "_Merge with system below_".
+We point at the upper system portion, and via the right-click {{ site.popup_system }} menu
+we select "_Merge with system below_".
diff --git a/docs/_pages/ui_tools/text.md b/docs/_pages/ui_tools/text.md
index a219f4d55..debfee568 100644
--- a/docs/_pages/ui_tools/text.md
+++ b/docs/_pages/ui_tools/text.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 13
---
-## Text
+# Text
{: .no_toc }
Recognition of textual elements is delegated to the Tesseract OCR library.
@@ -21,7 +21,7 @@ Table of contents
1. TOC
{:toc}
---
-### Recognition of text items
+## Recognition of text items
It is very difficult to automatically derive the meaning from the textual items in a musical score.
@@ -33,7 +33,7 @@ For **plain text**, Audiveris tries to detect the text role, such as directions
elements like: title, composer and lyricist.
If it fails, the role can be easily corrected manually.
-### TEXTS step
+## TEXTS step
The `TEXTS` step runs the Tesseract OCR on the whole image and tries to assign to each textual item its
probable content, type and role.
@@ -46,7 +46,7 @@ This engine step is influenced by three options available in the `Book parameter
Chord names and lyrics are special items; this is the reason why their recognition must be
explicitly selected to avoid collateral damages of the OMR engine when they are not desired.
-### Manual OCR
+## Manual OCR
Tesseract OCR can also be launched manually on a glyph(s) selection by pressing one of two
buttons provided in the `Physicals` family of the Shape palette:
@@ -60,7 +60,7 @@ plain text items, especially the gap between words can be much wider.
By choosing one button or the other, the user clearly specifies the desired result type of the
OCR operation.
-### Sentence vs Words
+## Sentence vs Words
A Sentence Inter is an ensemble of one or several Word Inter(s):
@@ -94,7 +94,7 @@ Rights,
EndingNumber,
EndingText.
-### Plain Sentence
+## Plain Sentence
A "plain" sentence is any sentence which is assigned a role different from Lyrics.
@@ -106,7 +106,7 @@ whereas the `text` button will always result in a non _lyrics_ role.
Since the 5.2 release, in all cases, the end-user can manually modify the sentence
role afterwards, from any role to any other role.
-### Chord Name
+## Chord Name
A chord name is a musical symbol which names and describes the related chord.
@@ -137,7 +137,7 @@ or `#` characters are automatically replaced by their true alteration signs.
For example, we can type "Bb" then press `Enter` and the chord name will be translated and
displayed as "B♭".
-### Lyric Line
+## Lyric Line
A lyric line is a sentence composed of lyric items.
diff --git a/docs/_pages/ui_tools/time.md b/docs/_pages/ui_tools/time.md
index 980a26f84..e2451627c 100644
--- a/docs/_pages/ui_tools/time.md
+++ b/docs/_pages/ui_tools/time.md
@@ -5,7 +5,7 @@ grand_parent: User Editing
parent: UI Tools
nav_order: 11
---
-## Time Signature
+# Time Signature
{: .no_toc }
---
@@ -15,7 +15,7 @@ Table of contents
1. TOC
{:toc}
---
-### Whole vs Pair
+## Whole vs Pair
Audiveris OMR is able to handle both whole- and pair- time signatures:
@@ -36,7 +36,7 @@ to a pair, and at the same time recognize the "2/4" compound glyph leading to a
The better grade will determine which interpretation will be kept.
In fact, the precise chosen interpretation has no impact on OMR processing.
-### Predefined time signatures
+## Predefined time signatures
If a time signature has not been detected or has been assigned a wrong value, we can select the
underlying glyph and assign the desired value, either via a double-click in the shape palette or
@@ -50,7 +50,7 @@ of a pair.
Moreover, in these two cases (glyph assignment and drag & drop), please note that the choice is
_limited to the predefined shapes_ of the palette.
-### Custom time signature
+## Custom time signature
Since the 5.2 release, the time shape palette provides a `custom` time signature.
This is a fully-customizable combo signature.
@@ -75,7 +75,7 @@ The only constraint is that each numerator or denominator value must stay within
-### Location
+## Location
We cannot resize a time signature, and its location is snapped on the containing staff.
diff --git a/docs/_pages/ui_tools/tips.md b/docs/_pages/ui_tools/tips.md
index 45d912415..33e590c5b 100644
--- a/docs/_pages/ui_tools/tips.md
+++ b/docs/_pages/ui_tools/tips.md
@@ -3,9 +3,9 @@ layout: default
title: Tips and Tricks
grand_parent: User Editing
parent: UI Tools
-nav_order: 15
+nav_order: 16
---
-## Tips and Tricks
+# Tips and Tricks
{: .no_toc }
This section gathers a few things based on concrete user experience.
@@ -19,7 +19,7 @@ Table of contents
{:toc}
---
-### Select glyphs using the selection Frame
+## Select glyphs using the selection Frame
In bad scans, often elements are detected as two or more separate glyphs
-- this is rather frequent for slurs.
@@ -31,7 +31,7 @@ define an inter for it:
We have to make sure not to select parts of other elements (e.g. augmentation dots)!
-### Delete incorrect interpretations before defining new ones
+## Delete incorrect interpretations before defining new ones
Before assigning another interpretation to a glyph / a group of glyphs, we make sure to delete
the previous one first.
@@ -43,7 +43,7 @@ interpretations, and thus remove the old one to just keep the new one.
But glyphs that differ by one pixel or more are, by definition, different glyphs!
So, when in doubt, we should not hesitate to clean up the scene beforehand.
-### Look for missing / wrongly defined augmentation dots
+## Look for missing / wrongly defined augmentation dots
The most frequent reasons for errors in the rhythm check are missing or wrongly detected
augmentation dots.
@@ -51,7 +51,7 @@ augmentation dots.
So when all obvious reasons for incorrect rhythm are solved and the measure is still in pink,
we can zoom into the image and look for augmentation dots in the concerned measure.
-### Wrongly detected grace notes
+## Wrongly detected grace notes
Sometimes grace notes are considered as standard notes with just a rather small head.
And while all standard notes are involved in rhythm building, true grace notes are not,
@@ -62,7 +62,7 @@ because they are considered as mere ornaments.
In such a case we just delete the note and re-define with the correct interpretation
(from the `Ornaments` palette in Shape board)
-### Add triplet to 2nd voice with missing "3"
+## Add triplet to 2nd voice with missing "3"
Sometimes scores that contain two voices use a "common" 3 for a tuplet in both voices.
@@ -73,7 +73,7 @@ In such a case we can add the missing triplet element by drag & drop to the 2nd
| :---: |:---:| :---: |
| | ===> ||
-### Perfectly opposite notes
+## Perfectly opposite notes
Sometimes there are two notes of two voices with opposite stems in the same horizontal position.
diff --git a/docs/_pages/updates.md b/docs/_pages/updates.md
index 1abb53921..2ac8ff874 100644
--- a/docs/_pages/updates.md
+++ b/docs/_pages/updates.md
@@ -22,22 +22,35 @@ Table of contents
{:toc}
---
-### 5.4 (on-going)
+## 5.4 (on-going)
- User Interface
+ - Past the SYMBOLS step, the manual removal of any Inter now triggers a dynamic rebuilding of glyphs,
+ as if the removed Inter had never existed.
- Improvement and extension of default/book/sheet parameters (interline, barline)
- - Ability to display some inters (augmentation dots by default) in jumbo mode
- - Ability to stop current book processing at next step end
- - Ability to clear the log window
+ - Ability to display some inters in jumbo mode to ease a visual inspection
+ -- by default this can apply to augmentation dots.
+ - Ability to gracefully stop the current book processing at the next step end.
+ - Ability to clear the log window -- the log file remains intact.
+- Engine
+ - The recognition of fermata no longer requires separate recognitions of fermata-arc and fermata-dot.
+ - The processing of an input image with no white margin around the staves is now possible.
- Project
+ - A Linux Flatpak package, gathering the needed libraries, proper Java environment
+ and the main Tesseract language files, is now provided on FlatHub.
- The Windows installer pre-populates the user `config`/`tessdata` folder with the main Tesseract
- languages
+ languages.
- Documentation
- - Support for a PDF version of the Audiveris Handbook
+ - Support for a PDF version of the Audiveris Handbook.
- Java
- - In `Audiveris.bat` and `Audiveris` start scripts, Java version is checked before being launched
+ - In `Audiveris.bat` (used by the Windows installer) and `Audiveris` start scripts,
+ the Java version is checked before the application is launched.
+ - Support of Java 21.
+ - Upgrade to Gradle 8.5 to support Java 21.
+ - Removal of all deprecated features such as JGoodies PanelBuilder, Observer/Observable,
+ class.newInstance(), etc.
-### 5.3
+## 5.3
- User Interface
- Editing of staff geometry, at individual line and global staff levels
@@ -61,7 +74,7 @@ Table of contents
- Java
- Support of Java 17
-### 5.2
+## 5.2
- User Interface
- Ability to move and resize symbols
@@ -97,7 +110,7 @@ Table of contents
- Support of Java 11
- Refined dependencies on Java EE, JAXB, etc away from Java 8
-### 5.1
+## 5.1
- User Interface
- Visual separation of shared heads
@@ -110,7 +123,7 @@ Table of contents
- Java
- Support of Java 8
-### 5.0
+## 5.0
- Engine
- Creation of `.omr` project files