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 or object | no |
The data value, required for graph styles dot-color and
dot-size . If an object is supplied, this allows styling
on a per-point basis. The object should be in the form of
{ "fill":"red", "stroke":"#999" } . For graph styles
bar , dot , dot-line ,
grid , and surface this column can be used
to specify data values, but no per-point styling is supported yet.
|
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 | Object | 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 | Object | Set the initial rotation and position of the camera. All parameters are optional. |
cameraPosition.horizontal | number | 1.0 | Value in radians. It can have any value, but is normally in the range of 0 and 2*Pi. |
cameraPosition.vertical | number | 0.5 | Value in radians between 0 and 0.5*Pi. |
cameraPosition.distance | number | 1.7 | 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. |
dataColor | string or object | Object |
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. |
colormap | array, function | none |
When colormap is set, the surface will be colored
according to the colors provided. If it is a function it will be
called with normalized values between 0 and 1 and must return the
RGB values as object with keys {r, g, b} . If it is an
object it must have the hue key, it will then be
converted into an array according to the following hue values
provided:
|
surfaceColors.hue.start | number | None | The hue value of the maximum z value of the surface. Hue is in degrees with a period of 360. |
surfaceColors.hue.end | number | None | The hue value of the minimum z value of the surface. Hue is in degrees with a period of 360. |
surfaceColors.hue.saturation | number | None | Saturation value of all hue colors. Saturation is in percent (0 to 100). |
surfaceColors.hue.brightness | number | None | Brightness value of all hue colors. Brightness is in percent (0 to 100). |
surfaceColors.hue.colorStops | number | None | How many color stops does the hue go through between hue start and hue end. |
surfaceColors | boolean, array or object | none |
This option is deprecated and may be removed in a future version.
Please use the colormap option instead. Note that the
colormap option uses the reverse array ordering
(running from vMin to vMax).
|
dotSizeRatio | number | 0.02 | Ratio of the size of the dots with respect to the width of the graph. |
dotSizeMinFraction | number | 0.5 |
Size of minimum-value dot as a fraction of dotSizeRatio. Applicable
when using style dot-size .
|
dotSizeMaxFraction | number | 2.5 |
Size of maximum-value dot as a fraction of dotSizeRatio. Applicable
when using style dot-size .
|
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 width.
|
onclick | function | none |
This option is deprecated and may be removed in a future version.
Please use graph.on('click', handler); instead. See
Events for further details.
|
rotateAxisLabels | boolean | true |
If rotateAxisLabels is true, the x-axis and y-axis
labels will rotate with the graph. Useful with long label values.
|
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. |
showGrayBottom | boolean | false | If true, draw the bottom side of the surface in gray. |
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. |
showSurfaceGrid | boolean | true |
If true, grid lines are drawn on the surface of the graph itself
(only effective if style: 'surface' .
|
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.
|
tooltipDelay | number | 300 | The delay time (in ms) for the tooltip to appear when the mouse cursor hovers over an x-y grid tile. |
tooltipStyle | Object | Object | Tooltip style properties. Provided properties will be merged with the default object. |
tooltipStyle.content.padding | string | '10px' | |
tooltipStyle.content.border | string | '1px solid #4d4d4d' | |
tooltipStyle.content.color | string | '#1a1a1a' | |
tooltipStyle.content.background | string | 'rgba(255,255,255,0.7)' | |
tooltipStyle.content.borderRadius | string | '2px' | |
tooltipStyle.content.boxShadow | string | '5px 5px 10px rgba(128,128,128,0.5)' | |
tooltipStyle.line.height | string | '40px' | |
tooltipStyle.line.width | string | '0' | |
tooltipStyle.line.borderLeft | string | '1px solid #4d4d4d' | |
tooltipStyle.dot.height | string | '0' | |
tooltipStyle.dot.width | string | '0' | |
tooltipStyle.dot.border | string | '5px solid #4d4d4d' | |
tooltipStyle.dot.borderRadius | string | '5px' | |
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 .
|
click |
|
Event handler for a click event with signature
function onclick(point) .Parameter point contains data for the nearest graph
element relative to the click in the line of sight.
|
All code and data are processed and rendered in the browser. No data is sent to any server.