Configuring Robot Keyframes

Introduction

A keyframe is a named state of your entire simulation world. They are commonly used to record states of interest in your simulation, similarly to waypoints. They differ from waypoints in that they may include uncontrolled elements of your simulation in addition to your robot. This means they can be used to put your robot in different environmental situations simply by choosing a different keyframe. A keyframe contains the position, velocity, and control inputs of all mobile joints in some desired configuration of your simulation world. The positions of joints are stored in qpos, the velocities in qvel, and the control inputs in ctrl. See here for more information on keyframes.

scene.xml

To add a keyframe to your simulation, you add it to your robot's scene.xml. A good example of this in action can be seen in the MoveIt Pro example workspace here.

Example

For an example, we will again turn to the MoveIt Pro example workspace, its scene.xml file in particular. We see that it has a view_tag keyframe and a default keyframe. Looking at the config.yaml file, we see that the default keyframe being used is this view_tag keyframe. This keyframe starts with a good view of the tag and a small angular velocity, perfect for testing visual servoing applications.

What if we want to see how far our vision system can operate at? Let's add a new keyframe, called far_keyframe. Since we don't know how far our system will operate at, let's give the satellite a small velocity toward ours. Then, we can test the operational range of our system by waiting until it moves to a functional point. To do this, all we have to do is modify the position of the client satellite to be far in front of the ego satellite and give it a small velocity in the opposite direction (toward the ego satellite). In our scene.xml file, let's add the following

    <key
      name="far_keyframe"
      qpos="
        30 0.5 1.7 1 0 0 0
        0 0 0 0 0 0
        -1.5708 1.8326 0 -2.3562 0 0.2618 1.5708 0
        0 0 0 0 0 0 0"
      qvel="
        -1 0 0 0 0 0
        0 0 0 0 0 0
        0 0 0 0 0 0 0 0
        0 0 0 0 0 0 0"
      ctrl="
        -1.5708 1.8326 0 -2.3562 0 0.2618 1.5708 0
        0 0 0 0 0 0"
    />

This removes the angular velocity (components 3-6 of the first line of qvel) and puts the client satellite 30 meters away, moving toward the ego satellite at 1 m/s.

However, this does not complete the task. Now, in our config.yaml file, let's change our mujoco_keyframe to "far_keyframe". With these steps completed, let's see the results.

Before our change, the client satellite is close and rotating:

After our change, the client satellite is far away and moving toward the ego satellite:

The above example illustrates a common use case of keyframes. Adding many keyframes representative of common states is a good way to save time and be able to quickly integration test behaviors on a variety of different states.