__NOTITLE__

= Using OpenRAVE with ROS =

Shows how to setup a full robot system with OpenRAVE and [http://ros.org Robot Operating System (ROS)]. Any robot system should deal with autonomous manipulation with vision feedback, sensor loops, and higher-level reasoning.

OpenRAVE can be used in many different scenarios.

* There is one openrave instance that does the planning and you would like all controllers/sensor feeding that to it. We'll call this the '''Master'''
* There are openrave instances outside of the Master that wrap hardware/simulation controllers, generate simulated sensor data. These instances publish to the ROS network and usually feed into the Master openrave.

== OpenRAVE plugins connecting to ROS ==

There are several openrave/ros plugins that create nodes internally and advertise/subscribe to messages. These plugins can be found in these ROS packages:

* [http://www.ros.org/browse/details.php?name=openrave_sensors openrave_sensors] - subscribe to ROS messages for getting sensor data into openrave (loaded by Master)
* [http://www.ros.org/browse/details.php?name=openrave_robot_control openrave_robot_control] - simple session interface for controlling robots over the ROS network with openrave being the underlying client. You'll notice in the lib folder is a librobot_control.so openrave plugin which the Master loads)
* [http://www.ros.org/browse/details.php?name=schunk_motion_controllers schunk_motion_controllers] - connects to the hardware Schunk interfaces and advertises services to control a robot.
* [http://www.ros.org/browse/details.php?name=orrosplanning orrosplanning] - misc plugins for reading sensing data and displaying it into openrave. For example, if there is a node plublishing checkerboard_detector/ObjectDetection messages, it is possible to use the '''ObjectTransform''' openrave SensorSystem interface to display the objects inside the environment.

== Component Tutorials ==

* [[ROS:ControllingRobots|Controlling Robots]] - Controlling robots through ROS using OpenRAVE
* [[ROS:sensors|Sensors]] - Publishing openrave sensor data through ROS.
* [[ROS:Object Detection]] - Simple object detection and inserting objects into the environment.

2011-07-20T03:36:34Z

Rdiankov:

[http://scholar.google.com/scholar?q=%22openrave%22&hl=en&btnG=Search&as_sdt=1%2C5&as_sdtp=on Research Paper References for OpenRAVE]

'''OpenRAVE Users:''' feel free to edit these pages.

= Projects =

* [http://personalrobotics.intel-research.net/ Personal Robotics] at Intel Research Pittsburgh

[[image:cmuherb.jpg|left|230px]] <videoflash>Nhx9KZwl_5A</videoflash>

* [http://opengrasp.sourceforge.net/ OpenGRASP] - OpenGRASP is an open source simulation toolkit for grasping and dexterous manipulation. It supports the creation and addition of new functionality and the integration of existing and widely used technologies and standards.
[[image:Opengrasp.png|500px]]

* [http://www.iearobotics.com/wiki/index.php?title=OpenMR:_Modular_Robots_plug-in_for_Openrave Modular Robots] - OpenMR is an OpenRave Modular Robots plug-in for simulating the locomotion of modular robots.
[[image:OpenMR.jpg|300px|link=http://www.iearobotics.com/wiki/index.php?title=OpenMR:_Modular_Robots_plug-in_for_Openrave]]

* [http://www.cs.cmu.edu/~dberenso/software.html Constrained Manipulation Planning Suite (CoMPS)] - by Dmitry Berenson. The algorithms in CoMPS allow robots to perform motion with a variety of simultaneous constraints including constraints on balance, closed-chain kinematics, and task-space constraints defined as Task Space Region (TSRs) and TSR Chains. Contains:
** The Constrained Bi-directional RRT (CBiRRT)
** An iterative IK solver
** A set of useful openrave functions for manipulation.

<videoflash>xIBRMNrutQc</videoflash> <videoflash>APAhs7GC090</videoflash>

* [http://correll.cs.colorado.edu/pmwiki/index.php/Main/PlanningSystemArm Planning Arm System]

* [http://www.openrtm.org/openrtm/ja/content/rtc-openrave%E3%81%8C%E6%9A%AB%E5%AE%9A%E5%85%AC%E9%96%8B RTC-OpenRAVE]

* [http://openprm.sourceforge.net/ Open Probabilistic Roadmap Planning]

* [http://smart-robotics.sourceforge.net/corbaSmartSoft/components.php?cmp=SmartOpenRave SmartSoft Toolchain]

* [http://trac.fawkesrobotics.org/wiki/Plugins/katana Fawkes Robotics]

* [http://personalrobotics.intel-research.net/intel-pkg/armmbhp/html/index.html Arm Model-Based Hierarchical Planner]

= Other =

* [http://www.robotic.dlr.de/Franziska.Zacharias/ Mobile Manipulation with DLR robot Justin] - Project headed by Franziska Zacharias to model and analyze the reachability spaces of robot arms and use these knowledge representations in planning manipulation tasks.
[[image:DLRJustin_Zacharias.png|500px]]

* [http://pr.cs.cornell.edu/articulated3d/ Box Packing Robot]

* [http://dasl.mem.drexel.edu/~seanMason/?page_id=252 Lego Project]

* [http://dasl.mem.drexel.edu/~christopherKorpela/?page_id=271 MiniHubo]

Format:XML

2011-07-20T02:30:11Z

Rdiankov:

__NOTITLE__

= OpenRAVE Custom XML Format =

[[image:Openrave_robots.jpg|600px]]

OpenRAVE uses XML to store all robot and scene descriptions. The XML format is flexible enough to link one XML file from another like including already created objects/robots in an environment. It is also possible to specify vrml or iv formatted files within it to import models.

All interface types can be created. Furthermore, an <environment> tag can optionally be specified to put all bodies/interfaces in.

* '''Environment''' - specify multiple objects and robots. Can also define some GUI properties like camera start location and background color. The environment allows the creation of '''any''' OpenRAVE interfaces. Each interface can take the '''type''' attribute specifying the interface type and can define custom XML readers.
* '''KinBody''' - The basic object that all other objects derive from. A kinematic body consists of a collection of rigid bodies and joints that connect these bodies.
* '''Robot''' - The basic robot that derives from '''KinBody'''. Usually every Robot has at least one KinBody declaration inside it. A robot can also hold a list of '''Manipulator''' and '''AttachedSensor''' objects describing the manipulation/sensing capabilities of the robot. Since plugin authors can create different robots, it is also possible to define custom fields in '''Robot''' to hold other information like balance control parameters for humanoids.

== KinBody ==

<source lang="xml">
<KinBody name="TestKinBody">



<Body name="Body1" type="dynamic">



<Translation>0 0 0</Translation>

<RotationAxis>1 0 0 90</RotationAxis>






<Mass type="mimicgeom">
<density>1000</density>
</Mass>









<Geom type="box">

<Extents>1 1 1</Extents>


<Translation>1 0 0</Translation>
<RotationAxis>0 1 0 45</RotationAxis>
</Geom>

<Geom type="box">
<Extents>2 1 2</Extents>
<Translation>0 1 0</Translation>

<RotationMat>1 0 0 0 1 0 0 0 1</RotationMat>

<transparency>0.4</transparency>
</Geom>
</Body>

<Body name="Body2" type="dynamic">

<Mass type="mimicgeom">

<total>0.40605</total>

<inertia>2 0 0 0 3 0 0 0 5</inertia>

<com>0.008842 -0.000018 0.07367</com>
</Mass>

<Geom type="sphere">


<Render>models/objects/coffeepot.iv</Render>
<Translation>0 -1.5 0</Translation>
<Radius>1.5</Radius>
</Geom>

<Geom type="trimesh">
<Render>models/objects/cup.iv 0.01</Render>


<collision>models/objects/cup.iv 0.01</collision>
<Translation>1.5 -2 0</Translation>
</Geom>
</Body>









<Joint name="j1" type="hinge">

<Body>Body1</Body>
<Body>Body2</Body>

<Anchor>0 0 0</Anchor>
<Axis>0 1 0</Axis>


<Weight>1.0</Weight>
</Joint>
</KinBody>
</source>

=== Models Directory ===

By default, the root directory for all models files is the folder openrave is launched at. To change this, '''<modelsdir>''' can be used to specify model files relative to where the current xml file is. For example:

<source lang="xml">
<KinBody>
<modelsdir>../mymodels</modelsdir>
<Body>
<Geom type="box">
<render>kitchen/myfile.wrl</render>
</Geom>
</Body>
</KinBody>
</source>

=== Circular Joints ===

Sometimes joints will have the upper and lower limits identified, meaning that as soon as the joint gets past one limit it will wrap around to the other. Infinitely revolving hinge joints are the most common example of '''circular''' joints where the <math>-\pi</math> and <math>\pi</math> limits are identified. In openrave, it is possible to set a joint as '''circular''' like this:
<source lang="xml">
<joint circular="true" ...>
...
</joint>
</source>

=== Adjacent Links ===

Robot self-collision usually checks all pairs of non-adjacent links for collision; links are adjacent if they are connected to a joint. In order to reduce self-collision computation time and spurious collisions of small links, it is possible to force pairs of links to be treated as adjacent by specifying an '''<adjacent>''' tag.

=== Scale ===

The first thing when importing a new model is to check that all the units are in meters (it is very common for robots to be in millimeters), otherwise the visualization model and the collision model will be in a different scale. to check this, open the robot and go to View->Geometry->Collision, this will show the collision model. If it is not the same scale, you need to go inside your model files and change the units. You can also enter a scale factor after model filenames like this:

<source lang="xml">
<collision>mydata.iv 0.001</collision>
<render>mydata.iv 0.001</render>
</source>

this will scale the models by 0.001.

== Robot ==

=== A simple 3DOF planar arm in XZ ===

<source lang="xml">
<Robot name="3DOFRobot">
<KinBody>



<Body name="Base" type="dynamic">
<Translation>0.0 0.0 0.0</Translation>
<Geom type="cylinder">
<rotationaxis>1 0 0 90</rotationaxis>
<radius>0.03</radius>
<height>0.02</height>
<diffuseColor>0.05 0.05 0.05</diffuseColor>
</Geom>
</Body>


<Body name="Arm0" type="dynamic">


<offsetfrom>Base</offsetfrom>

<Translation>0 0 0.005</Translation>
<Geom type="box">
<Translation>0.08 0 0</Translation>
<Extents>0.08 0.01 0.005</Extents>
</Geom>
</Body>

<Joint circular="true" name="Arm0" type="hinge">
<Body>Base</Body>
<Body>Arm0</Body>
<offsetfrom>Arm0</offsetfrom>
<weight>4</weight>
<limitsdeg>-180 180</limitsdeg>
<axis>0 0 1</axis>
<maxvel>3</maxvel>
<resolution>1</resolution>
</Joint>


<Body name="Arm1" type="dynamic">
<offsetfrom>Arm0</offsetfrom>
<Translation>0.14 0 0.01</Translation>
<Geom type="box">
<Translation>0.08 0.0 0</Translation>
<Extents>0.08 0.0075 0.005</Extents>
</Geom>
</Body>

<Joint circular="true" name="Arm1" type="hinge">
<Body>Arm0</Body>
<Body>Arm1</Body>
<offsetfrom>Arm1</offsetfrom>
<weight>3</weight>
<limitsdeg>-180 180</limitsdeg>
<axis>0 0 1</axis>
<maxvel>4</maxvel>
<resolution>1</resolution>
</Joint>


<Body name="Arm2" type="dynamic">
<offsetfrom>Arm1</offsetfrom>
<Translation>0.14 0 0.01</Translation>
<Geom type="box">
<Translation>0.04 0 0</Translation>
<Extents>0.04 0.005 0.005</Extents>
</Geom>
</Body>

<Joint circular="true" name="Arm2" type="hinge">
<Body>Arm1</Body>
<Body>Arm2</Body>
<offsetfrom>Arm2</offsetfrom>
<weight>3</weight>
<limitsdeg>-180 180</limitsdeg>
<axis>0 0 1</axis>
<maxvel>2</maxvel>
<resolution>2</resolution>
</Joint>



<Body name="RClaw" type="dynamic">
<offsetfrom>Arm2</offsetfrom>
<Translation>0.08 0 0.005</Translation>
<rotationaxis>0 0 1 -90</rotationaxis>
<Geom type="trimesh">
<Data>models/puma/RClaw.iv</Data>
<Render>models/puma/RClaw.iv</Render>
</Geom>
</Body>
<Joint name="j1" type="hinge">
<Body>Arm2</Body>
<Body>RClaw</Body>
<offsetfrom>RClaw</offsetfrom>
<weight>0.2</weight>
<limitsdeg>-56 16</limitsdeg>
<axis>0 0 1</axis>
<maxvel>0.4</maxvel>
<resolution>3</resolution>
</Joint>


<Body name="LClaw" type="dynamic">
<Translation>0.08 0.005 0</Translation>
<rotationaxis>0 0 1 -90</rotationaxis>
<offsetfrom>Arm2</offsetfrom>
<Geom type="trimesh">
<Data>models/puma/LClaw.iv</Data>
<Render>models/puma/LClaw.iv</Render>
</Geom>
</Body>
<Joint name="j2" type="hinge">
<Body>Arm2</Body>
<Body>LClaw</Body>
<offsetfrom>LClaw</offsetfrom>
<weight>0.2</weight>
<limitsdeg>-56 16</limitsdeg>
<axis>0 0 -1</axis>
<maxvel>0.4</maxvel>
<resolution>3</resolution>
</Joint>

<transparency>0.1</transparency>
</KinBody>


<Manipulator name="arm">
<effector>Arm2</effector> 
<base>Base</base> 
<joints>j1 j2</joints> 





<closingdirection>1 1</closingdirection>
<direction>1 0 0</direction>

<Translation>0.125 0 0</Translation>
</Manipulator>
</Robot>
</source>

3DOFRobot Robot: [[image:tridof.jpg|200px]]

=== Defining Manipulators ===

A robot manipulator defines a kinematic chain of the robot joint hierarchy along with optional gripper joint values that are not used in the inverse kinematics computation but are needed for grasping purposes (chains for heads, legs do not need the joint values). A manipulator defines a new frame of reference with respect to the end effector link; all inverse kinematics computations are computed using it. Furthermore, a manipulator can have a '''<direction>''' tag specifying an axis for approaching objects or line-of-sight. For example the '''robots/barrettwam.robot.xml''' gripper is defined by

<source lang="xml">
<Manipulator name="arm">
<base>wam0</base>
<effector>wam7</effector>
<Translation>0 0 0.22</Translation>
<joints>JF1 JF2 JF3 JF4</joints>
<closingdirection>1 1 1 0</closingdirection>
<direction>0 0 1</direction>
<iksolver>WAM7ikfast 0.05</iksolver>
</Manipulator>
</source>

The manipulator can optionally define a '''<iksolver>''' tag specifying the iksolver interface that is used for getting IK solutions, or a shared object (DLL) to load an [[Component:Ikfast|ikfast]] solver from.

=== Closed-chains and Mimic Joints ===

OpenRAVE allows closed-chains and complex kinematics to be simulated using mimic joints. A mimic joint's position, velocity, and acceleration values are computed from user-specified formulas using the values of other joints. OpenRAVE uses the Function Parser library to allow any formula to be specified. Refer to the documentation for more information [http://openrave.programmingvision.com/en/coreapihtml/classOpenRAVE_1_1KinBody_1_1Joint.html#a0e31c5be31c4145afa786e0c0d6a46ae here].

A mimic joint requires at least the position equation and its partial derivatives (for velocity) to be manually entered.

For example, the Barrett Hand mimic joints are defined as:

<source lang="xml">
<Joint type="hinge" name="JF1">
...
</Joint>
<Joint name="JF1mimic" type="hinge" enable="false" mimic_pos="JF1/3+0.8727" mimic_vel="|JF1 0.33333">
....
</Joint>
</source>

Of course, it is possible to have a mimic joint depend on more than one other joint:

<source lang="xml">
<Joint type="hinge" name="a">
...
</Joint>
<Joint type="hinge" name="b">
...
</Joint>
<Joint name="c" type="hinge" mimic_pos="a+b+atan(a)" mimic_vel="|a 1 + 1/(1+a*a) |b 1" mimic_accel="|a -2*a/((1+a*a)*(1+a*a)) |b 0">
....
</Joint>
</source>

When using mimic joints, it is important to still make all the correct joint connections so that loops are discovered and forces can be computed correctly.

If a joint has more than one degree of freedom, attach the axis index at the end. For example: "mimic_pos0", "mimic_pos1", "mimic_vel0", "mimic_vel1", "mimic_accel0", and "mimic_accel1".

=== Attaching Robot Sensors ===

Every robot can be attached a number of sensors onto it. The way to specify this in XML is:

<source lang="xml">
<Robot>



<AttachedSensor name="MyFirstLaser">
<link>wam1</link> 
<translation>0 0.2 0.4</translation> 
<rotationaxis>1 0 0 45</rotationaxis> 


<sensor type="BaseLaser2D">



<minangle>-135</minangle> 
<maxangle>135</maxangle> 
<resolution>0.35</resolution> 
<maxrange>5</maxrange> 
</sensor>
</AttachedSensor>
</Robot>
</source>

=== Setting joint values for initial state ===

Sometimes the robot's initial state is not when all the joints are at 0. Instead of transforming each of the geometry to the zero pose, it is possible to set the initial angle to use using the <initial> tag inside the <joint>. The definition for setting the initial angle to pi/2 radius is:

<source lang="xml">
<joint type="hinge">
<body>link0</body>
<body>link1</body>
<initial>1.570796326794</initial>
</joint>
</source>

=== Changing the Body Coordinate System ===

[[image:Barrettwam_coordchange.png|600px]]

Sometimes the robot origin and rotation should be defined in a different coordinate system. It is possible to create a new robot file that references the old one and changes its origin. This requires adding a new root link before the robot is defined. For example, consider the robots/barrettwam.robot.xml file whre the first link's name is 'wam0':

<source lang="xml">
<robot>

<kinbody>
<body name="root">
</body>
</kinbody>
<robot file="robots/barrettwam.robot.xml">

<kinbody>
<body name="wam0">
<rotationaxis>1 0 0 90</rotationaxis>
<translation>0.3 0.4 0.3</translation>
</body>
<joint name="dummy" type="hinge">
<body>root</body>
<body>wam0</body>
<limitsdeg>0 0</limitsdeg>
</joint>
</kinbody>
</robot>
</robot>
</source>

== Environment Example ==

This example is part of the '''bin/data/intel/lab1.env.xml''' file. The most important thing to note about this example is the use of the '''file=''' attribute to import other XML files. The filename specified with '''file=''' has to be '''relative''' to the current directory where the file calling it resides. Note the differences between segway.kinbody.xml and barrettwam.robot.xml.

<source lang="xml">
<Environment>

<bkgndcolor>0.3 0.7 0.8</bkgndcolor>

<camtrans>1.418 -1.234 2.963</camtrans>

<camrotaxis>0.724 0.302 0.619 68</camrotaxis>


<KinBody file="data/segway.kinbody.xml">
<Translation>-0.0671 -0.0819 0.7550</Translation>
</KinBody>


<Robot file="../../robots/barrettwam.robot.xml" name="BarrettWAM">
<KinBody>
<Translation>-.22 -.14 -.346</Translation>
<Body type="dynamic">
<Geom type="cylinder">
<RotationAxis>1 0 0 -90</RotationAxis>
<radius>0.08</radius>
<height>0.6</height>
<diffusecolor>0.3 0.3 0.3</diffusecolor>
<Translation> 0.2286 0.1397 -0.346</Translation>
</Geom>
</Body>
</KinBody>
<translation>-0.754 0.3265 1.036</translation>
</Robot>


<KinBody name="floor">

<Body type="static">
<Geom type="box">
<extents>2 2 0.005</extents>
<diffuseColor>.6 .6 .6</diffuseColor>
<ambientColor>0.6 0.6 0.6</ambientColor>
</Geom>
</Body>
</KinBody>
</Environment>
</source>

== Robot Composition ==

The way we recommend managing robots composed of several sub-robots (like a humanoid composed of arms, legs, hands, etc) is to first create separate .kinbody files for just the kinematics and geometry of each separate
part (ie a hand.kinbody.xml and a arm.kinbody.xml). Then create a robot file that includes both the kinematics and defines the manipulators, sensors, and controllers:

<source lang="xml">
<robot>
<kinbody file="arm.kinbody.xml"/>
<kinbody file="hand.kinbody.xml"/>
<attachedsensor>
....
</attachedsensor>
<manipulator>
....
</manipulator>
</robot>
</source>

Sometimes for grasp planning, the hand needs to be treated as a robot, so we create a hand.robot.xml file as follows:

<source lang="xml">
<robot>
<kinbody file="hand.kinbody.xml"/>
<manipulator>
....
</manipulator>
</robot>
</source>

1. A robot can reference other robots through:

<source lang="xml">
<Robot>
<Robot file="a.robot.xml"/>
<Robot file="b.robot.xml"/>
</Robot>
</source>

Both a's and b's '''<Manipulator>''' and '''<AttachedSensor>''' tags will be used
in the parent robot, so you don' t have to copy their definitions.

2. It is possible to prefix the links and joints of a child robot by using the
'prefix' attribute:

<source lang="xml">
<Robot>
<KinBody prefix="left_" file="arm.kinbody.xml"/>
<KinBody prefix="right_" file="arm.kinbody.xml"/>
</Robot>
</source>

Now all links and joints will either start with '''left_''' or '''right_'''.

3. When the xml parser sees a body with the same name as another body,
it 'appends' the specified geometries to the original body. This allows the same link to be referenced/defined in multiple robot files (Note that it is not possible to change the original body coordinate system).

=== Attaching Separate Links ===

When a robot is composed of multiple parts defined in different files, it is necessary to attach links from the different files together so that the robot hierarchy can be complete. This is done by defining '''disabled''' dummy joints that attach two links together. These disabled joints do not show up in the robot's description and are only present to maintain the relative transformation between two links. For example, the robot '''robots/pa10schunk.robot.xml''' is composed of '''robots/pa10.kinbody.xml''' and '''robots/schunk_manip.kinbody.xml''', in order to join the two, the robot is defined in the following way:

<source lang="xml">
<KinBody file="pa10.kinbody.xml">
<KinBody file="schunk_manip.kinbody.xml"/>
<Joint name="dummy" type="hinge" enable="False">
<body>link7</body>
<body>gripper_base</body>
<limits>0 0</limits>
</Joint>
</KinBody>
</source>

where '''link7''' is a link of the pa10 arm and '''gripper_base''' is a link of the gripper. The lower and upper joint limits are all 0, which OpenRAVE recognizes as a dummy joint.

=== Joining A Robot Arm and Hand ===

It is possible to load robots and bodies from COLLADA files by specifying the collada filename through the '''file''' attribute. For example, the following robot is a combination of an arm defined in OpenRAVE XML and a hand defined in COLLADA (download schunkSDHHand from [http://opengrasp.sourceforge.net/Downloads.html OpenGrasp]). The dummy joint is used to join the arm end effector with the hand base.

<source lang="xml">
<robot>
<robot file="robots/kuka-kr5-r650.robot.xml"></robot>
<robot prefix="hand_" file="schunkSDHhand.dae"></robot>
<kinbody>
<body name="hand_root">
<offsetfrom>link6</offsetfrom>
<translation>0.03 0 0</translation>
<rotationaxis>0 1 0 90</rotationaxis>
</body>
<joint type="hinge" enable="false">
<body>link6</body>
<body>hand_root</body>
<limits>0 0</limits>
</joint>
</kinbody>
<manipulator name="arm">
<base>base</base>
<effector>link6</effector>
<joints>hand_Bone_B1_Joint hand_Bone_B2_Joint hand_Bone_B3_Joint hand_Bone_A1_Joint hand_Bone_A2_Joint hand_Bone_A3_Joint hand_Bone_C1_Joint hand_Bone_C2_Joint hand_Bone_C3_Joint</joints>
<closingdirection>0 1 1 0 1 1 0 1 1</closingdirection>
<direction>1 0 0</direction>
</manipulator>
</robot>
</source>

Final robot: [[image:collada_sdh_kuka.jpg|150px]]

=== Dual-arm example ===

Here is an example file of having a robot composed of two arms attached to a common link named '''chest'''.

<source lang="xml">
<Robot name="schunk-dualarm">
<KinBody>
<body name="chest">
<geom type="box">
<extents>0.1 0.1 0.4</extents>
<translation>0 0 0.4</translation>
</geom>
</body>

<KinBody>
<KinBody prefix="l_" file="schunk-lwa3.kinbody.xml"></KinBody>
<RotationAxis>1 0 0 90</RotationAxis>
<translation>0 -0.1 0.7</translation>
</KinBody>

<KinBody>
<KinBody>prefix="r_" file="schunk-lwa3.kinbody.xml"></KinBody>
<RotationAxis>1 0 0 -90</RotationAxis>
<translation>0 0.1 0.7</translation>
</KinBody>

<joint name="leftdummy" type="hinge" enable="false">
<body>chest</body>
<body>l_base</body>
<limits>0 0</limits>
</joint>
<joint name="rightdummy" type="hinge" enable="false">
<body>chest</body>
<body>r_base</body>
<limits>0 0</limits>
</joint>
</KinBody>

<Manipulator name="leftarm">
<base>l_base</base>
<effector>l_link7</effector>
<armjoints>l_j0 l_j1 l_j2 l_j3 l_j4 l_j5 l_j6</armjoints>
</Manipulator>
<Manipulator name="rightarm">
<base>r_base</base>
<effector>r_link7</effector>
<armjoints>r_j0 r_j1 r_j2 r_j3 r_j4 r_j5 r_j6</armjoints>
</Manipulator>
</Robot>
</source>

Single arm: [[image:schunk-lwa3.jpg|300px]]

Dual arm: [[image:schunk-lwa3-dual.jpg|300px]]

== Custom XML ==

Openrave provides much more flexibility in creating and defining custom XML readers for interfaces. First the <environment> XML tag supports creating any interface type and supports loading plugins. For example:

<source lang="xml">
<Environment>
<plugin>libcustomreader</plugin>
<robot name="wam" file="robots/barrettwam.robot.xml"/>
<controller type="CustomController" robot="wam" args="">
..custom data....
</controller>
<module type="basemanipulation" args="wam"/>
</Environment>
</source>

In this example, openrave will first load the plugin, then will create a robot, and then will create a controller that is attached to the robot, then will create the basemanipulation module giving it the robot name as the argument.

Furthermore, using EnvironmentBase::RegisterXMLReader, it is possible to set a parser for custom XML tags for each interface type. For those curious on how to take advantage of custom readers, please refer to examples/plugincpp/customreader.cpp on how to attach a custom XML reader to a controller.

These changes will allow people to setup all their specific environment settings in the XML files without having to rely on external scripts or other programs to do it. Note that OpenRAVE processes tags in depth first order.

== Sensor ==

It is possible to have XML files that declare a sensor and its internal parameters. For example, '''data/camera.sensor.xml''' can look like:

<source lang="xml">
<sensor type="BaseCamera">
<KK>640 640 320 240</KK>
<width>640</width>
<height>480</height>
<framerate>5</framerate>
<color>0.5 0.5 1</color>
</sensor>
</source>

In order to attach a sensor defined by a file to a robot link do:

<source lang="xml">
<Robot>

<AttachedSensor name="MyCamera">
<sensor file="camera.sensor.xml">
</sensor>
</AttachedSensor>
</Robot>
</source>

It is also possible to put a sensor directly in the environment without a robot. Such a sensor will not have any geometry associated with it, and will only act as a sensing source.

<source lang="xml">
<Environment>

<sensor name="mysensor" file="camera.sensor.xml">

<translation>0 1 0</translation>
<rotationaxis>1 0 0 45</rotationaxis>
</sensor>
</Environment>
</source>

== XML Reference ==

'''Note:''' All XML handling is done in '''src/libopenrave-core/xmlreaders.cpp'''. If there's any parameters that are not explained well, make sure to check out that source file for further reference.

'''Note:''' You can find details on joints on : [http://opende.sourceforge.net/wiki/index.php/Manual_%28Joint_Types_and_Functions%29 ODE Manual page (joints)].

Here's a list of all possible fields the XML supports in a hierarchical structure.

'''environment''' - '''attributes:''' file
'''bkgndcolor''' - 3 floats
'''camrotaxis''' - 4 floats
'''camtrans''' - 3 floats
'''kinbody''' - '''attributes:''' name, file
'''robot''' - '''attributes:''' name, file
'''planner''' - '''attributes:''' type, file
'''sensorsystem''' - '''attributes:''' type, file
'''controller''' - '''attributes:''' type, file, robot, args
'''module''' - '''attributes:''' type, file
'''inversekinematicssolver''' - '''attributes:''' type, file
'''physicsengine''' - '''attributes:''' type, file
'''sensor''' - '''attributes:''' type, file
'''collisionchecker''' - '''attributes:''' type, file
'''trajectory''' - '''attributes:''' type, file
'''viewer''' - '''attributes:''' type, file
'''server''' - '''attributes:''' type, file

'''kinbody''' - '''attributes:''' name, file, prefix, type, makejoinedlinksadjacent
'''adjacent''' - 2 body names
'''body''' - '''attributes:''' name, type (dynamic, static)
'''geom''' - '''attributes:''' name, type (box, sphere, trimesh, cylinder), render (true,false), modifiable (true,false)
'''ambientcolor''' - 3 float
'''collision''' - '''attributes:''' file, scale
'''diffusecolor''' - 3 float
'''extents''' - 3 float [box]
'''height''' - float [cylinder]
'''quat''' - 4 float
'''radius''' - float [cylinder, sphere]
'''render''' - '''attributes:''' file, scale
'''rotationaxis''' - 4 float
'''rotationmat''' - 9 float
'''translation''' - 3 float
'''transparency''' - 1 float
'''vertices''' - 9*N floats where each 9 values defines 1 triangle with 3 vertices
'''mass''' - '''attributes:''' type (box, sphere, custom)
'''com''' - 3 float
'''density''' - float
'''inertia''' - 9 float
'''radius''' - float
'''total''' - float
'''joint''' - '''attributes:''' enable (true, false), type (hinge, slider, universal, hinge2, spherical), circular(true, false), mimic_pos (math equation), mimic_vel (math equation), mimic_accel (math equation)
'''anchor''' - 3 floats [hinge, hinge2, universal, spherical]
'''axis''' - 3 floats [hinge, slider]
'''axis1''' - 3 floats [hinge2, universal]
'''axis2''' - 3 floats [hinge2, universal]
'''body''' - string
'''limits''' - 2*dof floats in radians if applicable (first two specify first joint limits, etc)
'''limitsdeg''' - 2*dof floats in degrees if applicable (first two specify first joint limits, etc)
'''limitsrad''' - 2*dof floats in radians if applicable (first two specify first joint limits, etc)
'''maxvel''' - dof floats
'''mode''' - int [amotor]
'''offsetfrom''' - link name
'''resolution''' - float
'''weight''' - dof floats
'''initial''' - dof floats
'''jointvalues'''
'''kinbody - '''attributes:''' name, file, prefix
'''mass''' - '''attributes:''' type (box, sphere, custom)
'''density''' - float
'''radius''' - float
'''total''' - float
'''modelsdir''' - string
'''offsetfrom''' - bodyname
'''quat''' - 4 float
'''rotationaxis''' - 4 float
'''rotationmat''' - 9 float
'''translation''' - 3 float
'''transparency''' - 1 float

'''robot''' - '''attributes:''' name, file, prefix, type (robot plugin type)
'''attachedsensor''' - '''attributes:''' name
'''link'''
'''quat'''
'''rotationaxis'''
'''rotationmat'''
'''translation'''
'''sensor''' - '''attributes:''' type
'''...''' - fields defined by SensorBase class instantiated by type
'''controller''' - type args
'''jointvalues'''
'''kinbody''' - name
'''manipulator''' - '''attributes:''' name
'''armjoints''' - n joint names
'''base''' - link name
'''closed''' - k floats
'''effector''' - link name
'''iksolver''' - string
'''gripperjoints''' - k joint names
'''closingdirection''' - k floats
'''palmdirection''' - 3 floats
'''quat''' - 4 floats
'''rotationaxis''' - 4 floats
'''rotationmat''' - 9 floats
'''translation''' - 3 floats
'''quat''' - 4 float
'''robot''' - name, file, type
'''rotationaxis''' - 4 float
'''rotationmat''' - 9 float
'''translation''' - 3 float

File:Barrettwam coordchange.png

2011-07-20T02:29:31Z

Rdiankov:

Format:XML

2011-07-20T02:10:20Z

Rdiankov:

__NOTITLE__

= OpenRAVE Custom XML Format =

[[image:Openrave_robots.jpg|600px]]

OpenRAVE uses XML to store all robot and scene descriptions. The XML format is flexible enough to link one XML file from another like including already created objects/robots in an environment. It is also possible to specify vrml or iv formatted files within it to import models.

All interface types can be created. Furthermore, an <environment> tag can optionally be specified to put all bodies/interfaces in.

* '''Environment''' - specify multiple objects and robots. Can also define some GUI properties like camera start location and background color. The environment allows the creation of '''any''' OpenRAVE interfaces. Each interface can take the '''type''' attribute specifying the interface type and can define custom XML readers.
* '''KinBody''' - The basic object that all other objects derive from. A kinematic body consists of a collection of rigid bodies and joints that connect these bodies.
* '''Robot''' - The basic robot that derives from '''KinBody'''. Usually every Robot has at least one KinBody declaration inside it. A robot can also hold a list of '''Manipulator''' and '''AttachedSensor''' objects describing the manipulation/sensing capabilities of the robot. Since plugin authors can create different robots, it is also possible to define custom fields in '''Robot''' to hold other information like balance control parameters for humanoids.

== KinBody ==

<source lang="xml">
<KinBody name="TestKinBody">



<Body name="Body1" type="dynamic">



<Translation>0 0 0</Translation>

<RotationAxis>1 0 0 90</RotationAxis>






<Mass type="mimicgeom">
<density>1000</density>
</Mass>









<Geom type="box">

<Extents>1 1 1</Extents>


<Translation>1 0 0</Translation>
<RotationAxis>0 1 0 45</RotationAxis>
</Geom>

<Geom type="box">
<Extents>2 1 2</Extents>
<Translation>0 1 0</Translation>

<RotationMat>1 0 0 0 1 0 0 0 1</RotationMat>

<transparency>0.4</transparency>
</Geom>
</Body>

<Body name="Body2" type="dynamic">

<Mass type="mimicgeom">

<total>0.40605</total>

<inertia>2 0 0 0 3 0 0 0 5</inertia>

<com>0.008842 -0.000018 0.07367</com>
</Mass>

<Geom type="sphere">


<Render>models/objects/coffeepot.iv</Render>
<Translation>0 -1.5 0</Translation>
<Radius>1.5</Radius>
</Geom>

<Geom type="trimesh">
<Render>models/objects/cup.iv 0.01</Render>


<collision>models/objects/cup.iv 0.01</collision>
<Translation>1.5 -2 0</Translation>
</Geom>
</Body>









<Joint name="j1" type="hinge">

<Body>Body1</Body>
<Body>Body2</Body>

<Anchor>0 0 0</Anchor>
<Axis>0 1 0</Axis>


<Weight>1.0</Weight>
</Joint>
</KinBody>
</source>

=== Models Directory ===

By default, the root directory for all models files is the folder openrave is launched at. To change this, '''<modelsdir>''' can be used to specify model files relative to where the current xml file is. For example:

<source lang="xml">
<KinBody>
<modelsdir>../mymodels</modelsdir>
<Body>
<Geom type="box">
<render>kitchen/myfile.wrl</render>
</Geom>
</Body>
</KinBody>
</source>

=== Circular Joints ===

Sometimes joints will have the upper and lower limits identified, meaning that as soon as the joint gets past one limit it will wrap around to the other. Infinitely revolving hinge joints are the most common example of '''circular''' joints where the <math>-\pi</math> and <math>\pi</math> limits are identified. In openrave, it is possible to set a joint as '''circular''' like this:
<source lang="xml">
<joint circular="true" ...>
...
</joint>
</source>

=== Adjacent Links ===

Robot self-collision usually checks all pairs of non-adjacent links for collision; links are adjacent if they are connected to a joint. In order to reduce self-collision computation time and spurious collisions of small links, it is possible to force pairs of links to be treated as adjacent by specifying an '''<adjacent>''' tag.

=== Scale ===

The first thing when importing a new model is to check that all the units are in meters (it is very common for robots to be in millimeters), otherwise the visualization model and the collision model will be in a different scale. to check this, open the robot and go to View->Geometry->Collision, this will show the collision model. If it is not the same scale, you need to go inside your model files and change the units. You can also enter a scale factor after model filenames like this:

<source lang="xml">
<collision>mydata.iv 0.001</collision>
<render>mydata.iv 0.001</render>
</source>

this will scale the models by 0.001.

== Robot ==

=== A simple 3DOF planar arm in XZ ===

<source lang="xml">
<Robot name="3DOFRobot">
<KinBody>



<Body name="Base" type="dynamic">
<Translation>0.0 0.0 0.0</Translation>
<Geom type="cylinder">
<rotationaxis>1 0 0 90</rotationaxis>
<radius>0.03</radius>
<height>0.02</height>
<diffuseColor>0.05 0.05 0.05</diffuseColor>
</Geom>
</Body>


<Body name="Arm0" type="dynamic">


<offsetfrom>Base</offsetfrom>

<Translation>0 0 0.005</Translation>
<Geom type="box">
<Translation>0.08 0 0</Translation>
<Extents>0.08 0.01 0.005</Extents>
</Geom>
</Body>

<Joint circular="true" name="Arm0" type="hinge">
<Body>Base</Body>
<Body>Arm0</Body>
<offsetfrom>Arm0</offsetfrom>
<weight>4</weight>
<limitsdeg>-180 180</limitsdeg>
<axis>0 0 1</axis>
<maxvel>3</maxvel>
<resolution>1</resolution>
</Joint>


<Body name="Arm1" type="dynamic">
<offsetfrom>Arm0</offsetfrom>
<Translation>0.14 0 0.01</Translation>
<Geom type="box">
<Translation>0.08 0.0 0</Translation>
<Extents>0.08 0.0075 0.005</Extents>
</Geom>
</Body>

<Joint circular="true" name="Arm1" type="hinge">
<Body>Arm0</Body>
<Body>Arm1</Body>
<offsetfrom>Arm1</offsetfrom>
<weight>3</weight>
<limitsdeg>-180 180</limitsdeg>
<axis>0 0 1</axis>
<maxvel>4</maxvel>
<resolution>1</resolution>
</Joint>


<Body name="Arm2" type="dynamic">
<offsetfrom>Arm1</offsetfrom>
<Translation>0.14 0 0.01</Translation>
<Geom type="box">
<Translation>0.04 0 0</Translation>
<Extents>0.04 0.005 0.005</Extents>
</Geom>
</Body>

<Joint circular="true" name="Arm2" type="hinge">
<Body>Arm1</Body>
<Body>Arm2</Body>
<offsetfrom>Arm2</offsetfrom>
<weight>3</weight>
<limitsdeg>-180 180</limitsdeg>
<axis>0 0 1</axis>
<maxvel>2</maxvel>
<resolution>2</resolution>
</Joint>



<Body name="RClaw" type="dynamic">
<offsetfrom>Arm2</offsetfrom>
<Translation>0.08 0 0.005</Translation>
<rotationaxis>0 0 1 -90</rotationaxis>
<Geom type="trimesh">
<Data>models/puma/RClaw.iv</Data>
<Render>models/puma/RClaw.iv</Render>
</Geom>
</Body>
<Joint name="j1" type="hinge">
<Body>Arm2</Body>
<Body>RClaw</Body>
<offsetfrom>RClaw</offsetfrom>
<weight>0.2</weight>
<limitsdeg>-56 16</limitsdeg>
<axis>0 0 1</axis>
<maxvel>0.4</maxvel>
<resolution>3</resolution>
</Joint>


<Body name="LClaw" type="dynamic">
<Translation>0.08 0.005 0</Translation>
<rotationaxis>0 0 1 -90</rotationaxis>
<offsetfrom>Arm2</offsetfrom>
<Geom type="trimesh">
<Data>models/puma/LClaw.iv</Data>
<Render>models/puma/LClaw.iv</Render>
</Geom>
</Body>
<Joint name="j2" type="hinge">
<Body>Arm2</Body>
<Body>LClaw</Body>
<offsetfrom>LClaw</offsetfrom>
<weight>0.2</weight>
<limitsdeg>-56 16</limitsdeg>
<axis>0 0 -1</axis>
<maxvel>0.4</maxvel>
<resolution>3</resolution>
</Joint>

<transparency>0.1</transparency>
</KinBody>


<Manipulator name="arm">
<effector>Arm2</effector> 
<base>Base</base> 
<joints>j1 j2</joints> 





<closingdirection>1 1</closingdirection>
<direction>1 0 0</direction>

<Translation>0.125 0 0</Translation>
</Manipulator>
</Robot>
</source>

3DOFRobot Robot: [[image:tridof.jpg|200px]]

=== Defining Manipulators ===

A robot manipulator defines a kinematic chain of the robot joint hierarchy along with optional gripper joint values that are not used in the inverse kinematics computation but are needed for grasping purposes (chains for heads, legs do not need the joint values). A manipulator defines a new frame of reference with respect to the end effector link; all inverse kinematics computations are computed using it. Furthermore, a manipulator can have a '''<direction>''' tag specifying an axis for approaching objects or line-of-sight. For example the '''robots/barrettwam.robot.xml''' gripper is defined by

<source lang="xml">
<Manipulator name="arm">
<base>wam0</base>
<effector>wam7</effector>
<Translation>0 0 0.22</Translation>
<joints>JF1 JF2 JF3 JF4</joints>
<closingdirection>1 1 1 0</closingdirection>
<direction>0 0 1</direction>
<iksolver>WAM7ikfast 0.05</iksolver>
</Manipulator>
</source>

The manipulator can optionally define a '''<iksolver>''' tag specifying the iksolver interface that is used for getting IK solutions, or a shared object (DLL) to load an [[Component:Ikfast|ikfast]] solver from.

=== Closed-chains and Mimic Joints ===

OpenRAVE allows closed-chains and complex kinematics to be simulated using mimic joints. A mimic joint's position, velocity, and acceleration values are computed from user-specified formulas using the values of other joints. OpenRAVE uses the Function Parser library to allow any formula to be specified. Refer to the documentation for more information [http://openrave.programmingvision.com/en/coreapihtml/classOpenRAVE_1_1KinBody_1_1Joint.html#a0e31c5be31c4145afa786e0c0d6a46ae here].

A mimic joint requires at least the position equation and its partial derivatives (for velocity) to be manually entered.

For example, the Barrett Hand mimic joints are defined as:

<source lang="xml">
<Joint type="hinge" name="JF1">
...
</Joint>
<Joint name="JF1mimic" type="hinge" enable="false" mimic_pos="JF1/3+0.8727" mimic_vel="|JF1 0.33333">
....
</Joint>
</source>

Of course, it is possible to have a mimic joint depend on more than one other joint:

<source lang="xml">
<Joint type="hinge" name="a">
...
</Joint>
<Joint type="hinge" name="b">
...
</Joint>
<Joint name="c" type="hinge" mimic_pos="a+b+atan(a)" mimic_vel="|a 1 + 1/(1+a*a) |b 1" mimic_accel="|a -2*a/((1+a*a)*(1+a*a)) |b 0">
....
</Joint>
</source>

When using mimic joints, it is important to still make all the correct joint connections so that loops are discovered and forces can be computed correctly.

If a joint has more than one degree of freedom, attach the axis index at the end. For example: "mimic_pos0", "mimic_pos1", "mimic_vel0", "mimic_vel1", "mimic_accel0", and "mimic_accel1".

=== Attaching Robot Sensors ===

Every robot can be attached a number of sensors onto it. The way to specify this in XML is:

<source lang="xml">
<Robot>



<AttachedSensor name="MyFirstLaser">
<link>wam1</link> 
<translation>0 0.2 0.4</translation> 
<rotationaxis>1 0 0 45</rotationaxis> 


<sensor type="BaseLaser2D">



<minangle>-135</minangle> 
<maxangle>135</maxangle> 
<resolution>0.35</resolution> 
<maxrange>5</maxrange> 
</sensor>
</AttachedSensor>
</Robot>
</source>

=== Setting joint values for initial state ===

Sometimes the robot's initial state is not when all the joints are at 0. Instead of transforming each of the geometry to the zero pose, it is possible to set the initial angle to use using the <initial> tag inside the <joint>. The definition for setting the initial angle to pi/2 radius is:

<source lang="xml">
<joint type="hinge">
<body>link0</body>
<body>link1</body>
<initial>1.570796326794</initial>
</joint>
</source>

=== Changing the Body Coordinate System ===

Sometimes the robot origin and rotation should be defined in a different coordinate system. It is possible to create a new robot file that references the old one and changes its origin. This requires adding a new root link before the robot is defined. For example, consider the robots/barrettwam.robot.xml file whre the first link's name is 'wam0':

<source lang="xml">
<robot>

<kinbody>
<body name="root">
</body>
</kinbody>
<robot file="robots/barrettwam.robot.xml">

<kinbody>
<body name="wam0">
<rotationaxis>1 0 0 90</rotationaxis>
<translation>0.3 0.4 0.3</translation>
</body>
<joint name="dummy" type="hinge">
<body>root</body>
<body>wam0</body>
<limitsdeg>0 0</limitsdeg>
</joint>
</kinbody>
</robot>
</robot>
</source>

== Environment Example ==

This example is part of the '''bin/data/intel/lab1.env.xml''' file. The most important thing to note about this example is the use of the '''file=''' attribute to import other XML files. The filename specified with '''file=''' has to be '''relative''' to the current directory where the file calling it resides. Note the differences between segway.kinbody.xml and barrettwam.robot.xml.

<source lang="xml">
<Environment>

<bkgndcolor>0.3 0.7 0.8</bkgndcolor>

<camtrans>1.418 -1.234 2.963</camtrans>

<camrotaxis>0.724 0.302 0.619 68</camrotaxis>


<KinBody file="data/segway.kinbody.xml">
<Translation>-0.0671 -0.0819 0.7550</Translation>
</KinBody>


<Robot file="../../robots/barrettwam.robot.xml" name="BarrettWAM">
<KinBody>
<Translation>-.22 -.14 -.346</Translation>
<Body type="dynamic">
<Geom type="cylinder">
<RotationAxis>1 0 0 -90</RotationAxis>
<radius>0.08</radius>
<height>0.6</height>
<diffusecolor>0.3 0.3 0.3</diffusecolor>
<Translation> 0.2286 0.1397 -0.346</Translation>
</Geom>
</Body>
</KinBody>
<translation>-0.754 0.3265 1.036</translation>
</Robot>


<KinBody name="floor">

<Body type="static">
<Geom type="box">
<extents>2 2 0.005</extents>
<diffuseColor>.6 .6 .6</diffuseColor>
<ambientColor>0.6 0.6 0.6</ambientColor>
</Geom>
</Body>
</KinBody>
</Environment>
</source>

== Robot Composition ==

The way we recommend managing robots composed of several sub-robots (like a humanoid composed of arms, legs, hands, etc) is to first create separate .kinbody files for just the kinematics and geometry of each separate
part (ie a hand.kinbody.xml and a arm.kinbody.xml). Then create a robot file that includes both the kinematics and defines the manipulators, sensors, and controllers:

<source lang="xml">
<robot>
<kinbody file="arm.kinbody.xml"/>
<kinbody file="hand.kinbody.xml"/>
<attachedsensor>
....
</attachedsensor>
<manipulator>
....
</manipulator>
</robot>
</source>

Sometimes for grasp planning, the hand needs to be treated as a robot, so we create a hand.robot.xml file as follows:

<source lang="xml">
<robot>
<kinbody file="hand.kinbody.xml"/>
<manipulator>
....
</manipulator>
</robot>
</source>

1. A robot can reference other robots through:

<source lang="xml">
<Robot>
<Robot file="a.robot.xml"/>
<Robot file="b.robot.xml"/>
</Robot>
</source>

Both a's and b's '''<Manipulator>''' and '''<AttachedSensor>''' tags will be used
in the parent robot, so you don' t have to copy their definitions.

2. It is possible to prefix the links and joints of a child robot by using the
'prefix' attribute:

<source lang="xml">
<Robot>
<KinBody prefix="left_" file="arm.kinbody.xml"/>
<KinBody prefix="right_" file="arm.kinbody.xml"/>
</Robot>
</source>

Now all links and joints will either start with '''left_''' or '''right_'''.

3. When the xml parser sees a body with the same name as another body,
it 'appends' the specified geometries to the original body. This allows the same link to be referenced/defined in multiple robot files (Note that it is not possible to change the original body coordinate system).

=== Attaching Separate Links ===

When a robot is composed of multiple parts defined in different files, it is necessary to attach links from the different files together so that the robot hierarchy can be complete. This is done by defining '''disabled''' dummy joints that attach two links together. These disabled joints do not show up in the robot's description and are only present to maintain the relative transformation between two links. For example, the robot '''robots/pa10schunk.robot.xml''' is composed of '''robots/pa10.kinbody.xml''' and '''robots/schunk_manip.kinbody.xml''', in order to join the two, the robot is defined in the following way:

<source lang="xml">
<KinBody file="pa10.kinbody.xml">
<KinBody file="schunk_manip.kinbody.xml"/>
<Joint name="dummy" type="hinge" enable="False">
<body>link7</body>
<body>gripper_base</body>
<limits>0 0</limits>
</Joint>
</KinBody>
</source>

where '''link7''' is a link of the pa10 arm and '''gripper_base''' is a link of the gripper. The lower and upper joint limits are all 0, which OpenRAVE recognizes as a dummy joint.

=== Joining A Robot Arm and Hand ===

It is possible to load robots and bodies from COLLADA files by specifying the collada filename through the '''file''' attribute. For example, the following robot is a combination of an arm defined in OpenRAVE XML and a hand defined in COLLADA (download schunkSDHHand from [http://opengrasp.sourceforge.net/Downloads.html OpenGrasp]). The dummy joint is used to join the arm end effector with the hand base.

<source lang="xml">
<robot>
<robot file="robots/kuka-kr5-r650.robot.xml"></robot>
<robot prefix="hand_" file="schunkSDHhand.dae"></robot>
<kinbody>
<body name="hand_root">
<offsetfrom>link6</offsetfrom>
<translation>0.03 0 0</translation>
<rotationaxis>0 1 0 90</rotationaxis>
</body>
<joint type="hinge" enable="false">
<body>link6</body>
<body>hand_root</body>
<limits>0 0</limits>
</joint>
</kinbody>
<manipulator name="arm">
<base>base</base>
<effector>link6</effector>
<joints>hand_Bone_B1_Joint hand_Bone_B2_Joint hand_Bone_B3_Joint hand_Bone_A1_Joint hand_Bone_A2_Joint hand_Bone_A3_Joint hand_Bone_C1_Joint hand_Bone_C2_Joint hand_Bone_C3_Joint</joints>
<closingdirection>0 1 1 0 1 1 0 1 1</closingdirection>
<direction>1 0 0</direction>
</manipulator>
</robot>
</source>

Final robot: [[image:collada_sdh_kuka.jpg|150px]]

=== Dual-arm example ===

Here is an example file of having a robot composed of two arms attached to a common link named '''chest'''.

<source lang="xml">
<Robot name="schunk-dualarm">
<KinBody>
<body name="chest">
<geom type="box">
<extents>0.1 0.1 0.4</extents>
<translation>0 0 0.4</translation>
</geom>
</body>

<KinBody>
<KinBody prefix="l_" file="schunk-lwa3.kinbody.xml"></KinBody>
<RotationAxis>1 0 0 90</RotationAxis>
<translation>0 -0.1 0.7</translation>
</KinBody>

<KinBody>
<KinBody>prefix="r_" file="schunk-lwa3.kinbody.xml"></KinBody>
<RotationAxis>1 0 0 -90</RotationAxis>
<translation>0 0.1 0.7</translation>
</KinBody>

<joint name="leftdummy" type="hinge" enable="false">
<body>chest</body>
<body>l_base</body>
<limits>0 0</limits>
</joint>
<joint name="rightdummy" type="hinge" enable="false">
<body>chest</body>
<body>r_base</body>
<limits>0 0</limits>
</joint>
</KinBody>

<Manipulator name="leftarm">
<base>l_base</base>
<effector>l_link7</effector>
<armjoints>l_j0 l_j1 l_j2 l_j3 l_j4 l_j5 l_j6</armjoints>
</Manipulator>
<Manipulator name="rightarm">
<base>r_base</base>
<effector>r_link7</effector>
<armjoints>r_j0 r_j1 r_j2 r_j3 r_j4 r_j5 r_j6</armjoints>
</Manipulator>
</Robot>
</source>

Single arm: [[image:schunk-lwa3.jpg|300px]]

Dual arm: [[image:schunk-lwa3-dual.jpg|300px]]

== Custom XML ==

Openrave provides much more flexibility in creating and defining custom XML readers for interfaces. First the <environment> XML tag supports creating any interface type and supports loading plugins. For example:

<source lang="xml">
<Environment>
<plugin>libcustomreader</plugin>
<robot name="wam" file="robots/barrettwam.robot.xml"/>
<controller type="CustomController" robot="wam" args="">
..custom data....
</controller>
<module type="basemanipulation" args="wam"/>
</Environment>
</source>

In this example, openrave will first load the plugin, then will create a robot, and then will create a controller that is attached to the robot, then will create the basemanipulation module giving it the robot name as the argument.

Furthermore, using EnvironmentBase::RegisterXMLReader, it is possible to set a parser for custom XML tags for each interface type. For those curious on how to take advantage of custom readers, please refer to examples/plugincpp/customreader.cpp on how to attach a custom XML reader to a controller.

These changes will allow people to setup all their specific environment settings in the XML files without having to rely on external scripts or other programs to do it. Note that OpenRAVE processes tags in depth first order.

== Sensor ==

It is possible to have XML files that declare a sensor and its internal parameters. For example, '''data/camera.sensor.xml''' can look like:

<source lang="xml">
<sensor type="BaseCamera">
<KK>640 640 320 240</KK>
<width>640</width>
<height>480</height>
<framerate>5</framerate>
<color>0.5 0.5 1</color>
</sensor>
</source>

In order to attach a sensor defined by a file to a robot link do:

<source lang="xml">
<Robot>

<AttachedSensor name="MyCamera">
<sensor file="camera.sensor.xml">
</sensor>
</AttachedSensor>
</Robot>
</source>

It is also possible to put a sensor directly in the environment without a robot. Such a sensor will not have any geometry associated with it, and will only act as a sensing source.

<source lang="xml">
<Environment>

<sensor name="mysensor" file="camera.sensor.xml">

<translation>0 1 0</translation>
<rotationaxis>1 0 0 45</rotationaxis>
</sensor>
</Environment>
</source>

== XML Reference ==

'''Note:''' All XML handling is done in '''src/libopenrave-core/xmlreaders.cpp'''. If there's any parameters that are not explained well, make sure to check out that source file for further reference.

'''Note:''' You can find details on joints on : [http://opende.sourceforge.net/wiki/index.php/Manual_%28Joint_Types_and_Functions%29 ODE Manual page (joints)].

Here's a list of all possible fields the XML supports in a hierarchical structure.

'''environment''' - '''attributes:''' file
'''bkgndcolor''' - 3 floats
'''camrotaxis''' - 4 floats
'''camtrans''' - 3 floats
'''kinbody''' - '''attributes:''' name, file
'''robot''' - '''attributes:''' name, file
'''planner''' - '''attributes:''' type, file
'''sensorsystem''' - '''attributes:''' type, file
'''controller''' - '''attributes:''' type, file, robot, args
'''module''' - '''attributes:''' type, file
'''inversekinematicssolver''' - '''attributes:''' type, file
'''physicsengine''' - '''attributes:''' type, file
'''sensor''' - '''attributes:''' type, file
'''collisionchecker''' - '''attributes:''' type, file
'''trajectory''' - '''attributes:''' type, file
'''viewer''' - '''attributes:''' type, file
'''server''' - '''attributes:''' type, file

'''kinbody''' - '''attributes:''' name, file, prefix, type, makejoinedlinksadjacent
'''adjacent''' - 2 body names
'''body''' - '''attributes:''' name, type (dynamic, static)
'''geom''' - '''attributes:''' name, type (box, sphere, trimesh, cylinder), render (true,false), modifiable (true,false)
'''ambientcolor''' - 3 float
'''collision''' - '''attributes:''' file, scale
'''diffusecolor''' - 3 float
'''extents''' - 3 float [box]
'''height''' - float [cylinder]
'''quat''' - 4 float
'''radius''' - float [cylinder, sphere]
'''render''' - '''attributes:''' file, scale
'''rotationaxis''' - 4 float
'''rotationmat''' - 9 float
'''translation''' - 3 float
'''transparency''' - 1 float
'''vertices''' - 9*N floats where each 9 values defines 1 triangle with 3 vertices
'''mass''' - '''attributes:''' type (box, sphere, custom)
'''com''' - 3 float
'''density''' - float
'''inertia''' - 9 float
'''radius''' - float
'''total''' - float
'''joint''' - '''attributes:''' enable (true, false), type (hinge, slider, universal, hinge2, spherical), circular(true, false), mimic_pos (math equation), mimic_vel (math equation), mimic_accel (math equation)
'''anchor''' - 3 floats [hinge, hinge2, universal, spherical]
'''axis''' - 3 floats [hinge, slider]
'''axis1''' - 3 floats [hinge2, universal]
'''axis2''' - 3 floats [hinge2, universal]
'''body''' - string
'''limits''' - 2*dof floats in radians if applicable (first two specify first joint limits, etc)
'''limitsdeg''' - 2*dof floats in degrees if applicable (first two specify first joint limits, etc)
'''limitsrad''' - 2*dof floats in radians if applicable (first two specify first joint limits, etc)
'''maxvel''' - dof floats
'''mode''' - int [amotor]
'''offsetfrom''' - link name
'''resolution''' - float
'''weight''' - dof floats
'''initial''' - dof floats
'''jointvalues'''
'''kinbody - '''attributes:''' name, file, prefix
'''mass''' - '''attributes:''' type (box, sphere, custom)
'''density''' - float
'''radius''' - float
'''total''' - float
'''modelsdir''' - string
'''offsetfrom''' - bodyname
'''quat''' - 4 float
'''rotationaxis''' - 4 float
'''rotationmat''' - 9 float
'''translation''' - 3 float
'''transparency''' - 1 float

'''robot''' - '''attributes:''' name, file, prefix, type (robot plugin type)
'''attachedsensor''' - '''attributes:''' name
'''link'''
'''quat'''
'''rotationaxis'''
'''rotationmat'''
'''translation'''
'''sensor''' - '''attributes:''' type
'''...''' - fields defined by SensorBase class instantiated by type
'''controller''' - type args
'''jointvalues'''
'''kinbody''' - name
'''manipulator''' - '''attributes:''' name
'''armjoints''' - n joint names
'''base''' - link name
'''closed''' - k floats
'''effector''' - link name
'''iksolver''' - string
'''gripperjoints''' - k joint names
'''closingdirection''' - k floats
'''palmdirection''' - 3 floats
'''quat''' - 4 floats
'''rotationaxis''' - 4 floats
'''rotationmat''' - 9 floats
'''translation''' - 3 floats
'''quat''' - 4 float
'''robot''' - name, file, type
'''rotationaxis''' - 4 float
'''rotationmat''' - 9 float
'''translation''' - 3 float

Format:COLLADA

2011-07-15T16:21:12Z

Rdiankov:

__NOTITLE__

= COLLADA Robot Specification Version 0.2 =

The [https://collada.org/mediawiki/index.php/COLLADA_-_Digital_Asset_and_FX_Exchange_Schema COLLADA] format is used to specify all robot and scene related information. By default, COLLADA 1.5 handles geometry, visual effects, physical properties, and kinematics. This document describes how to extend the format to handle robot-specific information. An official example of a COLLADA extension can be found [http://www.collada.org/mediawiki/index.php/Morph_weights_EXT_extension here].

COLLADA allows extensions of any of its tags using the '''<extra>''' tag. Each '''<extra>''' defines what type of information to provide (ie manipulator, sensor, collision), and a format for that information, also called '''technique'''. All custom data defined here uses the '''OpenRAVE''' technique.

There are one-to-one correspondences between the OpenRAVE interface types and COLLADA tags:

* Robot <-> articulated_system
* KinBody <-> kinematics_model
* Sensor <-> sensor (new)

= interface_type =

== Introduction ==

Specifies the type of kinematics body/robot type to instantiate inside the code.

== Concepts ==

All of the kinematics body methods can be overridden with new implementations. Because this requires loading user code, a user-provided instantiation has to be used. The interface type specifies what this type is and where to load it from.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <articulated_system>, <kinematics_model>
|-
| Child elements || See the following subsection.
|-
| Other
|}

== Child Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <interface> || Contains the string id of the interface || 1
|-
| <plugin> || Optional. Contains the string of the location of the shared object object to load. Because plugin prefixes and suffixes depends on the OS, a prefix and suffix independent name can be specified. || 0 or 1
|-
|}

== Example ==

<source lang="xml">
<extra type="interface_type">
<technique profile="OpenRAVE">
<interface>MyGenericRobot</interface>
<plugin>myplugin</plugin>
</technique>
</extra>
</source>

= manipulator =

== Introduction ==

Defines a subset of the robot that acts as an '''arm''' and a '''gripper'''.

== Concepts ==

The arm is a chain of joints whose '''end effector''' is treated as a gripper. The arm is extracted from the '''origin''' and '''tip''' links. The '''tip''' contains the manipulator frame of reference. The gripper axes have to be specified manually. The direction is used as a hint for grasping and inverse kinematics.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <articulated_system>
|}

== Child Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <frame_origin> || The base frame that the arm starts at || 1
|-
| <frame_tip> || The end effector frame the arm ends at || 1
|-
| <gripper_joint> || Defines one joint of the gripper || 0 or more
|-
| <iksolver> || Defines properties of inverse kinematics functions when used with the arm || 0 or more
|}

== Attributes for <frame_origin>/<frame_tip> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| link || '''xs:token''' || Required. References the SID of a <link> defined in <kinematics_model>.
|}

== Child Elements for <frame_tip> ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <translate> || Translation. See main entry in Core. || 0 or more
|-
| <rotate> || Rotation axis. See main entry in Core. || 0 or more
|}

== Attributes for <gripper_joint> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| joint || '''xs:token''' || Required. The reference of the joint in the instantiated kinematics model that is part of the gripper.
|}

== Child Elements for <gripper_joint> ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <closing_direction> || '''common_float_or_param_type''' that contains the default closing direction of an axis on the joint. If a closing direction is not specified for an axis in the joint, it defaults to 0. || 0 or more
|-
|}

== Attributes for <gripper_joint>/<closing_direction> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| axis || '''xs:token''' || Required. The SID of the axis inside the referenced joint.
|}

== Attributes for <iksolver> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| type || '''xs:token''' || Required. The type of the inverse kinematics to set a property for. Possible types are: '''Transform6D, Rotation3D, Translation3D, Direction3D, Ray4D, Lookat3D, TranslationDirection5D'''.
|}

== Child Elements for <iksolver> ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <free_joint> || Specifies one free joint to use for ik. || 0 or more
|-
| <interface_type> || Optional. Specifies the interface of the inverse kinematics solver. || 0 or 1
|}

== Attributes for <iksolver>/<free_joint> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| joint || '''xs:token''' || Required. The reference of the joint in the instantiated kinematics model that is part of the manipulator chain.
|-
| stepsize || '''xs:float''' || The discretization value of this joint when searching for solutions
|}

== Details ==

The current IK types are:

* Transform6D - end effector reaches desired 6D transformation
* Rotation3D - end effector reaches desired 3D rotation
* Translation3D - end effector origin reaches desired 3D translation
* Direction3D - direction on end effector coordinate system reaches desired direction
* Ray4D - ray on end effector coordinate system reaches desired global ray
* Lookat3D - direction on end effector coordinate system points to desired 3D position
* TranslationDirection5D - end effector origin and direction reaches desired 3D translation and direction. Can be thought of as Ray IK where the origin of the ray must coincide.

The IK types are meant to be hints as to how a manipulator can be used. Multiple IK types can be set for one manipulator and differing free joint values. It is possible for a post-processing stage to determine what IK types are best suited for a particular manipulator structure, and then add those into the COLLADA file.

* Why is a manipulator frame necessary?
** Answer: Manipulator frames allow the user to define a coordinate system where it makes target tasks easier to complete. In this regard, the manipulator frame can be freely chosen by the user without worrying about destroying the link coordinate systems. For example, link frames are usually aligned with joint axes and center of masses and robot state is defined by their 6D transform in space. Having them also represent task-specific information could destroy consistency when the task changes. Also, the z-axis of the manipulator frame can define the "direction" of the manipulator. Direction can be used in many places like sensor line of sight and grasping approach, which makes it possible to quickly use the robot for planning.

