hilbert-chart
v1.21.8
Published
A hilbert space-filling curve D3 chart for representing one-dimensional lengths on a two-dimensional space.
Maintainers
Readme
Hilbert Chart
A hilbert space-filling curve chart for representing one-dimensional lengths on a two-dimensional space.
Supports optional rendering on Canvas to handle very large datasets, and features a heatmap layer for representing a set of single points.
Uses d3-hilbert for the layout computation.
Examples
- IPv4 Address Space (source)
- Large dataset (~1M cells using canvas) (source)
- Ordinal (square pie chart) (source)
- Heatmap (source)
- IPv4 BGP Routing Table (source)
- IPv6 BGP Routing Table (source)
- AS Numbers (source)
- Internet Fragmentation Heatmap (source)
Also live example at: https://observablehq.com/@vasturiano/hilbert-map-of-ipv4-address-space
Quick start
import HilbertChart from 'hilbert-chart';or using a script tag
<script src="//cdn.jsdelivr.net/npm/hilbert-chart"></script>then
const myChart = new HilbertChart(<myDOMElement>)
.hilbertOrder(<hilbertOrder>)
.data(<myData>);API reference
Initialisation
new HilbertChart(<domElement>, { configOptions })| Config options | Description | Default |
| --- | --- | :--: |
| useCanvas: boolean | Whether to use HTML5 Canvas (true) or SVG (false) as rendering method. Canvas yields much better rendering performance for very large number of items. | false |
| zoomWithModKey: boolean | Whether to require a modifier key (meta or ctrl) to be pressed in order to engage the scrolling zoom. | false |
Methods
| Method | Description | Default |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------- |
| width([number]) | Getter/setter for the length of each side of the square chart, in px. | (fit to window) |
| margin([number]) | Getter/setter for the chart margin that contains the axis ticks and labels, in px. | 90 |
| hilbertOrder([number]) | Getter/setter for the extent of the hilbert curve range, determined by 4^order. Orders above 26 use BigInt arithmetic; supply BigInt values or safe integer Numbers for exact input. | 4 |
| data([array]) | Getter/setter for the list of ranges to render. Each range object should follow the minimum syntax of {start: <number or bigint>, length: <number or bigint>}. | [] |
| heatmapPoints([array]) | Getter/setter for an array of numeric or BigInt values to render as a heatmap overlay on the chart. | [] |
| heatmapPointRadius([number]) | Getter/setter for the blur radius (in px) of each heatmap point. Larger values produce smoother, more diffuse heatmaps. | 20 |
| heatmapOpacity([number]) | Getter/setter for the opacity of the heatmap overlay. | 0.8 |
| rangeLabel([string or fn]) | Getter/setter for the range object label accessor function (fn(range)) or attribute. | name |
| rangeLabelColor([string or fn]) | Getter/setter for the range object label color accessor function (fn(range)) or attribute. | () => 'black' |
| rangeColor([string or fn]) | Getter/setter for the range object color accessor function (fn(range)) or attribute. | (cycle through d3.schemeCategory20 for unique labels) |
| rangePadding([number, string or fn]) | Getter/setter for the range object padding ratio accessor function (fn(range)), attribute or a constant number for all ranges. The padding ratio should be a number between 0 and 1 representing the proportional size of the padding space compared to the width of the path. | 0 |
| rangePaddingAbsolute([number, string or fn]) | Getter/setter for the range object absolute padding accessor function (fn(range)), attribute or a constant number for all ranges. This absolute padding is added to the relative one set with rangePadding. | 0 |
| valFormatter([fn]) | Getter/setter for the value formatting function (fn(value)), as text displayed in axis ticks and tooltips. Values may be Numbers or BigInts; should return a string. | d => d |
| simplifyCurves([boolean]) | Getter/setter for whether to simplify the resolution of the curve to the most canonical 2-bit boundary that fits the range integral. For example, in a 2nd order curve (16 values), a range from 4 to 11 can be simplified from 8 vertices to 2 (each filling a square with 4 values), on the lower quadrants. This simplification greatly reduces the number of vertices in the curve and improves the calculation and rendering performance, specially for high-order ranges which tend to fall on bit boundaries. | true |
| minCurveWidth([number]) | Getter/setter for the minimum curve cell width in screen pixels. Ranges with smaller cells are not rendered until zoomed in sufficiently. Only applicable to Canvas rendering mode. | 1 |
| focusOn(pos, length, [ms]) | Zoom-in on a particular area of the chart, defined by [pos, pos+length-1]. pos and length may be Numbers or BigInts. May be an approximation if length doesn't match a logical bit boundary. An optional 3rd argument defines the duration of the transition (in ms) to animate the zooming motion. A value of 0 (default) jumps immediately to the final position. ||
| showValTooltip([boolean]) | Getter/setter for whether to show a value tooltip on mouse-over. | true |
| showRangeTooltip([boolean]) | Getter/setter for whether to show a range tooltip on mouse-over. | true |
| rangeTooltipContent([string or fn]) | Getter/setter for the range object tooltip content accessor function or attribute. Supports plain text or HTML content. | <label>: <start> - <end> |
| enableZoom([boolean]) | Getter/setter for whether to enable zoom/pan interaction in the chart. | true |
| onRangeClick(fn) | Callback function for range clicks. The range object is included as single argument onRangeClick(range). | - |
| onRangeHover(fn) | Callback function for range mouse over events. The range object (or null if hovering out) is included as single argument onRangeHover(range). | - |
| onPointerMove(fn) | Callback function for pointer move events over the hilbert canvas. The hilbert curve value directly under the mouse pointer (a Number or BigInt, depending on order) is included as argument, as well as the event object itself. onPointerMove(value, event). | - |
| onZoom(fn) | Callback function for zoom/pan events. The current zoom transform is included as single argument onZoom({ k, x, y }). Note that onZoom is triggered by user interaction as well as programmatic zooming/panning with focusOn(). | - |
| onZoomEnd(fn) | Callback function for 'end' of zoom/pan events. The current zoom transform is included as single argument onZoomEnd({ k, x, y }). Note that onZoomEnd is triggered by user interaction as well as programmatic zooming/panning with focusOn(). | - |
Use BigInt literals (for example, 12345678901234567890n) when values exceed JavaScript's safe integer range.
❤️ Support This Project
If you find this module useful and would like to support its development, you can buy me a ☕. Your contributions help keep open-source sustainable!

