vexflow

<!DOCTYPE html> <html> <head> <title>formatter.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>formatter.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. <h2 id="description">Description</h2> This file implements the formatting and layout algorithms that are used to position notes in a voice. The algorithm can align multiple voices both within a stave, and across multiple staves. To do this, the formatter breaks up voices into a grid of rational-valued <code>ticks</code>, to which each note is assigned. Then, minimum widths are assigned to each tick based on the widths of the notes and modifiers in that tick. This establishes the smallest amount of space required for each tick. Finally, the formatter distributes the left over space proportionally to all the ticks, setting the <code>x</code> values of the notes in each tick. See <code>tests/formatter_tests.js</code> for usage examples. The helper functions included here (<code>FormatAndDraw</code>, <code>FormatAndDrawTab</code>) also serve as useful usage examples. <div class='highlight'><pre> import { Vex } from './vex'; import { Beam } from './beam'; import { Flow } from './tables'; import { Fraction } from './fraction'; import { Voice } from './voice'; import { StaveConnector } from './staveconnector'; import { StaveNote } from './stavenote'; import { ModifierContext } from './modifiercontext'; import { TickContext } from './tickcontext';</pre></div> To enable logging for this class. Set <code>Vex.Flow.Formatter.DEBUG</code> to <code>true</code>. <div class='highlight'><pre>function L(...args) { if (Formatter.DEBUG) Vex.L('Vex.Flow.Formatter', args); }</pre></div> Helper function to locate the next non-rest note(s). <div class='highlight'><pre>function lookAhead(notes, restLine, i, compare) {</pre></div> If no valid next note group, nextRestLine is same as current. <div class='highlight'><pre> let nextRestLine = restLine;</pre></div> Get the rest line for next valid non-rest note group. <div class='highlight'><pre> for (i += 1; i < notes.length; i += 1) { const note = notes[i]; if (!note.isRest() && !note.shouldIgnoreTicks()) { nextRestLine = note.getLineForRest(); break; } }</pre></div> Locate the mid point between two lines. <div class='highlight'><pre> if (compare && restLine !== nextRestLine) { const top = Math.max(restLine, nextRestLine); const bot = Math.min(restLine, nextRestLine); nextRestLine = Vex.MidLine(top, bot); } return nextRestLine; }</pre></div> Take an array of <code>voices</code> and place aligned tickables in the same context. Returns a mapping from <code>tick</code> to <code>ContextType</code>, a list of <code>tick</code>s, and the resolution multiplier. Params: <ul> <li><code>voices</code>: Array of <code>Voice</code> instances.</li> <li><code>ContextType</code>: A context class (e.g., <code>ModifierContext</code>, <code>TickContext</code>)</li> <li><code>addToContext</code>: Function to add tickable to context.</li> </ul> <div class='highlight'><pre>function createContexts(voices, ContextType, addToContext) { if (!voices || !voices.length) { throw new Vex.RERR('BadArgument', 'No voices to format'); }</pre></div> Find out highest common multiple of resolution multipliers. The purpose of this is to find out a common denominator for all fractional tick values in all tickables of all voices, so that the values can be expanded and the numerator used as an integer tick value. <div class='highlight'><pre> const totalTicks = voices[0].getTotalTicks(); const resolutionMultiplier = voices.reduce((resolutionMultiplier, voice) => { if (!voice.getTotalTicks().equals(totalTicks)) { throw new Vex.RERR( 'TickMismatch', 'Voices should have same total note duration in ticks.' ); } if (voice.getMode() === Voice.Mode.STRICT && !voice.isComplete()) { throw new Vex.RERR( 'IncompleteVoice', 'Voice does not have enough notes.' ); } return Math.max( resolutionMultiplier, Fraction.LCM(resolutionMultiplier, voice.getResolutionMultiplier()) ); }, 1);</pre></div> Initialize tick maps. <div class='highlight'><pre> const tickToContextMap = {}; const tickList = []; const contexts = [];</pre></div> For each voice, extract notes and create a context for every new tick that hasn’t been seen before. <div class='highlight'><pre> voices.forEach((voice, voiceIndex) => {</pre></div> Use resolution multiplier as denominator to expand ticks to suitable integer values, so that no additional expansion of fractional tick values is needed. <div class='highlight'><pre> const ticksUsed = new Fraction(0, resolutionMultiplier); voice.getTickables().forEach(tickable => { const integerTicks = ticksUsed.numerator;</pre></div> If we have no tick context for this tick, create one. <div class='highlight'><pre> if (!tickToContextMap[integerTicks]) { const newContext = new ContextType({ tickID: integerTicks }); contexts.push(newContext); tickToContextMap[integerTicks] = newContext; }</pre></div> Add this tickable to the TickContext. <div class='highlight'><pre> addToContext(tickable, tickToContextMap[integerTicks], voiceIndex);</pre></div> Maintain a sorted list of tick contexts. <div class='highlight'><pre> tickList.push(integerTicks); ticksUsed.add(tickable.getTicks()); }); }); return { map: tickToContextMap, array: contexts, list: Vex.SortAndUnique(tickList, (a, b) => a - b, (a, b) => a === b), resolutionMultiplier, }; } export class Formatter {</pre></div> Helper function to layout “notes” one after the other without regard for proportions. Useful for tests and debugging. <div class='highlight'><pre> static SimpleFormat(notes, x = 0, { paddingBetween = 10 } = {}) { notes.reduce((x, note) => { note.addToModifierContext(new ModifierContext()); const tick = new TickContext().addTickable(note).preFormat(); const metrics = tick.getMetrics(); tick.setX(x + metrics.totalLeftPx); return x + tick.getWidth() + metrics.totalRightPx + paddingBetween; }, x); }</pre></div> Helper function to plot formatter debug info. <div class='highlight'><pre> static plotDebugging(ctx, formatter, xPos, y1, y2, options) { options = { stavePadding: Vex.Flow.DEFAULT_FONT_STACK[0].lookupMetric('stave.padding'), ...options, }; const x = xPos + options.stavePadding; const contextGaps = formatter.contextGaps; function stroke(x1, x2, color) { ctx.beginPath(); ctx.setStrokeStyle(color); ctx.setFillStyle(color); ctx.setLineWidth(1); ctx.fillRect(x1, y1, Math.max(x2 - x1, 0), y2 - y1); } ctx.save(); ctx.setFont('Arial', 8, ''); contextGaps.gaps.forEach(gap => { stroke(x + gap.x1, x + gap.x2, 'rgba(100,200,100,0.4)'); ctx.setFillStyle('green'); ctx.fillText(Math.round(gap.x2 - gap.x1), x + gap.x1, y2 + 12); }); ctx.setFillStyle('red'); ctx.fillText(`Loss: ${(formatter.totalCost || 0).toFixed(2)} Shift: ${(formatter.totalShift || 0).toFixed(2)} Gap: ${contextGaps.total.toFixed(2)}`, x - 20, y2 + 27); ctx.restore(); }</pre></div> Helper function to format and draw a single voice. Returns a bounding box for the notation. Parameters: <ul> <li><code>ctx</code> - The rendering context</li> <li><code>stave</code> - The stave to which to draw (<code>Stave</code> or <code>TabStave</code>)</li> <li><code>notes</code> - Array of <code>Note</code> instances (<code>StaveNote</code>, <code>TextNote</code>, <code>TabNote</code>, etc.)</li> <li><code>params</code> - One of below:<ul> <li>Setting <code>autobeam</code> only <code>(context, stave, notes, true)</code> or <code>(ctx, stave, notes, {autobeam: true})</code></li> <li>Setting <code>align_rests</code> a struct is needed <code>(context, stave, notes, {align_rests: true})</code></li> <li>Setting both a struct is needed <code>(context, stave, notes, { autobeam: true, align_rests: true})</code></li> </ul> </li> </ul> <code>autobeam</code> automatically generates beams for the notes. <code>align_rests</code> aligns rests with nearby notes. <div class='highlight'><pre> static FormatAndDraw(ctx, stave, notes, params) { const options = { auto_beam: false, align_rests: false, }; if (typeof params === 'object') { Vex.Merge(options, params); } else if (typeof params === 'boolean') { options.auto_beam = params; }</pre></div> Start by creating a voice and adding all the notes to it. <div class='highlight'><pre> const voice = new Voice(Flow.TIME4_4) .setMode(Voice.Mode.SOFT) .addTickables(notes);</pre></div> Then create beams, if requested. <div class='highlight'><pre> const beams = options.auto_beam ? Beam.applyAndGetBeams(voice) : [];</pre></div> Instantiate a <code>Formatter</code> and format the notes. <div class='highlight'><pre> new Formatter() .joinVoices([voice], { align_rests: options.align_rests }) .formatToStave([voice], stave, { align_rests: options.align_rests, stave });</pre></div> Render the voice and beams to the stave. <div class='highlight'><pre> voice.setStave(stave).draw(ctx, stave); beams.forEach(beam => beam.setContext(ctx).draw());</pre></div> Return the bounding box of the voice. <div class='highlight'><pre> return voice.getBoundingBox(); }</pre></div> Helper function to format and draw aligned tab and stave notes in two separate staves. Parameters: <ul> <li><code>ctx</code> - The rendering context</li> <li><code>tabstave</code> - A <code>TabStave</code> instance on which to render <code>TabNote</code>s.</li> <li><code>stave</code> - A <code>Stave</code> instance on which to render <code>Note</code>s.</li> <li><code>notes</code> - Array of <code>Note</code> instances for the stave (<code>StaveNote</code>, <code>BarNote</code>, etc.)</li> <li><code>tabnotes</code> - Array of <code>Note</code> instances for the tab stave (<code>TabNote</code>, <code>BarNote</code>, etc.)</li> <li><code>autobeam</code> - Automatically generate beams.</li> <li><code>params</code> - A configuration object:<ul> <li><code>autobeam</code> automatically generates beams for the notes.</li> <li><code>align_rests</code> aligns rests with nearby notes.</li> </ul> </li> </ul> <div class='highlight'><pre> static FormatAndDrawTab(ctx, tabstave, stave, tabnotes, notes, autobeam, params) { const opts = { auto_beam: autobeam, align_rests: false, }; if (typeof params === 'object') { Vex.Merge(opts, params); } else if (typeof params === 'boolean') { opts.auto_beam = params; }</pre></div> Create a <code>4/4</code> voice for <code>notes</code>. <div class='highlight'><pre> const notevoice = new Voice(Flow.TIME4_4) .setMode(Voice.Mode.SOFT) .addTickables(notes);</pre></div> Create a <code>4/4</code> voice for <code>tabnotes</code>. <div class='highlight'><pre> const tabvoice = new Voice(Flow.TIME4_4) .setMode(Voice.Mode.SOFT) .addTickables(tabnotes);</pre></div> Then create beams, if requested. <div class='highlight'><pre> const beams = opts.auto_beam ? Beam.applyAndGetBeams(notevoice) : [];</pre></div> Instantiate a <code>Formatter</code> and align tab and stave notes. <div class='highlight'><pre> new Formatter() .joinVoices([notevoice], { align_rests: opts.align_rests }) .joinVoices([tabvoice]) .formatToStave([notevoice, tabvoice], stave, { align_rests: opts.align_rests });</pre></div> Render voices and beams to staves. <div class='highlight'><pre> notevoice.draw(ctx, stave); tabvoice.draw(ctx, tabstave); beams.forEach(beam => beam.setContext(ctx).draw());</pre></div> Draw a connector between tab and note staves. <div class='highlight'><pre> new StaveConnector(stave, tabstave).setContext(ctx).draw(); }</pre></div> Auto position rests based on previous/next note positions. Params: <ul> <li><code>notes</code>: An array of notes.</li> <li><code>alignAllNotes</code>: If set to false, only aligns non-beamed notes.</li> <li><code>alignTuplets</code>: If set to false, ignores tuplets.</li> </ul> <div class='highlight'><pre> static AlignRestsToNotes(notes, alignAllNotes, alignTuplets) { notes.forEach((note, index) => { if (note instanceof StaveNote && note.isRest()) { if (note.tuplet && !alignTuplets) return;</pre></div> If activated rests not on default can be rendered as specified. <div class='highlight'><pre> const position = note.getGlyph().position.toUpperCase(); if (position !== 'R/4' && position !== 'B/4') return; if (alignAllNotes || note.beam != null) {</pre></div> Align rests with previous/next notes. <div class='highlight'><pre> const props = note.getKeyProps()[0]; if (index === 0) { props.line = lookAhead(notes, props.line, index, false); note.setKeyLine(0, props.line); } else if (index > 0 && index < notes.length) {</pre></div> If previous note is a rest, use its line number. <div class='highlight'><pre> let restLine; if (notes[index - 1].isRest()) { restLine = notes[index - 1].getKeyProps()[0].line; props.line = restLine; } else { restLine = notes[index - 1].getLineForRest();</pre></div> Get the rest line for next valid non-rest note group. <div class='highlight'><pre> props.line = lookAhead(notes, restLine, index, true); } note.setKeyLine(0, props.line); } } } }); return this; } constructor(options) { this.options = { softmaxFactor: null, maxIterations: 2, ...options };</pre></div> Minimum width required to render all the notes in the voices. <div class='highlight'><pre> this.minTotalWidth = 0;</pre></div> This is set to <code>true</code> after <code>minTotalWidth</code> is calculated. <div class='highlight'><pre> this.hasMinTotalWidth = false;</pre></div> Total number of ticks in the voice. <div class='highlight'><pre> this.totalTicks = new Fraction(0, 1);</pre></div> Arrays of tick and modifier contexts. <div class='highlight'><pre> this.tickContexts = null; this.modiferContexts = null;</pre></div> Gaps between contexts, for free movement of notes post formatting. <div class='highlight'><pre> this.contextGaps = { total: 0, gaps: [], }; this.voices = []; this.iterationsCompleted = 0; this.lossHistory = []; }</pre></div> Find all the rests in each of the <code>voices</code> and align them to neighboring notes. If <code>alignAllNotes</code> is <code>false</code>, then only align non-beamed notes. <div class='highlight'><pre> alignRests(voices, alignAllNotes) { if (!voices || !voices.length) { throw new Vex.RERR('BadArgument', 'No voices to format rests'); } voices.forEach(voice => Formatter.AlignRestsToNotes(voice.getTickables(), alignAllNotes)); }</pre></div> Calculate the minimum width required to align and format <code>voices</code>. <div class='highlight'><pre> preCalculateMinTotalWidth(voices) {</pre></div> Cache results. <div class='highlight'><pre> if (this.hasMinTotalWidth) return this.minTotalWidth;</pre></div> Create tick contexts if not already created. <div class='highlight'><pre> if (!this.tickContexts) { if (!voices) { throw new Vex.RERR( 'BadArgument', "'voices' required to run preCalculateMinTotalWidth" ); } this.createTickContexts(voices); } const { list: contextList, map: contextMap } = this.tickContexts;</pre></div> Go through each tick context and calculate total width. <div class='highlight'><pre> this.minTotalWidth = contextList .map(tick => { const context = contextMap[tick]; context.preFormat(); return context.getWidth(); }) .reduce((a, b) => a + b, 0); this.hasMinTotalWidth = true; return this.minTotalWidth; }</pre></div> Get minimum width required to render all voices. Either <code>format</code> or <code>preCalculateMinTotalWidth</code> must be called before this method. <div class='highlight'><pre> getMinTotalWidth() { if (!this.hasMinTotalWidth) { throw new Vex.RERR( 'NoMinTotalWidth', "Call 'preCalculateMinTotalWidth' or 'preFormat' before calling 'getMinTotalWidth'" ); } return this.minTotalWidth; }</pre></div> Create <code>ModifierContext</code>s for each tick in <code>voices</code>. <div class='highlight'><pre> createModifierContexts(voices) { const contexts = createContexts( voices, ModifierContext, (tickable, context) => tickable.addToModifierContext(context) ); this.modiferContexts = contexts; return contexts; }</pre></div> Create <code>TickContext</code>s for each tick in <code>voices</code>. Also calculate the total number of ticks in voices. <div class='highlight'><pre> createTickContexts(voices) { const contexts = createContexts( voices, TickContext, (tickable, context, voiceIndex) => context.addTickable(tickable, voiceIndex) ); contexts.array.forEach(context => { context.tContexts = contexts.array; }); this.totalTicks = voices[0].getTicksUsed().clone(); this.tickContexts = contexts; return contexts; }</pre></div> This is the core formatter logic. Format voices and justify them to <code>justifyWidth</code> pixels. <code>renderingContext</code> is required to justify elements that can’t retreive widths without a canvas. This method sets the <code>x</code> positions of all the tickables/notes in the formatter. <div class='highlight'><pre> preFormat(justifyWidth = 0, renderingContext, voices, stave) {</pre></div> Initialize context maps. <div class='highlight'><pre> const contexts = this.tickContexts; const { list: contextList, map: contextMap } = contexts;</pre></div> Reset loss history for evaluator. <div class='highlight'><pre> this.lossHistory = [];</pre></div> If voices and a stave were provided, set the Stave for each voice and preFormat to apply Y values to the notes; <div class='highlight'><pre> if (voices && stave) { voices.forEach(voice => voice.setStave(stave).preFormat()); }</pre></div> Now distribute the ticks to each tick context, and assign them their own X positions. <div class='highlight'><pre> let x = 0; let shift = 0; this.minTotalWidth = 0;</pre></div> Pass 1: Give each note maximum width requested by context. <div class='highlight'><pre> contextList.forEach((tick) => { const context = contextMap[tick]; if (renderingContext) context.setContext(renderingContext);</pre></div> Make sure that all tickables in this context have calculated their space requirements. <div class='highlight'><pre> context.preFormat(); const width = context.getWidth(); this.minTotalWidth += width; const metrics = context.getMetrics(); x = x + shift + metrics.totalLeftPx; context.setX(x);</pre></div>