* Question: For dual arm manipulation, would a leftright manipulator ever be used including all joints? In this case, will it might be necessary to define two frame tips (one for left arm and one for right arm)?
** Answer: Having a leftright manipulator destroys the one-to-one correspondence between gripper joints and ik solver, and not much is gained. So better to have only have one frame tip and origin and treat two arms as separate. The constraint between the end effectors of the two arms is not always rigid, it very task dependent. Therefore, the user should take care of the dual relation.

* Question: What about closing gripper direction for complex hands? Fingers with many DOF might need special grasping strategies.
** Answer: The closing direction just provide a hint as to the usage. The real gripper movement depends on the grasp strategy, which is beyond the definition of this scope.

== Example ==

The example defines an arm with an end effector at link wam7 with a local coordinate system. It also defines two gripper axes. For the 'transform6d' inverse kinematics type, it specifies that the free joint should be 'joint4'.

<source lang="xml">
<extra type="manipulator" name="leftarm">
<technique profile="OpenRAVE">
<frame_origin link="wam0"/>
<frame_tip link="wam7">
<translate>0.0 0.0 0.22</translate>
<rotate>0.0 1.0 0.0 90.0</rotate>
</frame_tip>
<gripper_joint joint="jointname">
<closing_direction axis="axis0">
<float>1</float>
</closing_direction>
</gripper_joint>
<gripper_joint joint="jointname2">
<closing_direction axis="axis0">
<float>-1</float>
</closing_direction>
</gripper_joint>
<iksolver type="Transform6D">
<free_joint joint="jointname3"/>
<interface_type>
<technique profile="OpenRAVE">
<interface>WAM7ikfast</interface>
<plugin>WAM7ikfast</plugin>
</technique>
</interface_type>
</iksolver>
<iksolver type="Translation3D">
<free_joint joint="jointname4"/>
</iksolver>
</technique>
</extra>
</source>

