—DESCRIPTION LANGUAGE USER'S GUIDE

 

Introduction

3Space is a new way to apply 3D graphics to a web environment. It is made up of three components:

The 3Space viewer is a web browser plug-in that reads 3D scenes stored in files, plays animations and manages user interactions. 
The 3Space scene description language is an XML-based list of entities which allow you to create complex animations based on a dynamic engine. This engine handlea forces, links and solids to realize amazing animations. Using XML allows you to dynamically edit and interact with the scene from within scripting languages such as JavaScript.   
A proprietary file format for storing the geometric description of complex 3D objects separately from the scene description. This file format is called ZAP. It is very compact, very powerful and also secure. Secure means that ZAP files can be locked to a specific URL and cannot be copied. 

3Space allows you to define a scene as a 3D world containing a set of solids. Each solid will have initial attributes such as its initial position, mass, roughness, stiffness, associated geometry, and links to other objects to build assemblies. 

Forces will be applied to solids to make them move. For instances the gravity force is a force that is oriented vertically and applies to each object. Its intensity on the earth is (0,-9.81,0). Objects will move in the 3D world naturally.

You can control all the parameters of the dynamic world, thus you can simulate reality but you can also set values to produce nonrealistic effects. For instance, setting the stiffness to something higher than 1 will produce energy for each collision between objects. All dimensions are specified in ISO units: meters, seconds, meters/second... Angles are specified in degrees.  The 3D world is defined as follows: x is the horizontal axis, y is the vertical axis, z represents depth, and points toward the viewer.

Geometry is totally independent of the scene description. You can create basic geometric figures such as cubes, spheres, or text without using a geometry file. More complex geometry will be stored in separate ZAP files. ZAP files can be produced from Amapi 3D, 3Space ClipArtist and 3DSMax. Soon TGS will provide a completely new authoring tool to make it easier to create the scene description tags. When a solid object is defined by a geometry file, its position and size are taken from the geometry file. It is not necessary to set the position of the solid.

Interactive behaviors can be applied to the scene using several types of events. User Events are useful for detecting mouse clicks or moves. Collision Events can be used to detect that an object has contacted another one. Proximity Events allow you to react when objects are getting close to a specific object. When an event is triggered, a handler function is called. This handler is a JavaScript function allowing you to react at a very high level. In this type of event, you can edit the XML scene description dynamically or you can also do any HTML updates such as printing the description of the selected object in another HTML frame table.

3Space can really be seen as an HTML extension, with the same geometry files (or without any geometry files if you use basic shapes). You can write an infinity of scripts and behaviors from XML and JavaScript. Building the complex geometry remains a separate process, handled by 3D graphic artists using a 3D modeler such as Amapi 3D. 

 

 

The classical "Hello World" example

As any other language, the first example is to print "Hello World". Here is the html code:

<html>
<head>
</head>
<body bgcolor="#000000">

<xml id="HW" VALIDATEONPARSE="true" ASYNC="false">
<Scene id='scene' xmlns="x-schema:Schemas.xml">
    <Limit id="limit" min="-20 -5 -20" max="20 5 20"/>
    <SolidCamera id="camera" fixed="1" position="0 0 10" targetPoint="0 0 0"/>
    <Solid id="T" fixed="0" position="0 0 0" stiffness="1">
        <GeomText id="Tg" text="Hello World" bold="1" font="Arial" />
        <VolBounding id="Tb"/>
    </Solid>
    <GravityForce id="gravity"/>
</Scene>
</xml>

<OBJECT ID="myobj" 
CLASSID="CLSID:1397AAF0-611B-4a52-B554-036601CFBC67"
CODEBASE="3SPACE.CAB"
STYLE="width:600;height:600" >
<PARAM NAME="XMLID" VALUE="HW">
<PARAM NAME="EXAMINER" VALUE="ON">
</OBJECT>

</body>

</html>

There are two separate parts in this sample. The first one is the XML tag description. Here we use an IE5-specific feature called XML island. It consists of describing the XML tag inside the HTML file. We could also put it in a separate XML file and write something like:

<xml id="HW" VALIDATEONPARSE="true" ASYNC="false" SRC="HelloWorld.xml" />

The second part is the 3Space player OBJECT tag. We define the ActiveX control contained in the 3Space.cab file with the given CLSID and set its parameters. The most important parameter is the XMLID. This is the identifier of the XML tag you want to use. Although this first example is written using IE5 and Windows-specific code, we could write a cross-platform version for both Netscape Navigator and Internet Explorer for Windows and Mac. But this would be confusing for a first example. We will talk about portability issues later on.

The scene contains four objects:

Limit: defines the bounding box of the world. If not set, the player computes the default limits.
SolidCamera: a camera featuring the viewer position and the object position. Again if not set, a camera is added. This camera, behaves like a solid. It means that forces and links can change its position. Also a camera can be linked to another object.  Here, the camera is fixed (fixed="1") and is located on the Z axis looking at the origin.
The Solid tag is mobile (fixed="0"). It is initially located at the origin. It has a stiffness of 1 meaning that no energy is lost when it bounces against another object.
The Solid contains a text geometry GeomText defined by a character string.
The VolBounding tag defines the collision volume for the solid as being the bounding box of the text object.
The GravityForce defines a default gravity field force. All mobile solids will be attracted by this force.  

What happens when you load that file? You see the text falling down and bouncing on the limit of the world repeatedly. Because there is no attenuation and because the stiffness is equal to 1, the text characters bounce forever. You can move around the object using the mouse. 

 

 

The 3Space scene description language

  • XML Syntax

