find_calib_objectT_find_calib_objectFindCalibObjectFindCalibObject (Operator)

Name

find_calib_objectT_find_calib_objectFindCalibObjectFindCalibObject — Find the HALCON calibration plate and set the extracted points and contours in a calibration data model.

Signature

find_calib_object(Image : : CalibDataID, CameraIdx, CalibObjIdx, CalibObjPoseIdx, GenParamName, GenParamValue : )

Herror T_find_calib_object(const Hobject Image, const Htuple CalibDataID, const Htuple CameraIdx, const Htuple CalibObjIdx, const Htuple CalibObjPoseIdx, const Htuple GenParamName, const Htuple GenParamValue)

void FindCalibObject(const HObject& Image, const HTuple& CalibDataID, const HTuple& CameraIdx, const HTuple& CalibObjIdx, const HTuple& CalibObjPoseIdx, const HTuple& GenParamName, const HTuple& GenParamValue)

void HCalibData::FindCalibObject(const HImage& Image, Hlong CameraIdx, Hlong CalibObjIdx, Hlong CalibObjPoseIdx, const HTuple& GenParamName, const HTuple& GenParamValue) const

static void HOperatorSet.FindCalibObject(HObject image, HTuple calibDataID, HTuple cameraIdx, HTuple calibObjIdx, HTuple calibObjPoseIdx, HTuple genParamName, HTuple genParamValue)

void HCalibData.FindCalibObject(HImage image, int cameraIdx, int calibObjIdx, int calibObjPoseIdx, HTuple genParamName, HTuple genParamValue)

Description

find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject searches in ImageImageImageImageimage for a HALCON calibration plate corresponding to the description of the calibration object with the index CalibObjIdxCalibObjIdxCalibObjIdxCalibObjIdxcalibObjIdx from the calibration data model CalibDataIDCalibDataIDCalibDataIDCalibDataIDcalibDataID. If a calibration plate is found, find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject extracts the centers and the contours of its marks and estimates the pose of the plate relative to the observing camera CameraIdxCameraIdxCameraIdxCameraIdxcameraIdx. All collected observation data is stored in the calibration data model for the calibration object pose CalibObjPoseIdxCalibObjPoseIdxCalibObjPoseIdxCalibObjPoseIdxcalibObjPoseIdx. In order to ensure a successful detection of the calibration plate, at least one finder pattern has to be visible in the image. For calibration plates with hexagonally arranged marks this is a special mark hexagon where either four or six marks contain a hole, while for calibration plates with rectangularly arranged marks this is the border of the calibration plate with a triangle in one corner.

Preparation of the input data

Before the operator find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject can be called, a calibration data model has to be defined performing the following steps:

  1. Create a calibration data model with the operator create_calib_datacreate_calib_dataCreateCalibDataCreateCalibDataCreateCalibData, specifying the number of cameras in the setup and the number of used calibration objects.

  2. Specify the camera type and the initial internal camera parameters for all cameras with the operator set_calib_data_cam_paramset_calib_data_cam_paramSetCalibDataCamParamSetCalibDataCamParamSetCalibDataCamParam. Note that only cameras of the same type can be calibrated in a single setup.

  3. Specify the description of all calibration objects with the operator set_calib_data_calib_objectset_calib_data_calib_objectSetCalibDataCalibObjectSetCalibDataCalibObjectSetCalibDataCalibObject. Note that for a successful call of find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject a valid description file of the calibration plate is necessary. This description file has to be set beforehand via the operator set_calib_data_calib_objectset_calib_data_calib_objectSetCalibDataCalibObjectSetCalibDataCalibObjectSetCalibDataCalibObject. As a consequence, the usage of a user-defined calibration object can only be made by the operator set_calib_data_observ_pointsset_calib_data_observ_pointsSetCalibDataObservPointsSetCalibDataObservPointsSetCalibDataObservPoints.

Collecting observation data

find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject is used to collect observations in a calibration data model. Beyond, it stores additional observation data that cannot be added to the model with set_calib_data_observ_pointsset_calib_data_observ_pointsSetCalibDataObservPointsSetCalibDataObservPointsSetCalibDataObservPoints and that is dependent on the used calibration plate. While for calibration plates with rectangularly arranged marks (see gen_caltabgen_caltabGenCaltabGenCaltabGenCaltab) the rim of the calibration plate is added to the observations, calibration plates with hexagonal pattern (see create_caltabcreate_caltabCreateCaltabCreateCaltabCreateCaltab) store one of their finder pattern. Additionally and irrespective of the used calibration plate, the contour of each mark is added to the calibration model.

Setting additional parameters

Using calibration plates with hexagonally arranged marks, the following additional parameter can be set via GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue:

'sigma'"sigma""sigma""sigma""sigma":

Smoothing factor for the extraction of the mark contours. For increasing values of 'sigma'"sigma""sigma""sigma""sigma", the filter width and thereby the amount of smoothing increases (see also edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPix for the influence of the filter width on the Canny filter).

Suggested values: 0.5, 0.7, 0.9, 1.0 (default), 1.2, 1.5

For calibration plates with rectangularly arranged marks, find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject essentially encapsulates the sequence of three operator calls: find_caltabfind_caltabFindCaltabFindCaltabFindCaltab, find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPose and set_calib_data_observ_pointsset_calib_data_observ_pointsSetCalibDataObservPointsSetCalibDataObservPointsSetCalibDataObservPoints. For this kind of calibration plates the following parameters can be set using GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue:

'alpha'"alpha""alpha""alpha""alpha":

