Resources

Topics

RobWorkProject
Tag workcell setup format

Introduction

Workcell setup files in the tag format have suffix .wu or .dev. Conventionally a .dev file is used for a single device (rw::models::Device) whereas a .wu file is used for a complete workcell (rw::models::WorkCell) containing the environment and a number of imported devices. Tag workcell files are loaded with rw::loaders::WorkCellLoader::load().

Tag format

A tag file contains a sequence of tags. Every tag has a name and each name must be unique. A tag contains zero or more attributes that each take up one line. The first word on an attribute line is the name of the attribute, and the elements following the name are the attribute values. The following types of attribute values are supported:

The following is an example of a syntactically valid tag:

{ "demo tag" ! A tag named 'demo tag'

    ! Two attributes with mixed types of attribute values:
    StringsAndNumbers "one" 1 "two" 2 "three" 3
    DofsAndQs 1 (12) 2 (54, 12)

    ! An attribute with no attribute values:
    Hello
}

In workcell descriptions based on the tag format each tag maps to a frame (rw::kinematics::Frame) of the workcell. The name of the tag maps (prefixed by the device name) to the name of the frame. Here is an example of a typical tag for a frame:

{ "Obstacle" ! The name of the frame.

    ! The transform and parent of the frame:
    Position (0.8, -0.5, -0.4)
    RPY (0, 0, 0)
    ReferenceFrame "WORLD"

    ! CAD geometry for collision checking and display:
    GeoID "Geometry/obstacle"
}

The name of the frame is "Obstacle". Its parent frame is the frame named "WORLD" which is defined to be the world frame (rw::models::WorkCell::getWorldFrame()). The position and orientation of the frame relative to its parent is given by the Position and RPY attributes. The contents of the CAD file "Geometry/obstacle" is used for display and collision checking for the frame. The loader will add a suitable suffix so that e.g. "Geometry/obstacle.stl" is used for collision checking and "Geometry/obstacle.3ds" is used for display.

Geometric primitives

The tag attributes GeoID, CollisionModelID, and DrawableID each take an identifier for a CAD geometry as argument. The identifier can either be the name of the file of a CAD geometry, or it can be a string describing a geometric primitive.

The supported geometric primitives are:

This is a complete workcell showing the use of geometric primitives:

{ "p0"
Position (0, 0, 0.25)
}
{ "w1"
Position (1, 0.5, 0)
ReferenceFrame "p0"
DrawableID "#Box 0.05 1 0.5"
}
{ "w2"
Position (-0.5, 1, 0)
RPY (90, 0, 0)
ReferenceFrame "p0"
DrawableID "#Box 0.05 1 0.5"
}
{ "c1"
Position (-1, 0, 0.5)
DrawableID "#Cylinder 0.25 1 12"
}
{ "floor"
Position (0, 0, -0.0125)
DrawableID "#Box 4 3 0.025"
}

This is what the workcell looks like when loaded into RobWorkStudio:

Workcell
    environment built from geometric primitives
Workcell environment built from geometric primitives

Example of a workcell containing a device and item

We show the setup files for a workcell containing a static environment, a device and a movable item:

Workcell
    with device, environment and movable item
Workcell with device, environment and movable item

The workcell description is distributed across 3 files named workcell.wu, environment.wu, and device.dev. The workcell.wu file imports the environment and device files and positions the movable item:

{ "WORLD"
CollisionSetup "CollisionSetup.xml"
}
File "environment.wu"
{ "Device"
Device "device.dev"
DeviceHomePos (0.98, 1.503, -1.521, -0.76, -0.237, -0.895, 0)
}
{ "Item"
Position (0, 0.5, 0.5125)
Movable
DAF
DrawableID "#Cylinder 0.025 0.025 12"
}

The environment.wu file has a setup similar to the workcell described in section Geometric primitives :

{ "Pos-0"
Position (0, 0, 0.25)
}
{ "Wall-1"
Position (0.5, 0.5, 0)
ReferenceFrame "Pos-0"
GeoID "#Box 0.05 1 0.5"
}
{ "Wall-2"
Position (-0.5, 0.5, 0)
RPY (90, 0, 0)
ReferenceFrame "Pos-0"
GeoID "#Box 0.05 1 0.5"
}
{ "Cylinder-1"
Position (-0.6, -0.1, 0.5)
GeoID "#Cylinder 0.2 1 12"
}
{ "Floor"
Position (0, 0, -0.0125)
GeoID "#Box 4 3 0.025"
}

The device.dev file contains a device with 7 revolute joints that alternate between roll and pitch. To keep the example self-contained the built-in geometric primitives have been used for link geometries.

