scene3d is 3D interactive graphics jQuery plugin based on HTML5 and X3DOM. It allows rapid and effortless prototyping of 3D scenes for web.
Your graphics "scene" will be placed inside a <div> element. You can place it anywhere on the page and make it any size. However, inside the scene, the <div> position and dimensions are not applicable any more. The scene lives inside its own world, with its own coordinate system and its own units of measurements.
Root of a 3D scene is always in the centre at the position x=0, y=0, z=0. An object position is defined by (x y z) coordinates relative to the main scene. Forget about pixels - distances are measured in meters ( 1m=39.3” ) and angles in radians ( =degrees * 3.14/180 ) )
Like in a movie set, the scene is viewed by a "camera" which you can place anywhere in the scene (see the picture). If not explicitly defined, camera will be placed 10m up the z axis at the position (0 0 10) which will be your viewpoint of the scene.
In addition to the position, you can also specify camera rotation. Since this is a bit more advanced topic, if interested, you can find more about it in the advanced topics section.
The following table shows the list of available options:
|background||'#ffffff'||RGB hex string|
|backurl||'''||path to background image|
|fontFamily||'Sans'||font family name|
|fontSize||0.5||relative font size|
|height||'150px'||canvas height in pixels|
|id||'x3dElement'||x3d DOM id|
|sceneAnimation||false||realtime scene rotation (heavy on CPU)|
|showLog||false||show x3dom log (for debugging)|
|showStat||false||show realtime graphics statistics|
|ViewpointPosition||'0 0 10'||camera position relative to (0,0,0).|
Default viewpoint position is (0 0 10) meaning that the camera is placed on the same level as x and y axis and 10m on z axis or backwards/south from the 0,0,0 point.
|ViewpointOrientation||'0 0 0 1'||'x y z angle' The first three values specify a normalized rotation axis vector about which the rotation takes place. The fourth value specifies the amount of right-handed rotation about that axis in radians.|
Note: More about this you can find in the advanced topics section.
Graphics objects can be created by calling number of methods and specifying objects attributes as shown in the following table:
with default options
||Draw a box with selected properties. If property is omitted or none is specified, it will use defaults. Example:|
|addCone||Draw a cone with selected properties. If property is omitted or none is specified, it will use defaults. Example:|
|addCylinder||Draw a cylinder with selected properties. If property is omitted or none is specified, it will use defaults. Example:|
A graph consists of set of vertices and edges connecting them. It is drawn as spheres and lines connecting them.
The graph data structure is a JSON object.
Draws a line with selected properties from (x1,y1,z1) to (x2,y2,z2). If property is omitted or none is specified, it will use defaults. For example, to draw a coordinate system one can use:
|addSphere||Draw a sphere with selected properties. If property is omitted or none is specified, it will use defaults. Example:
|addText||Draw a text with selected properties. If property is omitted or none is specified, it will use defaults.|
|removeShape||Removes shape of a given id from the canvas
|importX3D||Imports x3d object to your canvas. This allows you to have an reusable library of different shapes and drawings.
Each shape can be initialized with two more options: click handler name and HTML5 "data-" attribute. The "data-" attribute can contain any string, and can have any name - as long as starts with "data-". For example, we can attach a click event to a sphere:
Please note that the attribute 'data-description' must be quoted. To retrieve the content of this attribute, simply use jQuery .data() method. If you wish to attach more complex information, a database record for example, you can retrieve a sphere id ($(gObj).attr('id')) and make an ajax call to your database to retrieve and display the desired record.
A graph consists of set of nodes and edges connecting them. In the simplest form, a graph can be created with a single command. The following example shows names (nodes) of Hollywood actors linked by movies (edges) they were acting together:
The information about nodes (actors) and edges (movies) is obtained from a variable called myGraph. This variable is a JSON object that can be hard coded, generated by a script, or loaded from a file or a database via an ajax call.
Notice that each node has an unique id which is used to define edges between nodes. This JSON object can be saved as a actors.json file and drawn with a few lines of code:
The following table shows all JSON attributes recognized by drawGraph function. The minimum attributes required is "id" for nodes and "source" and "target" ids for edges. Labels, coordinates, colors etc. are optional and if not given, it will be assigned automatically.
For function to work properly the JSON structure must have a valid format. If not familiar with JSON, you can use online tools to generate, or just to validate your JSON data.
The minimal information you need for a graph is just to specify where the graph data is. However, addGraph method accepts a rich set of options:
The following options: radius, linewidth, color, fontFamily, fontColor, fontSize will be ignored if the same attributes exists in your JSON object. It will be used as a fallback data if a node or a edge does not have specific requirement for a color, font, etc...
It is possible to draw three types of layouts:
Graphs can be enriched with additional data by using HTML5 "data-" attribute. Data can be displayed to the user by attaching click handlers to nodes or edges. In the following example we added attributes "data-bio" to nodes and "data-movie" to edges. As specified in HTML5 any attribute that starts with "data-" can carry data and can be included in a graph.
Only few lines of code is needed to display this graph:
If you wish to retrieve more complex information, a database record for example, you can use "data-" or "id" attribute as a database key and make an ajax call to your database to fetch a desired record.
In addition to the position (as described in 1.1. Graphics Scene section), you can specify the camera rotation by four values: (x y z angle). This settings is called ViewpointOrientation and corresponds to a SFRotation field in the X3D standard specification.
The first three values specify a normalized (having values between 0 and 1) rotation axis vector about which the rotation takes place. The fourth value specifies the amount of rotation.
Imagine someone taking a "selfie" as shown in the picture. The center of a local coordinate system (0 0 0) can be placed in the root of the right arm that will act as an axis vector about which hand can rotate the camera. Since we are interested in the vector direction and the rotation angle only, the length of this vector is not important. We'll use the length of 1 so the coordinates of the vector's endpoint will be our normalized values of the rotation axis.
Finally, the rotation angle is determined by rotation of the right hand holding the camera.
For example, if you wish to rotate camera 45 degrees (0.785 radians) around x axis only, the rotation will be defined as (1 0 0 0.785). Similarly, the rotation around y and z axes will be (0 1 0 0.785) and (0 0 1 0.785) respectively.
There is even more than it meets the eye. For example, the system gets its final rotation axis by comparing coordinates of the local axis with the origin of it's parent coordinate system, but this is beyond the scope of this manual.
All you need is two files. Simply right click on the link below and "Save as"
If you dont't have the latest jQuery and x3dom, you can get them here: