RobWorkProject  23.9.11-
Dynamic WorkCell XML File Format

Introduction

The dynamic workcell (DWC) XML file format have suffix .dwc.xml and follow the rules of standard XML. 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

  • workcell: a string identifying the workcell file.

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

  • file: a string identifying the file to include.

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:

  • Property

Child element Property

Attributes

  • name: a string identifying the property.
  • type: string (default), int, float or Q.

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:

  • Default: a string defining the default material for bodies where no material is defined explicitly.
  • Material

Child element Material

Attributes

  • id: a string giving the name of the material.

Child elements:

  • Description: (optional) a string with a description of the material.

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:

  • Pair

Child element Pair

Attributes

  • first: the material id of the first material.
  • second: the material id of the second material.

Child elements:

  • FrictionData

Child element FrictionData

Attributes

  • type: only Coulomb supported currently.

Child elements:

  • Mu: a float giving the Coulomb friction coefficient.

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:

  • Default: a string defining default object type for objects where no object types are set explicitly.
  • ObjectType

Child element ObjectType

Attributes

  • id: a string identifying the type of object.

Child elements:

  • Description: (optional) a string with a description of the type.

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:

  • Pair

Child element Pair

Attributes

  • first: the type id of the first object type.
  • second: the type id of the second object type.

Child elements:

  • ContactData

Element ContactData

Attributes

  • type: only Newton supported currently.

Child elements:

  • cr: a float giving the coefficient of restitution.

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 : The FixedBody specifies bodies that are static and does not move. Such a body influences the motion of other bodies, but other bodies can not influence a FixedBody.
  • KinematicBody : A KinematicBody can be moved during simulation, and can affect other bodies. Other bodies can however not affect the velocity of the KinematicBody.
  • RigidBody : Rigid bodies has mass and inertia and the motion is determined by the forces acting on the body.

FixedBody

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

Element FixedBody

Attributes

  • frame: a string associating the body to a Frame defined in the workcell.

Child elements:

  • MaterialID: (optional) a string giving the name of a material defined in MaterialData .
  • ObjectID: (optional) a string giving the name of a object type defined in ObjectTypeData .
  • Property: (optional) for additional data (Property tag defined in PhysicsEngine )

Example

<FixedBody frame="Floor" />

KinematicBody

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

Element KinematicBody

Attributes

  • frame: a string associating the body to a MovableFrame defined in the workcell.

Child elements:

  • MaterialID: (optional) a string giving the name of a material defined in MaterialData .
  • ObjectID: (optional) a string giving the name of a object type defined in ObjectTypeData .

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

  • frame: a string associating the body to a MovableFrame defined in the workcell.

Child elements:

  • Mass: a float with the mass of the body.
  • EstimateInertia: (optional) calculate Inertia and COG from geometry (geometry must be present in this case). If COG is given this will be used when calulating the Inertia.
  • COG: (required if EstimateInertia is not used, else optional) the center of gravity.
  • Inertia: (required if EstimateInertia is not used) the 3x3 inertia matrix of the body.
  • Integrator: the integrator used (not used in ODE).
  • Associate: (optional) allows associating geometry that is not attached to the main body frame to this body.
  • MaterialID: (optional) a string giving the name of a material defined in MaterialData .
  • ObjectID: (optional) a string giving the name of a object type defined in ObjectTypeData .
  • Property: (optional) for additional data (Property tag defined in PhysicsEngine )

Child element Associate

Attributes

  • object: a string identifying a object in the workcell to associate to this body. The geometry of the object is then added to this body.

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:

  • KinematicDevice : The KinematicDevice specifies a device that is composed of kinematic bodies. If dynamic simulation is not required this is the most efficient method to simulate a device.
  • RigidDevice : A RigidDevice is composed of rigid bodies, which have their motion constrained.

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

  • device: a string associating the dynamic device to a JointDevice defined in the workcell.

Child elements:

  • FixedBase: (one base element required) equivalent to FixedBody.
  • KinematicBase: (one base element required) equivalent to KinematicBody .
  • RefBase: (one base element required) use an existing body as base.
  • KinematicJoint/Link: equivalent to RigidBody - note that mass parameters can just be set to zero.

Child element RefBase

Attributes

  • body: a string identifying an existing body.

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

  • device: a string associating the dynamic device to a JointDevice defined in the workcell.

Child elements:

  • FixedBase: (one base element required) equivalent to FixedBody.
  • KinematicBase: (one base element required) equivalent to KinematicBody .
  • RigidBase: (one base element required) equivalent to RigidBody .
  • RefBase: (one base element required) use an existing body as base.
  • RigidJoint/Link: equivalent to RigidBody.
  • ForceLimit: the force or torque applied by each motor (depending on the joint it refers to)

Child element ForceLimit

Attributes

  • joint: the joint to set limit for.

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

  • name: a unique name for this constraint.
  • type: one of the ContraintType values defined in rwsim::dynamics::Constraint (Fixed, Prismatic, Revolute, Universal, Spherical, Piston, PrismaticRotoid, PrismaticUniversal, Free)
  • parent: the parent body.
  • child: the child body.

Child elements:

  • Transform3D: (optional) where the constraint acts relative to the parent body frame.
  • Spring: (optional) adds springs in the non-constrained directions (see Springs ).

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

  • constraint: the name of the constraint to attach the string to (the string works in the non-constrained directions).

Child elements:

  • Compliance: n times n compliance matrix where n is the number of non-constrained dimensions (between 0 and 6 according to constraint type).
  • Damping: matrix of same dimensions as the compliance matrix.

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