= collision =

== Introduction ==

Links all possible collision meshes and properties for one kinematics body. The meshes depends on the usage.

== Concepts ==

A link can have three different collision meshes:
* for visual rendering
* for self-collisions
* for environment collisions

For each link, COLLADA will store three geometries in the '''<library_geometries>'''. The geometries will have an <extra> tag that specifies which usage they are meant to. The '''self''' and '''env''' will be referenced inside the visual geometry.

The tag also stores information about what pairs of links can be completely ignored from self-collision detection. These links are either adjacent to each other, or so far from each other that no configuration of the robot can get them into possible collision.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <kinematics_model>
|}

== Child Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <bind_instance_geometry> || The geometry used for a particular link || 0 or more
|-
| <ignore_link_pair> || Specifies two links pairs whose self-collision should not be checked || 0 or more
|}

== Attributes for <bind_instance_geometry> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| type || '''xs:token''' || Required. The usage type: '''environment''' or '''self'''
|-
| link || '''xs:token''' || Required. References the SID of a <link> defined in <kinematics_model>. This link is where the geometries will be added.
|-
| url || '''xs:anyURI''' || Required. The URL of the location of the <geometry> element to instantiate. Can refer to a local instance or external reference.
|}

== Attributes for <ignore_link_pair> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| link0 || '''xs:token''' || Required. References the SID of a <link> defined in <kinematics_model>. One of the links defining the pair to be ignored.
|-
| link1 || '''xs:token''' || Required. References the SID of a <link> defined in <kinematics_model>. One of the links defining the pair to be ignored.
|}

