Protocol Documentation

A rotation of a specific angle around a specific axis.

An extrinsic camera calibration.

| calibration_id | string | optional | The ID of the calibration.

This field is only set if the calibration has already been saved.

If left unset when adding a calibration, a new unique ID will automatically be generated for it. | | timestamp | uint64 | | The timestamp when the calibration was recorded.

Specified as number of milliseconds since January 1 1970 00:00 UTC (the Unix epoch). | | num_samples | uint32 | | The number of valid samples used to compute this calibration. | | camera_moving | bool | | Specifies if the camera is attached to the moving frame (the robot) or the fixed frame. |

| camera_pose | Pose3 | | The pose of the camera with respect to the parent frame.

If camera_moving is true, the parent frame is the moving frame. Otherwise, the parent frame is the fixed frame. | | pattern_pose | Pose3 | | The pose of the calibration pattern with respect to the parent frame.

If camera_moving is true, the parent frame is the fixed frame. Otherwise, the parent frame is the moving frame. | | root_mean_square_error | float | optional | The root mean square error of the pattern pose for all calibration samples.

NOTE: The exact meaning of this field depends on the camera. Vendor specific camera algorithms may compute the RMSE slightly different, but a lower error is always better.

NOTE: This field may not be provided by all cameras, and it may not be set in manually uploaded calibrations. | | mean_translation_error | float | optional | The mean translation error in meters, computed over all calibration samples.

NOTE: This field may not be provided by all cameras, and it may not be set in manually uploaded calibrations. | | mean_rotation_error | float | optional | The mean rotation error in radians, computed over all calibration samples.

NOTE: This field may not be provided by all cameras, and it may not be set in manually uploaded calibrations. |

Request body for the close_calibration() service.

Response body for the close_calibration() service.

Request body for the compute_calibration service.

| no_save | bool | | Do not automatically close the computed calibration.

You can save it later if desired using the [save_calibration] service. | | no_close | bool | | Do not automatically close the calibration cycle.

You should close it later using the [close_calibration_cycle] service. | | moving_camera | bool | | Indicates if the camera is mounted attached to the moving frame (the robot). |

| skip_pattern_pose_computation | bool | | Skip computation of the calibration pattern pose.

If this is true, the pattern_pose field is used directly as the pattern pose. This is significantly faster than computing the pattern pose and it requires less samples: only 1 sample is enough, but using more samples can still improve the accuracy of the calibration.

However, if you skip the computation of the pattern pose, the calibration will not account for manufacturing tolerances, mounting inaccuracies or measurement errors.

If you enable this option, you must set pattern_pose correctly too. | | camera_pose | Pose3 | optional | An initial guess for pose of the camera.

The pose must be with respect to the fixed frame (if moving_camera is false) or the moving frame (if moving_camera is true).

This may be used to speed up the calibration routine, but providing a bad guess may actually slow down the calibration routine, or even lead to inaccurate results. | | pattern_pose | Pose3 | optional | The known pose of the calibration plate, or an initial guess for its pose.

The pose must be with respect to the moving frame (if moving_camera is false) or the fixed frame (if moving_camera is true).

This may be used to speed up the calibration routine, but providing a bad guess may actually slow down the calibration routine, or even lead to inaccurate results.

If skip_pattern_pose_computation is set, this pose must be the actual pose of the calibration pattern, and not just an initial guess. | | rotation_format | RotationFormat | optional | Specify the rotation format to use for the response.

This does not change the way the calibration is stored internally. It is only used for the response message to the request. |

Response body for the compute_calibration service.

Request body for the delete_calibration request.

Response body for the delete_calibration request.

An empty message

Euler rotation representation

| format | EulerRotationFormat | | The format of the Euler angles.

This determines the order in which the rotations are applied. | | angles | float | repeated | An array containing the angles of rotation for each axis.

The order of the angles is the order as per the variant of the format field.

This field needs exactly 3 values |

Request body for the get_api_version request.

Response body for the get_api_version request.

Request body for the get_calibration() service.

| calibration_id | string | optional | The ID of the calibration to retrieve.

If not set (or set to an empty string), the active calibration is returned. | | rotation_format | RotationFormat | optional | Specify the rotation format to use for the response. |

Response body for the get_calibration() service.

Request body for the get_server_info request.

Response body for the get_server_info request.

List open calibration cycles.

Response body for the list_calibration_cycles service.

Request body for the list_calibrations service.

Response body for the list_calibrations service.

A two dimensional point in space.

A three dimensional point in space.

A pose in three dimensional space.

A pose combines a position and an orientation.

This struct represents a quaternion.

The quaternion w+xi+yj+zk is a convenient representation of orientations and rotations of objects in three dimensions. Operations interpreting the quaternion as rotation have undefined behavior if the quaternion is not normalized.

