create_component_modelCreateComponentModelCreateComponentModelcreate_component_modelT_create_component_model🔗

Short description🔗

create_component_modelCreateComponentModelCreateComponentModelcreate_component_modelT_create_component_model — Prepare a component model for matching based on explicitly specified components and relations.

Warning🔗

create_component_modelCreateComponentModel is obsolete and is only provided for reasons of backward compatibility. The operator will be removed with HALCON 26.11.

Signature🔗

create_component_model( image ModelImage, region ComponentRegions, integer VariationRow, integer VariationColumn, angle.rad VariationAngle, angle.rad AngleStart, angle.rad AngleExtent, integer ContrastLowComp, integer ContrastHighComp, integer MinSizeComp, integer MinContrastComp, real MinScoreComp, integer NumLevelsComp, angle.rad AngleStepComp, string OptimizationComp, string MetricComp, string PregenerationComp, out component_model ComponentModelID, out integer RootRanking )

Description🔗

create_component_modelCreateComponentModel prepares patterns, which are passed in the form of a model image ModelImagemodelImagemodel_image and several regions ComponentRegionscomponentRegionscomponent_regions, as a component model for matching. The output parameter ComponentModelIDcomponentModelIDcomponent_model_id is a handle for this model, which is used in subsequent calls to find_component_modelFindComponentModel. In contrast to create_trained_component_modelCreateTrainedComponentModel, no preceding training with train_model_componentsTrainModelComponents needs to be performed before calling create_component_modelCreateComponentModel.

Each of the regions passed in ComponentRegionscomponentRegionscomponent_regions describes a separate model component. Later, the index of a component region in ComponentRegionscomponentRegionscomponent_regions is used to denote the model component. The reference point of a component is the center of gravity of its associated region, which is passed in ComponentRegionscomponentRegionscomponent_regions. It can be calculated by calling area_centerAreaCenter.

The relative movements (relations) of the model components can be set by passing VariationRowvariationRowvariation_row, VariationColumnvariationColumnvariation_column, and VariationAnglevariationAnglevariation_angle. Because directly passing the relations is complicated, instead of the relations the variations of the model components are passed. The variations describe the movements of the components independently from each other relative to their poses in the model image ModelImagemodelImagemodel_image. The parameters VariationRowvariationRowvariation_row and VariationColumnvariationColumnvariation_column describe the movement of the components in row and column direction by \(\pm\frac{1}{2}\textrm{VariationRow}\) and \(\pm\frac{1}{2}\textrm{VariationColumn}\), respectively. The parameter VariationAnglevariationAnglevariation_angle describes the angle variation of the component by \(\pm\frac{1}{2}\textrm{VariationAngle}\). Based on these values, the relations are automatically computed. The three parameters must either contain one element, in which case the parameter is used for all model components, or must contain the same number of elements as ComponentRegionscomponentRegionscomponent_regions, in which case each parameter element refers to the corresponding model component in ComponentRegionscomponentRegionscomponent_regions.

The parameters AngleStartangleStartangle_start and AngleExtentangleExtentangle_extent determine the range of possible rotations of the component model in an image.

Internally, a separate shape model is built for each model component (see create_shape_modelCreateShapeModel). Therefore, the parameters ContrastLowCompcontrastLowCompcontrast_low_comp, ContrastHighCompcontrastHighCompcontrast_high_comp, MinSizeCompminSizeCompmin_size_comp, MinContrastCompminContrastCompmin_contrast_comp, MinScoreCompminScoreCompmin_score_comp, NumLevelsCompnumLevelsCompnum_levels_comp, AngleStepCompangleStepCompangle_step_comp, OptimizationCompoptimizationCompoptimization_comp, MetricCompmetricCompmetric_comp, and PregenerationComppregenerationComppregeneration_comp correspond to the parameters of create_shape_modelCreateShapeModel, with the following differences: First, in the parameter Contrastcontrastcontrast of create_shape_modelCreateShapeModel the upper as well as the lower threshold for the hysteresis threshold method can be passed. Additionally, a third value, which suppresses small connected contour regions, can be passed. In contrast, the operator create_component_modelCreateComponentModel offers three separate parameters ContrastHighCompcontrastHighCompcontrast_high_comp, ContrastLowCompcontrastLowCompcontrast_low_comp, and MinScoreCompminScoreCompmin_score_comp in order to set these three values. Consequently, also the automatic computation of the contrast threshold(s) is different. If both hysteresis threshold should be automatically determined, both ContrastLowCompcontrastLowCompcontrast_low_comp and ContrastHighCompcontrastHighCompcontrast_high_comp must be set to 'auto'"auto". In contrast, if only one threshold value should be determined, ContrastLowCompcontrastLowCompcontrast_low_comp must be set to 'auto'"auto" while ContrastHighCompcontrastHighCompcontrast_high_comp must be set to an arbitrary value different from 'auto'"auto". Secondly, the parameter Optimizationoptimizationoptimization of create_shape_modelCreateShapeModel provides the possibility to reduce the number of model points as well as the possibility to completely pregenerate the shape model. In contrast, the operator create_trained_component_modelCreateTrainedComponentModel uses a separate parameter PregenerationComppregenerationComppregeneration_comp in order to decide whether the shape models should be completely pregenerated or not. A third difference concerning the parameter MinScoreCompminScoreCompmin_score_comp should be noted. When using the shape-based matching, this parameter needs not be passed when preparing the shape model using create_shape_modelCreateShapeModel, but only during the search using find_shape_modelFindShapeModel. In contrast, when preparing the component model it is favorable to analyze rotational symmetries of the model components and similarities between the model components. However, this analysis only leads to meaningful results if the value for MinScoreCompminScoreCompmin_score_comp that is used during the search (see find_component_modelFindComponentModel) is already approximately known.

