docs/graph3d.html

<html>

<head>
  <title>vis.js | graph3d documentation</title>

  <link href='css/prettify.css' type='text/css' rel='stylesheet'>
  <link href='css/style.css' type='text/css' rel='stylesheet'>

  <script type="text/javascript" src="lib/prettify/prettify.js"></script>
</head>

<body onload="prettyPrint();">
<div id="container">

<h1>Graph3d documentation</h1>

<h2 id="Overview">Overview</h2>
<p>
  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.
</p>
<p>
  Graph3d uses <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Canvas">HTML canvas</a>
  to render graphs, and can render up to a few thousands of data points smoothly.
</p>

<h2 id="Contents">Contents</h2>
<ul>
  <li><a href="#Overview">Overview</a></li>
  <li><a href="#Loading">Loading</a></li>
  <li><a href="#Data_Format">Data Format</a></li>
  <li><a href="#Configuration_Options">Configuration Options</a></li>
  <li><a href="#Methods">Methods</a></li>
  <li><a href="#Events">Events</a></li>
  <li><a href="#Data_Policy">Data Policy</a></li>
</ul>

<h2 id="Example">Example</h2>
<p>
  The following code shows how to create a Graph3d and provide it with data.
  More examples can be found in the <a href="../examples">examples</a> directory.
</p>

<pre class="prettyprint lang-html">
&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;Graph 3D demo&lt;/title&gt;

  &lt;style&gt;
    body {font: 10pt arial;}
  &lt;/style&gt;

  &lt;script type="text/javascript" src="../../dist/vis.js"&gt;&lt;/script&gt;

  &lt;script type="text/javascript"&gt;
  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 &lt; axisMax; x+=axisStep) {
      for (var y = 0; y &lt; 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);
  }
  &lt;/script&gt;
&lt;/head&gt;

&lt;body onload="drawVisualization();"&gt;
  &lt;div id="mygraph"&gt;&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;

</pre>


<h2 id="Loading">Loading</h2>

<p>
  The class name of the Graph3d is <code>vis.Graph3d</code>.
  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 <code>DataSet</code> or an <code>Array</code>, described in
  section <a href="#Data_Format">Data Format</a>.
  Options is a name-value map in the JSON format. The available options
  are described in section <a href="#Configuration_Options">Configuration Options</a>.
</p>
<pre class="prettyprint lang-js">var graph = new vis.Graph3d(container [, data] [, options]);</pre>

<p>
  Data and options can be set or changed later on using the functions
  <code>Graph3d.setData(data)</code> and <code>Graph3d.setOptions(options)</code>.
</p>

<h2 id="Data_Format">Data Format</h2>
<p>
  Graph3d can load data from an <code>Array</code>, a <code>DataSet</code> or a <code>DataView</code>.
  JSON objects are added to this DataSet by using the <code>add()</code> function.
  Data points must have properties <code>x</code>, <code>y</code>, and <code>z</code>,
  and can optionally have a property <code>style</code> and <code>filter</code>.

<h3>Definition</h3>
<p>
  The DataSet JSON objects are defined as:
</p>

<table>
  <tr>
    <th>Name</th>
    <th>Type</th>
    <th>Required</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>x</td>
    <td>number</td>
    <td>yes</td>
    <td>Location on the x-axis.</td>
  </tr>
  <tr>
    <td>y</td>
    <td>number</td>
    <td>yes</td>
    <td>Location on the y-axis.</td>
  </tr>
  <tr>
    <td>z</td>
    <td>number</td>
    <td>yes</td>
    <td>Location on the z-axis.</td>
  </tr>
  <tr>
    <td>style</td>
    <td>number</td>
    <td>no</td>
    <td>The data value, required for graph styles <code>dot-color</code> and
      <code>dot-size</code>.
    </td>
  </tr>
  <tr>
    <td>filter</td>
    <td>*</td>
    <td>no</td>
    <td>Filter values used for the animation.
      This column may have any type, such as a number, string, or Date.</td>
  </tr>
</table>


