get_calib_data — Query data stored or computed in a calibration data model.
get_calib_data( : : CalibDataID, ItemType, ItemIdx, DataName : DataValue)
With the operator get_calib_data, you can query data of the
calibration data model CalibDataID.
Note that in the following, all 'pose'-related data is given in relation to
the coordinate system of the model's reference camera, which can be
set with set_calib_data and queried with get_calib_data. By
default, the first camera (camera index 0) is used as reference camera.
The calibration data model contains various kinds of data. How to query specific data of the calibration data model is described for different categories of data:
Model-related data (ItemType 'model')
Camera-related data (ItemType 'camera')
Data related to calibration objects (ItemType 'calib_obj')
Data related to calibration object poses (ItemType 'calib_obj_pose')
Hand-eye calibration related data (different values for ItemType)
Before we describe the individual data you can query in detail, we provide
you with an overview on which data is available after the individual steps of
the calibration processes. When calibrating cameras or a hand-eye system,
several operators are called that step by step fill the calibration data
model with content. In the following, for each operator a table lists the
data that is added to the model. Additionally, you find information about the
combinations of the values for ItemType, ItemIdx, and
DataName that are needed to query the information with
get_calib_data. For the different indices that are used within the
tables the following abbreviations (or potential variable names) are used:
Camera index: CameraIdx
Calibration object index: CalibObjIdx
Calibration object pose index: CalibObjPoseIdx
Detailed descriptions of the data that can be queried can then be found in the specific sections that handle the different categories of data individually.
To get detailed information about the calibration process of your camera setup see the chapter reference Calibration.
For each operator that extends the calibration model, a table is provided to give an overview on the respective data:
For standard HALCON calibration plates, further calibration plate specific
information is added to the model, which is not accessible with
get_calib_data but can be obtained directly from the corresponding
calibration plate description files instead (for details about the
description files see create_caltab for a calibration plate with
hexagonally arranged marks and gen_caltab for a calibration plate
with rectangularly arranged marks).
find_calib_object (for standard HALCON calibration plates):
| Data added to the model | accessible with |
| Observed image coordinates of the calibration marks | get_calib_data_observ_points |
| Observed contours of the calibration marks | get_calib_data_observ_contours |
| Observed poses of the calibration plate relative to the camera coordinate system | get_calib_data_observ_pose or get_calib_data_observ_points
|
set_calib_data_observ_points (for other calibration objects than the HALCON calibration plates):
| Data added to the model | accessible with |
| Observed image coordinates of the calibration marks | get_calib_data_observ_points
|
| Data added to the model | ItemType |
ItemIdx |
DataName |
| Reference camera | 'model' | 'general' | 'reference_camera' |
| Internal and external camera parameters to calibrate | 'camera' | 'general' or CameraIdx |
'calib_settings' |
| Internal and external camera parameters to be excluded from the calibration | 'camera' | 'general' or CameraIdx |
'excluded_settings' |
| For stereo setups with telecentric line scan cameras: Do the cameras have a common motion vector? | 'model' | 'general' | 'common_motion_vector' |
| Calibration object pose settings to be optimized | 'calib_obj_pose' | 'general' or [CalibObjIdx, CalibObjPoseIdx] |
'calib_settings' |
| Calibration object pose settings to be excluded from the calibration | 'calib_obj_pose' | 'general' or [CalibObjIdx, CalibObjPoseIdx] |
'excluded_settings' |
| Data added to the model | ItemType |
ItemIdx |
DataName |
| Camera setup model (needed for multi-view stereo reconstruction) | 'model' | 'general' | 'camera_setup_model' |
| Optimized internal camera parameters | 'camera' | CameraIdx |
'params' |
| Standard deviations of the optimized internal camera parameters | 'camera' | CameraIdx |
'params_deviations' |
| Covariance matrices of the optimized internal camera parameters | 'camera' | CameraIdx |
'params_covariances' |
| Labels for the internal camera parameters | 'camera' | CameraIdx |
'params_labels' |
| Initial external camera parameters (camera poses) | 'camera' | CameraIdx |
'init_pose' |
| Optimized external camera parameters (camera poses) | 'camera' | CameraIdx |
'pose' |
| Labels for the external camera parameters (camera poses) | 'camera' | CameraIdx |
'pose_labels' |
| Initial calibration object poses | 'calib_obj_pose' | [CalibObjIdx, CalibObjPoseIdx] |
'init_pose' |
| Optimized calibration object poses | 'calib_obj_pose' | [CalibObjIdx, CalibObjPoseIdx] |
'pose' |
| Labels for the calibration object pose parameters | 'calib_obj_pose' | [CalibObjIdx, CalibObjPoseIdx] |
'pose_labels' |
For each operator that extends the calibration model when performing hand-eye calibration, a table is provided to give an overview on the respective data:
See the section 'Content of Calibration Data Model When Calibrating Cameras'.
set_calib_data_observ_pose (observations obtained by 3D sensors):
| Data added to the model | accessible with |
| Observed calibration object poses | get_calib_data_observ_pose
|
set_calib_data_cam_param,
set_calib_data_calib_object, and
find_calib_object or set_calib_data_observ_points
(observations obtained by cameras):
See the section 'Content of Calibration Data Model When Calibrating Cameras'.
Moving camera scenario:
| Data added to the model | ItemType |
ItemIdx |
DataName |
| Pose of robot tool in camera coordinate system | 'camera' | 0 | 'tool_in_cam_pose' |
| Pose of calibration object in robot base coordinate system | 'calib_obj' | 0 | 'obj_in_base_pose' |
| Standard deviations of the Pose of the robot tool in camera coordinate system | 'camera' | 0 | 'tool_in_cam_pose_deviations' |
| Covariance matrices of the Pose of the robot tool in camera coordinate system | 'camera' | 0 | 'tool_in_cam_pose_covariances' |
| Standard deviations of the Pose of the calibration object in robot base coordinate system | 'calib_obj' | 0 | 'obj_in_base_pose_deviations' |
| Covariance matrices of the Pose of the calibration object in robot base coordinate system | 'calib_obj' | 0 | 'obj_in_base_pose_covariances' |
Stationary camera scenario:
| Data added to the model | ItemType |
ItemIdx |
DataName |
| Pose of robot base in camera coordinate system | 'camera' | 0 | 'base_in_cam_pose' |
| Pose of calibration object in robot tool coordinate system | 'calib_obj' | 0 | 'obj_in_tool_pose' |
| Standard deviations of the Pose of the robot base in camera coordinate system | 'camera' | 0 | 'base_in_cam_pose_deviations' |
| Covariance matrices of the Pose of the robot base in camera coordinate system | 'camera' | 0 | 'base_in_cam_pose_covariances' |
| Standard deviations of the Pose of the calibration object in robot tool coordinate system | 'calib_obj' | 0 | 'obj_in_tool_pose_deviations' |
| Covariance matrices of the Pose of the calibration object in robot tool coordinate system | 'calib_obj' | 0 | 'obj_in_tool_covariances' |
Both hand-eye scenarios:
| Data added to the model | ItemType |
ItemIdx |
DataName |
| Calibrated poses of the calibration object in camera coordinate system (not available for SCARA robots) | 'calib_obj_pose' | [0, CalibObjPoseIdx] | 'pose' |
| Root mean square error (RMSE) of the back projection after the optimization of the camera system | 'model' | 'general' | 'camera_calib_error' |
| Pose error of the complete chain of transformations | 'model' | 'general' | 'hand_eye_calib_error' |
| Camera setup model (needed for multi-view stereo reconstruction) | 'model' | 'general' | 'camera_setup_model' |
The following sections describe the parameters for the specific categories of data in more detail.
ItemType='model':ItemIdx must be set to 'general'.
Depending on the selection
in DataName, the following model-related data is then
returned in DataValue:
Type of the calibration data model. Currently, the five types 'calibration_object', 'hand_eye_stationary_cam', 'hand_eye_moving_cam', 'hand_eye_scara_stationary_cam', and 'hand_eye_scara_moving_cam' are supported.
Index of the reference camera for the calibration model. All poses stored in the calibration data model are specified in the coordinate system of this reference camera.
Number of cameras in the calibration data model (see
create_calib_data).
Number of calibration objects in the calibration data model (see
create_calib_data).
For stereo setups with telecentric line scan cameras, a string with a Boolean value (i.e., 'true' or 'false') that determines whether the cameras have a common motion vector.
A handle to a camera setup model containing the poses and the internal parameters for the calibrated cameras from the current calibration setup.
The root mean square error (RMSE) of the back projection of the
optimization of the camera system. Typically, this error is
queried after a hand eye calibration
(calibrate_hand_eye) was performed, where internally the
camera system is calibrated without returning the error of the
camera calibration. The returned error is identical to the error
returned by calibrate_cameras.
After a successful hand_eye calibration, the pose error of the
complete chain of transformations is returned. To be more
precise, a tuple with four elements is returned, where the first
element is the root-mean-square error of the translational part,
the second element is the root-mean-square error of the
rotational part, the third element is the maximum translational
error and the fourth element is the maximum rotational
error. The returned errors are identical to the errors returned
by calibrate_hand_eye.
Optimization method that was set for the hand-eye calibration
(see set_calib_data).
The parameters 'reference_camera',
'common_motion_vector', and 'optimization_method'
can be set with set_calib_data. The other parameters are set
during the model creation or are a result of the calibration process
and cannot be modified.
ItemType='camera':ItemIdx determines, if data is queried for all cameras in
general or for a specific camera. With ItemIdx='general',
the default value of a parameter for all cameras is returned. In contrast,
if you pass a valid camera index instead, i.e., a number between 0 and
NumCameras-1 (NumCameras is specified during model
creation with create_calib_data), only the parameter value of the
specified camera is returned.
By selecting the following parameters in DataName, you can
query which camera parameters are (or have been) optimized during
the calibration performed by calibrate_cameras:
List of the camera parameters that are marked for calibration.
List of camera parameters that are excluded from the calibration.
These parameters can be modified by a corresponding call to
set_calib_data.
The following parameters can only be queried for a specific camera,
i.e., you must pass a valid camera index in ItemIdx:
The camera type that was set with set_calib_data_cam_param.
Initial internal camera parameters (set with
set_calib_data_cam_param).
Optimized internal camera parameters.
Standard deviations of the optimized camera parameters, as estimated at the end of the camera calibration. Note that if the tuple returned for 'params' contains elements, the tuple returned for 'params_deviations' contains elements since the camera parameter tuple contains the camera type in the first element of the tuple, whereas the tuple returned for 'params_deviations' does not contain the camera type.
Covariance matrix of the optimized camera parameters, as estimated at the end of the camera calibration. Note that if the tuple returned for 'params' contains elements, the tuple returned for 'params_covariances' contains elements since the camera parameter tuple contains the camera type in the first element of the tuple, whereas the tuple returned for 'params_covariances' does not contain the camera type.
A convenience list of labels for the entries returned by 'params'. This list is camera-type specific. Note that this list contains the label 'camera_type' in its first position. If the first element of the tuple is removed, the list refers to the labels of 'params_deviations' and the labels of the rows and columns of 'params_covariances'.
Initial camera pose, relative to the current reference camera. It is computed internally based on observation poses during the calibration process (see Calibration).
Optimized camera pose, relative to the current reference camera. If one single telecentric camera is calibrated, the translation along the z-axis is set to the value 0.0. If more than one telecentric camera is calibrated, the camera poses are moved in direction of their z-axis until they all lie on a sphere centered at the first observed calibration plate. The radius of the sphere corresponds to the longest distance of a camera to the first observed calibration plate. If this calculated distance is smaller than 1 m, the radius is set to 1 m.
A convenience list of labels for the entries returned by 'pose'.
The calibrated camera parameters ('params' and
'pose') can be queried only after a successful execution of
calibrate_cameras. The initial internal camera parameters
'init_params' can be queried after a successful call to
set_calib_data_cam_param.
ItemType='calib_obj':ItemIdx must be set to a valid calibration object index
(number between 0 and NumCalibObjects-1).
NumCalibObjects is specified during the model creation with
create_calib_data.
The following parameters can be queried with
DataName and are returned in DataValue:
Number of calibration marks of the calibration object.
Coordinates of the calibration marks relative to the calibration object coordinate system.
These parameters can be modified with
set_calib_data_calib_object.
ItemType='calib_obj_pose':ItemIdx determines, if data is queried for all
calibration object poses in general or for a specific calibration object
pose. With ItemIdx='general', the default value of a
parameter for all calibration object poses is returned. In contrast, if
you pass a valid calibration object index instead, i.e., a tuple
containing a valid index pair [CalibObjIdx, CalibObjPoseIdx],
only the parameter value of the specified calibration object pose is
returned.
By selecting the following parameters in DataName, you can
query which calibration object pose parameters are (or have been)
optimized during the calibration performed by
calibrate_cameras:
List of calibration object pose parameters marked for calibration.
List of calibration object pose parameters excluded from calibration.
These parameters can be set with set_calib_data.
The following parameters can only be queried for a specific
calibration object pose, i.e., you must pass a valid index pair
[CalibObjIdx, CalibObjPoseIdx] in ItemIdx:
Initial calibration object pose. It is computed internally based on observation poses during the calibration process (see Calibration). This pose is relative to the current reference camera.
Optimized calibration object pose, relative to current reference camera.
A convenience list of labels for the entries returned by 'pose'.
These parameters cannot be explicitly modified and can only be
queried after calibrate_cameras was executed.
After performing a successful hand-eye calibration using
calibrate_hand_eye, the following poses can be queried for a
calibration data model of type:
For ItemType='camera' and
DataName='tool_in_cam_pose', the pose of the
robot tool in the camera coordinate system is returned in
DataValue. For ItemType='calib_obj'
and DataName='obj_in_base_pose', the pose of
the calibration object in the robot base coordinate system is
returned in DataValue.
Note that when calibrating SCARA robots, it is not possible to
determine the Z translation of 'obj_in_base_pose'.
To eliminate this ambiguity the Z translation
'obj_in_base_pose' is internally set to 0.0 and the
'tool_in_cam_pose' is calculated accordingly. It is
necessary to determine the true translation in Z after the
calibration (see calibrate_hand_eye).
The standard deviations and the covariance matrices of the 6
pose parameters of both poses can be queried with
'tool_in_cam_pose_deviations',
'tool_in_cam_pose_covariances' (ItemType='camera'),
'obj_in_base_pose_deviations', and
'obj_in_base_pose_covariances' (ItemType='calib_obj'). Like poses, they are
specified in the units [m] and [°].
For ItemType='camera' and
DataName='base_in_cam_pose', the pose of the
robot base in the camera coordinate system is returned in
DataValue. For
ItemType='calib_obj' and
DataName='obj_in_tool_pose', the pose of the
calibration object in the robot tool coordinate system is returned
in DataValue.
Note that when calibrating SCARA robots, it is not possible to
determine the Z translation of 'obj_in_tool_pose'. To
eliminate this ambiguity the Z translation of
'obj_in_tool_pose' is internally set to 0.0 and the
'base_in_cam_pose' is calculated accordingly. It is
necessary to determine the true translation in Z after the
calibration (see calibrate_hand_eye).
The standard deviations and the covariance matrices of the 6
pose parameters of both poses can be queried with
'base_in_cam_pose_deviations',
'base_in_cam_pose_covariances' (ItemType='camera'),
'obj_in_tool_pose_deviations', and
'obj_in_tool_pose_covariances' (ItemType='calib_obj'). Like poses, they are
specified in the units [m] and [°].
For ItemType='tool' and
DataName='tool_in_base_pose', the pose of the
robot tool in the robot base coordinate system with Index
ItemIdx is returned in DataValue These poses were
previously set using set_calib_data and served as input for
the hand-eye calibration algorithm.
CalibDataID (input_control) calib_data → (handle)
Handle of a calibration data model.
ItemType (input_control) string → (string)
Type of calibration data item.
Default value: 'camera'
List of values: 'calib_obj', 'calib_obj_pose', 'camera', 'model', 'tool'
ItemIdx (input_control) integer(-array) → (integer / string)
Index of the affected item (depending on the
selected ItemType).
Default value: 0
Suggested values: 0, 1, 2, 'general'
DataName (input_control) attribute.name(-array) → (string)
The name of the inspected data.
Default value: 'params'
List of values: 'base_in_cam_pose', 'base_in_cam_pose_covariances', 'base_in_cam_pose_deviations', 'calib_settings', 'camera_calib_error', 'camera_setup_model', 'common_motion_vector', 'excluded_settings', 'hand_eye_calib_error', 'init_params', 'init_pose', 'num_calib_objs', 'num_cameras', 'num_marks', 'obj_in_base_pose', 'obj_in_base_pose_covariances', 'obj_in_base_pose_deviations', 'obj_in_tool_pose', 'obj_in_tool_pose_covariances', 'obj_in_tool_pose_deviations', 'optimization_method', 'params', 'params_covariances', 'params_deviations', 'params_labels', 'pose', 'pose_labels', 'reference_camera', 'tool_in_base_pose', 'tool_in_cam_pose', 'tool_in_cam_pose_covariances', 'tool_in_cam_pose_deviations', 'type', 'x', 'y', 'z'
DataValue (output_control) attribute.value(-array) → (real / integer / string)
Requested data.
* Get the camera type of camera 0. get_calib_data (CalibDataID, 'camera', 0, 'type', CameraType) * Get the optimized (calibrated) pose of pose 1 of the * calibration object 2. get_calib_data (CalibDataID, 'calib_obj_pose', [2,1], 'pose', CalobjPose)
calibrate_cameras,
calibrate_hand_eye,
create_calib_data,
read_calib_data
Calibration