d3-voronoi

This module implements Steven J. Fortune’s algorithm for computing the Voronoi diagram or Delaunay triangulation of a set of two-dimensional points. This implementation is largely based on work by Raymond Hill.

Voronoi diagrams are not only visually attractive but practical tools for interaction, such as to increase the target area of points in a scatterplot. See “Strikeouts on the Rise” in The New York Times and this multi-line chart for examples; also see Tovi Grossman’s paper on bubble cursors for a related technique. Voronoi diagrams can also be used to automate label positioning, and Delaunay meshes are useful in computing adjacency or grouping of visual elements.

Installing

If you use NPM, npm install d3-voronoi. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom build using Rollup or your preferred bundler. You can also load directly from d3js.org:

<script src="https://d3js.org/d3-voronoi.v0.1.min.js"></script>

In a vanilla environment, a d3_voronoi global is exported. Try d3-voronoi in your browser.

API Reference

# d3_voronoi.voronoi()

Creates a new Voronoi layout with default x- and y-accessors and the default extent.

# voronoi(data)

Returns an array of polygons, one for each input point in the specified data points, corresponding to the cells in the computed Voronoi diagram. For each element i in data, the polygon i represents the corresponding cell in the computed Voronoi diagram.

Each polygon is represented as an array of points [x, y] where x and y are the point coordinates, and a point field that refers to the corresponding element in data. Polygons are open in that they do not contain closing points that duplicate the initial point; a triangle, for example, is an array of three points. Polygons are also counterclockwise, assuming the origin ⟨0,0⟩ is in the top-left corner.

Note: if any points are coincident or have NaN positions, the behavior of this method is undefined. Most likely, invalid polygons will be returned! You must filter invalid points and consolidate coincident points before computing the Voronoi diagram.

# voronoi.x([x])

If x is specified, sets the x-coordinate accessor. If x is not specified, returns the current x-coordinate accessor, which defaults to:

function x(d) {
  return d[0];
}

# voronoi.y([y])

If y is specified, sets the y-coordinate accessor. If y is not specified, returns the current y-coordinate accessor, which defaults to:

function y(d) {
  return d[1];
}

# voronoi.extent([extent])

If extent is specified, sets the clip extent of the Voronoi layout to the specified bounds and returns the layout. The extent bounds are specified as an array [​[x0, y0], [x1, y1]​], where x0 is the left side of the extent, y0 is the top, x1 is the right and y1 is the bottom. If extent is null, no clipping is performed. If extent is not specified, returns the current clip extent which defaults to null.

Use of a clip extent is strongly recommended in conjunction with voronoi, as unclipped polygons may have large coordinates which may not render correctly.

# voronoi.size([size])

An alias for voronoi.extent where the minimum x and y of the extent are ⟨0,0⟩. Given a Voronoi layout v, this is equivalent to v.extent([[0, 0], size]).

# voronoi.links(data)

Returns the Delaunay triangulation of the specified data array as an array of links. Each link has the following attributes:

• source - the source node, an element in data.
• target - the target node, an element in data.

# voronoi.triangles(data)

Returns the Delaunay triangulation of the specified data array as an array of triangles. Each triangle is a three-element array of elements from data.