URDF Calibration

The Stretch URDF can be dynamically calibrated at load time by applying static calibration values to the joint origins. This ensures that the robot's physical dimensions (as measured during calibration) are reflected in the URDF used for visualization, planning, and kinematics.

How it Works

When a calibrated URDF is requested (e.g., via get_urdf_calibrated() or get_urdf_from_robot_params(apply_calibration=True)), the system looks for the stretch_calibration_values.yaml file within the stretch_user directory. If available, the nominal urdf joint origins are replaced by the saved values. These values represent the static offsets of the joint origins. They are typically generated by systems like the Stretch factory calibration or user-run calibration scripts (e.g., camera-to-body calibration).

List of Existing Calibration Procedures

The stretch_calibration_values.yaml file is used to store static offsets for any joint in the URDF. Currently, the following procedures are known to create or update this file:

Joint Calibrated	Calibration Script	Repository	Parent Link	Child Link
base_ref	ros_find_floor_calibration	stretch4_dual_lidar_calibration	base_footprint	base_link

Application Mechanism

The get_urdf_calibrated function performs the following steps:

1. Loads the nominal URDF (generated from the Xacro for the specific model, batch, and tool).
2. Parses the stretch_calibration_values.yaml file.
3. For every joint defined in the URDF, it checks if there is a matching entry in the YAML under robot_calibration.joints.
4. If a match is found, it replaces the <origin> element's xyz and rpy attributes with the values from the YAML.

YAML Structure

The stretch_calibration_values.yaml file follows this structure:

version: '2.0'
joint_calibration:
  base_ref:
    data: # Absolute joint origin data to swap into the URDF
      xyz: 0.0 0.0 0.027117761948801805
      rpy: -0.002335365281590182 0.008538679539879857 0.0
      parent: base_footprint
      child: base_link
    robot_id: stretch-se4-4010 # ID of the robot that performed the calibration
    timestamp: '2026-07-02T13:55:41.393513' # ISO timestamp of when the calibration was performed
    # Extra information can be added for additional context relevant to specific calibration procedures
    fit_method: svd
    rmse: 0.011093677602830953

Adding Calibrations

Users can add their own calibration entries to stretch_calibration_values.yaml. If you have measured an offset for a joint, you can manually add it to the calibration file, or programmatically add calibrations using the exported record_joint_calibration utility function. The calibration will be automatically applied to the URDF when it is loaded through util functions (e.g. get_urdf_from_robot_params, get_urdf_calibrated).

from stretch4_urdf import record_joint_calibration

record_joint_calibration(
    joint_name="base_ref",
    xyz="0.0 0.0 0.027",
    rpy="-0.002 0.008 0.0",
    parent="base_footprint",
    child="base_link",
    robot_id="stretch-se4-4010"
)

NOTE The values provided in the calibration YAML are absolute origin values for the joint, not deltas. The system replaces the nominal <origin> attributes in the URDF with these exact values.

Using Calibrated URDFs Example

To load a calibrated URDF in your Python scripts, use the get_urdf_from_robot_params utility. By default, apply_calibration is set to True:

from stretch4_urdf import get_urdf_from_robot_params

# This will automatically detect the robot model and load calibration if available
urdf_contents = get_urdf_from_robot_params()

If you are not running on a robot or want to provide parameters explicitly, use get_urdf_calibrated:

from stretch4_urdf import get_urdf_calibrated

# Explicitly provide model, batch, and tool
urdf_contents = get_urdf_calibrated(
    model_name="SE4",
    batch_name="francis",
    tool_name="eoa_wrist_dw4_tool_sg4"
)