Wednesday, 12 February 2014

Chart Generation

Chordography generates chord charts for any fretted instrument, banjo, guitar, mandolin, ukulele etc., in any tuning. Charts can be quickly generated and downloaded in a variety of formats. Or, you can use Chordography's JavaScript routines to generate charts in your own web pages.

The chart is generated and rendered Initially as in-line xml markup, so you can't copy it normally, as a regular image (right-click and copy). But you can if you change the chart's format to png or jpeg (anything but xml). See the Format section, below, if you prefer to copy the chart as in-line markup.

Note: The generated image can fail to display in some browsers. If this happens, try a different format, disable your ad-blocker, or change your browser.  …more▶

SVG is well supported in modern browsers. However, rasterizing a cross-sourced svg image can lead to potential security issues. Although images generated locally, as above, should not be affected, some browsers err on the side of caution and refuse to display a rasterized svg image, whether generated locally or otherwise.

Resolution of these issues has improved of late, and rasterized images now display in many popular browsers, including Chrome, Firefox, Opera, and MS Edge, but alas not in Safari and IE in which only xml and svg format options display correctly.
Click the Update button to implement any changes.
The image is generated as a Scalable Vector Graphic (svg) from four text inputs (Title, Frets, Labels, Footer) and three drop-down selectors (Barré, Style, Format). The chart header is generated automatically with blank, 0 and x entries for fingered, open and mute strings respectively.
Only Frets data are essential to create a basic chart; Title, Labels and Footer are all optional.
    No space is taken up by a null title
  • Title: optional chord name/type e.g. Am. Unicode characters such as ♯, ♭, ♮, °, Δ may be included, although not all are available in all fonts. Make a null entry if you prefer to use an external title.
  • Frets input also sets the number of strings on the instrument.
  • Frets: comma separated list of finger positions on the fret-board. Mute strings are represented by null, non-numeric or negative entries and show as x on the chart header. Every entry, even null or blank, should have a comma separator. Frets data alone are sufficient to create a basic chart.
  • Labels: optional comma separated list of labels used to indicate fingering, usually 1,2,3,4 for index, middle, ring, pinkie and t for thumb. Labels for non-fingered (open or mute) strings are ignored so anything, even null, is OK, but there must be a comma separator.
  • No space is taken up by a null footer
  • Footer: optional comma separated list of note names or chord function for each string. No specific tuning is assumed, so there can be no checks for errors; anything goes.
  • Barré: allows a barré to be drawn automatically for movable chords. Select none to omit it completely.
  • Style: offers a range of in line styles to make the image self-contained, usable without an external style-sheet. Choose none if you intend to use an external style-sheet with your svg image files, as in line styles will take precedence.
  • The chart looks much the same whatever format is selected
  • Format: determines how the image is rendered. Initially generated as a Scalable Vector Graphic (svg), it can be rendered directly as inline markup, as a regular image, or converted into a raster format. …more▶
    Only old browsers should fail to render in line XML.
    xml The svg code is rendered directly as in line XML markup. This is the most reliable way to display a generated image. The downside is that saving the image is a little less simple than usual:
    1. right-click the image and select 'Inspect Element' to open the Developer Console
    2. right-click the <svg> root element, and 'Copy' to the clipboard
    3. paste the image code to Notepad and 'Save As' an svg file (not as a txt file)

    svg The generated svg code is displayed as a regular HTML <img> element. As the image code is stored in memory rather than a file online, it has to be converted into a pseudo URL using the Data URI scheme. But the image can still be copied and saved normally.

    Safari and IE both fail to display rasterized svg images due to potential security issues
    png, jpeg, bmp, gif, etc. The svg code is converted into a non-scalable raster format and displayed as a regular HTML <img> element. Which raster formats are available varies with the browser, but usually includes png and jpeg. As for svg above, the image code has to be converted into a pseudo URL.

Example: Dm chart for a Banjo

The initial chart above is for an open chord on a guitar in standard tuning. Here's how to change it into a Dm chart for a Banjo in DGBD tuning. …more▶

Create a new chart

It takes three easy steps to create a basic chart:
  1. Clear the current data from all four text input boxes: Title, Frets, Labels, and Footer
  2. Add a new set of fret numbers i.e. 0,2,3,3
  3. Click Update to generate the new chart
Or you can cheat and click basic Dm to see how it should look at this stage.

Embellish the chart

Labels, Footer and Title can be added independently. Update the chart at each stage to see how it progresses.
  1. Add Labels to show the fingering i.e. 0,1,2,3
  2. Add a Footer to show the notes i.e. D,A,D,F
  3. Finally add a Title i.e. Dm
Or take the easy route and click embellished Dm to see how the completed chart should look.

Movable barré chords

Chordography automatically adjusts charts for movable chords. Only the fingered part of the fret-board is shown on the chart, subject to a minimum of four visible frets.
No labels means no barré will be drawn
If Barré = auto is selected, a barré is drawn when there are two or more fingered stages on the same fret with the same fingering (labels). Further visual clues that these are not open chords are a) the first fingered fret is numbered and b) the top-nut is not shown.
CAGED forms with a barré at the fifth fret on a guitar in standard tuning. Click scale up or scale down to change the scale in steps of 20%.
The five charts above are for a guitar in standard EADGBE tuning. They illustrate the major chords F D C A G played using open C A G E D forms respectively with a barré at the fifth fret. You can test your chart-generating skills by making up data to duplicate one of these examples. Enter your data into Chordography's text-input boxes, update the chart and compare the result with your chosen example. You can also check your data against that used to create the chart: click your example chart to load its actual data into Chordography.

Scale the image

A clue to the popularity of Scalable Vector Graphics lies in the name. SVG images are scalable. But judging by the large number of confusing articles on this topic, scaling svg images can cause a few headaches. It isn't difficult, but equally, it's not without its anomalies. …more▶
Chordography adds three attributes related to scaling the <svg> element: viewport, viewBox, and preserveAspectRatio. These are easily modified using a text editor such as Notepad.
  1. viewport comprises width and height attributes that tell the browser how much screen real estate you wish to allocate to the image. Typically, these will be the only attributes you ever need to modify.
    Chordography sets the width and height to display the image full size. But you can change these to any convenient values and the image will be rendered without distortion or pixellation.
  2. viewBox defines the region of the image canvas that gets mapped to the viewport. Chordography sets the four parameters (x y w h) to include the whole chart; there is normally no need to modify these values.
    No viewBox means no scaling takes place
    If you delete the viewBox attribute, the canvas will be copied full size and undistorted over the full extent of the viewport. In that case, top-left of the viewport corresponds to (0,0) on the canvas, even if the image extends into a negative quadrant
  3. preserveAspectRatio tells the browser how to map the image if the viewport and viewBox have differing aspect ratios. The region specified by the viewBox is either padded, clipped or distorted to make it fit.
    Chordography sets the default option viz. "xMidYMid meet"; this pads either the width or height equally on each side to centre the image in the viewport.
    Feel free to delete this attribute as it's the default option. Either way, you can set the viewport width and height to convenient values, roughly in the correct ratio, and it will look good.
Not recommended to those of a nervous disposition.
Things begin to get complicated if you delete the viewport width and height. With the viewBox in place, as set by Chordography, the image should be scaled but to what?

This can be a useful option.
If either the viewport width or height is defined (but not both) the image is scaled to it in the correct proportions. If neither width or height is defined, the image is scaled to the width of the enclosing HTML element.

But wait, we are not done yet. What if both viewBox and viewport are undefined? With no viewBox prescribed, the image gets copied to the viewport without any scaling as described above. But this time it's not the enclosing HTML element that determines the viewport width and/or height; default values 300 and 150 pixels are used instead (don't ask).

Adding style

