Nehzilrz / d3-wordcloud

d3-wordcloud using scanning line algorithm

Word Cloud Layout

Not same as Wordle [https://github.com/jasondavies/d3-cloud], this library uses the scanning line algorithm to ensure a compact layout, and also it applies the Fisheye Distortion mentioned in this paper [Understanding Text Corpora with Multiple Facets].

Usage

See the samples in examples/.

const len = 100
const text = 'The layout algorithm for positioning words without overlap is available on GitHub under an open source license as d3-cloud. Note that this is the only the layout algorithm and any code for converting text into words and rendering the final output requires additional development'.toLowerCase()
const segs = text.split(' ')
const words = segs.map(d => ({ text: d, size: Math.random() * 20 + 10 }))

let cloud = d3.wordcloud()
cloud.words(words)
.size([500, 500])
.fontSize((d) => d.size)
.font('Microsoft Yahei')
.on('end', function(words){
    let svg = d3.select("#wordcloud")
    svg.selectAll('.word').data(words).enter()
        .append('text')
        .text(d => d.text)
        .attr('class', 'word')
        .attr('x', d => d.x)
        .attr('y', d => d.y)
        .attr('font-size', d => `${d.size}px`)
        .attr('font-family', d => d.font)
})
.start()

API Reference

# d3.wordcloud()

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].

# polygon([polygon])

If specified, sets the sequence of vertices of a convex polygon, representing the outer border of the cloud; If not specified, the default is [[0, 0], [0, height], [width, height], [width, 0]]

# 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.

# 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.

# 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.