create_planar_calib_deformable_modelT_create_planar_calib_deformable_modelCreatePlanarCalibDeformableModelCreatePlanarCalibDeformableModelcreate_planar_calib_deformable_model (Operator)

Name

create_planar_calib_deformable_modelT_create_planar_calib_deformable_modelCreatePlanarCalibDeformableModelCreatePlanarCalibDeformableModelcreate_planar_calib_deformable_model — Create a deformable model for calibrated perspective matching.

Signature

create_planar_calib_deformable_model(Template : : CamParam, ReferencePose, NumLevels, AngleStart, AngleExtent, AngleStep, ScaleRMin, ScaleRMax, ScaleRStep, ScaleCMin, ScaleCMax, ScaleCStep, Optimization, Metric, Contrast, MinContrast, GenParamName, GenParamValue : ModelID)

Description

The operator create_planar_calib_deformable_modelcreate_planar_calib_deformable_modelCreatePlanarCalibDeformableModelCreatePlanarCalibDeformableModelcreate_planar_calib_deformable_model prepares a template, which is passed in the image TemplateTemplateTemplatetemplatetemplate, as a deformable model used for planar calibrated matching. The ROI of the model is passed as the domain of TemplateTemplateTemplatetemplatetemplate.

The planar calibrated matching can be used to detect the 3D pose of a planar object or planar subparts of non-planar objects that are distorted by a projective view. This is an alternative to create_planar_uncalib_deformable_modelcreate_planar_uncalib_deformable_modelCreatePlanarUncalibDeformableModelCreatePlanarUncalibDeformableModelcreate_planar_uncalib_deformable_model, which returns the position as a 2D projective transformation (homography), but not as a metric 3D pose.

In order to determine the 3D pose, the internal camera parameters CamParamCamParamCamParamcamParamcam_param must be provided. Typically, the internal parameters are determined with the help of calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerascalibrate_cameras.

Additionally to the internal camera parameters, the metric size of the image part that is passed in TemplateTemplateTemplatetemplatetemplate must be known. For this, a 3D reference pose that defines a 3D model plane in which the object resides must be provided with ReferencePoseReferencePoseReferencePosereferencePosereference_pose. The 3D model plane is spanned by the x and y axis of the coordinate system defined by ReferencePoseReferencePoseReferencePosereferencePosereference_pose.

As described in create_planar_uncalib_deformable_modelcreate_planar_uncalib_deformable_modelCreatePlanarUncalibDeformableModelCreatePlanarUncalibDeformableModelcreate_planar_uncalib_deformable_model, the origin (reference point) of the model is defined as the center of gravity of the domain (region) of the model image TemplateTemplateTemplatetemplatetemplate. This image point defines a ray that is cut with the plane that is provided with ReferencePoseReferencePoseReferencePosereferencePosereference_pose to obtain the absolute 3D model pose. This is also the absolute pose that is later returned in find_planar_calib_deformable_modelfind_planar_calib_deformable_modelFindPlanarCalibDeformableModelFindPlanarCalibDeformableModelfind_planar_calib_deformable_model. Hence, the 3D pose of the model might differ from the reference pose by a 2D translation in the model plane. The final model pose can be determined by calling get_deformable_model_paramsget_deformable_model_paramsGetDeformableModelParamsGetDeformableModelParamsget_deformable_model_params. The 3D model plane can be estimated by using calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerascalibrate_cameras or vector_to_posevector_to_poseVectorToPoseVectorToPosevector_to_pose. For consistency of the coordinate systems, the ReferencePoseReferencePoseReferencePosereferencePosereference_pose should be aligned as if a calibration plate would be put onto the object.

For further explanation on the planar deformable model and its parameters we refer to the description of create_planar_uncalib_deformable_modelcreate_planar_uncalib_deformable_modelCreatePlanarUncalibDeformableModelCreatePlanarUncalibDeformableModelcreate_planar_uncalib_deformable_model.

Execution Information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

TemplateTemplateTemplatetemplatetemplate (input_object) (multichannel-)image → object (byte / uint2)

Input image whose domain will be used to create the model.

CamParamCamParamCamParamcamParamcam_param (input_control) campar → (real / integer / string)

The parameters of the internal orientation of the camera.

ReferencePoseReferencePoseReferencePosereferencePosereference_pose (input_control) pose → (real / integer)

The reference pose of the object in the reference image.

NumLevelsNumLevelsNumLevelsnumLevelsnum_levels (input_control) integer → (integer / string)

Maximum number of pyramid levels.

Default: 'auto' "auto" "auto" "auto" "auto"

List of values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 'auto'"auto""auto""auto""auto"

AngleStartAngleStartAngleStartangleStartangle_start (input_control) angle.rad-array → (real)

This parameter is not used.

Default: []

AngleExtentAngleExtentAngleExtentangleExtentangle_extent (input_control) angle.rad-array → (real)

This parameter is not used.

Default: []

AngleStepAngleStepAngleStepangleStepangle_step (input_control) angle.rad → (real / string)

Step length of the angles (resolution).

Default: 'auto' "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto", 0.0175, 0.0349, 0.0524, 0.0698, 0.0873

Restriction: AngleStep > 0 && AngleStep <= pi / 16

ScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin (input_control) number → (real)

Minimum scale of the pattern in row direction.

Default: 1.0

Suggested values: 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Restriction: ScaleRMin > 0

ScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax (input_control) number-array → (real)

This parameter is not used.

Default: []

ScaleRStepScaleRStepScaleRStepscaleRStepscale_rstep (input_control) number → (real / string)

Scale step length (resolution) in row direction.

Default: 'auto' "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto", 0.01, 0.02, 0.05, 0.1, 0.15, 0.2

Restriction: ScaleRStep >= 0

ScaleCMinScaleCMinScaleCMinscaleCMinscale_cmin (input_control) number → (real)

Minimum scale of the pattern in column direction.

Default: 1.0

Suggested values: 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Restriction: ScaleCMin > 0

ScaleCMaxScaleCMaxScaleCMaxscaleCMaxscale_cmax (input_control) number-array → (real)

This parameter is not used.

Default: []

ScaleCStepScaleCStepScaleCStepscaleCStepscale_cstep (input_control) number → (real / string)

Scale step length (resolution) in the column direction.

Default: 'auto' "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto", 0.01, 0.02, 0.05, 0.1, 0.15, 0.2

Restriction: ScaleCStep >= 0

OptimizationOptimizationOptimizationoptimizationoptimization (input_control) string(-array) → (string)

Kind of optimization used for generating the model.

Default: 'none' "none" "none" "none" "none"

List of values: 'auto'"auto""auto""auto""auto", 'none'"none""none""none""none", 'point_reduction_high'"point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high", 'point_reduction_low'"point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low", 'point_reduction_medium'"point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium"

MetricMetricMetricmetricmetric (input_control) string → (string)

Match metric.

Default: 'use_polarity' "use_polarity" "use_polarity" "use_polarity" "use_polarity"

List of values: 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity", 'ignore_global_polarity'"ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity", 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity", 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity", 'use_polarity'"use_polarity""use_polarity""use_polarity""use_polarity"

ContrastContrastContrastcontrastcontrast (input_control) number-array → (integer / string)

Thresholds or hysteresis thresholds for the contrast of the object in the template image.

Default: 'auto' "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto", 10, 20, 30, 40, 60, 80, 100, 120, 140, 160

MinContrastMinContrastMinContrastminContrastmin_contrast (input_control) number → (integer / string)

Minimum contrast of the objects in the search images.

Default: 'auto' "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto", 1, 2, 3, 5, 7, 10, 20, 30, 40

Restriction: MinContrast < Contrast

GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) string-array → (string)

The parameter names.

Default: []

List of values: [], 'part_size'"part_size""part_size""part_size""part_size"

GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) integer-array → (integer / real / string)

Values of the parameters.

Default: []

List of values: [], 'big'"big""big""big""big", 'medium'"medium""medium""medium""medium", 'small'"small""small""small""small"

ModelIDModelIDModelIDmodelIDmodel_id (output_control) deformable_model → (handle)

Handle of the model.

Result

If the parameters are valid, the operator create_planar_calib_deformable_modelcreate_planar_calib_deformable_modelCreatePlanarCalibDeformableModelCreatePlanarCalibDeformableModelcreate_planar_calib_deformable_model returns the value 2 ( H_MSG_TRUE) . If necessary an exception is raised.