d3 / d3-hexbin

Group two-dimensional points into hexagonal bins.

d3-hexbin

Hexagonal binning is useful for aggregating data into a coarser representation for display. For example, rather than rendering a scatterplot of tens of thousands of points, bin the points into a few hundred hexagons to show the distribution. Hexbins can support a color encoding, area encoding, or both.

Installing

If you use NPM, npm install d3-hexbin. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3_hexbin global is exported:

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

const hexbin = d3.hexbin();

</script>

Try d3-hexbin in your browser.

API Reference

# d3.hexbin()

Constructs a new default hexbin generator.

# hexbin(points)

Bins the specified array of points, returning an array of hexagonal 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 hexagonal 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 hexagon
• y - the y-coordinate of the center of the associated bin’s hexagon

These x- and y-coordinates of the hexagon center can be used to render the hexagon at the appropriate location in conjunction with hexbin.hexagon. For example, given a hexbin generator:

const hexbin = d3.hexbin();

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

svg.selectAll("path")
  .data(hexbin(points))
  .enter().append("path")
    .attr("d", d => `M${d.x},${d.y}${hexbin.hexagon()}`);

Alternatively, using a transform:

svg.selectAll("path")
  .data(hexbin(points))
  .enter().append("path")
    .attr("transform", d => `translate(${d.x},${d.y})`)
    .attr("d", hexbin.hexagon());

This method ignores the hexbin’s extent; it may return bins outside the extent if necessary to contain the specified points.

# hexbin.hexagon([radius])

Returns the SVG path string for the hexagon centered at the origin ⟨0,0⟩. The path string is defined with relative coordinates such that you can easily translate the hexagon to the desired position. If radius is not specified, the hexbin’s current radius is used. If radius is specified, a hexagon with the specified radius is returned; this is useful for area-encoded bivariate hexbins.

# hexbin.centers()

Returns an array of [x, y] points representing the centers of every hexagon in the extent.

# hexbin.mesh()

Returns an SVG path string representing the hexagonal mesh that covers the extent; the returned path is intended to be stroked. The mesh may extend slightly beyond the extent and may need to be clipped.

# hexbin.x([x])

If x is specified, sets the x-coordinate accessor to the specified function and returns this hexbin 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 hexbin 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].

# hexbin.y([x])

If y is specified, sets the y-coordinate accessor to the specified function and returns this hexbin 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 hexbin 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].

# hexbin.radius([radius])

If radius is specified, sets the radius of the hexagon to the specified number. If radius is not specified, returns the current radius, which defaults to 1. The hexagons are pointy-topped (rather than flat-topped); the width of each hexagon is radius × 2 × sin(π / 3) and the height of each hexagon is radius × 3 / 2.

# hexbin.extent([extent])

If extent is specified, sets the hexbin generator’s extent to the specified bounds [[x0, y0], [x1, y1]] and returns the hexbin generator. If extent is not specified, returns the generator’s current extent [[x0, y0], [x1, y1]], where x0 and y0 are the lower bounds and x1 and y1 are the upper bounds. The extent defaults to [[0, 0], [1, 1]].

# hexbin.size([size])

If size is specified, sets the extent to the specified bounds [[0, 0], [dx, dy]] and returns the hexbin generator. If size is not specified, returns the generator’s current size [x1 - x0, y1 - y0], where x0 and y0 are the lower bounds and x1 and y1 are the upper bounds. The size defaults to [1, 1]. This is a convenience method for setting the extent. For example, these two statements are equivalent:

hexbin.extent([[0, 0], [width, height]]);
hexbin.size([width, height]);

d3-hexbin's Issues

HexBin ordering

Can someone tell me if there is an ordering to the hexagons (like a space filling curve) or aperture ?

Incremental binning (add and remove).

It might be nice to re-design this API more along the lines of d3-quadtree so that points could be incrementally added and removed from the bins, rather than requiring all the points to be re-binned.

Usage in ES6 import