In line styles take precedence over style sheets.
Rather than use one of Chordography's pre-defined styles, you may prefer to give your charts a customised look with your own style sheet. In that case you will need to select style = none for your charts and add an internal or an external style sheet.  …more▶
Each element of the chart is given a class to make it easy to target your styles exactly at the elements you want. Appropriate elements are also grouped together and these too are given a class so you can easily target the whole group. The main <svg> element is assigned the class chordChart; other groups and elements are arranged as follows:
Chart Element Classes
Element Class Sub-Group Classes
svg chordChart  grid, text, dots, nut, barre
group grid frets, strings
group text header, title, lofret, labels, footer
group dots  
lofret is the number of the first fingered fret on a movable chord
Perhaps the most useful svg-specific styles for chord charts are stroke (default none) and fill (default black). With stroke=none all text elements and geometric shapes such as dots, nut and barré are rendered solid black with no outline. Grid lines are invisible as are labels (black text on black dots), and the chart is transparent (no background specified).
A minimal style-sheet would need to include something like:
svg.chordChart .grid{ stroke: black;}
svg.chordChart .labels{ fill: white;}
These are in fact the in-line styles used with style=plain. The style sheet equivalent to style=default is only slightly more elaborate: Download default.css

Roll your own

Rather than save your images to file, you can also use Chordography's JavaScript code to generate and render svg images dynamically in your own web-pages. That will allow you full control of the image geometry and style (lines, fills, fonts etc.). You will need to download the source code, and provide a reference link to it in your HTML <head> section  ...more▶
The source-code comprises a single factory module, chartMaker(), that returns an anonymous function. The latter is the one that actually creates chord charts.
Assign the anonymous function to a variable (that is give it a name, e.g createChart), then locate the placeholder and execute createChart(), once for each chart you wish to create. e.g.:
var createChart = chartMaker();
var placeholder = document.getElementById("exampleChart");
  • placeholder provides the HTML location of the chart
  • udi contains the data necessary to create the chart.
The placeholder corresponds to an empty <svg> element placed in your mark-up at the required chart location. Typically, the HTML <body> element would contain something like:
<svg id="exampleChart" >Example chart goes here</svg>
Timing can be an issue as the <svg> element must exist, that is the HTML page must be loaded, before the DOM method can find it.

User Data Input

User Data Input (udi) is a Javascript object that contains the details of the new chart e.g.:
var udi = {title:"C7♭9",fret:"x,3,2,3,2,3",label:"x,2,1,3,1,4",footer:" ,C,E,B♭,D♭,G"};
Only fret data are essential to create a chart.

Scale & Barré

As described above an existing chart can be scaled by changing the viewport width and height parameters in its <svg> element, relative to the viewBox dimensions. A dynamically generated chart can be similarly scaled by adding a scale factor to the udi object. e.g.
var udi = {title:"C7♭9", fret:"x,3,2,3,2,3", label:"x,2,1,3,1,4", footer:" ,C,E,B♭,D♭,G", scale:1.5};
Likewise, you can ensure a barré is not drawn by adding barre:false to the udi object.

Core data

At this point, you may be wondering why we employ a factory function. Why doesn't chartMaker() create chord charts directly instead of creating an anonymous function to do it?

All chart elements are scaled to the font height
The answer is that doing it in two stages allows us to separate the data into chart-specific, or variant data (title, frets etc.), and core data such as chart geometry.

As described above, the anonymous function creates charts with a default geometry based on a font height of 16 pixels and a cell aspect ratio (fret to string spacing) of 1.2. But chartMaker() is a factory function, with optional parameters fontHeight and aspectRatio. It can produce anonymous functions to generate charts with bespoke geometries. So if you prefer your charts to be small and squat for example, as shown right, you can create an anonymous function to do just that e.g.:
var fontHeight = 8, aspectRatio = 1.0;
var smallChart = chartMaker(fontHeight,aspectRatio);
Charts much smaller than this do not look good on-screen unless you zoom in, but are fine in documents printed at a higher resolution.

You can create as many chart-makers as you like, each with its own built-in geometry, and each chart-maker can generate as many charts as you like, each with a unique placeholder. Charts can also be overwritten at any time as all child nodes of the placeholder, including descriptive text, are removed before new nodes are added.

And finally...

This software (images and/or source code) is provided free of charge, licence fees or royalties, and without warranty. You may download it, redistribute it and/or modify it under the terms of the GNU General Public License.
The code is minified which makes it load more quickly, but more difficult to reverse-engineer. Ideas on how it might be improved are very welcome.