<h2 id="Configuration_Options">Configuration Options</h2>

<p>
  Options can be used to customize the graph. Options are defined as a JSON object.
  All options are optional.
</p>

<pre class="prettyprint lang-js">
var options = {
    width:  '100%',
    height: '400px',
    style: 'surface'
};
</pre>

<p>
  The following options are available.
</p>

<table>
<tr>
  <th>Name</th>
  <th>Type</th>
  <th>Default</th>
  <th>Description</th>
</tr>

<tr>
  <td>animationInterval</td>
  <td>number</td>
  <td>1000</td>
  <td>The animation interval in milliseconds. This determines how fast
    the animation runs.</td>
</tr>
<tr>
  <td>animationPreload</td>
  <td>boolean</td>
  <td>false</td>
  <td>If false, the animation frames are loaded as soon as they are requested.
    if <code>animationPreload</code> 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.</td>
</tr>
<tr>
  <td>animationAutoStart</td>
  <td>boolean</td>
  <td>false</td>
  <td>If true, the animation starts playing automatically after the graph
    is created.</td>
</tr>

<tr>
  <td>backgroundColor</td>
  <td>string or Object</td>
  <td>'white'</td>
  <td>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.</td>
</tr>
<tr>
  <td>backgroundColor.stroke</td>
  <td>string</td>
  <td>'gray'</td>
  <td>The color of the chart border, as an HTML color string.</td>
</tr>
<tr>
  <td>backgroundColor.strokeWidth</td>
  <td>number</td>
  <td>1</td>
  <td>The border width, in pixels.</td>
</tr>
<tr>
  <td>backgroundColor.fill</td>
  <td>string</td>
  <td>'white'</td>
  <td>The chart fill color, as an HTML color string.</td>
</tr>

<tr>
  <td>cameraPosition</td>
  <td>Object</td>
  <td>{horizontal:&nbsp;1.0, vertical:&nbsp;0.5, distance:&nbsp;1.7}</td>
  <td>Set the initial rotation and position of the camera.
    The object <code>cameraPosition</code> contains three parameters:
    <code>horizontal</code>, <code>vertical</code>, and <code>distance</code>.
    Parameter <code>horizontal</code> is a value in radians and can have any
    value (but normally in the range of 0 and 2*Pi).
    Parameter <code>vertical</code> is a value in radians between 0 and 0.5*Pi.
    Parameter <code>distance</code> 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.
</tr>

<tr>
  <td>height</td>
  <td>string</td>
  <td>'400px'</td>
  <td>The height of the graph in pixels or as a percentage.</td>
</tr>

<tr>
  <td>keepAspectRatio</td>
  <td>boolean</td>
  <td>true</td>
  <td>If <code>keepAspectRatio</code> 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.</td>
</tr>

<tr>
  <td>showAnimationControls</td>
  <td>boolean</td>
  <td>true</td>
  <td>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.</td>
</tr>
<tr>
  <td>showGrid</td>
  <td>boolean</td>
  <td>true</td>
  <td>If true, grid lines are draw in the x-y surface (the bottom of the 3d
    graph).</td>
</tr>
<tr>
  <td>showPerspective</td>
  <td>boolean</td>
  <td>true</td>
  <td>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.
  </td>
</tr>
<tr>
  <td>showShadow</td>
  <td>boolean</td>
  <td>false</td>
  <td>Show shadow on the graph.</td>
</tr>
<tr>
  <td>style</td>
  <td>string</td>
  <td>'dot'</td>
  <td>The style of the 3d graph. Available styles:
    <code>bar</code>,
    <code>bar-color</code>,
    <code>bar-size</code>,
    <code>dot</code>,
    <code>dot-line</code>,
    <code>dot-color</code>,
    <code>dot-size</code>,
    <code>line</code>,
    <code>grid</code>,
    or <code>surface</code></td>
</tr>

