Status: Draft                                            William Denniss
Version: 1                                                 Tank Software
Revision: 03                                                  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 and graphical 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.

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
  
  mesh
    A list of three dimensional coordinate data used to display an
    object in a graphical engine
  
  trimesh
    A collision geom consisting of a mesh of triangles.  Whilst it 
    shares a similar structure to 3D meshes used in the graphical
    engine, it must not be confused with them.
    
  group
    A collection of objects organised into a bag for organisational 
    reasons.

2 XML Tags

2.1 <xode>
  
  The root tag of an XODE file, there must be one and only one.  It can
  contain multiple <world> the <ext> tag and nothing else.
  
2.2 <world>

  Represents an ODE world - a container for bodies, geoms, meshes and 
  joints.  It can contain all ODE tags such as <body>, <geom>, <mesh>
  and <group>.
  
  
2.3 <body>

  Representation for the ODE body object (used in the physics engine).
  Belongs to the <world> - or a <group>
  
2.4 <geom>

  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 it is representing a static - immovable
  object (such as a wall).
  
  All <geom>s must have a <properties> tag which among other things 
  specifies the shape of the geom (for example, box or sphere).
  
  [ TODO:  Define geom shape tags ]
  
2.2 <mesh> tag

  Representation for the graphical objects used by the graphical engine
  to display the ODE scene.  As for <geom>, it is usually attached to a 
  body but not in the case that it represents a static object. 
  The actual type of the object is not stored to preserve the
  Independence of this format from any one graphical engine.  Instead
  only basic data such as the mesh's name and scale are stored.  It 
  is up to the importer to determine what to do with the name.  For
  example it could use the name of the mesh to load a particular file
  or extract the relevant node from a Map of names to nodes.
  
2.3 <ext> tag

  For extensibility reasons - all XODE tags without exception may 
  additionally contain an "<ext>" tag.  This tag is provided so that 
  extensions can be added to the format by applications.
  
  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 <ext> 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 a tag named <extension> with the name of
  the extension stored in a "name" attribute.
  
  Eg:
  
  <ext>
  	<extension name="foo">
		<mydata>
			...
		</mydata>
	</extension>
	<extension name="bar">
		<mydata>
			...
		<mydata>
	</extension>
  </ext>
  
  In the above example, and application not supporting the extension 
  "foo" should still preserve its data when exporting.

2.4 <group>

  The group tag is a container for all the objects that <world> is but
  has no actual meaning in ODE.  Importers MUST be able to read the 
  group and it's contents but it is OPTIONAL for them to actually
  do anything with the group meta-data itself.  Exporters MAY export
  groups.  The <group> tag can be present in a <world> or another
  <group> only.
  
  It exists for a variety of reasons, mainly so that objects can be
  organised by editors and applications for other uses.

2.5 <jointgroup>

  Attached to a <world> or <group> tag - this is a container for joints.
  
2.6 <joint>

  Represents a joint in ODE.  Can either belong to a <jointgroup> or 
  directly to a <world> (or <group>).
  
  Must contain a <properties> tag which among other things defines the
  type of joint it is.
  
  [ TODO - define joint types ]

3 Example File
     	
  This is an example XODE file.
  
<xode name="motorcycle">
    <world name="1">
    
        <group name="wheels">
        
            <body name="forwardWheel">
                <position x="-1" y="0" z="4" />
                <rotation x="0" y="0" z="0" />
                <mass density="1"/>
                <settings gravitymode="1" />
                
                <geom name="wheel1geom">
                    <properties>
                        <cylinder>
                            <position x="-1" y="0" z="4" />
                            <rotation x="0" y="0" z="0" />
                            <scale xy="1" z="1" />
                        </cylinder>
                    </properties>
                </geom>
    
                <mesh name="tire">
                    <scale x="0.5" y="0.5" z="0.5" />
                    <ext>
                        <extension name="file-location">
                            <location>./data/models/tire-small.3ds</location>
                        </extension>
                    </ext>
                </mesh>
                
                
            </body>
            
            <body name="aftWheel">
                <position x="1" y="0" z="4" />
                <rotation x="0" y="0" z="0" />
                <mass density="1"/>
                <settings gravitymode="1" />
                
                <geom name="wheel2geom">
                    <properties>
                        <cylinder>
                            <position x="-1" y="0" z="4" />
                            <rotation x="0" y="0" z="0" />
                            <scale xy="1" z="1" />
                        </cylinder>
                    </properties>
                </geom>
    
                <mesh name="tire">
                    <scale x="0.5" y="0.5" z="0.5" />
                    <ext>
                        <extension name="file-location">
                            <location>./data/models/tire-small.3ds</location>
                        </extension>
                    </ext>
                </mesh>
                
                
            </body>
        
        </group>
        
        <body name="chassis">
            <position x="0" y="0" z="4" />
            <rotation x="0" y="0" z="0" />
            <mass density="1"/>
            <settings gravitymode="1" />
            
            <geom name="forwardSection">
                <properties>
                    <box>
                        <position x="0.5" y="0" z="4" />
                        <rotation x="0" y="0" z="0" />
                        <scale x="1" y="1" z="1" />
                    </box>
                </properties>
            </geom>
            <geom name="aftSection">
                <properties>
                    <box>
                        <position x="-0.5" y="0" z="4" />
                        <rotation x="0" y="0" z="0" />
                        <scale x="1" y="1" z="1" />
                    </box>
                </properties>
            </geom>

            <mesh name="tire">
                <scale x="0.5" y="0.5" z="0.5" />
                <ext>
                    <extension name="file-location">
                        <location>./data/models/motorcycle-body.3ds</location>
                    </extension>
                </ext>
            </mesh>     
        
        </body>
        
        <jointgroup>
            <joint name="jointForwardWheel">
                <properties>
                    <hinge2>
                        <position x="-0.5" y="0" z="4" />
                        <rotation x="0" y="0" z="0" />
                        <scale x="1" y="1" z="1" />
                        
                        <axis number="1">
                            <link body="chassis" />
                            <tuple x="0" y="0" z="1" />
                            <lowStop>0</lowStop>
                            <SuspensionERP>0.05</SuspensionERP>
                            <SuspensionCFM>0.0001</SuspensionCFM>
                        </axis>
                        <axis number="1">
                            <link body="forwardWheel" />
                            <tuple x="0" y="-1" z="0" />
                            <lowStop>0</lowStop>
                            <SuspensionERP>0.2</SuspensionERP>
                            <SuspensionCFM>0.00001</SuspensionCFM>
                        </axis>
                        
                    </hinge2>
                </proteries>
            
            </joint>

            <joint name="jointAftWheel">

                <properties>
                    <hinge2>
                        <position x="-0.5" y="0" z="4" />
                        <rotation x="0" y="0" z="0" />
                        <scale x="1" y="1" z="1" />
                        
                        <axis number="1">
                            <link body="chassis" />
                            <tuple x="0" y="0" z="1" />
                            <lowStop>0</lowStop>
                            <SuspensionERP>0.05</SuspensionERP>
                            <SuspensionCFM>0.0001</SuspensionCFM>
                        </axis>
                        <axis number="1">
                            <link body="aftWheel" />
                            <tuple x="0" y="-1" z="0" />
                            <lowStop>0</lowStop>
                            <SuspensionERP>0.2</SuspensionERP>
                            <SuspensionCFM>0.00001</SuspensionCFM>
                        </axis>
                        
                    </hinge2>
                </proteries>
            
            </joint>
        
        </jointgroup>
        
    </world>

</xode>



4 References

  ODE Homepage: http://opende.sourceforge.net/