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>
<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.        graph3d = new vis.Graph3d(document.getElementById('mygraph'));
        // Draw our graph with the created data and options        graph3d.draw(data, options);
        // subscribe to event        graph3d.on("camerapositionchange", function(event) {console.log(event);});    }    &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>vis.Graph3d</code><pre class="prettyprint lang-js">var graph = new vis.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 vis <code>DataSet</code>, and options is a name-value map in the JSON format.
<h2 id="Data_Format">Data Format</h2><p>    Graph3d requires a vis DataSet. JSON objects are added to this DataSet by using the <code>add()</code> function.    These JSON objects have 5 fields, of which 2 are optional. These are described below.
<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>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>


<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>
<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>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);}// 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>