== Details ==

Convex decompositions can be defined by using one geometry per convex hull and attaching multiple geometries to the same link.

<ignore_link_pair> tags help self-collision detection to help prune possibilities. The adjacency information is not just the neighboring links. It is also meant to prune any collisions between two links that *cannot* possibly happen if the robot maintains its joint limits. This information depends not only on the kinematics of the robot, but also on the geometry of every link. Also for triplets of joints j1, j2, j3 that intersect at a common axis, you would want to add (j1,j2),(j2,j3),(j1,j3).

== Example ==

<source lang="xml">
<library_visual_scenes>
<node id="mynode">
<instance_geometry url="#linka_vis0"/>
<instance_geometry url="#linka_vis1"/>
</node>
</library_visual_scenes>
<library_geometries>
<geometry id="linka_vis0"/>
<geometry id="linka_vis1"/>
<geometry id="linka_env0"/>
<geometry id="linka_env1"/>
<geometry id="linka_self"/>
<geometry id="linkb_env0"/>
</library_geometries>
<library_kinematics_models>
<kinematics_model>
<extra type="collision">
<technique profile="OpenRAVE">
<bind_instance_geometry type="environment" link="linka" url="#linka_env0"/>
<bind_instance_geometry type="environment" link="linka" url="#linka_env1"/>
<bind_instance_geometry type="self" link="linka" url="#linka_self"/>
<bind_instance_geometry type="environment" link="linkb" url="#linkb_env0"/>
<ignore_link_pair link0="linka" link1="linkb"/>
</technique>
</extra>
</library_kinematics_models>
</source>

= library_sensors =

== Introduction ==

Provides a library in which to place <sensor> elements.

== Concepts ==

Allows sensors to be stored as modular resources in libraries. Can be easily referenced through files.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <COLLADA>
|}

= sensor =

== Introduction ==

Defines a sensor's type and the geometric and intrinsic parameters.

== Concepts ==

Each sensor will be associated with a particular sensor type; depending on the sensor type, the parameters that need to be set will change. The parameters should contain everything necessary to simulate the sensor accurately. They *should not* contain parameters that define the format and transfer of the data.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <articulated_system>
|}

== Attributes ==

{| border=1 cellspacing=0 cellpadding=3
|-
| type || '''xs:token''' || Required. The type of the sensor. Possible types are: '''base_pinhole_camera, base_stereo_camera, base_laser2d, base_laser3d, base_flash_laser, base_encoder, base_force6d, base_imu, base_odometry'''
|-
| id || '''xs:ID''' || Required. A text string containing the unique identifier of the <sensor> element. This value must be unique within the instance document.
|}

== Child Elements ==

'''common''':

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <interface_type> || Optional. Contains the interface type to load the sensor with. || 0 or 1
|}

'''type base_pinhole_camera''':

Simple pin hole camera defined by an intrinsic matrix. The camera can support multiple image dimensions with multiple channel formats. It is not clear whether all supported formats for one camera should be enumerated in one <sensor> tag, or there should be multiple sensor tags for each different type where the sensors are exclusively mutual.

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <image_dimensions> || Contains a '''int3_type''' that specifies the image width, height, and channels. || 1
|-
| <format> || Contains a string that specifies the format of every value in the image. Possible types are '''uint8, uint16, uint32, int8, int16, int32, float32, float64'''. || 1
|-
| <measurement_time> || Contains a '''float_type''' that specifies time between images (ie exposure time). || 0 or 1
|-
| <intrinsic> || Contains a '''float2x3_type''' that specifies the intrinsic parameters defining the principal point, field of view, and skew. || 1
|-
| <focal_length> || Contains a '''float_type''' that specifies the physical focal length of the camera. || 0 or 1
|-
| <distortion_model> || The distortion model to use. It has a '''type''' attribute specifying the actual model type, and contains a '''list_of_floats_type''' that specifies the distortion coefficients of the model. || 0 or 1
|}

'''type base_stereo_camera:'''

Uses two cameras together to extract a depth map. The stereo camera's coordinate system is in the first instanced camera.

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <instance_sensor> || The camera sensors, the scan time should be equal || 2
|}

== Attributes for <instance_sensor> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| url || '''xs:anyURI''' || Required. The URL of the location of the <sensor> element to instantiate.
|}

== Child Elements for <instance_sensor> ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <rectification> || Contains a '''float3x3_type''' that specifies a homography which takes an image to the ideal stereo image plane so that epipolar lines in both stereo images are parallel. The homography transforms from the second image to the first image. || 1
|}

'''type base_laser2d''':

Single scan from a planar laser range-finder along the xy plane.

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <angle_range> || Contains a '''float2_type''' that specifies the minimum and maximum angles (degrees) of the laser range. || 1
|-
| <distance_range> || Contains a '''float2_type''' that specifies the minimum and maximum distance of the laser. || 1
|-
| <angle_increment> || Contains a '''float_type''' that specifies the angular distance between measurements (degrees). || 1
|-
| <time_increment> || Contains a '''float_type''' that specifies the time between measurements (seconds). If your scanner is moving, this will be used in interpolating position of 3d points. || 1
|-
| <measurement_time> || Contains a '''float_type''' that specifies the time between scans (seconds) || 1
|}

'''type base_laser3d:'''

'''type base_flash_laser:'''

'''type base_encoder:'''

'''type base_force6d:'''

'''type base_imu:'''

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <measurement_time> || Contains a '''float_type''' that specifies the time between scans (seconds). || 1
|-
| <rotation_covariance> || The uncertainty covariance matrix (3x3 row-major matrix) in x, y, and z axes. || 1
|-
| <angular_velocity_covariance> || The uncertainty covariance matrix (3x3 row-major matrix) in x, y, and z axes. || 1
|-
| <linear_acceleration_covariance> || The uncertainty covariance matrix (3x3 row-major matrix) in x, y, and z axes. || 1
|}

'''type base_odometry:'''

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <measurement_time> || Contains a '''float_type''' that specifies the time between scans (seconds). || 1
|-
| <target> || The name of the target whose odometry is being measured || 0 or 1
|}

== Example ==

Example using a default sensor with a custom interface

<source lang="xml">
<extra type="library_sensors" id="libsensors">
<technique profile="OpenRAVE">
<sensor type="base_laser2d" id="ExampleLaser1">
<angle_min>-90</angle_min>
<angle_max>90</angle_max>
<range_min>0.01</range_min>
<range_max>4.0</range_max>
<angle_increment>1</angle_increment>
<time_increment>0.0005</time_increment>
<measurement_time>0.025</measurement_time>
<interface_type>
<technique profile="OpenRAVE">
<interface>BaseLaser2D</interface>
</technique>
</interface_type>
</sensor>
</technique>
</extra>
</source>

Using a non-default, custom sensor

<source lang="xml">
<extra type="library_sensors" id="libsensors">
<technique profile="OpenRAVE">
<sensor type="BaseLaser2D" id="ExampleLaser1">
<minangle>-135</minangle>
<maxangle>135</maxangle>
<resolution>0.35</resolution>
<maxrange>5</maxrange>
<scantime>0.1</scantime>
<color>0.5 0.5 1</color>
</sensor>
</technique>
</extra>
</source>

Develop a formal sensor XML file format for different sensor types.

= attach_sensor =

== Introduction ==

Attaches a sensor to a link of the robot.

== Concepts ==

The sensor comes from the sensor library. It can be attached anywhere onto a link defined from the kinematics section. The sensor will maintain a constant transformation between the link.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <articulated_system>
|}

== Child Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <instance_sensor> || Instantiate a sensor. || 1
|-
| <frame_origin> || The base link that the sensor is attached to. || 1
|}