How to import this as an ES6 import? Happy to have it renamed (I dont need to have it in d3. namespace , I just want it in my project. Ive tried:
import * as d3hexbin from "d3-hexbin";
import { hexbin } as d3hexbin from "d3-hexbin";
import d3hexbin from "d3-hexbin/src/hexbin";
import * as d3hexbin from "d3-hexbin/src/hexbin";
import * as hexbin from "d3-hexbin";

I got sankey working with this:
import * as d3Sankey from "d3-sankey";

But no matter how I import this, im getting an error that it is not a function Hope you can help. - D

Use d3-hexbin with Angular 8

HI! I'm trying to find some reference on how to use the library with Angular 8, but didn't find anything by now. If someone can help me, I would appreciate it.

Thanks!

Row vs Column Offset Issues

Hi, first thanks for this great plugin!

I'm having an issue that the offset of rows and columns is different depending on the size of the radius. The code is..

d3hexbin.hexbin().radius(tileSize)

Depending on the size, the row shifts. Hard to explain, so will provide images. It also seems like it's different depending on machine and/or browser.

The relationship between row vs column seems unpredictable, which causes problems for my code. Would like to know if there's a way to make this predictable. Maybe there is some math I can do to make sure I get one state vs the other.

I call one good and one bad, but actually it doesn't matter to me, as long as it can be predictable.

Good State (tile size 39)

Bad State (tile size 37)

code can be found here
https://github.com/snellcode/insulam/blob/main/src/services/map.ts

Cannot properly fill mesh hexagons

All the hexagons generated by the associated hexbin.mesh function are basically half-hexagons, which makes filling via a svg "fill" quite impossible. The use-case is to have them look just like any other hexbin.hexagon in a lot of use-cases where they need a specific color.

I removed this .slice(0,4) from the library and it seems to work properly now ,even if i'm still missing one top left side of the hexagon.

It would be great to have some support to disable this half-hexagon optimization, not only it's useful for coloring the mesh but also hexes are not cut at the edges anymore.

Here's how it looks like:

And notice how the mesh gets cut at the top left corners

Forced Label Layout

Hi Moritz,

http://bl.ocks.org/MoritzStefaner/1377729

The forced layout of labels is pretty cool -- what the license on it?

• Chris

Take d3.hexbin when available

<script src="//d3js.org/d3.v4.js"></script>
<script src="https://unpkg.com/d3-hexbin@0"></script>
<script>

var hexbin = d3.hexbin();    // currently requires d3_hexbin.hexbin()

</script>

implicit dependency on d3

Line 43 hexbin.js: use of "d3.values" lets to an error if d3.js is not present, is there any equivalent in a smaller d3 module?

1.0 release.

I should tackle #1 and then push a 1.0 release now that D3 4.0 is out.

bin(point)?

hexbin.bin(point) returns the bin that corresponds to the point, without adding the point.

When the bin is empty, we return an empty array with (x,y) properties.

But (partly because of that, and also because of rebin()), one must not trust that bin to stay up-to-date with additions and removals of points.

Inconsistency between README and global namespace

Between 0.2.0 and 0.2.1, the d3 hexbin global namespace changed from 'd3_hexbin' to 'd3'. The README now incorrectly gives the example of using 'd3_hexbin' as the namespace.

Version 0.2.0:

(function (global, factory) {
  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
  typeof define === 'function' && define.amd ? define(['exports'], factory) :
  (factory((global.d3_hexbin = global.d3_hexbin || {})));
}(this, function (exports) { 'use strict';

Version 0.2.1:

// https://github.com/d3/d3-hexbin Version 0.2.1. Copyright 2017 Mike Bostock.
(function (global, factory) {
	typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
	typeof define === 'function' && define.amd ? define(['exports'], factory) :
	(factory((global.d3 = global.d3 || {})));
}(this, (function (exports) { 'use strict';

README v0.2.1:

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

var hexbin = d3_hexbin.hexbin();

</script>

Hexgrid Rotation

The orientation of the hexgrid should be configurable. See http://bl.ocks.org/jasondavies/f5922ed4d0ac1ac2161f

Support Canvas.

Should hexbin.hexagon implement the symbol type interface? But it has a specific radius, not an arbitrary size…

Should the hexagon method take a context? But then you have to construct a path buffer manually?

Should the hexbin take a context? And then render like a shape? (Rendering either a mesh of individual hexbins?) Maybe?

Rounded Edges

How do I generate hexagons with rounded edges?

Function .centers() returns only 3 items

Hello :)
I wanna use .centers() but when i use this I get only 3 points

0: [0, 0]
1: [1.7320508075688772, 0]
2: [0.8660254037844386, 1.5]

Why visible and not visible hexagon centers points is not return ?

"or as part of D3 4.0" statement in the readme does not appear to be true for d3.v4 version 4.2.7

Just downloaded the latest from d3js.org/d3.v4.min.js and this does not appear to be one of the functions within. Not really issue, but probably worth mentioning.