Status: Draft                                            Jean-Philippe Egger
Version: 1.0                                 Ecole Polytechnique de Lausanne
		                                                  	 March 2004
                                  
                XML Motion Data Interchange Format - XMDI

Status of this Memo

   This document specifies a proposed standard for the Robotics community.
   Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) Jean-Philippe Egger (2004).
   
Abstract

   This document describes an XML format, which can be used as a common
   Motion storage and interchange format.
  
1 Introduction

1.1 About WEBOTS
   
   Webots is a physic-based 3D mobile robot simulation software powered by Cyberbotics Ltd.
   It is used for modeling and simulating any kind of mobile robot - 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".
   Since 2002 Cyberbotics Ltd. works in close collaboration with the Biologically
   Inspired Robotics Group (BIRG) of the Ecole Polytechnique fédéral de Lausanne (EPFL).
   
   
1.2 Purpose
   
   The goal of this standard is to provide a method of storing complex Motions
   representing serveral trajectories of servos over time, and to do so in a 
   generic, interoperable and extensible manner.
   
   By definition a Motion in robotics is created by sending position values to 
   the robots servos. The set of all the positions for a certain servo over a 
   time window is called a trajectory. The combination of trajectories from different 
   servos defines a movement.
   
  
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 XMDI format into some internal 
     representation for manipulation, display or otherwise.
  
   exporter/writer
     Code that can write an XMDI formatted file from some internal
     representation.
  
   Frame
     In Webots time is simulated in discrete steps of 32ms. 
     This means, that every 32ms the servos can take a new position. A
     Frame is the time space in between two steps.
   
   Motion
     A set of trajectories for diffrent servos
    
   Trajectory
     By definition a Motion in robotics is created by sending position values
     to the robots servos. The set of all the positions for a certain servo over
     a time window is called a trajectory.
    
   Key Frame
     A key Frame defines what position a certain servo must have at a specific frame.
     Combining Key Frames and interpolating the positions in-between them will completely 
     define a trajectory.		  
     
   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 XMDI are classified into two groups.  Containers and 
   Objects.
   
2.1 XMDI Objects

   XMDI objects are entities which contain the position information.  These
   are:
  
   <positions>
   <frames>
  
   All XMDI objects shall not contain any attribute. Its content is a single text representation
   of several floating point values.
   
   Examples:
   
   <positions>0 -.7 .2</positions>
   
   <frames> 0 10 40</frames>

  
2.2 Containers

   Containers are groups of XMDI objects. The containers are:
  
   <MotionTool>
   <MotionDef>
   <Motion>
   <servo>

2.2.1 <MotionTool>

   The root node of the file of which there can only be one.  It is a 
   container for <MotionDef> nodes.  
   
   Example:
   
   <MotionTool>
   
   	<MotionDef>
   	  ... 
   	</MotionDef>
       
   </MotionToll>
   
   
2.2.2 <MotionDef>

   It is a container for <Motion> nodes.  
   
   Example:
   
   <MotionDef>
   
   	<Motion>
   	  ... 
   	</Motion>
      
   	<Motion>
   	  ...
   	</Motion>
      
   </MotionDef>
   
   

2.2.3 <Motion>

   
   This element contains only servo elements. It must have the name attribute. Further attributes
   can be assigned to it. Programmers are encouraged to add as many attributes to their motion 
   as they feel is necessary.
   
   Example:
   
   <Motion name="Jump" height="12">
   	
   	<servo>
   	  ...
   	</servo>
   	
   	<servo>
   	  ...
   	</servo>
   	
   </Motion>
   
   
2.2.4 <servo>

   
   Unlike the other containers, servo must contain exactly two XMDI objects:
   The servo element must be composed of a single position object followed by a frames object.
   The name attribute must be defined. Further the numbers of position values must be equal to 
   the numbers of frame values.
   
   Example:
   
   <servo name="back_2">
	<positions>0 -.7 .2</positions>
	<frames> 0 10 40</frames>
   </servo>

   

3 XML Schema

   Valid XMDI files MUST conform to this XML Schema
   
   <?xml version="1.0" encoding="UTF-8"?>
   <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
        <xs:element name="MotionTool">
                <xs:complexType>
                        <xs:all>
                                <xs:element name="MotionDef" minOccurs="0">
                                        <xs:complexType>
                                                <xs:sequence>
                                                        <xs:element name="Motion" minOccurs="0" maxOccurs="unbounded">
                                                                <xs:complexType>
                                                                        <xs:sequence>
                                                                                <xs:element name="servo" minOccurs="0" maxOccurs="22">
                                                                                        <xs:complexType>
                                                                                                <xs:all>
                                                                                                        <xs:element name="positions" type="xs:string"/>
                                                                                                        <xs:element name="frames" type="xs:string"/>
                                                                                                </xs:all>
                                                                                                <xs:attribute name="name" type="xs:string" use="required"/>
                                                                                        </xs:complexType>
                                                                                </xs:element>
                                                                        </xs:sequence>
                                                                        <xs:attribute name="name" type="xs:string" use="required"/>
                                                                        <xs:attribute name="DefaultLoop" type="xs:int" use="optional"/>
                                                                </xs:complexType>
                                                        </xs:element>
                                                </xs:sequence>
                                        </xs:complexType>
                                </xs:element>
                                <xs:element name="VarDef" minOccurs="0">
                                        <xs:complexType/>
                                </xs:element>
                        </xs:all>
                </xs:complexType>
        </xs:element>
</xs:schema>



4 References

   Cyberbotics Ltd.: http://www.cyberbotics.com
   Roboka Cyber Robot Competition: http://roboka.org
   
5 Acknowledgements

   Olivier Michel for helping design the XML Schema.
   
   
6 Full Copyright Statement

   Copyright (C) 2004 Jean-Philippe Egger.

   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.