Status: Draft William Denniss Version: 1 Tank Software Revision: 07 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. 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 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 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. 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 attributes (with examples): 1 false 1 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 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 '' tag. The index data is stored using multiple index '' tags. Example: 1 2 3 4 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: Some joints have one or more axes which is defined like so: 0 0 0 0 0 0 0 0.05 0.0001 0.05 0.0001 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 tag has special significance as it represents an ODE world. Implementations MUST support this container. 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.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 four tags each with four "dn" attributes numbered n=1 to 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. 2.4 Extension Mechanism For extensibility reasons - all XODE objects and containers without exception may contain multiple "" tags. 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. 5 ./data/models/tire-small.3ds 5 10 0 0 0 0 1 0 0 0.05 0.0001 0.05 0.0001 0 0 0 0 1 0 0 0.05 0.0001 0.05 0.0001 0 0 0 0 1 0 0 0.05 0.0001 0.05 0.0001 0 0 0 0 1 0 0 0.05 0.0001 0.05 0.0001 1 2 3 4 4 References ODE: http://opende.sourceforge.net/