Robot Description in PyCRAM

The robot description assigns meaning to the physical description of a robot from the URDF. This includes manipulator chains, meaning the links and joints which are part of an arm, the camera link and predefined poses for joint chains, like for example a default parking pose for an arm.

On this page we will list the parts of the robot description and explain them, for a tutorial on how to create your own robot description please look at the tutorial.

The robot_description file contains 6 classes:

  • ChainDescription
  • GripperDescription
  • InteractionDescription
  • ManipulatorDescription
  • CameraDescriptin
  • RobotDescription

Chain Description

This class represents a kinematic chain by saving the links and joints. This chain can for example be an arm of a robot. The parameter of the constructor along with a description and the type can be seen in the table below.

Parameter Description Type
name The name of this chain. String
joints All joints contained in this chain in the right order. List
links All links contained in this chain in the right order. List
base_link The name of the first link in the chain. String
static_joint_states Static joint states for this chain, for example the joint states so the arm ends up in a parking position. The parameter is a dictionary with the name of this state as key and the joint states in a list as value. dict[str: list[float]]

The class provides a number of methods to interact with static joint chains. These methods provide interfaces to add one or more joint chains or get a specific saved joint chain.

add_static_joint_chain

Adds a specific configuration of the joints saved in this chain. For example a static joint chain would be the default parking pose of an arm of a robot.

Parameter Description Type
configuration The name for this joint chain. String
static_joint_states A list of joint states this chain should archive. List[float]

add_static_joint_chains

This method lets you add more than one static joint chain at a time. The different static joint chains are given in a dictionary with the name of the static joint chain as key and the list of states as value.

Parameter Description Type
static_joint_states A dictionary containing all static joint chains to be added. The name of the static joint chain is the key and the corresponding value is a list of all joint states. dict{str: list[float]}

get_static_joint_chain

This method returns a static joint chain, given the name of the static joint chain.

Parameter Description Type
configuration The name of the static joint chain which should be returned. String

Gripper Description

This class inherits from the ChainDescrioption class and describes a gripper of a robot. This class allows you to specify more details about the gripper as well as specify joint configurations for this gripper. The constructor of this class takes a lot of additional parameter to describe the gripper however all except for the name are optional. The parameter of the constructor will be explained in the table below.

Parameter Description Type
name The name of this gripper description, it doesn't have to correspond to the links of the gripper. String
gripper_links A list of the names of all links belonging to this gripper in the right order. List[String]
gripper_joints A list of the names of all joints belonging to this gripper in the right order. List[String]
static_gripper_joint_states A dictionary containing static joint states. See also add_static_joints_chains dict{str: list[float]}
gripper_meter_to_jnt_multiplier A parameter specifying the relationship between meters and the joint state value. float
gripper_minimal_position The lowest value the gripper joint can be. float
gripper_convergence_delta Describes the convergence delta of this gripper. float

The GripperDescription class doesn't define any methods. However, since it inherits from the ChainDescription class all methods of the ChainDescription class are also available.

Interaction Description

This class allows to put on the end of an chain another link, which is saved as an end effector. Therefore, chains can be defined which specify the interaction frame for the robot. An example could be a storage place for grasped objects on the robot. The parameter of the constructor can be seen in the table below.

      chain of links: chain_description <-> eef_link
Parameter Description Type
chain_description A chain description for which this interaction should be defined. ChainDescription
eef_link The name of a link which should be saved as the end effector. String

This class doesn't define any methods but since it inherits from the ChainDescription class all methods of the ChainDescription are also available.

Manipulator Description

This class allows with the given interaction description to include a gripper description which is placed between the last link of the interaction description and the rest of it. Independently from that a tool frame can be saved, which allows to use objects to manipulate the environment.

                                                                         |--> (tool_frame)
      chain of links: interaction_description <-> (gripper_description) -|
                                                                         |--> eef_link
                                                                         

The parameter of the constructor will be shown in the following table.

Parameter Description Type
interaction_description The interaction description for which this manipulator description should be appended. InteractionDescription
tool_frame The name of a link which should be used as a tool frame for this manipulator description. This parameter is optional. String
gripper_description A gripper description which should be used between the interaction description and the end effector and tool frame. This parameter is optional. GripperDesctiption

This class doesn't define any methods but since it inherits from the InteractionDescription class all methods of the InteractionDescription are also available.

Camera Description

This class represents a camera of the robot, it saves the link in the URDF as well as additional parameter which describe physical properties of the camera. The parameter of the constructor of this class can be seen in the table below.

