Graph3d is an interactive visualization chart to draw data in a three dimensional graph. You can freely move and zoom in the graph by dragging and scrolling in the window. Graph3d also supports animation of a graph.
Graph3d uses HTML canvas to render graphs, and can render up to a few thousands of data points smoothly.
The following code shows how to create a Graph3d and provide it with data. More examples can be found in the examples directory.
<!DOCTYPE HTML>
<html>
<head>
<title>Graph 3D demo</title>
<style>
body {font: 10pt arial;}
</style>
<script type="text/javascript" src="../../dist/vis.js"></script>
<script type="text/javascript">
var data = null;
var graph = null;
function custom(x, y) {
return (Math.sin(x/50) * Math.cos(y/50) * 50 + 50);
}
// Called when the Visualization API is loaded.
function drawVisualization() {
// Create and populate a data table.
var data = new vis.DataSet();
// create some nice looking data with sin/cos
var steps = 50; // number of datapoints will be steps*steps
var axisMax = 314;
var axisStep = axisMax / steps;
for (var x = 0; x < axisMax; x+=axisStep) {
for (var y = 0; y < axisMax; y+=axisStep) {
var value = custom(x, y);
data.add({
x: x,
y: y,
z: value,
style: value
});
}
}
// specify options
var options = {
width: '600px',
height: '600px',
style: 'surface',
showPerspective: true,
showGrid: true,
showShadow: false,
keepAspectRatio: true,
verticalRatio: 0.5
};
// create a graph3d
var container = document.getElementById('mygraph');
graph3d = new vis.Graph3d(container, data, options);
}
</script>
</head>
<body onload="drawVisualization();">
<div id="mygraph"></div>
</body>
</html>
The class name of the Graph3d is vis.Graph3d.
When constructing a Graph3d, an HTML DOM container must be provided to attach
the graph to. Optionally, data an options can be provided.
Data is a vis DataSet or an Array, described in
section Data Format.
Options is a name-value map in the JSON format. The available options
are described in section Configuration Options.
var graph = new vis.Graph3d(container [, data] [, options]);
Data and options can be set or changed later on using the functions
Graph3d.setData(data) and Graph3d.setOptions(options).
Graph3d can load data from an Array, a DataSet or a DataView.
JSON objects are added to this DataSet by using the add() function.
Data points must have properties x, y, and z,
and can optionally have a property style and filter.
The DataSet JSON objects are defined as:
| Name | Type | Required | Description |
|---|---|---|---|
| x | number | yes | Location on the x-axis. |
| y | number | yes | Location on the y-axis. |
| z | number | yes | Location on the z-axis. |
| style | number | no | The data value, required for graph styles dot-color and
dot-size.
|
| filter | * | no | Filter values used for the animation. This column may have any type, such as a number, string, or Date. |
Options can be used to customize the graph. Options are defined as a JSON object. All options are optional.
var options = {
width: '100%',
height: '400px',
style: 'surface'
};
The following options are available.
| Name | Type | Default | Description |
|---|---|---|---|
| animationInterval | number | 1000 | The animation interval in milliseconds. This determines how fast the animation runs. |
| animationPreload | boolean | false | If false, the animation frames are loaded as soon as they are requested.
if animationPreload is true, the graph will automatically load
all frames in the background, resulting in a smoother animation as soon as
all frames are loaded. The load progress is shown on screen. |
| animationAutoStart | boolean | false | If true, the animation starts playing automatically after the graph is created. |
| axisColor | string | '#4D4D4D' | The color of the axis lines and the text along the axis. |
| backgroundColor | string or Object | {fill: 'white', stroke: 'gray', strokeWidth: 1} | The background color for the main area of the chart. Can be either a simple HTML color string, for example: 'red' or '#00cc00', or an object with the following properties. |
| backgroundColor.fill | string | 'white' | The chart fill color, as an HTML color string. |
| backgroundColor.stroke | string | 'gray' | The color of the chart border, as an HTML color string. |
| backgroundColor.strokeWidth | number | 1 | The border width, in pixels. |
| cameraPosition | Object | {horizontal: 1.0, vertical: 0.5, distance: 1.7} | Set the initial rotation and position of the camera.
The object cameraPosition contains three parameters:
horizontal, vertical, and distance.
Parameter horizontal is a value in radians and can have any
value (but normally in the range of 0 and 2*Pi).
Parameter vertical is a value in radians between 0 and 0.5*Pi.
Parameter distance is the (normalized) distance from the
camera to the center of the graph, in the range of 0.71 to 5.0. A
larger distance puts the graph further away, making it smaller.
All parameters are optional.
|
| dataColor | string or object | {fill: '#7DC1FF', stroke: '#3267D2', strokeWidth: 1} | When dataColor is a string, it will set the color for both border and fill color of dots and bars. Applicable for styles dot-size, bar-size, and line. When an object, it can contain the properties descibed below. |
| dataColor.fill | string | '#7DC1FF' | The border color of the dots or bars. Applicable when using styles dot-size or bar-size. |
| dataColor.stroke | string | '#3267D2' | The fill color of the dots or bars. Applicable when using styles dot-size, bar-size, or line. |
| dataColor.strokeWidth | number | 1 | The line width of dots, bars and lines. Applicable for all styles. |
| gridColor | string | '#D3D3D3' | The color of the grid lines. |
| height | string | '400px' | The height of the graph in pixels or as a percentage. |
| keepAspectRatio | boolean | true | If keepAspectRatio is true, the x-axis and the y-axis
keep their aspect ratio. If false, the axes are scaled such that they
both have the same, maximum with. |
| showAnimationControls | boolean | true | If true, animation controls are created at the bottom of the Graph. The animation controls consists of buttons previous, start/stop, next, and a slider showing the current frame. Only applicable when the provided data contains an animation. |
| showGrid | boolean | true | If true, grid lines are draw in the x-y surface (the bottom of the 3d graph). |
| showPerspective | boolean | true | If true, the graph is drawn in perspective: points and lines which are further away are drawn smaller. Note that the graph currently does not support a gray colored bottom side when drawn in perspective. |
| showShadow | boolean | false | Show shadow on the graph. |
| style | string | 'dot' | The style of the 3d graph. Available styles:
bar,
bar-color,
bar-size,
dot,
dot-line,
dot-color,
dot-size,
line,
grid,
or surface |
| tooltip | boolean | function | false | Show a tooltip showing the values of the hovered data point.
The contents of the tooltip can be customized by providing a callback
function as tooltip. In this case the function is called
with an object containing parameters x,
y, and z argument,
and must return a string which may contain HTML.
|
| valueMax | number | none | The maximum value for the value-axis. Only available in combination
with the styles dot-color and dot-size. |
| valueMin | number | none | The minimum value for the value-axis. Only available in combination
with the styles dot-color and dot-size. |
| verticalRatio | number | 0.5 | A value between 0.1 and 1.0. This scales the vertical size of the graph When keepAspectRatio is set to false, and verticalRatio is set to 1.0, the graph will be a cube. |
| width | string | '400px' | The width of the graph in pixels or as a percentage. |
| xBarWidth | number | none | The width of bars in x direction. By default, the width is equal to the distance
between the data points, such that bars adjoin each other.
Only applicable for styles 'bar' and 'bar-color'. |
| xCenter | string | '55%' | The horizontal center position of the graph, as a percentage or in pixels. |
| xMax | number | none | The maximum value for the x-axis. |
| xMin | number | none | The minimum value for the x-axis. |
| xStep | number | none | Step size for the grid on the x-axis. |
| xValueLabel | function | none | A function for custom formatting of the labels along the x-axis,
for example function (x) {return (x * 100) + '%'}.
|
| yBarWidth | number | none | The width of bars in y direction. By default, the width is equal to the distance
between the data points, such that bars adjoin each other.
Only applicable for styles 'bar' and 'bar-color'. |
| yCenter | string | '45%' | The vertical center position of the graph, as a percentage or in pixels. |
| yMax | number | none | The maximum value for the y-axis. |
| yMin | number | none | The minimum value for the y-axis. |
| yStep | number | none | Step size for the grid on the y-axis. |
| yValueLabel | function | none | A function for custom formatting of the labels along the y-axis,
for example function (y) {return (y * 100) + '%'}.
|
| zMin | number | none | The minimum value for the z-axis. |
| zMax | number | none | The maximum value for the z-axis. |
| zStep | number | none | Step size for the grid on the z-axis. |
| zValueLabel | function | none | A function for custom formatting of the labels along the z-axis,
for example function (z) {return (z * 100) + '%'}.
|
| xLabel | String | x | Label on the X axis. |
| yLabel | String | y | Label on the Y axis. |
| zLabel | String | z | Label on the Z axis. |
| filterLabel | String | time | Label for the filter column. |
| legendLabel | String | value | Label for the style description. |
Graph3d supports the following methods.
| Method | Return Type | Description |
|---|---|---|
| animationStart() | none | Start playing the animation. Only applicable when animation data is available. |
| animationStop() | none | Stop playing the animation. Only applicable when animation data is available. |
| getCameraPosition() | An object with parameters horizontal,
vertical and distance |
Returns an object with parameters horizontal,
vertical and distance,
which each one of them is a number, representing the rotation and position
of the camera. |
| redraw() | none | Redraw the graph. Useful after the camera position is changed externally, when data is changed, or when the layout of the webpage changed. |
| setData(data) | none | Replace the data in the Graph3d. |
| setOptions(options) | none | Update options of Graph3d. The provided options will be merged with current options. |
| setSize(width, height) | none | Parameters width and height are strings,
containing a new size for the graph. Size can be provided in pixels
or in percentages. |
| setCameraPosition (pos) | {horizontal: 1.0, vertical: 0.5, distance: 1.7} | Set the rotation and position of the camera. Parameter pos
is an object which contains three parameters: horizontal,
vertical, and distance.
Parameter horizontal is a value in radians and can have any
value (but normally in the range of 0 and 2*Pi).
Parameter vertical is a value in radians between 0 and 0.5*Pi.
Parameter distance is the (normalized) distance from the
camera to the center of the graph, in the range of 0.71 to 5.0. A
larger distance puts the graph further away, making it smaller.
All parameters are optional.
|
Graph3d fires events after the camera position has been changed.
The event can be catched by creating a listener.
Here an example on how to catch a cameraPositionChange event.
function onCameraPositionChange(event) {
alert('The camera position changed to:\n' +
'Horizontal: ' + event.horizontal + '\n' +
'Vertical: ' + event.vertical + '\n' +
'Distance: ' + event.distance);
}
// assuming var graph3d = new vis.Graph3d(document.getElementById('mygraph'));
graph3d.on('cameraPositionChange', onCameraPositionChange);
The following events are available.
| name | Properties | Description |
|---|---|---|
| cameraPositionChange |
|
The camera position changed. Fired after the user modified the camera position
by moving (dragging) the graph, or by zooming (scrolling),
but not after a call to setCameraPosition method.
The new camera position can be retrieved by calling the method
getCameraPosition. |
All code and data are processed and rendered in the browser. No data is sent to any server.