Package Exports

d3-hexjson

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (d3-hexjson) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

d3-hexjson

This D3 plugin makes it easy to generate hexmaps from data that uses the Open Data Institute's HexJSON format. The plugin provides a single function that takes a HexJSON object and adds the properties needed to render it as a hexmap of a given size. The renderHexJSON function calculates the hex size necessary to render the hexmap within an svg of the specified dimensions, and generates the position and the points for each hex. This data is returned as an array of hexes that you can render directly with D3 as polygons, by using the x and y coordinates to position each hex, and the points property as the points attribute of its polygon. Hex coordinates are rendered according to the coordinate system specified by the layout property of the HexJSON provided.

Installing

If you use NPM, npm install d3-hexjson. Otherwise, download the latest release and use d3-hexjson.min.js, which can be found in the build directory. The module is designed to be used in conjunction with the core D3 library (see the example usage below).

API Reference

# d3.renderHexJSON(hexjson, width, height)

Returns an array of hexes from a HexJSON object, adding to each hex the properties needed to render them as a hexmap with D3. The function calculates the appropriate size to render the hexes within an svg of the given width and height. The central pixel coordinates of each hex are stored in x and y properties, while the vertices property holds an array of coordinate pairs, which specify the position of each vertex relative to x and y. The points property contains the vertex coordinates as a string that can be inserted directly into the points attribute of a polygon. The key used to reference each hex within the HexJSON object is stored within each hex in the key property. As these properties are added to the hexes stored in the source HexJSON, the hexes and their properties can be accessed either through the returned array or through the original HexJSON object (if you need to merge additional data based on the key, for example).

The full list of properties that the function adds to each hex is as follows:

key - The key against which the hex is stored in the source HexJSON
qc - The absolute column number of the hex, measured left to right from zero
rc - The absolute row number of the hex, measured top to bottom from zero
x - The pixel coordinate of the centre of the hex within the svg on the x-axis
y - The pixel coordinate of the centre of the hex within the svg on the y-axis
vertices - The pixel coordinates of the vertices relative to x and y
points - The vertex positions represented as a string for use in an svg polygon

Note that while the absolute row numbers of each hex are represented internally in the rc property from top to bottom, the r property of the HexJSON data represents row numbers from bottom to top. This follows the row numbering convention used in the example HexJSON implementation provided by the ODI in their hexmap of UK Parliamentary constituencies.

Example Usage

The following example shows the most common usage. See the code in action in this block by Henry Lau.

Given this HexJSON stored in the file example.hexjson:

{
    "layout":"odd-r",
    "hexes":{
        "C0R0":{"q":0,"r":0},
        "C1R0":{"q":1,"r":0},
        "C2R0":{"q":2,"r":0},
        "C3R0":{"q":3,"r":0},
        "C0R1":{"q":0,"r":1},
        "C1R1":{"q":1,"r":1},
        "C2R1":{"q":2,"r":1},
        "C3R1":{"q":3,"r":1},
        "C0R2":{"q":0,"r":2},
        "C1R2":{"q":1,"r":2},
        "C2R2":{"q":2,"r":2},
        "C3R2":{"q":3,"r":2},
        "C0R3":{"q":0,"r":3},
        "C1R3":{"q":1,"r":3},
        "C2R3":{"q":2,"r":3},
        "C3R3":{"q":3,"r":3}
    }
}

A hexmap of the data can be rendered in the following way:

<html>
<head>
<style>
#vis {
    margin: 0;
    padding: 0;
    text-align: center;
    font-family: sans-serif;
    font-size: 10pt;
}
</style>
</head>
<body>
<div id="vis"></div>
<script src="d3.min.js"></script>
<script src="d3-hexjson.min.js"></script>
<script>

d3.json("example.hexjson", function(error, hexjson) {

    // Set the size and margins of the svg
    var margin = {top: 10, right: 10, bottom: 10, left: 10},
        width = 500 - margin.left - margin.right,
        height = 420 - margin.top - margin.bottom;

    // Create the svg element
    var svg = d3
        .select("#vis")
        .append("svg")
        .attr("width", width + margin.left + margin.right)
        .attr("height", height + margin.top + margin.bottom)
        .append("g")
        .attr("transform", "translate(" + margin.left + "," + margin.top + ")");

    // Render the hexes
    var hexes = d3.renderHexJSON(hexjson, width, height);

    // Bind the hexes to g elements of the svg and position them
    var hexmap = svg
        .selectAll("g")
        .data(hexes)
        .enter()
        .append("g")
        .attr("transform", function(hex) {
            return "translate(" + hex.x + "," + hex.y + ")";
        });

    // Draw the polygons around each hex's centre
    hexmap
        .append("polygon")
        .attr("points", function(hex) {return hex.points;})
        .attr("stroke", "white")
        .attr("stroke-width", "2")
        .attr("fill", "#b0e8f0");

    // Add the hex codes as labels
    hexmap
        .append("text")
        .append("tspan")
        .attr("text-anchor", "middle")
        .text(function(hex) {return hex.key;});
});

</script>
</body>
</html>