d3-x3dom

3D Data Visualisation Library

Combining the power of the D3.js data-driven documents visualisation library, and the X3DOM declarative 3D DOM framework, d3-x3dom makes it easy to quickly produce beautiful 3D data visualisations with minimal code.

Inspired by Mike Bostock's reusable charts, d3-x3dom is built on a foundation of building blocks, called components, which can be combined to create a variety of different data visualisations.

Examples

Getting Started

Include D3.js, X3DOM and d3-x3dom js and css files in the <head> section of your page:

<head>
   <script src="https://d3js.org/d3.v5.min.js"></script>
   <script src="https://x3dom.org/download/1.7.2/x3dom-full.js"></script>
   <link rel="stylesheet" href="https://x3dom.org/download/1.7.2/x3dom.css" />
   <script src="https://raw.githack.com/jamesleesaunders/d3-x3dom/master/build/d3-x3dom.js"></script>
</head>

Add a chartholder <div> and <script> tags to your page <body>:

<body>
   <div id="chartholder"></div>
   <script></script>
</body>

Place the following code between the <script></script> tags:

Select chartholder:

var chartHolder = d3.select("#chartholder");

Generate some data:

var myData = [
	{
		key: "UK",
		values: [
			{ key: "Apples", value: 9 },
			{ key: "Oranges", value: 3 },
			{ key: "Pears", value: 5 },
			{ key: "Bananas", value: 7 }
		]
	},
	{
		key: "France",
		values: [
			{ key: "Apples", value: 5 },
			{ key: "Oranges", value: 4 },
			{ key: "Pears", value: 6 },
			{ key: "Bananas", value: 2 }
		]
	}
];

Declare the chart component:

var myChart = d3.x3dom.chart.barChartMultiSeries();

Attach chart and data to the chartholder:

chartHolder
	.datum(myData)
	.call(myChart);

That's all there is to it! View the page in your browser and you should see a basic 3D bar chart.

Install from NPM

If your project is using ES6 modules you can also import d3-x3dom, for example from NPM:

npm install --save d3-x3dom

Then in your project:

let d3X3dom = require("d3-x3dom");

Components and Charts

d3-x3dom has two types of reusable modules: component and chart. For more information see the API Reference.

Components

The component modules are lower level building blocks which can be used independently, or combined to build higher level chart modules. For example, combining component.bars(), component.axis() and component.viewpoint() modules together we have built the chart.barChartMultiSeries(). Component modules do not generate a x3d tag, these should be attached to an exiting x3d tag.

Function	Description	Example	Documentation
component.axis()	Single plane x/y Axis	View	View
component.axisThreePlane()	Three plane x/y/z Axis	View	View
component.bars()	Single series Bar Chart	View	View
component.barsMultiSeries()	Multi series Bar Chart	View	View
component.bubbles()	Bubble / Scatter Plot	View	View
component.bubblesMultiSeries()	Multi series Bubbles / Scatter Plot	View	View
component.crosshair()	Crosshair	View	View
component.ribbon()	Ribbon Chart / Line Chart	View	View
component.ribbonMultiSeries()	Multi series Ribbon Chart	View	View
component.surface()	Surface Area	View	View
component.vectorFields()	Vector Field Chart	View	View
component.viewpoint()	Camera position	View	View

Charts

The chart modules are higher level, pre-combined components, making it even simpler to quickly create charts. All the charts are typically constructed of a viewpoint, axis and one or more of the other components above. Chart modules also generate the x3d tag, these should be attached to a div tag.

Function	Description	Example	Documentation
chart.barChartMultiSeries()	Multi series Bar Chart & Axis	View	View
chart.barChartVertical()	Vertical Bar Chart & Axis	View	View
chart.bubbleChart()	Bubble Chart & Axis	View	View
chart.ribbonChartMultiSeries()	Multi series Ribbon Chart	View	View
chart.scatterPlot()	Scatter Plot & Axis	View	View
chart.surfacePlot()	Surface Plot & Axis	View	View
chart.vectorFieldChart()	Vector Field Chart	View	View

Data Structures

At its most basic description, the format of the d3-x3dom data is a series of key / value pairs. Depending on whether the chart is a single series or multi series chart the data structure differs slightly.

Single Series Data

Used by charts such as a single series bar chart, the data structure is an object with the following structure:

key {string} - The series name
values {array} - An array of objects containing:
- key {string} - The value name
- value {number} - The value
- x {number} - X axis value*
- y {number} - Y axis value*
- z {number} - Z axis value*

*optional, x, y & z values are used for cartesian coordinate type graphs such as the scatter plot.

var myData = {
	key: "UK",
	values: [
		{ key: "Apples", value: 9, x: 1, y: 2, z: 5 },
		/* ... */
		{ key: "Bananas", value: 7, x: 6, y: 3, z: 8 }
	]
};

Multi Series Data

Used by charts such as the multi series scatter plot, the multi series data structure is simply an array of the single series data objects above.

var myData = [
	{
		key: "UK",
		values: [
			{ key: "Apples", value: 2 },
			/* ... */
			{ key: "Bananas", value: 3 }
		]
	},
	/* ... */
	{
		key: "France",
		values: [
			{ key: "Apples", value: 5 },
			/* ... */
			{ key: "Bananas", value: 9 }
		]
	}
];

Credits

Fabian Dubois - For the original 3D Axis, Surface Area and Scatter Plot.
David Sankel - For the original Bar Chart.
Victor Glindås - Various contributions to JSDoc and ES6 standardisation.
You may also be interested in the sister project d3-ez Reusable 2D Charts Library.

l4cr0ss/d3-x3dom