Request body for the record_sample() service.

| rotation_format | RotationFormat | optional | Specify the rotation format to use for the response.

This does not have to match with the format of the robot_pose field. It is only used to choose the rotation format in the response. |

Response body for the record_sample() service.

| sample_id | uint32 | | The ID of the recorded sample.

Sample ids are specific to the calibration cycle in which they were recorded. | | pattern_found | bool | | Indicates if the pattern was found in the recorded image.

If no pattern was found, the sample can not be used for calibration. | | pattern_pose | Pose3 | optional | The detected pose of the calibration pattern in the uncalibrated camera frame.

NOTE: The call may be forwarded to a camera-vendor-specific calibration algorithm. Such algorithms may not report the pose of the detected pattern. In that case, this field may be empty / omitted even though pattern_found is true. |

A rotation in one of several possible formats.

Request body for the save_calibration service.

| calibration_id | string | optional | Save the calibration under the given ID.

If you leave this unset, a new ID is generated automatically. | | overwrite_existing | bool | | Overwrite a calibration with the same ID, if it already exists. |

Response body for the save_computed_calibration service.

| calibration_id | string | | The ID of the saved calibration.

Useful if you left the [SaveComputedCalibrationRequest::calibration_id] field unset. |

Information about a server, including software and API versions.

| application_name | string | | The name of the application.

This is important for interfaces that are implemented by multiple applications, (eg: cameras). | | application_version | Version | | The version of the application.

This can be useful for logging purposes. However, for checking compatibility with an interface you should always look at the interface name and version, not at the application name or version. | | service_name | string | | The name of this particular instance of the application.

This can be used to distinguish between different instances of a service if there is more than one instance of the same application running on the system. |

Request body for the set_active_calibration service.

Response body for the set_active_calibration service.

Request body for the start_calibration_cycle() service.

Response body for the start_calibration_cycle() service.

Request body for the upload_calibration request.

| calibration | Calibration | | The calibration to upload.

You can choose the ID of the calibration by setting the [Calibration::calibration_id] field. If you leave it unset, then a new unique ID is generated automatically. | | overwrite_existing | bool | | Overwrite the calibration with the given ID if it already exists.

If this is set to false or not specified, an error is returned if a saved calibration with the same ID already exists. | | make_active | bool | | If set to true, make the uploaded calibration the active calibration. |

Response body for the upload_calibration request.

| calibration_id | string | | The ID of the saved calibration.

Mostly useful if you left the [Calibration::calibration_id] field unset during the upload. Otherwise, it is just copy of that value. |

A three dimensional vector.

A version with major, minor and patch number.

| major | uint32 | | The major version.

A change to this value indicates a backwards-incompatible change to the public interface. | | minor | uint32 | | The minor version.

A change to this value indicates a backwards-compatible change to the public interface. | | patch | uint32 | | The patch version.

A change to this value indicates an internal change with no impact on the public interface. |

The type of Euler (Tait-Bryan) angles and the sequence of the rotation.

| EULER_ROTATION_FORMAT_UNSPECIFIED | 0 | Unspecified value.

If used, the server will act as if no value has been specified. | | EULER_ROTATION_FORMAT_INTRINSIC_XYZ | 1 | The angles represent intrinsic rotations in XYZ order.

See [RotationFormat::EulerIntrinsicXyz] for more information. | | EULER_ROTATION_FORMAT_INTRINSIC_XZY | 2 | The angles represent intrinsic rotations in XZY order.

See [RotationFormat::EulerIntrinsicXzy] for more information. | | EULER_ROTATION_FORMAT_INTRINSIC_YXZ | 3 | The angles represent intrinsic rotations in YXZ order.

See [RotationFormat::EulerIntrinsicYxz] for more information. | | EULER_ROTATION_FORMAT_INTRINSIC_YZX | 4 | The angles represent intrinsic rotations in YZX order.

See [RotationFormat::EulerIntrinsicYzx] for more information. | | EULER_ROTATION_FORMAT_INTRINSIC_ZXY | 5 | The angles represent intrinsic rotations in ZXY order.

See [RotationFormat::EulerIntrinsicZxy] for more information. | | EULER_ROTATION_FORMAT_INTRINSIC_ZYX | 6 | The angles represent intrinsic rotations in ZYX order.

See [RotationFormat::EulerIntrinsicZyx] for more information. | | EULER_ROTATION_FORMAT_EXTRINSIC_XYZ | 7 | The angles represent extrinsic rotations in XYZ order.

See [RotationFormat::EulerExtrinsicXyz] for more information. | | EULER_ROTATION_FORMAT_EXTRINSIC_XZY | 8 | The angles represent extrinsic rotations in XZY order.

