| Author | +Jos de Jong, Almende B.V. | +
| Webpage | +Chap Links Library | +
| License | +Apache License, Version 2.0 | +
+ 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. +
+ ++ 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>
+
+
+
+
+ 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.
+
++ 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').
+
+ 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. | +
+ 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]);
+// ...
+
+
+
+
+ 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]);
+// ...
+
+
+
++ 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]);
+// ...
+
+
+
++ 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 | +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, 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. | +
+ 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.
+ |
+
+ 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. |
+
+
|
+
| 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 | +
+ All code and data are processed and rendered in the browser. No data is sent to any server. +
+ +