README.md

Overview

stretch_calibration provides tools for calibrating and managing the URDF for the Stretch robot. The code's primary role is to generate a geometric model (i.e., a URDF) of the robot's body that corresponds well with views of the body from the robot's 3D camera (i.e., a Intel RealSense D435i). The code achieves this objective by adjusting the geometry of the model to predict where the 3D camera will see markers (i.e., ArUco markers) on the robot's body.

Hello Robot Inc. uses this code to calibrate each robot prior to shipping. Users may wish to recalibrate their robots to compensate for changes over time or take advantage of improvements to the calibration code.

In addition, after changing a tool, this code can be used to generate a new calibrated URDF that incorporates the tool without performing a new calibration optimization.

Checking the Current Calibration with New Observations

1. Make sure the basic joint limit calibration has been performed.

   stretch_robot_home.py

2. Make sure the uncalibrated URDF is up to date.

   ros2 run stretch_calibration update_uncalibrated_urdf

3. Collect new observations

   ros2 launch stretch_calibration collect_check_head_calibration_data.launch.py

4. Test how well the current calibrated model fits the new observations

   ros2 run stretch_calibration check_head_calibration

   • The total_error printed on the command line should be less than 0.05. If it is not, an error will be printed on the command line.

   • In RViz the white markers represent the locations for the ArUco markers predicted by the calibrated URDF. The colored markers represent the observed locations of the ArUco markers on the robot's body. For a good fit, the white markers will be close to the colored markers.

   

Visually Inspecting the Current Calibration

The following command will allow you to visually inspect a calibration with Rviz. You can use RViz to see how well the robot's 3D body model matches point clouds from the 3D camera. While visualizing the 3D model and point clouds in RViz, you can use keyboard commands in the terminal to move the head around, the lift up and down, and the arm in and out. The keyboard commands will be printed in the terminal.

A good calibration should result in a close correspondence between the robot's 3D body model and the point cloud throughout the ranges of motion for the head, lift, and arm. You may notice higher error when the head is looking upward due to challenges associated with head tilt backlash. You might also notice higher error when the arm is fully extended, since small angular errors can result in larger positional errors at the robot's wrist.

1. Test the current head calibration

   ros2 launch stretch_calibration simple_test_head_calibration.launch.py

Examples of Good and Bad Visual Fit

In the images below, examples of good and bad fit between the point cloud and the geometric model are presented side by side. To make the distinction clear, the images have green and red circles indicating where the fit is either good or bad.

Calibrate Stretch

1. Make sure the basic joint limit calibration has been performed.

   stretch_robot_home.py

2. Make sure the uncalibrated URDF is up to date.

   ros2 run stretch_calibration update_uncalibrated_urdf

3. Collect head calibration data

   • Put the robot on a flat surface. Give it room to move its arm and good lighting. Then, have the robot collect data using the command below. While the robot is collecting data, do not block its view of its markers.

     ros2 launch stretch_calibration collect_head_calibration_data.launch.py

4. Process head calibration data

   • Specify how much data to use and the quality of the fit

     • YAML file with parameters: stretch_ros2/stretch_calibration/config/head_calibration_options.yaml

     • More data and higher quality fitting result in optimizations that take longer

     • When quickly testing things out

       • ~3 minutes without visualization
       • data_to_use: use_very_little_data
       • fit_quality: fastest_lowest_quality

     • When calibrating the robot

       • ~1 hour without visualization
       • data_to_use: use_all_data
       • fit_quality: slow_high_quality

   • Perform the optimization to fit the model to the collected data

     • Without visualization (faster)

       ros2 launch stretch_calibration process_head_calibration_data.launch.py

     • With visualization (slower)

       ros2 launch stretch_calibration process_head_calibration_data_with_visualization.launch.py

5. Inspect the fit of the most recent head calibration

   ros2 run stretch_calibration visualize_most_recent_head_calibration

6. Start using the newest head calibration

   ros2 run stretch_calibration update_with_most_recent_calibration

7. Build the workspace and source environment variables

   cd ~/ament_ws

   colcon build

   source install/setup.bash

8. Test the current head calibration

   ros2 launch stretch_calibration simple_test_head_calibration.launch.py

   Use RViz to visually inspect the calibrated model. The robot's 3D body model should look similar to the structure of your robot. You may refer to the section above to see examples of good and bad fit.

Generate a New URDF After Changing the Tool

See the instructions here.

Revert to a Previous Calibration

When a new calibration is performed, it is timestamped and added to the calibration directory under "stretch_user/". If you'd like to revert to a previous calibration, you may run the following command. It will move the most recent calibration files to a reversion directory and update the calibration in the stretch_description package from the remaining most recent calibration files.

1. Revert to the previous head calibration

   ros2 run stretch_calibration revert_to_previous_calibration

2. Build the workspace and source environment variables

   cd ~/ament_ws

   colcon build

   source install/setup.bash

License

stretch_calibration is licensed with the GPLv3. Please see the LICENSE file for details.