d3-cloud

What is d3-cloud?

The d3-cloud npm package is a layout algorithm for positioning words in a cloud, where the size of each word is determined by a specified weight. It is part of the D3.js family and is used to create word clouds, which are visual representations of text data where the importance of each word is shown with font size or color.

What are d3-cloud's main functionalities?

Basic Word Cloud

This code sample demonstrates how to create a basic word cloud using the d3-cloud package. It sets up a list of words with associated sizes, configures the layout, and draws the word cloud in an SVG element.

const d3 = require('d3');
const cloud = require('d3-cloud');

const words = [
  { text: 'Hello', size: 40 },
  { text: 'World', size: 30 },
  { text: 'D3', size: 20 },
  { text: 'Cloud', size: 50 }
];

const layout = cloud()
  .size([500, 500])
  .words(words)
  .padding(5)
  .rotate(() => ~~(Math.random() * 2) * 90)
  .font('Impact')
  .fontSize(d => d.size)
  .on('end', draw);

layout.start();

function draw(words) {
  d3.select('body').append('svg')
    .attr('width', layout.size()[0])
    .attr('height', layout.size()[1])
    .append('g')
    .attr('transform', 'translate(' + layout.size()[0] / 2 + ',' + layout.size()[1] / 2 + ')')
    .selectAll('text')
    .data(words)
    .enter().append('text')
    .style('font-size', d => d.size + 'px')
    .style('font-family', 'Impact')
    .attr('text-anchor', 'middle')
    .attr('transform', d => 'translate(' + [d.x, d.y] + ')rotate(' + d.rotate + ')')
    .text(d => d.text);
}

Custom Word Rotation

This code sample demonstrates how to customize the rotation of words in the word cloud. In this example, words longer than 4 characters are rotated by 90 degrees, while shorter words are not rotated.

const d3 = require('d3');
const cloud = require('d3-cloud');

const words = [
  { text: 'Hello', size: 40 },
  { text: 'World', size: 30 },
  { text: 'D3', size: 20 },
  { text: 'Cloud', size: 50 }
];

const layout = cloud()
  .size([500, 500])
  .words(words)
  .padding(5)
  .rotate(d => d.text.length > 4 ? 90 : 0)
  .font('Impact')
  .fontSize(d => d.size)
  .on('end', draw);

layout.start();

function draw(words) {
  d3.select('body').append('svg')
    .attr('width', layout.size()[0])
    .attr('height', layout.size()[1])
    .append('g')
    .attr('transform', 'translate(' + layout.size()[0] / 2 + ',' + layout.size()[1] / 2 + ')')
    .selectAll('text')
    .data(words)
    .enter().append('text')
    .style('font-size', d => d.size + 'px')
    .style('font-family', 'Impact')
    .attr('text-anchor', 'middle')
    .attr('transform', d => 'translate(' + [d.x, d.y] + ')rotate(' + d.rotate + ')')
    .text(d => d.text);
}

Other packages similar to d3-cloud

wordcloud

The wordcloud package is a JavaScript library for creating word clouds. It offers similar functionality to d3-cloud but is more focused on simplicity and ease of use. It provides a straightforward API for generating word clouds and supports various customization options.

d3-wordcloud

The d3-wordcloud package is another D3-based library for creating word clouds. It is similar to d3-cloud but offers additional features such as better support for different fonts and more customization options for word placement and styling.

README

Word Cloud Layout

This is a Wordle-inspired word cloud layout written in JavaScript. It uses HTML5 canvas and sprite masks to achieve near-interactive speeds.

See here for an interactive demonstration along with implementation details.

Usage

See the samples in examples/.

API Reference

# d3.layout.cloud()

Constructs a new cloud layout instance.

# on(type, listener)

Registers the specified listener to receive events of the specified type from the layout. Currently, only "word" and "end" events are supported.

A "word" event is dispatched every time a word is successfully placed. Registered listeners are called with a single argument: the word object that has been placed.

An "end" event is dispatched when the layout has finished attempting to place all words. Registered listeners are called with two arguments: an array of the word objects that were successfully placed, and a bounds object of the form [{x0, y0}, {x1, y1}] representing the extent of the placed objects.

# start()

Starts the layout algorithm. This initialises various attributes on the word objects, and attempts to place each word, starting with the largest word. Starting with the centre of the rectangular area, each word is tested for collisions with all previously-placed words. If a collision is found, it tries to place the word in a new position along the spiral.

Note: if a word cannot be placed in any of the positions attempted along the spiral, it is not included in the final word layout. This may be addressed in a future release.

# stop()

Stops the layout algorithm.

# timeInterval([time])

Internally, the layout uses setInterval to avoid locking up the browser’s event loop. If specified, time is the maximum amount of time that can be spent during the current timestep. If not specified, returns the current maximum time interval, which defaults to Infinity.

# words([words])

If specified, sets the words array. If not specified, returns the current words array, which defaults to [].

# size([size])

If specified, sets the rectangular [width, height] of the layout. If not specified, returns the current size, which defaults to [1, 1].

# font([font])

If specified, sets the font accessor function, which indicates the font face for each word. If not specified, returns the current font accessor function, which defaults to "serif". A constant may be specified instead of a function.

# fontStyle([fontStyle])

If specified, sets the fontStyle accessor function, which indicates the font style for each word. If not specified, returns the current fontStyle accessor function, which defaults to "normal". A constant may be specified instead of a function.

# fontWeight([fontWeight])

If specified, sets the fontWeight accessor function, which indicates the font weight for each word. If not specified, returns the current fontWeight accessor function, which defaults to "normal". A constant may be specified instead of a function.

# fontSize([fontSize])

If specified, sets the fontSize accessor function, which indicates the numerical font size for each word. If not specified, returns the current fontSize accessor function, which defaults to:

function(d) { return Math.sqrt(d.value); }

A constant may be specified instead of a function.

# rotate([rotate])

If specified, sets the rotate accessor function, which indicates the rotation angle (in degrees) for each word. If not specified, returns the current rotate accessor function, which defaults to:

function() { return (~~(Math.random() * 6) - 3) * 30; }

A constant may be specified instead of a function.

# text([text])

If specified, sets the text accessor function, which indicates the text for each word. If not specified, returns the current text accessor function, which defaults to:

function(d) { return d.text; }

A constant may be specified instead of a function.

# spiral([spiral])

If specified, sets the current type of spiral used for positioning words. This can either be one of the two built-in spirals, "archimedean" and "rectangular", or an arbitrary spiral generator can be used, of the following form:

// size is the [width, height] array specified in cloud.size
function(size) {
  // t indicates the current step along the spiral; it may monotonically
  // increase or decrease indicating clockwise or counterclockwise motion.
  return function(t) { return [x, y]; };
}

If not specified, returns the current spiral generator, which defaults to the built-in "archimedean" spiral.

# padding([padding])

If specified, sets the padding accessor function, which indicates the numerical padding for each word. If not specified, returns the current padding, which defaults to 1.

# random([random])

If specified, sets the internal random number generator, used for selecting the initial position of each word, and the clockwise/counterclockwise direction of the spiral for each word. This should return a number in the range [0, 1).

If not specified, returns the current random number generator, which defaults to Math.random.

# canvas([canvas])

If specified, sets the canvas generator function, which is used internally to draw text. If not specified, returns the current generator function, which defaults to:

function() { return document.createElement("canvas"); }

When using Node.js, you will almost definitely override this default, e.g. using the canvas module.