In addition to the parameters ContrastLowCompcontrastLowCompcontrast_low_comp, ContrastHighCompcontrastHighCompcontrast_high_comp, and MinSizeCompminSizeCompmin_size_comp also the parameters MinContrastCompminContrastCompmin_contrast_comp, NumLevelsCompnumLevelsCompnum_levels_comp, AngleStepCompangleStepCompangle_step_comp, and OptimizationCompoptimizationCompoptimization_comp can be automatically determined by passing 'auto'"auto" for the respective parameters.

All component-specific input parameters (parameter names terminate with the suffix Comp) must either contain one element, in which case the parameter is used for all model components, or must contain the same number of elements as the number of regions in ComponentRegionscomponentRegionscomponent_regions, in which case each parameter element refers to the corresponding element in ComponentRegionscomponentRegionscomponent_regions.

In addition to the individual shape models, the component model also contains information about the way the single model components must be searched relative to each other using find_component_modelFindComponentModel in order to minimize the computation time of the search. For this, the components are represented in a tree structure. First, the component that stands at the root of this search tree (root component) is searched. Then, the remaining components are searched relative to the pose of their predecessor in the search tree.

The root component can be passed as an input parameter of find_component_modelFindComponentModel during the search. To what extent a model component is suited to act as the root component depends on several factors. In principle, a model component that can be found in the image with a high probability should be chosen. Therefore, a component that is sometimes occluded to a high degree or that is missing in some cases is not well suited to act as the root component. Additionally, the computation time that is associated with the root component during the search can serve as a criterion. A ranking of the model components that is based on the latter criterion is returned in RootRankingrootRankingroot_ranking. In this parameter the indices of the model components are sorted in descending order according to their associated search time, i.e., RootRankingrootRankingroot_ranking[0] contains the index of the model component that, chosen as root component, allows the fastest search. Note that the ranking returned in RootRankingrootRankingroot_ranking represents only a coarse estimation. Furthermore, the calculation of the root ranking assumes that the image size as well as the value of the system parameter 'border_shape_models'"border_shape_models" are identical when calling create_component_modelCreateComponentModel and find_component_modelFindComponentModel.

Execution information🔗

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🔗

ModelImagemodelImagemodel_image (input_object) (multichannel-)image → object (byte / uint2)HObject (byte / uint2)HImage (byte / uint2)HObject (byte / uint2)Hobject (byte / uint2)

Input image from which the shape models of the model components should be created.

ComponentRegionscomponentRegionscomponent_regions (input_object) region-array → objectHObjectHRegionHObjectHobject

Input regions from which the shape models of the model components should be created.

VariationRowvariationRowvariation_row (input_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)MaybeSequence[int]Htuple (Hlong)

Variation of the model components in row direction.

Suggested values: 0, 1, 2, 3, 4, 5, 10, 20, 30, 40, 50, 100, 150
Restriction: VariationRow >= 0

VariationColumnvariationColumnvariation_column (input_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)MaybeSequence[int]Htuple (Hlong)

Variation of the model components in column direction.

Suggested values: 0, 1, 2, 3, 4, 5, 10, 20, 30, 40, 50, 100, 150
Restriction: VariationColumn >= 0

VariationAnglevariationAnglevariation_angle (input_control) angle.rad(-array) → (real)HTuple (double)HTuple (double)MaybeSequence[float]Htuple (double)

Angle variation of the model components.

Suggested values: 0.0, 0.017, 0.035, 0.05, 0.07, 0.09, 0.17, 0.35, 0.52, 0.67, 0.87
Restriction: VariationAngle >= 0