The 3Space scene description language is a very powerful yet simple way to define the aspect of your 3D world. The 3D world is defined as a list of XML elements. Some elements can contain other elements. Each element is uniquely identified by its ID. Elements can contain attributes that specifies their own appearance. An element is defined with the following syntax:

<ElementType id="elementId" attribute="value" > ... </ElementType>

... can be embedded elements or simple HTML text. If the element does not contain other elements you can simplify that syntax:

<ElementType id="elementId" attribute="value" /> 

The 3Space description language uses XML schemas to define and validate the semantic of its XML elements and attributes. If you specify elements incorrectly, the XML parser will complain and fail to load the scene. You can open the schemas.xml file to have a full list of elements and attributes supported by 3Space. 

  • The Scene element 

The first element to define in a 3Space world in the Scene. A Scene is a container for all other elements. It can contain a Limit element to set the boundaries of the world and to define what happens when solids reaches these limits. 

  • Solids, Lights and Camera 

The next type of elements to define is the list of solids. The elements are <SolidXXX>. A solid is the basic 3D object. It has some physical properties like mass, stiffness or roughness. It can move freely in the world, or be static. It contains several other elements: 

The geometry element used to display it. 
The collision volume used to simulate collision between solids.    
Some forces applied to it such as DragForces.
Links used to build assemblies of solids.
Event handlers useful to build interactive worlds. 

The position and orientation in the 3D space where the solid is located when the scene is loaded and the animation starts is given in the position attribute. However, its size is defined by the geometry element. 

Cameras and Lights are also defined as solids but they have some extra attributes defining their specific parameters. 

The scene must contain a camera. This camera defines the position and orientation of the viewer. It also contains a head light that lit other solids even if the scene does not contain other lights.

Lights can be added to the scene to give  more realistic effects. 

  • Specifying the geometry and collision volume of a Solid

A solid can contain a single geometry specified with a <GeomXXX > element.  Geometries can be basic shapes such as a cube, a plan or a sphere, 3D text or geometry files stored in ZAP files. Amapi 3D, 3Space ClipArtist, 3DStudioMax  and 3Space Builder (not available yet) can generate ZAP files. ZAP files are cached in the web browser cache directory and in memory. If the same geometry file is used by several solids, only one instance of this file is loaded in memory. 

A Collision volumes can be specified independently from the geometry by using one of the <VolXXX> elements. Collision detection is a very CPU intensive process so it is often necessary to provide a simple collision shape to avoid slow collision detection. When a solid does not contain a collision volume, it will not collide with other solids. When specifying a VolGeometry element, the ZAP file used for the geometry can be given to define the exact collision volume. However, for performance reasons, it is better to use a simplified version of the geometry by creating a second ZAP file with less details (using the simplification tools).  

  • Forces: the engines of solids

Once solids and their geometry are defined, we can start to move them. But in this dynamic world, you don't move objects by changing their position, you apply forces on solids. Forces are the engines of solids. Like in real life, when you stay seated, you stay on your chair thanks to the gravity force that the earth applies on all solids. When you want to move an object, you drag it or push it. With 3Space it is exactly how you will handle animations of solids. But you can do more than simulate the reality: on the earth, avoiding the effect of the force of gravity is impossible. With 3Space, you can do what you want. Add or remove gravity, set it to be up-side-down, ...

3Space provides several types of forces. Some apply to every solid like the gravity or the wind. Some apply to a single solid like drag forces or shoot forces. Except for shoot forces and explode forces, a force remains active on an object as long as it is not removed from the scene. 

Each time 3Space computes new positions of solids, it applies all the forces of the scene to the solid. Thus if you change the object position by hand instead of using forces, you will break the rules of the dynamic and introduce unpredictable results. 

The effect of forces can be attenuated using damping elements <DampingForce> and <DampingSolid>. This can simulate air resistance by stopping the acceleration.

Attention, the effect of forces will vary depending on solid attributes like mass, stiffness, roughness,... Thus be careful in defining these attributes.

  • Links: building assemblies

Now that we can simulate solid movements using forces, we need to put constraints on some of the movements to obtain animations between objects. The wheel of a car is attached to a link that allows it to turn around one axis and blocks all other movements. Several types of links can be used to build simple assemblies.  

First, let's talk about "degree of freedom": the 3D space and object has 6 degrees of freedom: 3 rotations (one around each axis X,Y and Z) and 3 translations (one along each axis X,Y and Z). Creating links between a reference solid and a target solid means reducing the number of freedom degrees of the target solid relatively to the reference solid. For instance, a Spherical Link avoids all the translations of a solid relatively to a reference point. Thus the target solid can only rotate around the three axis. An Axis Link removes five degrees of freedom leaving only a rotation. Typically, this is how you can define a door.

As in real life, links can be broken. If masses, speed or distances are too big, the physical model will fail to compute the assembly and the link will be broken.

  • Event handling

Several types of events can be used to interact with the scene or solids. User events (UserEvent element) are triggered when a mouse pointer action happens on a solid or on the scene. For instance when the user clicks on a solid or moves the cursor over a solid. Timer Events (TimerEvent elements) are triggered at specified time periods. Collision events (CollideEvent element) are triggered when a solid collides with other solids. Proximity events (ProximityEvent element) are triggered when a solid is closer than a specified distance to the specified solid.

When an event is triggered, the 3Space player calls a JavaScript method: the event handler.This method must be specified by the user in the current HTML document. This event handler can contain any JavaScript code including DHTML effects or edition of the 3Space XML elements. Such an edition makes it possible to change the description of the scene dynamically.

The event handler receives, in its parameter list, the object that triggered the event and the event itself. It can then use the XML DOM features to edit the scene description. Once done, it just needs to tell the player to update the changed objects.