{ "J0"
ReferenceFrame ""
ActiveJoint
Revolute
JointPosLimit -180 180
JointVelLimit 20
CollisionSetup "DeviceCollisionSetup.xml"
}
{ "J0Geo"
ReferenceFrame "J0"
Position (0, 0, 0.05)
GeoID "#Cylinder 0.05 0.1 12"
}
{ "J1"
ReferenceFrame "J0"
Position (0, 0, 0.1)
RPY (0, -90, 0)
ActiveJoint
Revolute
JointPosLimit -90 90
JointVelLimit 20
}
{ "J1Geo"
ReferenceFrame "J1"
Position (0, 0, 0)
GeoID "#Cylinder 0.05 0.1 12"
}
{ "J2"
ReferenceFrame "J1"
Position (0.5, 0, 0)
RPY (0, 90, 0)
ActiveJoint
Revolute
JointPosLimit -180 180
JointVelLimit 20
}
{ "J2Geo"
ReferenceFrame "J2"
Position (0, 0, -0.25)
GeoID "#Cylinder 0.05 0.5 12"
}
{ "J3"
ReferenceFrame "J2"
Position (0, 0, 0)
RPY (0, -90, 0)
ActiveJoint
Revolute
JointPosLimit -90 90
JointVelLimit 20
}
{ "J3Geo"
ReferenceFrame "J3"
Position (0, 0, 0)
GeoID "#Cylinder 0.05 0.1 12"
}
{ "J4"
ReferenceFrame "J3"
Position (0.5, 0, 0)
RPY (0, 90, 0)
ActiveJoint
Revolute
JointPosLimit -180 180
JointVelLimit 20
}
{ "J4Geo"
ReferenceFrame "J4"
Position (0, 0, -0.25)
GeoID "#Cylinder 0.05 0.5 12"
}
{ "J5"
ReferenceFrame "J4"
Position (0, 0, 0)
RPY (0, -90, 0)
ActiveJoint
Revolute
JointPosLimit -90 90
JointVelLimit 20
}
{ "J5Geo"
ReferenceFrame "J5"
Position (0, 0, 0)
GeoID "#Cylinder 0.05 0.1 12"
}
{ "J6"
ReferenceFrame "J5"
Position (0.1, 0, 0)
RPY (0, 90, 0)
ActiveJoint
Revolute
JointPosLimit -180 180
JointVelLimit 20
}
{ "J6Geo"
ReferenceFrame "J6"
Position (0, 0, -0.05)
GeoID "#Cylinder 0.05 0.1 12"
}
{ "TCP"
ReferenceFrame "J6"
}

The device.dev file as well as well as the workcell.wu file has a collision setup file that lists the pairs of frames for which to omit collision checking. This is the DeviceCollisionSetup.xml file referred to in the device.dev file:

1 <CollisionSetup>
2  <Exclude>
3  <FramePair first="J0Geo" second="J1Geo"/>
4  <FramePair first="J0Geo" second="J2Geo"/>
5  <FramePair first="J0Geo" second="J3Geo"/>
6  <FramePair first="J0Geo" second="J4Geo"/>
7  <FramePair first="J0Geo" second="J5Geo"/>
8  <FramePair first="J0Geo" second="J6Geo"/>
9  <FramePair first="J1Geo" second="J2Geo"/>
10  <FramePair first="J1Geo" second="J3Geo"/>
11  <FramePair first="J1Geo" second="J4Geo"/>
12  <FramePair first="J1Geo" second="J5Geo"/>
13  <FramePair first="J1Geo" second="J6Geo"/>
14  <FramePair first="J2Geo" second="J3Geo"/>
15  <FramePair first="J2Geo" second="J4Geo"/>
16  <FramePair first="J2Geo" second="J5Geo"/>
17  <FramePair first="J2Geo" second="J6Geo"/>
18  <FramePair first="J3Geo" second="J4Geo"/>
19  <FramePair first="J3Geo" second="J5Geo"/>
20  <FramePair first="J3Geo" second="J6Geo"/>
21  <FramePair first="J4Geo" second="J5Geo"/>
22  <FramePair first="J4Geo" second="J6Geo"/>
23  <FramePair first="J5Geo" second="J6Geo"/>
24  </Exclude>
25 </CollisionSetup>

This is the CollisionSetup.xml file referred to in the workcell.wu file:

1 <CollisionSetup>
2  <Exclude>
3  <FramePair first="Cylinder-1" second="Device.J0Geo"/>
4  <FramePair first="Cylinder-1" second="Device.J1Geo"/>
5  <FramePair first="Cylinder-1" second="Floor"/>
6  <FramePair first="Cylinder-1" second="Wall-1"/>
7  <FramePair first="Cylinder-1" second="Wall-2"/>
8  <FramePair first="Device.J0Geo" second="Floor"/>
9  <FramePair first="Device.J0Geo" second="Wall-1"/>
10  <FramePair first="Device.J0Geo" second="Wall-2"/>
11  <FramePair first="Device.J1Geo" second="Floor"/>
12  <FramePair first="Device.J1Geo" second="Wall-1"/>
13  <FramePair first="Device.J1Geo" second="Wall-2"/>
14  <FramePair first="Device.J2Geo" second="Floor"/>
15  <FramePair first="Device.J3Geo" second="Floor"/>
16  <FramePair first="Floor" second="Wall-1"/>
17  <FramePair first="Floor" second="Wall-2"/>
18  <FramePair first="Wall-1" second="Wall-2"/>
19  </Exclude>
20 </CollisionSetup>

Constructing such collision setup files can be cumbersome; in fact the two files were computed by a script.

Built-in attributes

ActiveJoint

CollisionModelID

CollisionSetup

CompositeDevice

CraigDH

DAF

Device

DeviceHomePos

DrawableHighlight

DrawableID

DrawableWireMode

Fixed

GeoID

GeoScale

I, J, K

JointAccLimit

JointHomePos

JointPosLimit

JointVelLimit

Movable

PassivePrismatic

PassiveRevolute

Position

RPY

ReferenceFrame

Revolute

Prismatic