Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including d3-x3d with all npm packages installed. Try it out:

var d3X3d = require("d3-x3d")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

d3-x3d v2.0.5

3D Data Driven Charting Library with D3 and X3D

d3-x3d

3D Data Driven Charting Library with D3 and X3D

npm version Build Status

Combining the power of the D3.js data-driven documents visualisation library and the Extensible 3D X3D 3D graphics standard, d3-x3d makes it simple to produce beautiful 3D data visualisations with minimal code.

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

The aspiration for the X3D specification is for it to become the de facto HTML5 standard for 3D graphics in the browser, in a similar manner to that of SVG (Scalable Vector Graphics). The aim is that one day X3D will be integrated as standard into all browsers, without the need for additional plugins. For the time being, there are two JavaScript based players for X3D:

Both these players are compatible with modern browsers supporting HTML5 and enable X3D scenes to be embedded in any HTML page. d3-x3d has been tested to work with both X3DOM and X_ITE (there are a couple of more advanced features and charts which currently only work with X3DOM).

Examples

ExampleX3DOMX_ITEObservable
Area ChartViewViewView
Multi Series Bar ChartViewViewView
Vertical Bar ChartViewViewView
Bubble ChartViewViewView
Scatter PlotViewViewView
Surface PlotViewViewView
Ribbon ChartViewViewView
Vector Field ChartViewViewView
Volume SliceViewWIPWIP

Getting Started

Include the following JavaScript and CSS files in the <head> section of your page:

If using X3DOM:

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

If using X_ITE:

<head>
   <script src="https://d3js.org/d3.v5.min.js"></script>
   <script src="https://code.create3000.de/x_ite/latest/dist/x_ite.min.js"></script>
   <script src="https://raw.githack.com/andreasplesch/x_ite_dom/master/latest/x_ite_dom.js"></script>
   <link rel="stylesheet" href="https://code.create3000.de/x_ite/latest/dist/x_ite.css" />
   <script src="https://raw.githack.com/jamesleesaunders/d3-x3d/master/dist/d3-x3d.js"></script>
</head>

Add the following chartholder <div> (or <X3DCanvas>) and <script> tags to your page <body>:

If using X3DOM:

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

If using X_ITE:

<body>
   <X3DCanvas id="chartholder"></X3DCanvas>
   <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.x3d.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-x3d, for example from NPM:

npm install --save d3-x3d

Then in your project:

let d3X3d = require("d3-x3d");

Components and Charts

d3-x3d has two types of reusable module: 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.

FunctionDescriptionDocumentation
component.area()Single series Area ChartView
component.areaMultiSeries()Multi series Area ChartView
component.axis()Single plane x/y AxisView
component.axisThreePlane()Three plane x/y/z AxisView
component.bars()Single series Bar ChartView
component.barsMultiSeries()Multi series Bar ChartView
component.bubbles()Bubble / Scatter PlotView
component.bubblesMultiSeries()Multi series Bubbles / Scatter PlotView
component.crosshair()CrosshairView
component.ribbon()Ribbon Chart / Line ChartView
component.ribbonMultiSeries()Multi series Ribbon ChartView
component.surface()Surface AreaView
component.vectorFields()Vector Field ChartView
component.viewpoint()Camera positionView
component.volumeSlice()Volume Slice (MRI Scan)View

Charts

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

FunctionDescriptionDocumentation
chart.areaChartMultiSeries()Multi series Area Chart & AxisView
chart.barChartMultiSeries()Multi series Bar Chart & AxisView
chart.barChartVertical()Vertical Bar Chart & AxisView
chart.bubbleChart()Bubble Chart & AxisView
chart.ribbonChartMultiSeries()Multi series Ribbon ChartView
chart.scatterPlot()Scatter Plot & AxisView
chart.surfacePlot()Surface Plot & AxisView
chart.vectorFieldChart()Vector Field ChartView
chart.volumeSliceChart()Volume Slice ChartView

Data Structures

At its most basic description, the format of the d3-x3d data is a series of key / value pairs. Depending on whether the chart is a single series or multi series chart the data structure differ 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 or area chart, 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.
  • Jefferson Hudson - For contributions to axis labels and transitions.
  • Andreas Plesch - For contributing the Area Chart and Components (and generally being an x3dom hero!).
  • Also see alternative d3-3d by @Niekes.
RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free