Graph3d documentation

Overview

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.

Overview
Loading
Data Format
Configuration Options
Methods
Events
Data Policy

Example

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>

Loading

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).

Data Format

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.

Definition

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.

Configuration Options

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.
backgroundColor	string or Object	'white'	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.stroke	string	'gray'	The color of the chart border, as an HTML color string.
backgroundColor.strokeWidth	number	1	The border width, in pixels.
backgroundColor.fill	string	'white'	The chart fill color, as an HTML color string.
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 2Pi). Parameter `vertical` is a value in radians between 0 and 0.5Pi. 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.
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.

Methods

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 2Pi). Parameter `vertical` is a value in radians between 0 and 0.5Pi. 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.

Events

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	Description	Properties
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`.	`horizontal`: Number. The horizontal angle of the camera. `vertical`: Number. The vertical angle of the camera. `distance`: Number. The distance of the camera to the center of the graph.

Data Policy

All code and data are processed and rendered in the browser. No data is sent to any server.