vexflow

<!DOCTYPE html> <html> <head> <title>accidental.js</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="public/stylesheets/normalize.css" /> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div class="container"> <div class="page"> <div class="header"> <h1>accidental.js</h1> <div class="toc"> <h3>Table of Contents</h3> <ol> <li> <a class="source" href="accidental.html"> accidental.js </a> </li> <li> <a class="source" href="annotation.html"> annotation.js </a> </li> <li> <a class="source" href="articulation.html"> articulation.js </a> </li> <li> <a class="source" href="barnote.html"> barnote.js </a> </li> <li> <a class="source" href="beam.html"> beam.js </a> </li> <li> <a class="source" href="bend.html"> bend.js </a> </li> <li> <a class="source" href="boundingbox.html"> boundingbox.js </a> </li> <li> <a class="source" href="boundingboxcomputation.html"> boundingboxcomputation.js </a> </li> <li> <a class="source" href="canvascontext.html"> canvascontext.js </a> </li> <li> <a class="source" href="clef.html"> clef.js </a> </li> <li> <a class="source" href="clefnote.html"> clefnote.js </a> </li> <li> <a class="source" href="crescendo.html"> crescendo.js </a> </li> <li> <a class="source" href="curve.html"> curve.js </a> </li> <li> <a class="source" href="dot.html"> dot.js </a> </li> <li> <a class="source" href="easyscore.html"> easyscore.js </a> </li> <li> <a class="source" href="element.html"> element.js </a> </li> <li> <a class="source" href="factory.html"> factory.js </a> </li> <li> <a class="source" href="formatter.html"> formatter.js </a> </li> <li> <a class="source" href="fraction.html"> fraction.js </a> </li> <li> <a class="source" href="frethandfinger.html"> frethandfinger.js </a> </li> <li> <a class="source" href="ghostnote.html"> ghostnote.js </a> </li> <li> <a class="source" href="glyph.html"> glyph.js </a> </li> <li> <a class="source" href="glyphnote.html"> glyphnote.js </a> </li> <li> <a class="source" href="gracenote.html"> gracenote.js </a> </li> <li> <a class="source" href="gracenotegroup.html"> gracenotegroup.js </a> </li> <li> <a class="source" href="gracetabnote.html"> gracetabnote.js </a> </li> <li> <a class="source" href="index.html"> index.js </a> </li> <li> <a class="source" href="keymanager.html"> keymanager.js </a> </li> <li> <a class="source" href="keysignature.html"> keysignature.js </a> </li> <li> <a class="source" href="keysignote.html"> keysignote.js </a> </li> <li> <a class="source" href="modifier.html"> modifier.js </a> </li> <li> <a class="source" href="modifiercontext.html"> modifiercontext.js </a> </li> <li> <a class="source" href="multimeasurerest.html"> multimeasurerest.js </a> </li> <li> <a class="source" href="music.html"> music.js </a> </li> <li> <a class="source" href="note.html"> note.js </a> </li> <li> <a class="source" href="notehead.html"> notehead.js </a> </li> <li> <a class="source" href="notesubgroup.html"> notesubgroup.js </a> </li> <li> <a class="source" href="ornament.html"> ornament.js </a> </li> <li> <a class="source" href="parser.html"> parser.js </a> </li> <li> <a class="source" href="pedalmarking.html"> pedalmarking.js </a> </li> <li> <a class="source" href="raphaelcontext.html"> raphaelcontext.js </a> </li> <li> <a class="source" href="registry.html"> registry.js </a> </li> <li> <a class="source" href="renderer.html"> renderer.js </a> </li> <li> <a class="source" href="repeatnote.html"> repeatnote.js </a> </li> <li> <a class="source" href="smufl.html"> smufl.js </a> </li> <li> <a class="source" href="stave.html"> stave.js </a> </li> <li> <a class="source" href="stavebarline.html"> stavebarline.js </a> </li> <li> <a class="source" href="staveconnector.html"> staveconnector.js </a> </li> <li> <a class="source" href="stavehairpin.html"> stavehairpin.js </a> </li> <li> <a class="source" href="staveline.html"> staveline.js </a> </li> <li> <a class="source" href="stavemodifier.html"> stavemodifier.js </a> </li> <li> <a class="source" href="stavenote.html"> stavenote.js </a> </li> <li> <a class="source" href="staverepetition.html"> staverepetition.js </a> </li> <li> <a class="source" href="stavesection.html"> stavesection.js </a> </li> <li> <a class="source" href="stavetempo.html"> stavetempo.js </a> </li> <li> <a class="source" href="stavetext.html"> stavetext.js </a> </li> <li> <a class="source" href="stavetie.html"> stavetie.js </a> </li> <li> <a class="source" href="stavevolta.html"> stavevolta.js </a> </li> <li> <a class="source" href="stem.html"> stem.js </a> </li> <li> <a class="source" href="stemmablenote.html"> stemmablenote.js </a> </li> <li> <a class="source" href="stringnumber.html"> stringnumber.js </a> </li> <li> <a class="source" href="strokes.html"> strokes.js </a> </li> <li> <a class="source" href="svgcontext.html"> svgcontext.js </a> </li> <li> <a class="source" href="system.html"> system.js </a> </li> <li> <a class="source" href="tables.html"> tables.js </a> </li> <li> <a class="source" href="tabnote.html"> tabnote.js </a> </li> <li> <a class="source" href="tabslide.html"> tabslide.js </a> </li> <li> <a class="source" href="tabstave.html"> tabstave.js </a> </li> <li> <a class="source" href="tabtie.html"> tabtie.js </a> </li> <li> <a class="source" href="textbracket.html"> textbracket.js </a> </li> <li> <a class="source" href="textdynamics.html"> textdynamics.js </a> </li> <li> <a class="source" href="textnote.html"> textnote.js </a> </li> <li> <a class="source" href="tickable.html"> tickable.js </a> </li> <li> <a class="source" href="tickcontext.html"> tickcontext.js </a> </li> <li> <a class="source" href="timesignature.html"> timesignature.js </a> </li> <li> <a class="source" href="timesignote.html"> timesignote.js </a> </li> <li> <a class="source" href="tremolo.html"> tremolo.js </a> </li> <li> <a class="source" href="tuning.html"> tuning.js </a> </li> <li> <a class="source" href="tuplet.html"> tuplet.js </a> </li> <li> <a class="source" href="vex.html"> vex.js </a> </li> <li> <a class="source" href="vibrato.html"> vibrato.js </a> </li> <li> <a class="source" href="vibratobracket.html"> vibratobracket.js </a> </li> <li> <a class="source" href="voice.html"> voice.js </a> </li> <li> <a class="source" href="voicegroup.html"> voicegroup.js </a> </li> </ol> </div> </div> <a href="http://vexflow.com">VexFlow</a> - Copyright (c) Mohit Muthanna 2010. @author Mohit Cheppudira @author Greg Ristow (modifications) <h2 id="description">Description</h2> This file implements accidentals as modifiers that can be attached to notes. Support is included for both western and microtonal accidentals. See <code>tests/accidental_tests.js</code> for usage examples. <div class='highlight'><pre> import { Vex } from './vex'; import { Fraction } from './fraction'; import { Flow } from './tables'; import { Music } from './music'; import { Modifier } from './modifier'; import { Glyph } from './glyph';</pre></div> To enable logging for this class. Set <code>Vex.Flow.Accidental.DEBUG</code> to <code>true</code>. <div class='highlight'><pre>function L(...args) { if (Accidental.DEBUG) Vex.L('Vex.Flow.Accidental', args); } const getGlyphWidth = glyph => glyph.getMetrics().width;</pre></div> An <code>Accidental</code> inherits from <code>Modifier</code>, and is formatted within a <code>ModifierContext</code>. <div class='highlight'><pre>export class Accidental extends Modifier { static get CATEGORY() { return 'accidentals'; }</pre></div> Arrange accidentals inside a ModifierContext. <div class='highlight'><pre> static format(accidentals, state) { const noteheadAccidentalPadding = 1; const leftShift = state.left_shift + noteheadAccidentalPadding; const accidentalSpacing = 3;</pre></div> If there are no accidentals, we needn’t format their positions <div class='highlight'><pre> if (!accidentals || accidentals.length === 0) return; const accList = []; let prevNote = null; let shiftL = 0;</pre></div> First determine the accidentals’ Y positions from the note.keys <div class='highlight'><pre> for (let i = 0; i < accidentals.length; ++i) { const acc = accidentals[i]; const note = acc.getNote(); const stave = note.getStave(); const props = note.getKeyProps()[acc.getIndex()]; if (note !== prevNote) {</pre></div> Iterate through all notes to get the displaced pixels <div class='highlight'><pre> for (let n = 0; n < note.keys.length; ++n) { shiftL = Math.max(note.getLeftDisplacedHeadPx(), shiftL); } prevNote = note; } if (stave !== null) { const lineSpace = stave.options.spacing_between_lines_px; const y = stave.getYForLine(props.line); const accLine = Math.round(y / lineSpace * 2) / 2; accList.push({ y, line: accLine, shift: shiftL, acc, lineSpace }); } else { accList.push({ line: props.line, shift: shiftL, acc }); } }</pre></div> Sort accidentals by line number. <div class='highlight'><pre> accList.sort((a, b) => b.line - a.line);</pre></div> FIXME: Confusing name. Each object in this array has a property called <code>line</code>. So if this is a list of lines, you end up with: <code>line.line</code> which is very awkward. <div class='highlight'><pre> const lineList = [];</pre></div> amount by which all accidentals must be shifted right or left for stem flipping, notehead shifting concerns. <div class='highlight'><pre> let accShift = 0; let previousLine = null;</pre></div> Create an array of unique line numbers (lineList) from accList <div class='highlight'><pre> for (let i = 0; i < accList.length; i++) { const acc = accList[i];</pre></div> if this is the first line, or a new line, add a lineList <div class='highlight'><pre> if (previousLine === null || previousLine !== acc.line) { lineList.push({ line: acc.line, flatLine: true, dblSharpLine: true, numAcc: 0, width: 0, }); }</pre></div> if this accidental is not a flat, the accidental needs 3.0 lines lower clearance instead of 2.5 lines for b or bb. FIXME: Naming could use work. acc.acc is very awkward <div class='highlight'><pre> if (acc.acc.type !== 'b' && acc.acc.type !== 'bb') { lineList[lineList.length - 1].flatLine = false; }</pre></div> if this accidental is not a double sharp, the accidental needs 3.0 lines above <div class='highlight'><pre> if (acc.acc.type !== '##') { lineList[lineList.length - 1].dblSharpLine = false; }</pre></div> Track how many accidentals are on this line: <div class='highlight'><pre> lineList[lineList.length - 1].numAcc++;</pre></div> Track the total x_offset needed for this line which will be needed for formatting lines w/ multiple accidentals: width = accidental width + universal spacing between accidentals <div class='highlight'><pre> lineList[lineList.length - 1].width += acc.acc.getWidth() + accidentalSpacing;</pre></div> if this accShift is larger, use it to keep first column accidentals in the same line <div class='highlight'><pre> accShift = acc.shift > accShift ? acc.shift : accShift; previousLine = acc.line; }</pre></div> <h3 id="place-accidentals-in-columns">Place Accidentals in Columns</h3> Default to a classic triangular layout (middle accidental farthest left), but follow exceptions as outlined in G. Read’s Music Notation and Elaine Gould’s Behind Bars. Additionally, this implements different vertical collision rules for flats (only need 2.5 lines clearance below) and double sharps (only need 2.5 lines of clearance above or below). Classic layouts and exception patterns are found in the ‘tables.js’ in ‘Vex.Flow.accidentalColumnsTable’ Beyond 6 vertical accidentals, default to the parallel ascending lines approach, using as few columns as possible for the verticle structure. TODO (?): Allow column to be specified for an accidental at run-time? <div class='highlight'><pre> let totalColumns = 0;</pre></div> establish the boundaries for a group of notes with clashing accidentals: <div class='highlight'><pre> for (let i = 0; i < lineList.length; i++) { let noFurtherConflicts = false; const groupStart = i; let groupEnd = i; while (groupEnd + 1 < lineList.length && !noFurtherConflicts) {</pre></div> if this note conflicts with the next: <div class='highlight'><pre> if (this.checkCollision(lineList[groupEnd], lineList[groupEnd + 1])) {</pre></div> include the next note in the group: <div class='highlight'><pre> groupEnd++; } else { noFurtherConflicts = true; } }</pre></div> Gets an a line from the <code>lineList</code>, relative to the current group <div class='highlight'><pre> const getGroupLine = (index) => lineList[groupStart + index]; const getGroupLines = (indexes) => indexes.map(getGroupLine); const lineDifference = (indexA, indexB) => { const [a, b] = getGroupLines([indexA, indexB]).map(item => item.line); return a - b; }; const notColliding = (...indexPairs) => indexPairs .map(getGroupLines) .every(lines => !this.checkCollision(...lines));</pre></div> Set columns for the lines in this group: <div class='highlight'><pre> const groupLength = groupEnd - groupStart + 1;</pre></div> Set the accidental column for each line of the group <div class='highlight'><pre> let endCase = this.checkCollision(lineList[groupStart], lineList[groupEnd]) ? 'a' : 'b'; switch (groupLength) { case 3: if (endCase === 'a' && lineDifference(1, 2) === 0.5 && lineDifference(0, 1) !== 0.5) { endCase = 'second_on_bottom'; } break; case 4: if (notColliding([0, 2], [1, 3])) { endCase = 'spaced_out_tetrachord'; } break; case 5: if (endCase === 'b' && notColliding([1, 3])) { endCase = 'spaced_out_pentachord'; if (notColliding([0, 2], [2, 4])) { endCase = 'very_spaced_out_pentachord'; } } break; case 6: if (notColliding([0, 3], [1, 4], [2, 5])) { endCase = 'spaced_out_hexachord'; } if (notColliding([0, 2], [2, 4], [1, 3], [3, 5])) { endCase = 'very_spaced_out_hexachord'; } break; default: break; } let groupMember; let column;</pre></div> If the group contains more than seven members, use ascending parallel lines of accidentals, using as few columns as possible while avoiding collisions. <div class='highlight'><pre> if (groupLength >= 7) {</pre></div> First, determine how many columns to use: <div class='highlight'><pre> let patternLength = 2; let collisionDetected = true; while (collisionDetected === true) { collisionDetected = false; for (let line = 0; line + patternLength < lineList.length; line++) { if (this.checkCollision(lineList[line], lineList[line + patternLength])) { collisionDetected = true; patternLength++; break; } } }</pre></div> Then, assign a column to each line of accidentals <div class='highlight'><pre> for (groupMember = i; groupMember <= groupEnd; groupMember++) { column = ((groupMember - i) % patternLength) + 1; lineList[groupMember].column = column; totalColumns = (totalColumns > column) ? totalColumns : column; }</pre></div> Otherwise, if the group contains fewer than seven members, use the layouts from the accidentalsColumnsTable housed in tables.js. <div class='highlight'><pre> } else { for (groupMember = i; groupMember <= groupEnd; groupMember++) { column = Flow.accidentalColumnsTable[groupLength][endCase][groupMember - i]; lineList[groupMember].column = column; totalColumns = (totalColumns > column) ? totalColumns : column; } }</pre></div> Increment i to the last note that was set, so that if a lower set of notes does not conflict at all with this group, it can have its own classic shape. <div class='highlight'><pre> i = groupEnd; }</pre></div> <h3 id="convert-columns-to-x_offsets">Convert Columns to x_offsets</h3> This keeps columns aligned, even if they have different accidentals within them which sometimes results in a larger x_offset than is an accidental might need to preserve the symmetry of the accidental shape. Neither A.C. Vinci nor G. Read address this, and it typically only happens in music with complex chord clusters. TODO (?): Optionally allow closer compression of accidentals, instead of forcing parallel columns. track each column’s max width, which will be used as initial shift of later columns: <div class='highlight'><pre> const columnWidths = []; const columnXOffsets = []; for (let i = 0; i <= totalColumns; i++) { columnWidths[i] = 0; columnXOffsets[i] = 0; } columnWidths[0] = accShift + leftShift; columnXOffsets[0] = accShift + leftShift;</pre></div> Fill columnWidths with widest needed x-space; this is what keeps the columns parallel. <div class='highlight'><pre> lineList.forEach(line => { if (line.width > columnWidths[line.column]) columnWidths[line.column] = line.width; }); for (let i = 1; i < columnWidths.length; i++) {</pre></div> this column’s offset = this column’s width + previous column’s offset <div class='highlight'><pre> columnXOffsets[i] = columnWidths[i] + columnXOffsets[i - 1]; } const totalShift = columnXOffsets[columnXOffsets.length - 1];</pre></div> Set the xShift for each accidental according to column offsets: <div class='highlight'><pre> let accCount = 0; lineList.forEach(line => { let lineWidth = 0; const lastAccOnLine = accCount + line.numAcc;</pre></div> handle all of the accidentals on a given line: <div class='highlight'><pre> for (accCount; accCount < lastAccOnLine; accCount++) { const xShift = (columnXOffsets[line.column - 1] + lineWidth); accList[accCount].acc.setXShift(xShift);</pre></div> keep track of the width of accidentals we’ve added so far, so that when we loop, we add space for them. <div class='highlight'><pre> lineWidth += accList[accCount].acc.getWidth() + accidentalSpacing; L('Line, accCount, shift: ', line.line, accCount, xShift); } });</pre></div> update the overall layout with the full width of the accidental shapes: <div class='highlight'><pre> state.left_shift += totalShift; }</pre></div> Helper function to determine whether two lines of accidentals collide vertically <div class='highlight'><pre> static checkCollision(line1, line2) { let clearance = line2.line - line1.line; let clearanceRequired = 3;</pre></div> But less clearance is required for certain accidentals: b, bb and ##. <div class='highlight'><pre> if (clearance > 0) { // then line 2 is on top clearanceRequired = (line2.flatLine || line2.dblSharpLine) ? 2.5 : 3.0; if (line1.dblSharpLine) clearance -= 0.5; } else { // line 1 is on top clearanceRequired = (line1.flatLine || line1.dblSharpLine) ? 2.5 : 3.0; if (line2.dblSharpLine) clearance -= 0.5; } const collision = Math.abs(clearance) < clearanceRequired; L('Line_1, Line_2, Collision: ', line1.line, line2.line, collision); return collision; }</pre></div> Use this method to automatically apply accidentals to a set of <code>voices</code>. The accidentals will be remembered between all the voices provided. Optionally, you can also provide an initial <code>keySignature</code>. <div class='highlight'><pre> static applyAccidentals(voices, keySignature) { const tickPositions = []; const tickNoteMap = {};</pre></div> Sort the tickables in each voice by their tick position in the voice <div class='highlight'><pre> voices.forEach(voice => { const tickPosition = new Fraction(0, 1); const notes = voice.getTickables(); notes.forEach(note => { if (note.shouldIgnoreTicks()) return; const notesAtPosition = tickNoteMap[tickPosition.value()]; if (!notesAtPosition) { tickPositions.push(tickPosition.value()); tickNoteMap[tickPosition.value()] = [note]; } else { notesAtPosition.push(note); } tickPosition.add(note.getTicks()); }); }); const music = new Music();</pre></div> Default key signature is C major <div class='highlight'><pre> if (!keySignature) keySignature = 'C';</pre></div> Get the scale map, which represents the current state of each pitch <div class='highlight'><pre> const scaleMap = music.createScaleMap(keySignature); tickPositions.forEach(tick => { const notes = tickNoteMap[tick];</pre></div> Array to store all pitches that modified accidental states at this tick position <div class='highlight'><pre> const modifiedPitches = []; const processNote = (note) => { if (note.isRest() || note.shouldIgnoreTicks()) return;</pre></div> Go through each key and determine if an accidental should be applied <div class='highlight'><pre> note.keys.forEach((keyString, keyIndex) => { const key = music.getNoteParts(keyString.split('/')[0]);</pre></div> Force a natural for every key without an accidental <div class='highlight'><pre> const accidentalString = key.accidental || 'n'; const pitch = key.root + accidentalString;</pre></div> Determine if the current pitch has the same accidental as the scale state <div class='highlight'><pre> const sameAccidental = scaleMap[key.root] === pitch;</pre></div> Determine if an identical pitch in the chord already modified the accidental state <div class='highlight'><pre> const previouslyModified = modifiedPitches.indexOf(pitch) > -1;</pre></div> Add the accidental to the StaveNote <div class='highlight'><pre> if (!sameAccidental || (sameAccidental && previouslyModified)) {</pre></div> Modify the scale map so that the root pitch has an updated state <div class='highlight'><pre> scaleMap[key.root] = pitch;</pre></div> Create the accidental <div class='highlight'><pre> const accidental = new Accidental(accidentalString);</pre></div> Attach the accidental to the StaveNote <div class='highlight'><pre> note.addAccidental(keyIndex, accidental);</pre></div> Add the pitch to list of pitches that modified accidentals <div class='highlight'><pre> modifiedPitches.push(pitch); } });</pre></div> process grace notes <div class='highlight'><pre> note.getModifiers().forEach(modifier => { if (modifier.getCategory() === 'gracenotegroups') { modifier.getGraceNotes().forEach(processNote); } }); }; notes.forEach(processNote); }); }</pre></div> Create accidental. <code>type</code> can be a value from the <code>Vex.Flow.accidentalCodes.accidentals</code> table in <code>tables.js</code>. For example: <code>#</code>, <code>##</code>, <code>b</code>, <code>n</code>, etc. <div class='highlight'><pre> constructor(type = null) { super(); this.setAttribute('type', 'Accidental'); L('New accidental: ', type); this.note = null;</pre></div> The <code>index</code> points to a specific note in a chord. <div class='highlight'><pre> this.index = null; this.type = type; this.position = Modifier.Position.LEFT; this.render_options = {</pre></div> Font size for glyphs <div class='highlight'><pre> font_scale: 38,</pre></div> Length of stroke across heads above or below the stave. <div class='highlight'><pre> stroke_px: 3,</pre></div> Padding between accidental and parentheses on each side <div class='highlight'><pre> parenLeftPadding: 2, parenRightPadding: 2, }; this.accidental = Flow.accidentalCodes(this.type); if (!this.accidental) { throw</s