jrtechs
/
jrtechs-vis
mirror of https://github.com/jrtechs/vis.git

<html>
<head>    <title>Graph3d documentation</title>    <link rel='stylesheet' href='css/default.css' type='text/css'>
    <link href="lib/prettify/prettify.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>
<table>    <tr>        <td>Author</td>        <td>Jos de Jong, <a href="http://www.almende.com" target="_blank">Almende B.V.</a></td>    </tr>    <tr>        <td>Webpage</td>        <td><a href="http://almende.github.com/chap-links-library" target="_blank">Chap Links Library</a></td>    </tr>    <tr>        <td>License</td>        <td> <a href="http://www.apache.org/licenses/LICENSE-2.0" target="_blank">Apache License, Version 2.0</a></td>    </tr>
</table>

<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="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>
<pre class="prettyprint lang-html">&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"&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        };
        // Instantiate our graph object.        graph = new links.Graph3d(document.getElementById('mygraph'));
        // Draw our graph with the created data and options        graph.draw(data, options);    }    &lt;/script&gt;    &lt;/head&gt;
&lt;body onload="drawVisualization();"&gt;&lt;div id="mygraph"&gt;&lt;/div&gt;
        &lt;div id="info"&gt;&lt;/div&gt;&lt;/body&gt;&lt;/html&gt;
</pre>

The class name of the Graph3d is <code>links.Graph3d</code><pre class="prettyprint lang-js">var graph = new links.Graph3d(container);</pre>
After being loaded, the graph can be drawn via the function <code>draw()</code>,provided with data and options.<pre class="prettyprint lang-js">graph.draw(data, options);</pre>where data is a <code>DataTable</code>, and options is a name-value map in the JSON format.
<h2 id="Data_Format">Data Format</h2><p>    Graph3d requires a data table with tree to five columns, depending on the chosen style    and animation.
    The first three columns must contain the location coordinates for x-axis,    y-axis, and z-axis.
    The forth column is optional, and can contain a data value.
    The last column (this can be the fourth or fifth column) and can contain    filter values used for animation.</p>
<p>    Note that the column labels can be changed (for example instead of <code>'value'</code>    one can use <code>'Temperature'</code>).</p>

<h3>Definition</h3><p>    The data columns 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>value</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>filtervalue</td>        <td>anytype</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>
<h3>Construction of 3D data</h3><p>    Graph3d supports the following styles to display data in three dimensions:    <code>dot</code>, <code>dot-line</code>, <code>line</code>, <code>grid</code>,    and <code>surface</code>.
    The data table for these styles is constructed as follows.</p>
<pre class="prettyprint lang-js">var data = new google.visualization.DataTable();data.addColumn('number', 'x');data.addColumn('number', 'y');data.addColumn('number', 'z');  // the data value, visualized as a height at the z-axis                                // and by a color.
data.addRow([2.3, 5.2, 102.1]);// ...</pre>

<h3>Construction of 4D data</h3><p>    Graph3d supports the following styles to display data in four dimensions:    <code>dot-color</code>, <code>dot-size</code>.
    The data table for these styles is constructed as follows.</p>
<pre class="prettyprint lang-js">var data = new google.visualization.DataTable();data.addColumn('number', 'x');data.addColumn('number', 'y');data.addColumn('number', 'z');data.addColumn('number', 'value');  // the data value, visualized by a color or size
data.addRow([2.3, 5.2, 102.1, 45.2]);// ...</pre>

<h3>Construction of animation data</h3><p>    If an extra column with filter values is provided in the data table, Graph3d    will use these values for animation.
    The filter values are grouped and each group represents one animation frame.
    When animating, Graph3d loops through the distinct filter values,    and draws all data points which have the current filter value.</p><p>    For example, to create an animation with three frames, first add all datapoints    for the first frame with a filtervalue 1. Next, add the datapoints for the    second frame and give them a filtervalue 2. Last, add the datapoints for the    third frame and give them a filtervalue of 3. Now, when the Graph3d is loaded,    a slider with buttons play/next/previous will be drawn below the graph, where one can loop through the    three frames.</p>
<p>    To create an animation, add an extra column to the data table.    This column may have any type (number, date, string, ...).</p>
<pre class="prettyprint lang-js">var data = new google.visualization.DataTable();data.addColumn('number', 'x');data.addColumn('number', 'y');data.addColumn('number', 'value');data.addColumn('number', 'filtervalue'); // Optional column with filter values for animation
data.addRow([2.3, 5.2, 102.1, 23]);// ...</pre>

<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">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>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>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>
</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>draw(data, options)</td>        <td>none</td>        <td>Loads data, sets the provided options, and draws the 3d graph.</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>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);}
google.visualization.events.addListener(mygraph, '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>
    <tr>        <td>ready</td>        <td>The graph is ready for external method calls.            If you want to interact with the graph, and call methods after you draw it,            you should set up a listener for this event before you call the draw method,            and call them only after the event was fired.</td>        <td>none</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>