Merge pull request #223 from DCMLab/readme-ui-update

Readme UI update
DCMLab · May 3, 2022 · 197da6f · 197da6f
2 parents 0386a86 + 8a79ec0
commit 197da6f
Show file tree

Hide file tree

Showing 12 changed files with 32 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -20,18 +20,17 @@ It is currently very much under construction, but can be tested [here](https://d
 The basics are as follows:
 
  * Clicking selects notes. Shift-click selects them as _primary_
- * Linking together the selected notes into a _relation_, alternatively
-   referred to as a _relation_ can be done either without giving the
+ * Linking together the selected notes into a _relation_ can be done either without giving the
    relation a type at all, by clicking one of the preset buttons or their
    key bindings, or by writing a custom type into the text field and
-   clicking the "Add relation with custom type" button.
+   clicking the "Assign" button.
  * Relations with both primary and secondary notes imply a priority among
    the notes. If we add a number of relations such that no circular
-   priorities are introduced, we have defined a typ of _hierarchy_ among
+   priorities are introduced, we have defined a type of _hierarchy_ among
    the notes and relations.
  * After having annotated a number of relations/relations, we can _reduce_
-   the lowest-ranked notes in our hierarchy by clicking the "Reduce
-   Relations" button. We can also select a subset of the existing
+   the lowest-ranked notes in our hierarchy by clicking the "Reduce" button. 
+   We can also select a subset of the existing
    relations to attempt to reduce. The basic algorithm is this: Each
    reduced relation also removes its secondary notes, and leaves its
    primary notes to the next step.  However, any relations that are _not_
@@ -40,88 +39,80 @@ The basics are as follows:
    this step, and the removed notes are only secondaries of removed
    relations.
 
-*Note that the below illustrations all come from a previous version referring to "hyperedges". In the present version these have all been replaced by "relations".*
-
 ## A short example
 
 Let us load a familiar piece into the annotation app: Bach's Prelude in C
 Major from The Well-tempered Clavier (BWV 846). This is done by selecting
-the file from your computer through the file selector at the bottom left. Once
-chosen, the app should render it directly as in
+the file from your computer through the file selector accessed from the 
+"Select a score" button. Once chosen, the app should render it directly as in
 
-![](images/tutorial1.png?raw=true)
+![](images/tutorial21.png?raw=true)
 
 This done, we can begin selecting notes by clicking them. We can also select notes as _primary_ by shift-clicking them.
 
 After selecting a number of notes, we can associate them using a relation,
 either of some specific type, or untyped. There are a number of predefined
-edge types with dedicated buttons and keybindings, and a textfield for
-entering a custom type.
+relation types with dedicated buttons and keybindings, and a textfield for
+entering a custom type in the expanded menu.
 
 Let us select the first E in the upper voice as primary, and the rest of the E's in that measure as secondary:
 
-![](images/tutorial2.png?raw=true)
+![](images/tutorial22.png?raw=true)
 
 We can do this either by clicking and shift-clicking the individual notes,
-and then either clicking the button marked "Add repeat(+) relation" or
+and then either clicking the button marked "Repeat" or
 using the "+" keyboard shortcut. However, specifically for the situation
 that all the notes of the same pitch in a single bar should be selected and
 related as repeats, it is also possible to just select the primary note of
 the repeat and then hitting "+".
 
-![](images/tutorial3.png?raw=true)
+![](images/tutorial23.png?raw=true)
 
-After having created a number of relations, we can choose to a "Reduce"
-step, which hides the "lowest" level of edges, as described above.. For
+After having created a number of relations, we can choose to do a "Reduce"
+step (by clicking the button in the layer menu on the left) which hides 
+the "lowest" level of edges, as described above. For
 example, if we have made similar relations for the other parts in the
 arpeggio, we can reduce the first bar of the Prelude from this:
 
-![](images/tutorial4.png?raw=true)
+![](images/tutorial24.png?raw=true)
 
 To this:
 
-![](images/tutorial5.png?raw=true)
+![](images/tutorial25.png?raw=true)
 
 However, this doesn't look very nice, as we only hide the notes, and not
 the beams and other things related to notes. We can hide stems and beams
-and such things with the button "Toggle (s)tems etc." or the keyboard
+and such things with the button "Stems etc." in the "More options" menu, or the keyboard
 shortcut "s".
 
-![](images/tutorial6.png?raw=true)
+![](images/tutorial26.png?raw=true)
 
 But this still leaves us with an embarrassing amount of unused space, as
-well as unused ledger lines. To rerender the MEI with the removed notes, we
-can click the button marked "Rerender less hidden notes" **but beware**! Up
-until now, we can undo things to no ill effect (with the button or the "u"
-key), but as soon as we rerender, undo is not going to work past that
-point. 
-
-Still, let's go ahead:
+well as unused ledger lines. We can, however, create a _new layer_, which
+will be added in the app below the first layer, where such unused spaced can be
+significantly reduced, and features like note editing becomes available.
 
-![](images/tutorial7.png?raw=true)
+![](images/tutorial27.png?raw=true)
 
-Much better!
+Slightly better!
 
-Having done a number of reductions and rerenderings, we can end up with something similar to:
+Having done a number of reductions and new layers, we can end up with something similar to:
 
-![](images/tutorial8.png?raw=true)
+![](images/tutorial28.png?raw=true)
 
 Which starts to be useful for further analysis.
 
 By clicking the "Save" button, you will get the option to save the original
-MEI plus the graph as currently envisioned. For example, saving the above
+MEI, any selection of additional layers, plus the graph as currently envisioned. For example, saving the above
 state and then loading the resulting file will show this view:
 
-![](images/tutorial9.png?raw=true)
-
-Which can then be turned into the previous view by first reducing and then
-rerendering (and also hiding stems etc.).
+![](images/tutorial29.png?raw=true)
 
 ## Hierarchical analysis
 
 More exciting possibilities are open by having overlapping and interacting
 relations, though this is beyond the scope of this simple example. For
-presenting this work as a Late-Breaking Demo at ISMIR2020, the following
+presenting an earlier version of this work as a Late-Breaking Demo at ISMIR2020, the following
 illustrative gifs were produced, showcasing some more advanced ideas:
 
 **Update**: In the GIFs below, reference is made to needing to delete edges in order to see relations "behind" them. This is no longer required: instead, by scrolling with the scroll wheel (up or down), the currently highlighted edge is sent to the "bottom" of the stack, showing the edges that were "hidden".

diff --git a/images/tutorial21.png b/images/tutorial21.png
diff --git a/images/tutorial22.png b/images/tutorial22.png
diff --git a/images/tutorial23.png b/images/tutorial23.png
diff --git a/images/tutorial24.png b/images/tutorial24.png
diff --git a/images/tutorial25.png b/images/tutorial25.png
diff --git a/images/tutorial26.png b/images/tutorial26.png
diff --git a/images/tutorial27.png b/images/tutorial27.png
diff --git a/images/tutorial28.png b/images/tutorial28.png
diff --git a/images/tutorial29.png b/images/tutorial29.png
diff --git a/src/components.html b/src/components.html
@@ -471,7 +471,7 @@ <h4 class="fly-out__title">File</h4>
                 <button class="btn btn--plain btn--small" type="button"><span>Save as <abbr title="Scalable Vector Graphics">SVG</abbr></span></button>
                 <label class="file | btn btn--plain btn--small" for="file">
                     <span>
-                        Select a <abbr title="Music Encoding Initiative">MEI</abbr> file
+                        Select a score <!--abbr title="Music Encoding Initiative">MEI</abbr> file-->
                         <input class="file__input" id="file" type="file" accept=".mei,.mxl,.musicxml,.xml,.abc">
                     </span>
                 </label>

diff --git a/src/index.html b/src/index.html
@@ -174,7 +174,7 @@ <h4 class="fly-out__title">File</h4>
 
                         <label class="file | btn btn--plain btn--small" for="score-file-picker">
                             <span>
-                                Select a <abbr title="Music Encoding Initiative">MEI</abbr> file
+				Select a score <!--abbr title="Music Encoding Initiative">MEI</abbr> file-->
                                 <input class="file__input" id="score-file-picker" type="file" accept=".mei,.mxl,.musicxml,.xml,.abc">
                             </span>
                         </label>