hilbert-chart-3d
v0.8.0
Published
A 3d hilbert space-filling curve D3 chart for representing one-dimensional lengths on a three-dimensional space.
Maintainers
Readme
Hilbert Chart 3D
A 3D hilbert space-filling curve chart for representing one-dimensional lengths on a three-dimensional space.
Uses ThreeJS/WebGL for 3D rendering.
See also the 2D version.
Examples
Quick start
import HilbertChart3D from 'hilbert-chart-3d';or using a script tag
<script src="//cdn.jsdelivr.net/npm/hilbert-chart-3d"></script>then
const myChart = new HilbertChart3D(<myDOMElement>)
.hilbertOrder(<hilbertOrder>)
.data(<myData>);API reference
Initialisation
new HilbertChart3D(<domElement>, { configOptions })| Config options | Description | Default |
| --- | --- | :--: |
| controlType: str or class | Which type of control to use to control the camera. Choice between trackball, arcball, orbit, fly, or a custom Three.js controls class. | arcball |
| rendererConfig: object | Configuration parameters to pass to the ThreeJS WebGLRenderer constructor. | { antialias: true, alpha: true } |
Container
| Method | Description | Default | | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------- | | width([px]) | Getter/setter for the canvas width. | <window width> | | height([px]) | Getter/setter for the canvas height. | <window height> |
Hilbert layout
| Method | Description | Default |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------- |
| hilbertOrder([number]) | Getter/setter for the extent of the hilbert curve range, determined by 8^order. Orders above 17 use BigInt arithmetic; supply BigInt values or safe integer Numbers for exact input. | 3 |
| 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 (64 values), a range from 8 to 23 can be simplified from 16 vertices to 2 (each filling a cube with 8 values). 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 |
| padding([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 |
| paddingAbsolute([number, string or fn]) | Getter/setter for the range object absolute padding accessor function (fn(range)), attribute or a constant number for all ranges. The value represents the absolute padding size as a fraction of the full Hilbert width. | 0 |
| getPositionAtVal(value) | Returns the THREE.Vector3 position at the specified value along the curve. value may be a Number or BigInt. | |
Data input
| Method | Description | Default |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------- |
| 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>}; start and length must both be Numbers or both be BigInts. | [] |
| color([string or fn]) | Getter/setter for the range object color accessor function (fn(range)) or attribute. | (cycle through d3.schemePaired for unique labels) |
| label([string or fn]) | Getter/setter for the range object label accessor function (fn(range)) or attribute. | name |
| labelColor([string, false or fn]) | Getter/setter for the range object label color accessor function (fn(range)) or attribute. A falsy value disables the label. | () => 'white' |
| valFormatter([fn]) | Getter/setter for the value formatting function (fn(value)), in default tooltips. Values may be Numbers or BigInts. | d => d |
Render control
| Method | Description | Default |
| --- | --- | :--: |
| useInstancedMeshes([boolean or fn]) | Getter/setter for whether to render compatible segments with THREE.InstancedMesh to reduce draw calls. Accepts a boolean or a function of the datum. Recommended for very large datasets. Segments that cannot be instanced use regular meshes. | false |
| zoomToFit([ms], [px]) | Automatically moves the camera so that all of the hilbert segments become visible within its field of view. It accepts two optional arguments: the first defines the duration of the transition (in ms) to animate the camera motion (default: 0ms). The second argument is the amount of padding (in px) between the edge of the canvas and the outermost node location (default: 10px). | (0, 10) |
| 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. 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. ||
| cameraPosition([{x,y,z}], [lookAt], [ms]) | Getter/setter for the camera position, in terms of x, y, z coordinates. Each of the coordinates is optional, allowing for motion in just some dimensions. The optional second argument can be used to define the direction that the camera should aim at, in terms of an {x,y,z} point in the 3D space. The 3rd optional argument defines the duration of the transition (in ms) to animate the camera motion. A value of 0 (default) moves the camera immediately to the final position. | |
| lights([array]) | Getter/setter for the list of lights to use in the scene. Each item should be an instance of Light. | AmbientLight + DirectionalLight (from above) |
| scene() | Access the internal ThreeJS Scene. | |
| camera() | Access the internal ThreeJS Camera. | |
| renderer() | Access the internal ThreeJS WebGL renderer. ||
| controls() | Access the internal ThreeJS controls object. ||
Interaction
| Method | Description | Default |
| --- | --- | :--: |
| tooltipContent([string or fn]) | Getter/setter for the range object tooltip content accessor function or attribute. Supports plain text or HTML content. | <label>: <start> - <end> |
| onHover(fn) | Callback function for range mouse over events. Receives the current range (or null if hovering out) and the previous range (or null). | - |
| onClick(fn) | Callback function for range clicks. Receives the range object and the mouse event. | - |
| onBackgroundClick(fn) | Callback function for click events on the empty background space. Receives the mouse event. | - |
| hoverOrderComparator(fn) | Comparator function to use when hovering over multiple ranges under the same line of sight. This function can be used to prioritize hovering some ranges over others. | By default, hovering priority is based solely on camera proximity (closest range wins). |
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!

