RobWorkProject
Dynamic WorkCell XML File Format

Table of Contents

Introduction

The dynamic workcell (DWC) XML file format have suffix .dwc.xml and follow the rules of standard XML. See also the section about dynamic workcells in the manual. A dynamic workcell can be loaded with rwsim::loaders::DynamicWorkCellLoader::load() :

DynamicWorkCell::Ptr dwc = DynamicWorkCellLoader::load("DynamicWorkCellFile.dwc.xml");

The dynamic workcell file referes to an existing workcell file, and adds dynamic concepts such as dynamic bodies, dynamic devices, mass, inertia, material properties, constraints, gravity, controllers, and sensors.

The DynamicWorkCell element is the root element in the fileformat and refers to the underlying WorkCell file:

<DynamicWorkcell workcell="pih.wc.xml">
    ...
</DynamicWorkcell>

XML Elements

In the following the different possible elements in the DWC format will be described.

DynamicWorkCell

Element DynamicWorkCell

Attributes

Child elements:

Example

<DynamicWorkcell workcell="pih.wc.xml">
    ...
</DynamicWorkcell>

Include

The dynamic workcell can be split into multiple files. The extension of a included file should be .xml (and not dwc.xml as it is not a valid dynamic workcell on its own).

Element Include

Attributes

Example

<Include file="include.xml" />

The included file must have a root element called IncludeData:

<IncludeData>
    ...
</IncludeData>

Everything inside the IncludeData element is interpreted as if it was inserted directly in the .dwc.xml file instead of the Include tag.

PhysicsEngine

For dynamic simulation different Physics Engines can be used. The PhysicsEngine element allows modification of parameters that are specific to the PhysicsEngine used. See also rwsim::simulator::PhysicsEngine .

Element PhysicsEngine

Child elements:


Child element Property

Attributes


Example The following example shows an example with properties for the Open Dynamics Engine (see rwsim::simulator::ODESimulator and ODE documentation for further information). All properties are optional, and the example shows the default values used for ODE.

<PhysicsEngine>
    <Property name="StepMethod">WorldStep</Property> <!-- WorldQuickStep/WorldStep/WorldFast1 -->
    <Property name="WorldCFM" type="float">0.0000001</Property>
    <Property name="WorldERP" type="float">0.2</Property>
    <Property name="SpaceType">Simple</Property> <!-- QuadTree/Simple/HashTable -->
    <Property name="MaxIterations" type="int">20</Property>
    <Property name="ContactSurfaceLayer" type="float">0.0001</Property>
    <Property name="MaxSepDistance" type="float">0.0005</Property>
    <Property name="MaxPenetration" type="float">0.0005</Property>
    <Property name="MaxCorrectingVelocity" type="float">0.1</Property>
</PhysicsEngine>

For similar options for the RobWorkPhysicsEngine (RWPE), please see rwsimlibs::rwpe::RWPEIsland::getDefaultPropertyMap documentation.

Gravity

Set the gravity in world coordinates.

Element Gravity

Example

<Gravity>0 0 -9.82</Gravity>

Materials

Each body in a dynamic workcell must be associated to a material and object type. These determine how bodies interact with each other by defining friction and restitution. The material database is made of the following four elements:

In practice the material database can be big, and often the materials are defined in a separate file (often named DynamicMaterialDataBase.xml) using the Include element.

MaterialData

Defines names and an optional descriptions of all materials used in the dynamic workcell. See also rwsim::dynamics::MaterialDataMap .

Element MaterialData

Child elements:


Child element Material

Attributes

Child elements:


Example

The following example shows the definition of a single material.

<MaterialData>
    <Default>Plastic</Default>
    <Material id="Plastic">
        <Description>Optional description</Description>
    </Material>
</MaterialData>

FrictionMap

Definition of friction between different materials defined in MaterialData . See also rwsim::dynamics::FrictionData .

Element FrictionMap

Child elements:


Child element Pair

Attributes

Child elements:


Child element FrictionData

Attributes

Child elements:


Example

<FrictionMap>
    <Pair first="Plastic" second="Plastic">
        <FrictionData type="Coulomb">
            <Mu>0.4</Mu>
        </FrictionData>
    </Pair>
</FrictionMap>

ObjectTypeData

Definition of different object types. This is primarily used for defining restitution between objects. See also rwsim::dynamics::ContactDataMap .

Element ObjectTypeData

Child elements:


Child element ObjectType

Attributes

Child elements:


Example

<ObjectTypeData>
    <Default>hardObj</Default>
    <ObjectType id="hardObj">
        <Description>A hard object. with low elasticity</Description>
    </ObjectType>
</ObjectTypeData>

ContactMap

Definition of restitution coefficients between different object types defined in ObjectTypeData . See also rwsim::dynamics::ContactDataMap::NewtonData .

Element ContactMap

Child elements:


Child element Pair

Attributes

Child elements:


Element ContactData

Attributes

Child elements:


Example

<ContactMap>
    <Pair first="hardObj" second="hardObj">
        <ContactData type="Newton">
            <cr>0.0</cr>
        </ContactData>
    </Pair>
</ContactMap>

Bodies

Bodies that should be a part of the simulation must be defined in the dynamic workcell. There are three available types:

FixedBody

Fixed bodies will typically be static environment, such as floors and walls. See also rwsim::dynamics::FixedBody .

Element FixedBody

Attributes

Child elements:

Example

<FixedBody frame="Floor" />

KinematicBody

Kinematic bodies can be controlled directly with velocities. See also rwsim::dynamics::KinematicBody .

Element KinematicBody

Attributes

Child elements:

Example

<KinematicBody frame="MovingBody">
    <MaterialID>Plastic</MaterialID>
</KinematicBody>

RigidBody

Rigid bodies moves due to forces acting on the bodies. Hence they require specification of dynamic parameters as mass and inertia. See also rwsim::dynamics::RigidBody .

Element RigidBody

Attributes

Child elements:


Child element Associate

Attributes


Example

<RigidBody frame="DynBodyFrame">
    <Mass>0.1</Mass>
    <EstimateInertia />
    <Integrator>Euler</Integrator>
    <Associate object="DynBodyGeometry" />
</RigidBody>

Devices

Devices that should be a part of the simulation must be defined in the dynamic workcell. There are two available types:

Please note that a Body that is part of a device is called a Link. A Body in the dynamic workcell format referes to a body that is not part of a device (it is free). A Link is part of a device and has its motion constrained. Because of this, the syntax for a Link and a Body is equivalent in practice.

KinematicDevice

See also rwsim::dynamics::KinematicDevice .

Element KinematicDevice

Attributes

Child elements:


Child element RefBase

Attributes


Example

 <KinematicDevice device="Robot">
    <KinematicBase frame="Base" />
    <KinematicJoint object="Joint0">
        <Mass>0</Mass> 
        <COG>0 0 0</COG>
        <Inertia>0 0 0 0 0 0 0 0 0</Inertia>
        <MaterialID>Plastic</MaterialID> 
    </KinematicJoint>
    ...
 </KinematicDevice>

RigidDevice

See also rwsim::dynamics::RigidDevice .

Element RigidDevice

Attributes

Child elements:


Child element ForceLimit

Attributes


Example

 <RigidDevice device="UR1">
    <ForceLimit joint="Joint0">1000</ForceLimit>
    <FixedBase frame="Base">
        <MaterialID>Plastic</MaterialID> 
    </FixedBase> 
    <Link object="Joint0">
        <Mass>3.8</Mass>
        <EstimateInertia/>
        <MaterialID>Plastic</MaterialID> 
    </Link> 
    ...
 </RigidDevice>

SuctionCup

The SuctionCup element is not documented yet.

Constraints

The only way to constraint bodies is to use devices. In some cases it might however be useful to constrain arbitrary bodies without requiring that the bodies are part of the same device. This could for instance be if one wants to model a spring. The Constraint element is the equivalent of a rwsim::dynamics::Constraint objects.

Element Constraint

Attributes

Child elements:

Note the Spring element can be defined under the Constraint or after the Constraint with a reference to the name of the constraint.

Example of a Fixed constraint:

<Constraint name="FixedConstraint" type="Fixed" parent="Parent" child="Child" />

Example of a non-fixed constraint (the spring works for the one linear and two angular directions that are not constrained by the PrismaticUniversal constraint):

<Constraint name="ComplianceConstraint" type="PrismaticUniversal" parent="Parent" child="Child">
    <Transform3D>
        <Pos>0 0 0.01</Pos>
        <RPY>0 0 0</RPY>
    </Transform3D>
    <Spring>
        <Compliance>
            0.0005 0 0
            0 0.5 0
            0 0 0.5
        </Compliance>
        <Damping>
            50 0 0
            0 0.1 0
            0 0  0.1
        </Damping>
    </Spring>
</Constraint>

Springs

It is possible to attach a spring to a constraint as described in Constraints . If the spring is defined outside the Constraint tags, it must refer to a constraint by name.

Element Spring

Attributes

Child elements:

Example of a spring attached to a PrismaticUniversal constraint (the spring works for the one linear and two angular directions that are not constrained by the PrismaticUniversal constraint):

<Spring constraint="ComplianceConstraint">
    <Compliance>
        0.0005 0 0
        0 0.5 0
        0 0 0.5
    </Compliance>
    <Damping>
        50 0 0
        0 0.1 0
        0 0  0.1
    </Damping>
</Spring>

Sensors

Not documented yet.

TactileArraySensor

BodyContactSensor

TactileMultiAxisSensor

FTSensor

Controllers

Not documented yet.

PDDeviceController

PoseDeviceController

SerialDeviceController

SpringJointController