d3-tribin

This D3 plugin is largely inspired by the d3-hexbin plugin but instead of using hexagons to bin points it uses triangles. It is therefore used to group two-dimensional points into (equilateral) triangular bins. It supports color encoding, area encoding, or both.

Installing

If you use NPM, npm install d3-tribin. Otherwise, download the latest release.

API Reference

# tribin()

Constructs a new default tribin generator.

# tribin(points)

Bins the specified array of points, returning an array of triangular bins. For each point in the specified points array, the x- and y-accessors are invoked to compute the x- and y-coordinates of the point, which is then used to assign the point to a triangular bin. If either the x- or y-coordinate is NaN, the point is ignored and will not be in any of the returned bins.

Each bin in the returned array is an array containing the bin’s points. Only non-empty bins are returned; empty bins without points are not included in the returned array. Each bin has these additional properties:

• x - the x-coordinate of the center of the associated bin’s triangle
• y - the y-coordinate of the center of the associated bin’s triangle
• rotation - the rotation (in gradients) with respect to the vertical axe of the associated bin’s triangle

The x- and y-coordinates of the triangle center and its rotation can be used to render the triangle at the appropriate location in conjunction with tribin.triangle or tribin.triangleFromBin or . For example, given a tribin generator:

var tribin = d3.tribin();

You could display a triangle for each non-empty bin as follows:

svg.selectAll("path")
  .data(tribin(points))
  .enter().append("path")
    .attr("d", function(d) { return tribin.triangleFromBin(d); });

Which is equivalent to:

svg.selectAll("path")
  .data(tribin(points))
  .enter().append("path")
    .attr("d", function(d) { return tribin.triangle(1, d.rotation, [d.x, d.y]); });

And also equivalent to:

svg.selectAll("path")
  .data(tribin(points))
  .enter().append("path")
    .attr("d", function(d) { return "M" + d.x + "," + d.y + tribin.triangle(1, d.rotation); });

# tribin.triangleFromBin(bin, [side])

Returns the SVG path string for the (equilateral) triangle with default size. The center and the rotation of the triangle are automatically set by using the bin properties x, y and rotation. If side is not specified, the tribin’s current side is used. If side is specified, a triangle with the specified side is returned, this is useful for area-encoded bivariate tribins.

# tribin.triangle([side], [rotation], [center])

Returns the SVG path string for the (equilateral) triangle with default size, zero rotation and centered at the origin ⟨0,0⟩. The path string is defined with relative coordinates such that you can easily translate the triangle to the desired position. If side is not specified, the tribin’s current side is used. If side is specified, a triangle with the specified side is returned. If rotation is not specified, zero is used. If rotation is specified, a triangle with the specified rotation is returned. The rotation is applied clockwise and specified in radians (e.g. 180 degrees correspond to Math.PI rad). If center is not specified, the triangle is centered at ⟨0,0⟩. If center is specified, the triangle will be centered at ⟨center[0],center[1]⟩.

# tribin.x([x])

If x is specified, sets the x-coordinate accessor to the specified function and returns this tribin generator. If x is not specified, returns the current x-coordinate accessor, which defaults to:

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

The x-coordinate accessor is used by tribin to compute the x-coordinate of each point. The default value assumes each point is specified as a two-element array of numbers [x, y].

# tribin.y([y])

If y is specified, sets the y-coordinate accessor to the specified function and returns this tribin generator. If y is not specified, returns the current y-coordinate accessor, which defaults to:

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

The y-coordinate accessor is used by tribin to compute the y-coordinate of each point. The default value assumes each point is specified as a two-element array of numbers [x, y].

# tribin.side([side])

If side is specified, sets the side of the triangle to the specified number. If side is not specified, returns the current side, which defaults to 1.