<tr>
  <td>tooltip</td>
  <td>boolean | function</td>
  <td>false</td>
  <td>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 <code>tooltip</code>. In this case the function is called
    with an object containing parameters <code>x</code>,
    <code>y</code>, and <code>z</code> argument,
    and must return a string which may contain HTML.
  </td>
</tr>

<tr>
  <td>valueMax</td>
  <td>number</td>
  <td>none</td>
  <td>The maximum value for the value-axis. Only available in combination
    with the styles <code>dot-color</code> and <code>dot-size</code>.</td>
</tr>
<tr>
  <td>valueMin</td>
  <td>number</td>
  <td>none</td>
  <td>The minimum value for the value-axis. Only available in combination
    with the styles <code>dot-color</code> and <code>dot-size</code>.</td>
</tr>
<tr>
  <td>verticalRatio</td>
  <td>number</td>
  <td>0.5</td>
  <td>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.</td>
</tr>

<tr>
  <td>width</td>
  <td>string</td>
  <td>'400px'</td>
  <td>The width of the graph in pixels or as a percentage.</td>
</tr>

<tr>
  <td>xBarWidth</td>
  <td>number</td>
  <td>none</td>
  <td>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 <code>'bar'</code> and <code>'bar-color'</code>.</td>
</tr>

<tr>
  <td>xCenter</td>
  <td>string</td>
  <td>'55%'</td>
  <td>The horizontal center position of the graph, as a percentage or in
    pixels.</td>
</tr>
<tr>
  <td>xMax</td>
  <td>number</td>
  <td>none</td>
  <td>The maximum value for the x-axis.</td>
</tr>
<tr>
  <td>xMin</td>
  <td>number</td>
  <td>none</td>
  <td>The minimum value for the x-axis.</td>
</tr>
<tr>
  <td>xStep</td>
  <td>number</td>
  <td>none</td>
  <td>Step size for the grid on the x-axis.</td>
</tr>
<tr>
  <td>xValueLabel</td>
  <td>function</td>
  <td>none</td>
  <td>A function for custom formatting of the labels along the x-axis,
    for example <code>function (x) {return (x * 100) + '%'}</code>.
  </td>
</tr>

<tr>
  <td>yBarWidth</td>
  <td>number</td>
  <td>none</td>
  <td>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 <code>'bar'</code> and <code>'bar-color'</code>.</td>
</tr>

<tr>
  <td>yCenter</td>
  <td>string</td>
  <td>'45%'</td>
  <td>The vertical center position of the graph, as a percentage or in
    pixels.</td>
</tr>
<tr>
  <td>yMax</td>
  <td>number</td>
  <td>none</td>
  <td>The maximum value for the y-axis.</td>
</tr>
<tr>
  <td>yMin</td>
  <td>number</td>
  <td>none</td>
  <td>The minimum value for the y-axis.</td>
</tr>
<tr>
  <td>yStep</td>
  <td>number</td>
  <td>none</td>
  <td>Step size for the grid on the y-axis.</td>
</tr>
<tr>
  <td>yValueLabel</td>
  <td>function</td>
  <td>none</td>
  <td>A function for custom formatting of the labels along the y-axis,
    for example <code>function (y) {return (y * 100) + '%'}</code>.
  </td>
</tr>

<tr>
  <td>zMin</td>
  <td>number</td>
  <td>none</td>
  <td>The minimum value for the z-axis.</td>
</tr>
<tr>
  <td>zMax</td>
  <td>number</td>
  <td>none</td>
  <td>The maximum value for the z-axis.</td>
</tr>
<tr>
  <td>zStep</td>
  <td>number</td>
  <td>none</td>
  <td>Step size for the grid on the z-axis.</td>
</tr>
<tr>
  <td>zValueLabel</td>
  <td>function</td>
  <td>none</td>
  <td>A function for custom formatting of the labels along the z-axis,
    for example <code>function (z) {return (z * 100) + '%'}</code>.
  </td>
</tr>

<tr>
  <td>xLabel</td>
  <td>String</td>
  <td>x</td>
  <td>Label on the X axis.</td>
