Status: Draft William Denniss Version: 1 Tank Software Revision: 13 March 2004 XML ODE Data Interchange Format - XODE Status of this Memo This document specifies a proposed standard for the ODE community. Distribution of this memo is unlimited. Copyright Notice Copyright (C) William Denniss (2004). Abstract This document describes an XML format which can be used as a common ODE storage and interchange format. 1 Introduction 1.1 About ODE Open Dynamics Engine (ODE) is a "free, industrial quality library for simulating articulated rigid body dynamics - for example ground vehicles, legged creatures, and moving objects in VR environments. It is fast, flexible, robust and platform independent, with advanced joints, contact with friction, and built-in collision detection". A typical ODE scene hierarchy consists of physics, collision and display objects. Physics and collision is typically handled by ODE with the graphics potentially using any number of display libraries (three dimensional or otherwise). This scene structure is commonly used in both graphical ODE editing applications, and software using ODE. 1.2 Purpose The goal of this standard is to provide a method of storing an ODE scene, representing the physics, collision objects and to do so in a generic, interoperable and extensible manner. It is not a generic physics scene notation, but rather is ODE specific so as to fully represent an ODE scene without compromise or addition. Like ODE, there is no binding to a particular display library, although it is possible to store display-specific (and any other) information though the use of extensions. 1.3 Requirements The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant." 1.4 Terminology importer/parser/reader Code which can read the XODE format into some internal representation for manipulation, display or otherwise. exporter/writer Code that can write an XODE formatted file from some internal representation. collision system A mathematical engine which detects when two objects intersect and generates an appropriate response physics engine A mathematical engine that has set of physical rules for example gravity or friction that it applies to objects in it's system graphical engine A programming library used to display objects to the user, for example a 3D OpenGL scenegraph. world A container for physics body objects body A physics object with such properties as mass collision geom A geometry describing a shape that is used for collision group A collection of objects organised into a bag for organisational reasons. joint A relationship between two bodies that connects them together in some way. ODE object an object which exits in ode. For example body and geom container a collection of ODE objects element an identified component of a document, consisting of a start-tag, content and an end-tag attribute an element parameter consisting of a name and value. 2 Elements The elements of XODE are classified into two groups. Containers and Objects (some elements are classified as both) which share common properties. All Containers and Objects may define a name attribute, which is a unique textual identifier and may contain elements (further defined in section 2.4). 2.1 ODE Objects ODE objects are entities which have a direct meaning in ODE. These are: All ODE objects may contain a attribute which. If this attribute is not present, the transform of the objects parent is used. 2.1.1 Representation for the ODE body object (used in the physics engine). It has the following properties (with examples): Attributes: enabled="false" gravitymode="1" Elements: (see below) The Mass element can be represented in one of two ways - 'shape' or 'struct'. The 'shape' representation is a complex element which describes the density, shape and transform of the object which is used by ODE to build the mass matrix. Valid shapes are cylinder, sphere, box and cappedCylinder whose attributes are specified in section 2.1.2 The mass element can either have a 'density' or 'total' attribute which determines the relevent ODE method to use. The element is optional. Alternativly, ODE's mass struct can be stored directly. The mass struct includes the center of gravity (as a vector), inertia tensor (as a 3x3 matrix) and total mass. 2.1.2 Representation for geometry objects (used in the collision detection engine). It is usually attached to a body (as a child node) but this doesn't have to be the case if representing a static - immovable object (such as a wall). Geometry objects must contain an element that represents the shape of the geom and contains its values. Listed below are those elements and their expected attributes. In each case, the data type for values is a float with the exception of 'trimesh': sizex, sizey, sizez radius, length radius, length radius, length a, b, c, d length radius vertices, indices Examples: Geom Box: ... Geom Cylinder: ... The 'trimesh' shape is unique as a 3D mesh must be defined. The mesh is an indexed triangle array. The vertex data is stored as 'x', 'y', and 'z' attributes of the vertex '' element. The indicies of the triangles are stored as 'ia', 'ib', and 'ic' attributes of the element. Example: The vertex 'v' element may also contain a fourth attribute 'e' (short for extension). That element can contain any data. Unlike support of the element, support of this element is OPTIONAL and it should be used carefully. 2.1.3 Represents a joint in ODE. Joint objects must contain an element which represents the type of joint and stores the properties specific to that joint (such as the axes). Below is a list of valid joint types: "amotor" "ball" "fixed" "hinge" "hinge2" "slider" "universal" Joints link two bodies together. The first body is assumed to be the parent of the joint unless specified with the "link1" element. Eg. The second body is specified by the "link2" element, eg: Some joints have one or more axes which is defined like so: The number of axes per joint type is fixed at the following numbers: amotor 3 ball 0 fixed 0 hinge 1 hinge2 2 slider 1 universal 2 A joint MUST have the exact number of required axes. 2.2 Containers Containers are groups of ODE objects. Some of the containers have a representation within ODE itself, but not all. The containers are: Each container can store the following objects: In addition, there are two special containers with different goals: is a special form of container which can only store objects. is a special form of container which can only store containers All containers (including ) can have the transform attribute. If they do not, then the transform object of that containers parent is used (in the case of , this is the origin). This transform is relative to its parent transform. The attribute is further defined below. 2.2.1 The root node of the file of which there can only be one. It is a container for nodes. The version of XODE that is being used MUST be specified using the 'version' attribute. Optionally, a name may also be specified. Like all XODE containers and objects, it may contain extensions. 2.2.2 In addition to its properties as a container, the element has special significance as it represents an ODE world. Implementations MUST support this container. Additionally, this element specified how all transforms of objects belonging to this container will be represented with the 'transformstyle' attribute (see section 2.3 for details). 2.2.3 Unlike the other containers, group has no actual meaning in ODE. This is also part of its usefulness as it can be used to structure data in a way which does not directly affect the ODE representation. Importers MUST be able to read the group container and it's contents and it is RECOMMENDED that exporters preserve and export the group structure. 2.2.4 and The body and geom elements are both a container and an object. Like the other containers, it can store objects (including other bodies and geoms) whose transforms are relative to its own. 2.3 Transform Attribute Transforms can be defined in one of two ways, although the same method must be used throughout a given . They are always considered to be relative to their parent unless otherwise specified by setting the "absolute" attribute to 'true'. Matrix Transform Style: The 4x4 transform matrix is represented by a . It contains sixteen attributes numbered d_1_1 to d_4_4. Example: Vector Transform Style: Three vectors representing the position, rotation and scale. Example: By default, the Matrix transform style is assumed. To manually specify either transform style, the "transformstyle" attribute of must be specified. It's value is either 'matrix' for the Matrix Transform Style, or 'vector' for the Vector Transform Style Importers MUST be able to read both styles, and SHOULD be able to export either style. Rotational values are the angle that the object is rotated on the x,z and z axes. Note that x, y and z are commonly referred to as roll, pitch and yaw respectively. The format of the angles is radians unless explicitly set (using the 'aformat="degrees"' attribute and value). 2.4 Extension Mechanism For extensibility reasons - all XODE objects and containers without exception may contain multiple "" elements. This element is provided so that extensions can be added to the format by applications. This element MUST contain a name attribute so importers can recognise the extension. Any time an XODE file is imported with the intention of being altered and exported, the importer SHOULD read this element and retain it's data for exporting even if they are not using any extensions themselves. This is so that an XODE file with such extension data can be opened in an editor which, regardless of whether if supports the extensions will not discard their data. Applications using the element of XODE SHOULD attempt to do so in a way that multiple extensions can co-exist in a file. Thus, each extension should have a unique name. Eg: ... ... The ename attribute is to identify which extension it is. It is the only allowable attribute of . In the above example, and application not supporting the extension "foo" should still preserve its data when exporting. 3 Example File This is an example XODE file. ./data/models/tire-small.3ds 4 References ODE: http://opende.sourceforge.net/ 5 Acknowledgements Thank you to those who helped by contributing their comments and ideas to this effort. 6 Full Copyright Statement Copyright (C) 2004 William Denniss. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.