== Attributes for <frame_origin> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| link || '''xs:token''' || Required. References the SID of a <link> defined in <kinematics_model>.
|}

== Child Elements for <frame_origin> ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <translate> || Translation. See main entry in Core. || 0 or more
|-
| <rotate> || Rotation axis. See main entry in Core. || 0 or more
|}

== Example ==

<source lang="xml">
<extra type="attach_sensor" name="left_head_camera">
<technique profile="OpenRAVE">
<instance_sensor url="#pgr_camera"/>
<frame_origin link="head">
<translate>0 1 0</translate>
<rotate>0 1 0 90</rotate>
</frame_origin>
</technique>
</extra>
</source>

= formula/technique =

== Introduction ==

Full specifies a formula for a joint and annotates it with extra information necessary for robotics.

== Concepts ==

The original <formula>/<technique_common> supports only one equation for the value of the joint. More complex kinematics systems have more than one degree of freedom per joint and use the partial derivatives of the equation to compute Jacobians and simulate physics.

This "OpenRAVE" technique for <formula> can specify partial derivatives of the position
equation for computing velocity and accelerations.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <formula>
|}

== Child Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <equation> || Equation in MathML format. Used to specify the position and partial derivatives. || 0 or more
|}

== Attributes for <equation> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| type || '''xs:token''' || Required. can be one of "position", "first_partial", or "second_partial".
|-
| target || '''xs:token''' || If 'type' is "first_partial" or "second_partial", then fill this with the variable taking the partial derivative with respect to.
|}

== Example ==

<source lang="xml">
<technique profile="OpenRAVE">
<equation type="position">
<math>
<apply>
<plus/>
<apply>
<times/>
<cn>0.333330</cn>
<csymbol encoding="COLLADA">kmodel1/joint0</csymbol>
</apply>
<cn>0.872700</cn>
</apply>
</math>
</equation>
<equation type="first_partial" target="kmodel1/joint0">
<math>
<cn>0.333330</cn>
</math>
</equation>
</technique>
</source>

= library_actuators =

== Introduction ==

Provides a library in which to place <actuator> elements.

== Concepts ==

Allows actuators to be stored as modular resources in libraries. Can be easily referenced through files.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <COLLADA>
|}

= actuator =

== Introduction ==

An actuator provides force/momentum/action to kinematics joints.

== Concepts ==

Defines a actuator's physical properties necessary to simulate dynamics and control algorithms of a robot. They '''should not''' contain parameters that define the format and transfer of the data to and from actuators.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <articulated_system>
|}

== Attributes ==

{| border=1 cellspacing=0 cellpadding=3
|-
| type || '''xs:token''' || Required. The type of the actuator. Possible types are: '''motor'''
|-
| id || '''xs:ID''' || Required. A text string containing the unique identifier of the <actuator> element. This value must be unique within the instance document.
|}

== Child Elements ==

'''common''':

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <interface_type> || Optional. Contains the interface type to load the actuator with. || 0 or 1
|}

'''type electric_motor''':

Converts electrical energy into mechanical energy usually using magnetic fields and conductors. The '''speed''' of a motor is measured in revolutions/Time (Time is defined by the <asset> tag and usually measured in seconds). DC Motor Theory References:

* http://hades.mech.northwestern.edu/index.php/Brushed_DC_Motor_Theory

* http://en.wikipedia.org/wiki/Brushed_DC_electric_motor

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <assigned_power_rating> || Contains a '''float_type''' that specifies the nominal power the electric motor can safely produce. Units are '''Mass * Distance² * Time-³'''. || 1
|-
| <max_speed> || Contains a '''float_type''' that specifies the maximum speed of the motor. Units are '''Time-¹'''. || 1
|-
| <no_load_speed> || Contains a '''float_type''' that specifies the speed of the motor powered by the nominal voltage when the motor provides zero torque. Units are '''Time-¹'''. || 0 or 1
|-
| <nominal_torque> || Contains a '''float_type''' that specifies the maximum torque the motor can provide continuously without overheating. Units are '''Mass * Distance * Time-²'''. || 1
|-
| <nominal_voltage> || Contains a '''float_type''' that specifies the nominal voltage the electric motor can safely produce. Units are '''Mass * Distance² * Time-² * Charge'''. || 1
|-
| <rotor_inertia> || Contains a '''float_type''' that specifies the inertia of the rotating element about the axis of rotation. Units are '''Mass * Distance²'''. || 1
|-
| <speed_constant> || Contains a '''float_type''' that specifies the constant of proportionality relating speed to voltage. Units are '''Mass-¹ * Distance-² * Time * Charge-¹'''. || 1
|-
| <speed_torque_gradient> || Contains a '''float_type''' that specifies the slope of the speed-torque curve, approximately equal to the no load speed divided by the stall torque. Units are ''' Mass-¹ * Distance-¹ * Time-¹'''. || 1
|-
| <starting_current> || Contains a '''float_type''' that specifies the current through the motor at zero velocity, equal to the nominal voltage divided by the terminal resistance. Also called the stall current. Units are '''Time-¹ * Charge'''. || 1
|-
| <terminal_resistance> || Contains a '''float_type''' that specifies the resistance of the motor windings. Units are '''Mass * Distance² * Time-¹ * Charge-²'''. || 1
|-
| <torque_constant> || Contains a '''float_type''' that specifies the proportion relating current to torque. Units are '''Mass * Distance * Time-¹ * Charge-¹'''. || 1
|}

Related variables, but not inserted in the electric_motor specification:

* Stall torque - The time it takes the unloaded motor to reach 63% of its no load speed under a constant voltage, starting from rest. Proportional to the inertia of the rotor and inversely proportional to the square of the the torque constant.
* Max. efficiency - The maximum efficiency of the motor in converting electrical power to mechanical power. This maximum efficiency typically occurs at high speed and low torque; the efficiency is zero at zero speed and zero torque, since the mechanical power is τω.
* No load current - The current required to spin the motor at the no load condition (i.e., the current needed to provide the torque necessary to overcome friction).
* Nominal current (max. continuous current) - The current that yields the maximum continuous torque. This maximum is determined by thermal characteristics of the motor. The power dissipated by the motor as heat is i2R. Larger currents are acceptable intermittently, but large continuous currents may cause the motor to overheat.
* Mechanical time constant - The time it takes the unloaded motor to reach 63% of its no load speed under a constant voltage, starting from rest. Proportional to the inertia of the rotor and inversely proportional to the square of the the torque constant.
* Terminal inductance - The inductance of the motor windings.
* Thermal resistance housing-ambient
* Thermal resistance winding-housing
* Thermal time constant winding.

== Example ==

<source lang="xml">
<extra type="library_actuators" id="libactuators">
<technique profile="OpenRAVE">
<actuator type="electric_motor" id="ExampleMotor1">
<assigned_power_rating>1.0</assigned_power_rating>
<max_speed>3000</max_speed>
<no_load_speed>3990</no_load_speed>
<nominal_torque>0.012</nominal_torque>
<nominal_voltage>24.0</nominal_voltage>
<rotor_inertia>0.0000023</rotor_inertia>
<speed_constant>173.0</speed_constant>
<speed_torque_gradient>130000.0</speed_torque_gradient>
<starting_current>0.578</starting_current>
<terminal_resistance>41.5</terminal_resistance>
<torque_constant>0.0552</torque_constant>
</actuator>
</technique>
</extra>
</source>

= attach_actuator =

== Introduction ==

Attaches an actuator to a joint.

== Concepts ==

The actuator comes from the actuator library.

== Related Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
| Parent elements || <articulated_system>
|}

== Child Elements ==

{| border=1 cellspacing=0 cellpadding=3
|-
!width=20%| Element !! Description !! Occurrences
|-
| <instance_actuator> || Instantiate an actuator. || 1
|-
| <bind_actuator> || Binds the actuator to a joint. || 1
|}

== Attributes for <bind_actuator> ==

{| border=1 cellspacing=0 cellpadding=3
|-
| joint || '''xs:token''' || Required. The reference of the joint in the instantiated kinematics model that is part of the manipulator chain.
|}

== Example ==

<source lang="xml">
<extra type="attach_actuator" name="motor0">
<technique profile="OpenRAVE">
<instance_actuator url="#ExampleMotor1"/>
<bind_actuator joint="kmodel0/myjoint"/>
</technique>
</extra>
</source>

= COLLADA Usage =

== COLLADA Format Notes ==

* '''articulated_system''' tag is equivalent to OpenRAVE robot
** if child is a '''motion''' tag, get accelerations and velocity limits from it
* '''kinematics_model''' tag is equivalent to KinBody
* If visual_scene tag present, but no kinematics, then add each node tree as a rigid link.
* In order to set a static link in physics, use the <instance_rigid_body>/<dynamic> tag.

== Hard and Soft Joint Limits ==

In many scenarios, the controllers on the robots use joints limits which are smaller than the maximum limits. The controller limits are called '''soft limits''', while the hardware limits are called '''hard limits'''. In COLLADA, the specification is:

* '''hard limits''' - specified inside the <joint> tag using the <limits> tag.

* '''soft limits''' - specified inside the <articulated_system>/<kinematics>/<technique_common>/<axis_info> tag using the <limits> tag.

== Planning Weights ==

For each joint, a measure of how much a joint's movement impacts the robot (base joints have more impact than end effector joints). this information should be used by all planners to evaluate importance of joints. Calculating this accurately might require an offline process.

== Composition ==

Robots usually have grippers, robot arms, and robot bases in separate files, then we have one file that references all of them and specifies the links to merge together (ie, we do not complicate things by creating dummy joints). This can be done with articulated systems (<kinematics> tag supports multiple <instance_kinematics_model> tags).

== Geometric Primitives ==

Use COLLADA <brep> for spheres, cylinders, boxes, etc.

== Storing Convex Decompositions ==

Each link is composed of a set of convex hulls. Need to create one geometry per convex hull (<convex_mesh>?) and specify multiple geometries per <node>.

== Calibration vs Static Data ==

One thing that separates a base description of the robot from the real
robot that will be used in labs is calibration:
* where each sensor is with respect to the robot (6D pose)
* intrinsic parameters for each sensor
* joint offsets for encoder calibration
* controller parameters like PID gains for dynamic properties of motors
* possibly even link lengths depending on how much you trust the manufacturer

All these parameters will change per robot, and it won't be a good
idea asking every person to go and modify their one robot file.
Instead we should have a different calibration file that the main
collada file always references. It should be setup in such a way that the calibration file becomes optional.

== Controllers ==

Specifying controller parameters in the collada file falls somewhere
in between calibration parameters and parameters that will never
change and should be in the main robot file. In my opinion it is very
hard to find static parameters especially when considering controllers
in simulation along with real world controllers. Also, there's as many
control algorithms out there as planners, and I wouldn't feel
comfortable specifying planning algorithms and parameters inside a
robot file.

= COLLADA Samples Using OpenRAVE Extensions =

[https://openrave.svn.sourceforge.net/svnroot/openrave/data/robots/ Robot Database]

== Contributors ==

* University of Tokyo - Rosen Diankov and Ryohei Ueda