RobWorkProject  20.10.1-
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:

  • Strings (std::string): For example "Hi"
  • Numbers (double): For example 12 and 42.0.
  • Configurations (rw::math::Q): For example (12) and (3.1, 4, 15).

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:

  • #Box dx dy dz

    A box of with x-, y-, z-dimensions dx, dy, and dz. The box is centered at the position of the frame.
  • #Cylinder radius height level

    A cylinder of the given radius and height and approximated by level faces. The cylinder is centered at the position of the frame. The axis of the cylinder is in the direction of the z-axis of the frame.

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:

<CollisionSetup>
<Exclude>
<FramePair first="J0Geo" second="J1Geo"/>
<FramePair first="J0Geo" second="J2Geo"/>
<FramePair first="J0Geo" second="J3Geo"/>
<FramePair first="J0Geo" second="J4Geo"/>
<FramePair first="J0Geo" second="J5Geo"/>
<FramePair first="J0Geo" second="J6Geo"/>
<FramePair first="J1Geo" second="J2Geo"/>
<FramePair first="J1Geo" second="J3Geo"/>
<FramePair first="J1Geo" second="J4Geo"/>
<FramePair first="J1Geo" second="J5Geo"/>
<FramePair first="J1Geo" second="J6Geo"/>
<FramePair first="J2Geo" second="J3Geo"/>
<FramePair first="J2Geo" second="J4Geo"/>
<FramePair first="J2Geo" second="J5Geo"/>
<FramePair first="J2Geo" second="J6Geo"/>
<FramePair first="J3Geo" second="J4Geo"/>
<FramePair first="J3Geo" second="J5Geo"/>
<FramePair first="J3Geo" second="J6Geo"/>
<FramePair first="J4Geo" second="J5Geo"/>
<FramePair first="J4Geo" second="J6Geo"/>
<FramePair first="J5Geo" second="J6Geo"/>
</Exclude>
</CollisionSetup>

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

<CollisionSetup>
<Exclude>
<FramePair first="Cylinder-1" second="Device.J0Geo"/>
<FramePair first="Cylinder-1" second="Device.J1Geo"/>
<FramePair first="Cylinder-1" second="Floor"/>
<FramePair first="Cylinder-1" second="Wall-1"/>
<FramePair first="Cylinder-1" second="Wall-2"/>
<FramePair first="Device.J0Geo" second="Floor"/>
<FramePair first="Device.J0Geo" second="Wall-1"/>
<FramePair first="Device.J0Geo" second="Wall-2"/>
<FramePair first="Device.J1Geo" second="Floor"/>
<FramePair first="Device.J1Geo" second="Wall-1"/>
<FramePair first="Device.J1Geo" second="Wall-2"/>
<FramePair first="Device.J2Geo" second="Floor"/>
<FramePair first="Device.J3Geo" second="Floor"/>
<FramePair first="Floor" second="Wall-1"/>
<FramePair first="Floor" second="Wall-2"/>
<FramePair first="Wall-1" second="Wall-2"/>
</Exclude>
</CollisionSetup>

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

Built-in attributes

ActiveJoint

CollisionModelID

  • CollisionModelID id1 id2 ... idN

    Geometric primitives or file names for CAD geometries to use for collision checking exclusively (see also attributes DrawableID and GeoID and section Geometric primitives).

CollisionSetup

  • CollisionSetup file-name

    Use file file-name as collision checking setup for the workcell (rw::proximity::CollisionSetup). If more than one CollisionSetup attribute is found in a workcell description, the contents of the files are merged into a single collision setup.

CompositeDevice

  • CompositeDevice dev1 dev2 ... devN

    Construct a composite device (rw::models::CompositeDevice) from devices the named dev1 dev2 ... devN. The CompositeDevice attribute may refer also to devices that are only loaded later in the workcell file. The base of the composite device is current frame and the end frame is the end frame of device dev1. See also attribute Device.

CraigDH

  • CraigDH alpha a d theta

    Let the displacement transform of the frame be given by the modified Denavit-Hartenberg parameters (alpha, a, d, theta). The CraigDH attribute is an alternative to the Position and RPY attributes and can not be used in combination with these attributes.

DAF

  • DAF

    The frame is a dynamically attachable frame (DAF), meaning that the parent of the frame can be changed (rw::kinematics::Frame::attachFrame()).

Device

  • Device device-file

    Load the device of file device-file and attach the base frame of the device to this frame. The name of the device (rw::models::Device::getName()) is the name of the frame. The frames names of the device are prefixed with the name of the device.

DeviceHomePos

  • DeviceHomePos q

    The configuration of the device in the initial state of the workcell (rw::models::getDefaultState()). Attribute DeviceHomePos has precedence over attribute JointHomePos. Later DeviceHomePos attributes take precedence over earlier DeviceHomePos attributes that assign values for the same joints. The attribute is meaningful only in the tag from which the device was loaded (see attribute Device or CompositeDevice).

DrawableHighlight

  • DrawableHighlight

    Highlight the drawable (rwlibs::drawable::Drawable::setHighlighted()).

DrawableID

DrawableWireMode

  • DrawableWireMode

    Draw the drawable in wire mode (rwlibs::drawable::Drawable::DrawType::WIRE).

Fixed

  • Fixed

    The frame is a fixed joint (rw::models::FixedJoint). This attribute is used in combination with attribute ActiveJoint.

GeoID

GeoScale

  • GeoScale scale-factor

    Factor by which to scale the CAD geometries loaded for the frame.

I, J, K

  • I (x, y, z)
  • J (x, y, z)
  • K (x, y, z)

    The attributes I, J and K together specify the rotation of the frame relative to its parent. The values for I, J and K are respectively the first, second and third column of the rotation matrix. If no rotation is specified for the frame (see also attribute RPY) the relative rotation of the frame defaults to zero.

JointAccLimit

JointHomePos

JointPosLimit

JointVelLimit

Movable

PassivePrismatic

  • PassivePrismatic frame-name scale offset

    The frame is a passive prismatic frame (rw::models::PassivePrismaticFrame). The frame is controlled by frame frame-name. Frame frame-name must have been given previously in the workcell description. Scale and offset parameters for the passive frame are given by scale and offset.

PassiveRevolute

  • PassiveRevolute frame-name scale offset

    The frame is a passive revolute frame (rw::models::PassiveRevoluteFrame). The frame is controlled by frame frame-name. Frame frame-name must have been given previously in the workcell description. Scale and offset parameters for the passive frame are given by scale and offset.

Position

  • Position (x, y, z):

    The position of the frame relative to its parent. If no position is given the relative position of the frame defaults to zero.

RPY

  • RPY (roll, pitch, yaw)

    The rotation of the frame relative to its parent in (roll, pitch, yaw) angles (rw::math::RPY). Angles are given in degrees. If no rotation is specified for the frame (see also the I, J, K attributes) the relative rotation of the frame defaults to zero.

ReferenceFrame

  • ReferenceFrame frame-name

    The parent of the frame is frame-name (rw::kinematics::Frame::getParent()). The frame named frame-name must have been processed previously in the workcell description. If no ReferenceFrame attribute is given, the parent frame defaults to the world frame (rw::models::WorkCell::getWorldFrame()). If frame-name in a device file is the empty string "", the frame will be attached to the frame from which the device is loaded (see attribute Device).

Revolute

Prismatic