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

create_component_model prepares patterns, which are passed in the form of a model image ModelImage and several regions ComponentRegions, as a component model for matching. The output parameter ComponentModelID is a handle for this model, which is used in subsequent calls to find_component_model. In contrast to create_trained_component_model, no preceding training with train_model_components needs to be performed before calling create_component_model.

Each of the regions passed in ComponentRegions describes a separate model component. Later, the index of a component region in ComponentRegions 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 ComponentRegions. It can be calculated by calling area_center.

The relative movements (relations) of the model components can be set by passing VariationRow, VariationColumn, and VariationAngle. 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 ModelImage. The parameters VariationRow and VariationColumn describe the movement of the components in row and column direction by ±VariationRow/2 and ±VariationColumn/2, respectively. The parameter VariationAngle describes the angle variation of the component by ±VariationAngle/2. 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 ComponentRegions, in which case each parameter element refers to the corresponding model component in ComponentRegions.

The parameters AngleStart and AngleExtent 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_model). Therefore, the parameters ContrastLowComp, ContrastHighComp, MinSizeComp, MinContrastComp, MinScoreComp, NumLevelsComp, AngleStepComp, OptimizationComp, MetricComp, and PregenerationComp correspond to the parameters of create_shape_model, with the following differences: First, in the parameter Contrast of create_shape_model 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_trained_component_model offers three separate parameters ContrastHighComp, ContrastLowComp, and MinScoreComp 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 ContrastLowComp and ContrastHighComp must be set to 'auto'. In contrast, if only one threshold value should be determined, ContrastLowComp must be set to 'auto' while ContrastHighComp must be set to an arbitrary value different from 'auto'. Secondly, the parameter Optimization of create_shape_model 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_model uses a separate parameter PregenerationComp in order to decide whether the shape models should be completely pregenerated or not. A third difference concerning the parameter MinScoreComp should be noted. When using the shape-based matching, this parameter needs not be passed when preparing the shape model using create_shape_model, but only during the search using find_shape_model. 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 MinScoreComp that is used during the search (see find_component_model) is already approximately known.

In addition to the parameters ContrastLowComp, ContrastHighComp, and MinSizeComp also the parameters MinContrastComp, NumLevelsComp, AngleStepComp, and OptimizationComp can be automatically determined by passing '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 ComponentRegions, in which case each parameter element refers to the corresponding element in ComponentRegions.

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_model 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_model 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 RootRanking. In this parameter the indices of the model components are sorted in descending order according to their associated search time, i.e., RootRanking[0] contains the index of the model component that, chosen as root component, allows the fastest search. Note that the ranking returned in RootRanking represents only a coarse estimation. Furthermore, the calculation of the root ranking assumes that the image size is identical when calling create_component_model and find_component_model.

* Read the model image.
read_image (ModelImage, 'model_image.tif')
* Describe the model components.
gen_rectangle2 (ComponentRegions, 318, 109, -1.62, 34, 19)
gen_rectangle2 (Rectangle2, 342, 238, -1.63, 32, 17)
gen_rectangle2 (Rectangle3, 355, 505, 1.41, 25, 17)
ComponentRegions := [ComponentRegions,Rectangle2]
ComponentRegions := [ComponentRegions,Rectangle3]
* Create the component model by explicitly specifying the relations.
create_component_model (ModelImage, ComponentRegions, 20, 20, rad(25), 0,
                        rad(360), 15, 40, 15, 10, 0.8, 'auto', 'auto', 
                        'none', 'use_polarity', 'false', ComponentModelID,
                        RootRanking)
* Find the component model in a run-time image.
read_image (SearchImage, 'search_image.tif')
find_component_model (SearchImage, ComponentModelID, RootRanking, 0,
                      rad(360), 0.5, 0, 0.5, 'stop_search',
                      'search_from_best', 'none', 0.8, 'least_squares', 0,
                      0.8, ModelStart, ModelEnd, Score, RowComp, ColumnComp,
                      AngleComp, ScoreComp, ModelComp)

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

create_component_model is processed completely exclusively without parallelization.

draw_region, concat_obj

find_component_model

create_trained_component_model

create_shape_model, find_shape_model

Matching