See [RotationFormat::EulerExtrinsicXzy] for more information. | | EULER_ROTATION_FORMAT_EXTRINSIC_YXZ | 9 | The angles represent extrinsic rotations in YXZ order.

See [RotationFormat::EulerExtrinsicYxz] for more information. | | EULER_ROTATION_FORMAT_EXTRINSIC_YZX | 10 | The angles represent extrinsic rotations in YZX order.

See [RotationFormat::EulerExtrinsicYzx] for more information. | | EULER_ROTATION_FORMAT_EXTRINSIC_ZXY | 11 | The angles represent extrinsic rotations in ZXY order.

See [RotationFormat::EulerExtrinsicZxy] for more information. | | EULER_ROTATION_FORMAT_EXTRINSIC_ZYX | 12 | The angles represent extrinsic rotations in ZYX order.

See [RotationFormat::EulerExtrinsicZyx] for more information. |

The format of a 3D rotation.

| ROTATION_FORMAT_UNSPECIFIED | 0 | Unspecified value.

If used, the server will act as if no value has been specified. | | ROTATION_FORMAT_ANGLE_AXIS | 1 | The rotation is represented as an axis and an angle of rotation. | | ROTATION_FORMAT_QUATERNION | 2 | The rotation is represented as a quaternion. |

| ROTATION_FORMAT_EULER_INTRINSIC_XYZ | 3 | The rotation is represented as three intrinsic rotations: around the X axis, then the Y axis and then the Z axis.

The rotations are intrinsic: this means that the second rotation is applied in the rotated reference frame of the first rotation, and the third rotation is applied in the rotated reference frame of the second rotation.

This representation is also known as (improper) Euler angles or Tait-Bryan angles.

Known robots manufacturers that use this representation: - Staubli (NOTE: uses degrees rather than radians) | | ROTATION_FORMAT_EULER_INTRINSIC_XZY | 4 | The rotation is represented as three intrinsic rotations: around the X axis, then the Z axis and then the Y axis.

The rotations are intrinsic: this means that the second rotation is applied in the rotated reference frame of the first rotation, and the third rotation is applied in the rotated reference frame of the second rotation.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_INTRINSIC_YXZ | 5 | The rotation is represented as three intrinsic rotations: around the Y axis, then the X axis and then the Z axis.

The rotations are intrinsic: this means that the second rotation is applied in the rotated reference frame of the first rotation, and the third rotation is applied in the rotated reference frame of the second rotation.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_INTRINSIC_YZX | 6 | The rotation is represented as three intrinsic rotations: around the Y axis, then the Z axis and then the X axis.

The rotations are intrinsic: this means that the second rotation is applied in the rotated reference frame of the first rotation, and the third rotation is applied in the rotated reference frame of the second rotation.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_INTRINSIC_ZXY | 7 | The rotation is represented as three intrinsic rotations: around the Z axis, then the X axis and then the Y axis.

The rotations are intrinsic: this means that the second rotation is applied in the rotated reference frame of the first rotation, and the third rotation is applied in the rotated reference frame of the second rotation.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_INTRINSIC_ZYX | 8 | The rotation is represented as three intrinsic rotations: around the Z axis, then the Y axis and then the X axis.

The rotations are intrinsic: this means that the second rotation is applied in the rotated reference frame of the first rotation, and the third rotation is applied in the rotated reference frame of the second rotation.

This representation is also known as (improper) Euler angles or Tait-Bryan angles.

Known robots models that use intrinsic Euler ZYX: - Mitsubishi Industrial Robot CR750/CR751 Series - Kawasaki (NOTE: uses degrees rather than radians) - Kuka (NOTE: uses degrees rather than radians) - Yaskawa (NOTE: uses degrees rather than radians) | | ROTATION_FORMAT_EULER_EXTRINSIC_XYZ | 9 | The rotation is represented as three extrinsic rotations: around the X axis, then the Y axis and then the Z axis.

The rotations are extrinsic: this means that the second rotation is applied in the unrotated base or world frame, and the third rotation is again applied in the unrotated base or world frame.

This representation is also known as (improper) Euler angles or Tait-Bryan angles.

Known robots models that use intrinsic Euler ZYX: - Fanuc (NOTE: Fanuc calls them W, P, and R instead of X, Y and Z, and they use degrees rather than radians). | | ROTATION_FORMAT_EULER_EXTRINSIC_XZY | 10 | The rotation is represented as three extrinsic rotations: around the X axis, then the Z axis and then the Y axis.

