# Graph3d

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

## Contents

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

## Data Format

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

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

## 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 | Properties | Description
--- | --- | ---
cameraPositionChange | `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. | 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`.

## Data Policy

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