Graph3d documentation

Author Jos de Jong, Almende B.V.
Webpage Chap Links Library
License Apache License, Version 2.0

Contents

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.

The graph works smooth on any modern browser for data up to 10.000 points.

The Graph is developed as a Google Visualization Chart in javascript. It runs on all modern browsers without additional requirements. Graph is tested on Firefox 3.6+, Safari 5.0+, Chrome 6.0+, Opera 10.6+, Internet Explorer 9+.

To get started with Graph3d, download graph3d.zip, and unzip the contents in a subfolder graph3d on your site. Examples can be found in the examples directory. The possiblities of Graph3d can be tested on the playground.

Example

Here a graph example. Click and drag to move the graph, scroll to zoom the graph.

<!DOCTYPE HTML PUBLIC
     "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>Graph 3D demo</title>

    <style>
      body {font: 10pt arial;}
    </style>

    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript" src="../graph3d.js"></script>

    <script type="text/javascript">
      var data = null;
      var graph = null;

      google.load("visualization", "1");

      // Set callback to run when API is loaded
      google.setOnLoadCallback(drawVisualization);

      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.
        data = new google.visualization.DataTable();
        data.addColumn('number', 'x');
        data.addColumn('number', 'y');
        data.addColumn('number', 'value');

        // create some nice looking data with sin/cos
        var steps = 25;  // number of datapoints will be steps*steps
        var axisMax = 314;
        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.addRow([x, y, value]);
          }
        }

        // specify options
        options = {width:  "400px",
                   height: "400px",
                   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);
      }
   </script>
  </head>

  <body>
    <div id="mygraph"></div>
  </body>
</html>

Loading

Graph3d is no built-in visualization of Google. To load Graph3d, download the file graph3d.zip, and unzip it in your html page such that the files are located in a subfolder graph3d. Include the google API and the following files in the head of your html code:

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript" src="graph/graph3d.js"></script>

The google visualization needs to be loaded in order to use DataTable.

google.load("visualization", "1");
google.setOnLoadCallback(drawVisualization);
function drawVisualization() {
  // load data and create the graph here
}
The class name of the Graph3d is links.Graph3d
var graph = new links.Graph3d(container);
After being loaded, the graph can be drawn via the function draw(), provided with data and options.
graph.draw(data, options);
where data is a DataTable, and options is a name-value map in the JSON format.

Data Format

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.

Note that the column labels can be changed (for example instead of 'value' one can use 'Temperature').

Definition

The data columns 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.
value number no The data value, required for graph styles dot-color and dot-size.
filtervalue anytype no Filter values used for the animation. This column may have any type, such as a number, string, or Date.

Construction of 3D data

Graph3d supports the following styles to display data in three dimensions: dot, dot-line, line, grid, and surface. The data table for these styles is constructed as follows.

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]);
// ...

Construction of 4D data

Graph3d supports the following styles to display data in four dimensions: dot-color, dot-size. The data table for these styles is constructed as follows.

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]);
// ...

Construction of animation data

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.

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.

To create an animation, add an extra column to the data table. This column may have any type (number, date, string, ...).

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]);
// ...

Configuration Options

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

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

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.
draw(data, options) none Loads data, sets the provided options, and draws the 3d graph.
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.
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);
}

google.visualization.events.addListener(mygraph, '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.
ready 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. none

Data Policy

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