The rotations are extrinsic: this means that the second rotation is applied in the unrotated base or world frame, and the third rotation is again applied in the unrotated base or world frame.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_EXTRINSIC_YXZ | 11 | The rotation is represented as three extrinsic rotations: around the Y axis, then the X axis and then the Z axis.

The rotations are extrinsic: this means that the second rotation is applied in the unrotated base or world frame, and the third rotation is again applied in the unrotated base or world frame.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_EXTRINSIC_YZX | 12 | The rotation is represented as three extrinsic rotations: around the Y axis, then the Z axis and then the X axis.

The rotations are extrinsic: this means that the second rotation is applied in the unrotated base or world frame, and the third rotation is again applied in the unrotated base or world frame.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_EXTRINSIC_ZXY | 13 | The rotation is represented as three extrinsic rotations: around the Z axis, then the X axis and then the Y axis.

The rotations are extrinsic: this means that the second rotation is applied in the unrotated base or world frame, and the third rotation is again applied in the unrotated base or world frame.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. | | ROTATION_FORMAT_EULER_EXTRINSIC_ZYX | 14 | The rotation is represented as three extrinsic rotations: around the Z axis, then the Y axis and then the X axis.

The rotations are extrinsic: this means that the second rotation is applied in the unrotated base or world frame, and the third rotation is again applied in the unrotated base or world frame.

This representation is also known as (improper) Euler angles or Tait-Bryan angles. |

| GetCalibration | GetCalibrationRequest | GetCalibrationResponse | Get the data of a saved calibration.

Can also be used to get the data of the currently active calibration. | | SetActiveCalibration | SetActiveCalibrationRequest | SetActiveCalibrationResponse | Set the active calibration to any of the saved calibrations. | | DeleteCalibration | DeleteCalibrationRequest | DeleteCalibrationResponse | Delete a saved calibration. |

| UploadCalibration | UploadCalibrationRequest | UploadCalibrationResponse | Upload a calibration to the server.

This service can be used to upload calibration data managed by some other system. You can set make_active to true to directly make it the active calibration. | | StartCalibrationCycle | StartCalibrationCycleRequest | StartCalibrationCycleResponse | Start a new calibration cycle.

Note that not all cameras support starting multiple calibration cycles at once. In that case, you must close any open calibration cycle before starting a new one.

A calibration cycle will calibrate the camera with respect to either a fixed frame or a moving frame. A common choice for fixed frame is the base frame of the robot. It is important that this frame does not move (or the robot moves along with it). The moving frame is usually the flange of the robot, or some other tool or end-effector configured on the robot.

If the camera is attached to the moving frame then the calibration plate must be attached to the fixed frame. And the other way around: if the camera is attached to the fixed frame then the calibration plate must be attached to the moving frame.

A normal calibration cycle could consist of the following service calls: * One call to [start_calibration_cycle] to start the cycle. * One or more calls to [record_sample] to add samples. * One call to [compute_calibration] (which by defalt also saves the calibration and closes the calibration cycle). * One call to [set_active_calibration] to make the newly computed calibration the active one (if desired). | | CloseCalibrationCycle | CloseCalibrationCycleRequest | CloseCalibrationCycleResponse | Close an open calibration cycle.

If the calibration has not been computed or saved yet, it is lost.

This service gives an error if there is no calibration cycle currently open. | | ListCalibrationCycles | ListCalibrationCyclesRequest | ListCalibrationCyclesResponse | List all open calibration cycles. |

| RecordSample | RecordSampleRequest | RecordSampleResponse | Record a new sample for a calibration cycle.

The robot (or moving frame) must be standing still at the pose indicated in the request.

This will record an image and (try to) detect the calibration pattern in it.

This service gives an error if there is no calibration cycle currently open. | | ComputeCalibration | ComputeCalibrationRequest | ComputeCalibrationResponse | Compute the calibration for a calibration cycle.

The amount of samples required depends on whether or not [skip_pattern_pose_computation] is enabled. If it is, only 1 sample is needed, but you can still add more samples to increase the accuracy of the calibration.

If [skip_pattern_pose_computation] is disabled, then the absolute minimum number of samples is 3. However, it is recommended to record at least 10 samples with different robot positions and orientations.

By default, the calibration will be saved using an auto-generated name, and the calibration cycle will be closed. However, both of these actions can be disabled by setting [no_save] and [no_close] respectively.

This service gives an error if there is no calibration cycle currently open. | | SaveComputedCalibration | SaveComputedCalibrationRequest | SaveComputedCalibrationResponse | Save the calibration computed in a calibration cycle.

By default, this service will also close the calibration cycle, but this can be disabled by setting [no_close] to true.

Note that the [compute_calibration] service already saves the calibration by default.

This service gives an error if there is no calibration cycle currently open, or if no calibration has been computed yet. |