Status: Draft William Denniss Version: 1 Tank Software Revision: 04 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. Notices Copyright (C) William Denniss (2004). All Rights Reserved. Abstract This document describes an XML format which can be used as a common ODE 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 domain specific to ODE to avoid compromises and hence is suited to people using the built in ODE physics and collision objects but like ODE, doesn't limit them to one display method or another. Hence, display objects such as 3D meshes are not represented in this document and are left to the individual to best determine how to best achieve these functions. 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 Code which can read the XODE format into some internal representation for manipulation, display or otherwise. exporter 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 space A container for collision objects collision geom A geometry describing a shape that is used for collision group A collection of objects organised into a bag for organisational reasons. 2 XML Tags 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 is relative to the objects parent. 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). [ TODO: define attributes] 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 define a 'shape' attribute which can have one of several values. Listed below are those values with the list of expected attributes for each shape. In each case, the data type for the value is a float with the exception of 'trimesh' which is further detailed following this list: "box" sizex, sizey, sizez "cappedcylinder" radius, length "cone" radius, length "cylinder" radius, length "plane" a, b, c, d "ray" length "sphere" radius "trimesh" vertices, indices Examples: Geom Box: ... Geom Cylinder: ... The 'trimesh' shape is different and must define a mesh. The format for this is as follows: [ TODO: Define format ] 2.1.3 Represents a joint in ODE. Joint objects must define a 'type' attribute which can have one of several values and determines the underlying ODE joint which is used. Listed below are those values. "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" tag. Eg. The second body is specified by the "link2" tag, eg: The expected set of attributes for each joint type are listed below: "hinge2" 0 0.05 0.0001 0 0.05 0.0001 [ TODO - define more joint attributes ] 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 In addition to its properties as a container, the tag has special significance as it represents an ODE world. Implementations MUST support this container. 2.2.2 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.3 Transform Attribute Transforms are defined as a 4x4 matrix which is relative to the parent object. Example: [0,0,0,0] [0,0,0,0] [0,0,0,0] [0,0,0,0] Alternatively, there are some more "human" friendly ways of representing this matrix. [ TODO add more explanation ] 2.4 Extension Mechanism For extensibility reasons - all XODE tags without exception may additionally contain an "" tag. This tag is provided so that extensions can be added to the format by applications. This tag 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 tag and save 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 edited in an editor which doesn't support it's extensions without losing said data. Applications using the tag of XODE SHOULD attempt to do so in a way that multiple extensions can co-exist in a file. The recommended way of doing this is using giving each extension a unique name. Eg: ... ... 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 [0,0,0,0] [0,0,0,0] [0,0,0,0] [0,0,0,0] 0 0.05 0.0001 0 0.2 0.00001 0 0.05 0.0001 0 0.2 0.00001 4 References ODE Homepage: http://opende.sourceforge.net/