Highcharts: Implement Wordcloud series type

[gvaartjes]

Read for examples and Uservoice's FR here: https://highcharts.uservoice.com/forums/55896-highcharts-javascript-api/suggestions/4180727-add-a-word-cloud-graph

@jon-a-nygaard has made some research here.

[jon-a-nygaard]

Documentation

Status: Pre-Alpha
Last update: 2017-08-04
Subscribe to the issue to receive notification about technical updates.

A word cloud is a visualization of a set of words, where the size and placement of a word is determined by how it is weighted.

Requirements

The word cloud chart requires the modules/wordcloud.js.

Demo

• Wordcloud of Lorem Ipsum (95 words)
  

  Options

An overview of all options available for the wordcloud series can be found at https://api.highcharts.com/highcharts/series\.

Data structure

Each point in the wordcloud series is requiered to have a name and a weight. The name determines the text to be drawn in the visualization, while the weight determines its priority. The points with the highest priority gets drawn first, and will be draw with larger font-size.

data: [{
    name: 'Lorem',
    weight: 3
}, {
    name: 'Ipsum',
    weight: 2
}, {
    name: 'Dolor',
    weight: 1
}]

Advanced usage

Custom spiralling algorithm

Spirals are used for moving a word after the inital position experienced a collision with either another word or the borders of the playing field.
To implement a custom spiral, look at the function archimedeanSpiral for example:

/**
 * archimedeanSpiral - Gives a set of cordinates for an Archimedian Spiral.
 *
 * @param {number} t How far along the spiral we have traversed.
 * @return {object} Resulting coordinates, x and y.
 */
var archimedeanSpiral = function archimedeanSpiral(t) {
    t *= 0.1;
    return {
        x: t * Math.cos(t),
        y: t * Math.sin(t)
    };
};

The spiralling algorithm is made accesible by attaching it to the spirals property:

Highcharts.seriesTypes.wordcloud.prototype.spirals.archimedean = archimedeanSpiral;

Afterwards you can use the algorithm by specifying the option series.spiral:

Highcharts.chart(..., {
  series: [{
    type: 'wordcloud',
    spiral: 'archimedean'
  }]
});

Custom placement strategies

Strategies are used for deciding rotation and initial position of a word.
To implement a custom strategy, have a look at the function randomPlacement for example:

var randomPlacement = function randomPlacement(point, options) {
  var field = options.field,
    r = options.rotation;
  return {
    x: getRandomPosition(field.width) - (field.width / 2),
    y: getRandomPosition(field.height) - (field.height / 2),
   rotation: getRotation(r.orientations, r.from, r.to)
  };
};

The placement algorithm is made accesible by attaching it to the placementStrategy property:

Highcharts.seriesTypes.wordcloud.prototype.placementStrategy.random= randomPlacement;

Afterwards you can use the algorithm by specifying the option series.placementStrategy:

Highcharts.chart(..., {
  series: [{
    type: 'wordcloud',
    placementStrategy: 'random'
  }]
});

Custom font sizing

The size of the font is calculated by the function deriveFont, which gives a result based on the relative weight of a word. The weight is on a scale 0-1, which indicates the words weight compared to the word with the largest weight.
When customizing the font sizes, you should be aware that higher font sizes can make the placement algorithm run slower, while a lower font size can make the placement of words more scattered.

// Include this snippet after loading Highcharts and before Highcharts.chart is executed.
Highcharts.seriesTypes.wordcloud.prototype.deriveFontSize = function (relativeWeight) {
   var maxFontSize = 25;
  // Will return a fontSize between 0px and 25px.
  return Math.floor(maxFontSize * relativeWeight);
};

Nice to have

• Pass in a string as series.data. In stead of creating a set of points with weights, Highcharts will analyze a given text and create the points from it.

  Known issues

• When words are rotated in angles not divisible by 90, there is a lot of air between them.

  • The current collision algorithm does not take rotation into count, and only checks if the outer areas of two words collides. To fix this we can utilize the Seperating Axis Theorem
• The words has changed places when I export my chart.
  
  
  
  • The exporting does a new render of the data, which causes the words to be repositioned in different coordinates than the original chart.
  
  
• There is a different font type in my exported chart.
  
  
  
  • The current default font used in our Wordcloud series is not installed on the export server.