</tr>
<tr>
  <td>yLabel</td>
  <td>String</td>
  <td>y</td>
  <td>Label on the Y axis.</td>
</tr>
<tr>
  <td>zLabel</td>
  <td>String</td>
  <td>z</td>
  <td>Label on the Z axis.</td>
</tr>
<tr>
  <td>filterLabel</td>
  <td>String</td>
  <td>time</td>
  <td>Label for the filter column.</td>
</tr>
<tr>
  <td>legendLabel</td>
  <td>String</td>
  <td>value</td>
  <td>Label for the style description.</td>
</tr>
</table>


<h2 id="Methods">Methods</h2>
<p>
  Graph3d supports the following methods.
</p>

<table>
  <tr>
    <th>Method</th>
    <th>Return Type</th>
    <th>Description</th>
  </tr>

  <tr>
    <td>animationStart()</td>
    <td>none</td>
    <td>Start playing the animation.
      Only applicable when animation data is available.</td>
  </tr>

  <tr>
    <td>animationStop()</td>
    <td>none</td>
    <td>Stop playing the animation.
      Only applicable when animation data is available.</td>
  </tr>

  <tr>
    <td>getCameraPosition()</td>
    <td>An object with parameters <code>horizontal</code>,
      <code>vertical</code> and <code>distance</code></td>
    <td>Returns an object with parameters <code>horizontal</code>,
      <code>vertical</code> and <code>distance</code>,
      which each one of them is a number, representing the rotation and position
      of the camera.</td>
  </tr>

  <tr>
    <td>redraw()</td>
    <td>none</td>
    <td>Redraw the graph. Useful after the camera position is changed externally,
      when data is changed, or when the layout of the webpage changed.</td>
  </tr>

  <tr>
    <td>setData(data)</td>
    <td>none</td>
    <td>Replace the data in the Graph3d.</td>
  </tr>

  <tr>
    <td>setOptions(options)</td>
    <td>none</td>
    <td>Update options of Graph3d.
      The provided options will be merged with current options.</td>
  </tr>

  <tr>
    <td>setSize(width, height)</td>
    <td>none</td>
    <td>Parameters <code>width</code> and <code>height</code> are strings,
      containing a new size for the graph. Size can be provided in pixels
      or in percentages.</td>
  </tr>

  <tr>
    <td>setCameraPosition (pos)</td>
    <td>{horizontal:&nbsp;1.0, vertical:&nbsp;0.5, distance:&nbsp;1.7}</td>
    <td>Set the rotation and position of the camera. Parameter <code>pos</code>
      is an object which contains three parameters: <code>horizontal</code>,
      <code>vertical</code>, and <code>distance</code>.
      Parameter <code>horizontal</code> is a value in radians and can have any
      value (but normally in the range of 0 and 2*Pi).
      Parameter <code>vertical</code> is a value in radians between 0 and 0.5*Pi.
      Parameter <code>distance</code> 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.
    </td>
  </tr>

</table>

<h2 id="Events">Events</h2>
<p>
  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 <code>cameraPositionChange</code> event.
</p>

<pre class="prettyprint lang-js">
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);
</pre>

<p>
  The following events are available.
</p>

<table>
  <col width="10%">
  <col width="60%">
  <col width="30%">

  <tr>
    <th>name</th>
    <th>Description</th>
    <th>Properties</th>
  </tr>

  <tr>
    <td>cameraPositionChange</td>
    <td>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 <code>setCameraPosition</code> method.
      The new camera position can be retrieved by calling the method
      <code>getCameraPosition</code>.</td>
    <td>
      <ul>
        <li><code>horizontal</code>: Number. The horizontal angle of the camera.</li>
        <li><code>vertical</code>: Number. The vertical angle of the camera.</li>
        <li><code>distance</code>: Number. The distance of the camera to the center of the graph.</li>
      </ul>
    </td>
  </tr>
</table>

<h2 id="Data_Policy">Data Policy</h2>
<p>
  All code and data are processed and rendered in the browser. No data is sent to any server.
</p>

</div>
</body>
</html>