Smoothing factor for the extraction of the mark contours. For increasing values of 'alpha'"alpha""alpha""alpha""alpha", the filter width and thereby the amount of smoothing decreases (see also edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPix for the influence of the filter width on the Lanser2 filter ).

Suggested values: 0.5, 0.7, 0.9 (default), 1.0, 1.2, 1.5

'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance":

Tolerance factor for gaps between the marks. If the marks appear closer to each other than expected, you might set 'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance" < 1.0 to avoid disturbing patterns outside the calibration plate to be associated with the calibration plate. This can typically happen if the plate is strongly tilted and positioned in front of a background that exposes mark-like patterns. If the distances between single marks vary in a wide range, e.g., if the calibration plate appears with strong perspective distortion in the image, you might set 'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance" > 1.0 to enforce the marks grouping (see also find_caltabfind_caltabFindCaltabFindCaltabFindCaltab).

Suggested values: 0.75, 0.9, 1.0 (default), 1.1, 1.2, 1.5

'max_diam_marks'"max_diam_marks""max_diam_marks""max_diam_marks""max_diam_marks":

Maximum expected diameter of the marks (needed internally by find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPose). By default, this value is estimated by the preceding internal call to find_caltabfind_caltabFindCaltabFindCaltabFindCaltab. However, if the estimation is erroneous for no obvious reason or the internal call to find_caltabfind_caltabFindCaltabFindCaltabFindCaltab fails or is simply skipped (see 'skip_find_caltab'"skip_find_caltab""skip_find_caltab""skip_find_caltab""skip_find_caltab" below), you might have to adjust this value.

Suggested values: 50.0, 100.0, 150.0, 200.0, 300.0

'skip_find_caltab'"skip_find_caltab""skip_find_caltab""skip_find_caltab""skip_find_caltab":

Skip the internal call to find_caltabfind_caltabFindCaltabFindCaltabFindCaltab. If activated, only the domain of ImageImageImageImageimage reduces the search area for the internal call of find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPose. Thus, a user defined calibration plate region can be incorporated by setting 'skip_find_caltab'"skip_find_caltab""skip_find_caltab""skip_find_caltab""skip_find_caltab"='false'"false""false""false""false" and reducing the ImageImageImageImageimage domain to the user region.

List of values: 'false'"false""false""false""false" (default), 'true'"true""true""true""true"

If using a HALCON calibration plate as calibration object, it is recommended to use find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject instead of set_calib_data_observ_pointsset_calib_data_observ_pointsSetCalibDataObservPointsSetCalibDataObservPointsSetCalibDataObservPoints where possible, since the contour information, which it stores in the calibration data model, enables a more precise calibration procedure with calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerasCalibrateCameras.

After a successful call to find_calib_objectfind_calib_objectFindCalibObjectFindCalibObjectFindCalibObject, the extracted points can be queried by get_calib_data_observ_pointsget_calib_data_observ_pointsGetCalibDataObservPointsGetCalibDataObservPointsGetCalibDataObservPoints and the extracted contours can be accessed by get_calib_data_observ_contoursget_calib_data_observ_contoursGetCalibDataObservContoursGetCalibDataObservContoursGetCalibDataObservContours.

Execution Information

This operator modifies the state of the following input parameter:

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

ImageImageImageImageimage (input_object)  singlechannelimage objectHImageHImageHobject (byte / uint2)

Input image.

CalibDataIDCalibDataIDCalibDataIDCalibDataIDcalibDataID (input_control, state is modified)  calib_data HCalibData, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of a calibration data model.

CameraIdxCameraIdxCameraIdxCameraIdxcameraIdx (input_control)  number HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Index of the observing camera.

Default value: 0

Suggested values: 0, 1, 2

CalibObjIdxCalibObjIdxCalibObjIdxCalibObjIdxcalibObjIdx (input_control)  number HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Index of the calibration object.

Default value: 0

Suggested values: 0, 1, 2

CalibObjPoseIdxCalibObjPoseIdxCalibObjPoseIdxCalibObjPoseIdxcalibObjPoseIdx (input_control)  number HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Index of the observed calibration object.

Default value: 0

Suggested values: 0, 1, 2

Restriction: CalibObjPoseIdx >= 0

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name-array HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters to be set.

Default value: []

List of values: 'alpha'"alpha""alpha""alpha""alpha", 'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance", 'max_diam_marks'"max_diam_marks""max_diam_marks""max_diam_marks""max_diam_marks", 'sigma'"sigma""sigma""sigma""sigma", 'skip_find_caltab'"skip_find_caltab""skip_find_caltab""skip_find_caltab""skip_find_caltab"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  attribute.value-array HTupleHTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

Values of the generic parameters to be set.

Default value: []

Suggested values: 0.5, 0.9, 1.0, 1.2, 1.5, 2.0, 'true'"true""true""true""true", 'false'"false""false""false""false"

Possible Predecessors

read_imageread_imageReadImageReadImageReadImage, find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPose, set_calib_data_cam_paramset_calib_data_cam_paramSetCalibDataCamParamSetCalibDataCamParamSetCalibDataCamParam, set_calib_data_calib_objectset_calib_data_calib_objectSetCalibDataCalibObjectSetCalibDataCalibObjectSetCalibDataCalibObject

Possible Successors

set_calib_dataset_calib_dataSetCalibDataSetCalibDataSetCalibData, calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerasCalibrateCameras

Alternatives

find_caltabfind_caltabFindCaltabFindCaltabFindCaltab, find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPose, set_calib_data_observ_pointsset_calib_data_observ_pointsSetCalibDataObservPointsSetCalibDataObservPointsSetCalibDataObservPoints

Module

Calibration