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 and 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
(offering 2 way data binding), or a DataView
(offering 1 way data binding).
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 fill color of the dots or bars. Applicable when using styles dot-size , bar-size , or line . |
dataColor.stroke | string | '#3267D2' | The border color of the dots or bars. Applicable when using styles dot-size or bar-size . |
dataColor.strokeWidth | number | 1 | The line width of dots, bars and lines. Applicable for all styles. |
dotSizeRatio | number | 0.02 | Ratio of the size of the dots with respect to the width of the graph. |
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 drawn in the x-y surface (the bottom of the 3d graph). |
showXAxis | boolean | true | If true, X axis and X axis labels are drawn. |
showYAxis | boolean | true | If true, Y axis and Y axis labels are drawn. |
showZAxis | boolean | true | If true, Z axis and Z axis labels are drawn. |
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. |
showLegend | boolean | none | If true, a legend is drawn for the graph (if the graph type supports it). By default a legend is drawn for dot and dot-color style graphs. |
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 , z , and data
(the source JS object for the point) as an 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 smallest distance
between the data points.
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 | from data | The maximum value for the x-axis. If not set, the largest value for x in the data set is used. |
xMin | number | from data | The minimum value for the x-axis. If not set, the smallest value for x in the data set is used. |
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 smallest distance
between the data points.
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 | from data | The maximum value for the y-axis. If not set, the largest value for y in the data set is used. |
yMin | number | from data | The minimum value for the y-axis. If not set, the smallest value for y in the data set is used. |
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) + '%'} .
|
zMax | number | from data | The maximum value for the z-axis. If not set, the largest value for z in the data set is used. |
zMin | number | from data | The minimum value for the z-axis. If not set, the smallest value for z in the data set is used. |
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.