AngleStartangleStartangle_start (input_control) angle.rad → (real)HTuple (double)HTuple (double)floatHtuple (double)

Smallest rotation of the component model.

Default: -0.39-0.39
Suggested values: -3.14, -1.57, -0.79, -0.39, -0.20, 0.0-3.14, -1.57, -0.79, -0.39, -0.20, 0.0

AngleExtentangleExtentangle_extent (input_control) angle.rad → (real)HTuple (double)HTuple (double)floatHtuple (double)

Extent of the rotation of the component model.

Default: 0.790.79
Suggested values: 6.28, 3.14, 1.57, 0.79, 0.396.28, 3.14, 1.57, 0.79, 0.39
Restriction: AngleExtent >= 0

ContrastLowCompcontrastLowCompcontrast_low_comp (input_control) integer(-array) → (integer / string)HTuple (Hlong / HString)HTuple (int / long / string)MaybeSequence[Union[int, str]]Htuple (Hlong / char*)

Lower hysteresis threshold for the contrast of the components in the model image.

Default: 'auto'"auto"
Suggested values: 'auto', 10, 20, 30, 40, 60, 80, 100, 120, 140, 160
Restriction: ContrastLowComp > 0

ContrastHighCompcontrastHighCompcontrast_high_comp (input_control) integer(-array) → (integer / string)HTuple (Hlong / HString)HTuple (int / long / string)MaybeSequence[Union[int, str]]Htuple (Hlong / char*)

Upper hysteresis threshold for the contrast of the components in the model image.

Default: 'auto'"auto"
Suggested values: 'auto', 10, 20, 30, 40, 60, 80, 100, 120, 140, 160
Restriction: ContrastHighComp > 0 && ContrastHighComp >= ContrastLowComp

MinSizeCompminSizeCompmin_size_comp (input_control) integer(-array) → (integer / string)HTuple (Hlong / HString)HTuple (int / long / string)MaybeSequence[Union[int, str]]Htuple (Hlong / char*)

Minimum size of the contour regions in the model.

Default: 'auto'"auto"
Suggested values: 'auto', 0, 5, 10, 20, 30, 40"auto", 0, 5, 10, 20, 30, 40
Restriction: MinSizeComp >= 0

MinContrastCompminContrastCompmin_contrast_comp (input_control) integer(-array) → (integer / string)HTuple (Hlong / HString)HTuple (int / long / string)MaybeSequence[Union[int, str]]Htuple (Hlong / char*)

Minimum contrast of the components in the search images.

Default: 'auto'"auto"
Suggested values: 'auto', 10, 20, 20, 40"auto", 10, 20, 20, 40
Restriction: MinContrastComp <= ContrastLowComp && MinContrastComp >= 0

MinScoreCompminScoreCompmin_score_comp (input_control) real(-array) → (real)HTuple (double)HTuple (double)MaybeSequence[float]Htuple (double)

Minimum score of the instances of the components to be found.

Default: 0.50.5
Suggested values: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.00.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Minimum increment: 0.01
Recommended increment: 0.05
Restriction: 0 <= MinScoreComp && MinScoreComp <= 1

NumLevelsCompnumLevelsCompnum_levels_comp (input_control) integer(-array) → (integer / string)HTuple (Hlong / HString)HTuple (int / long / string)MaybeSequence[Union[int, str]]Htuple (Hlong / char*)

Maximum number of pyramid levels for the components.

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

AngleStepCompangleStepCompangle_step_comp (input_control) angle.rad(-array) → (real / string)HTuple (double / HString)HTuple (double / string)MaybeSequence[Union[float, str]]Htuple (double / char*)

Step length of the angles (resolution) for the components.

Default: 'auto'"auto"
Suggested values: 'auto', 0.0175, 0.0349, 0.0524, 0.0698, 0.0873
Restriction: AngleStepComp >= 0

OptimizationCompoptimizationCompoptimization_comp (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Kind of optimization for the components.

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

MetricCompmetricCompmetric_comp (input_control) string(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Match metric used for the components.

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

PregenerationComppregenerationComppregeneration_comp (input_control) string(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Complete pregeneration of the shape models for the components if equal to 'true'"true".

Default: 'false'"false"
List of values: 'false', 'true'"false", "true"

ComponentModelIDcomponentModelIDcomponent_model_id (output_control) component_model → (handle)HTuple (HHandle)HComponentModel, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the component model.

RootRankingrootRankingroot_ranking (output_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)Sequence[int]Htuple (Hlong)

Ranking of the model components expressing the suitability to act as the root component.

Result🔗

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

Module🔗

Matching