Parameter Description Type
name The name of the link in the URDF representing the camera. String
minimal_height The minimal height the camera can see. float
maximal_height The maximal height the camera can see. float
vertical_angle The vertical angle of the camera mount. float
horizontal_angle The horizontal angle of the camera mount. float
other_params Here can parameter be specified which are not mentioned before like the focal length of the camera. dict{str: float}

This class doesn't define any methods.

Robot Description

The RobotDescription is an abstract class which needs to be inherited from to implement a robot description for a specific robot. It implements different functions to add and get chains of different objects types which inherit of the class ChainDescription. Moreover, it allows to model the robot with its odom_frame, base_frame, base_link and torso links and joints. Different cameras can be added and static transforms and poses can be added too. The parameter of the constructor can be seen in the table below.

Parameter Description Type
name The name of this robot. String
base_frame The link name of the base frame of this robot. String
base_link The link name of the base link of this robot. String
torso_link The link name of the torso of this robot. String
torso_joint The name of the joint moving the torso. String
ik_joints Deprecated, should not be used. None
odom_frame The link name of the odom frame of this robot, can also be a list of link names. This parameter is optional. String or List
odom_joints The joint name of the odom joint, if there are more than one a list can be given which has to correspond with the order of the odom_frame list String or list

There are a number of methods defined by the RobotDescription class to add more information or retrieve saved informations about the robot. In the following we will take a close look at all methods and explain the parameter these methods take.

get_tool_frame

This method returns the saved tool frame of a manipulator description, saved by the given name.

Parameter Description Type
manipulator_name The name for which the manipulator description is saved. String

get_static_joint_chain

Returns a static joint chain given the name of a ChainDescription and a configuration of this chain. The chain name is the name which identifies a particular chain description in the robot description. For example, 'left' for a chain description describing the left arm of a robot.

Parameter Description Type
chain_name The name for which a chain description is saved in the robot description. String
configuration The desired configuration saved in the chain description, this is equal to the static joint chains. String

add_chain

This method adds a chain description with a name identifying this chain. For example, the name is 'left' and the chain description describes the left arm of a robot.

Parameter Description Type
name A name which is used for identifying the chain description. String
chain_description A chain description which should be added to the robot description. ChainDescription

add_chains

This method lets you add more than one chain at a time by taking a dictionary composed of the name identifying the chain as key and the chain description as value.

Parameter Description Type
chains_dict A dictionary containing multiple chain descriptions. dict{str: ChainDescrition}

add_camera

This method adds a camera description to this robot description. The method uses, like add_chain, a name to identify the camera description.

Parameter Description Type
name The name which should identify the camera. String
camera_description A camera description which should be added under the given name. CameraDescription

add_cameras

This method lets you add more than one camera at a time by taking a dictionary containing multiple camera descriptions. The key of the dictionary functions as the name to identify the camera description in the corresponding value.

Parameter Description Type
cameras_dict A dictionary containing multiple camera descriptions.

get_camera_frame

Returns the camera frame for a given name of a camera description.

Parameter Description Type
camera_name The name of the camera description for which the frame should be returned. String

add_static_joint_chain

This method adds a static joint chain to a chain description saved in this robot description. See also add_static_joint_chain of the ChainDescription above.

Parameter Description Type
chain_name The name used to identify the chain description String
configuration The name of the configuration which should be added. String
static_joint_states The joint states used in this configuration. list[float]

add_static_joint_chains

This method allows you to add multiple static joint chains at once. See also add_static_joint_chains of the ChainDescription above.

Parameter Description Type
chain_name The name used to identify the chain description String
static_joint_states A dictionary containing the static joint chains. dict{str: list[float]}

add_static_gripper_chain

This method adds a static joint chain to a saved manipulator description. The static joint chain is meant to be used for the gripper.

Parameter Description Type
manipulator_name The name used to identify the manipulator description in the robot description. String
configuration A name describing the configuration of this static joint chain. String
static_joint_states A list of joint states. list[float]

add_static_gripper_chains

This method adds more than one static joint chain to a manipulator description.

Parameter Description Type
manipulator_name The name used to identify the manipulator description in the robot description. String
static_joint_states A dictionary containing the static joint chains. dict{str: list[float]}

get_static_gripper_chain

Returns a static gripper joint chain for a given manipulator description and configuration.

Parameter Description Type
manipulator_name The name used to identify the manipulator description in the robot description. String
configuration The name of the desired configuration in the given manipulator description. String