Find the best matches of a component model in an image.

The operator find_component_model finds the best NumMatches instances of the component model ComponentModelID in the input image Image. The model must have been created previously by calling create_trained_component_model, create_component_model, or read_component_model.

The components of the component model ComponentModelID are represented in in a tree structure. The component that stands at the root of this search tree (root component) is searched within the full search space, i.e., at all allowed positions and in the allowed range of orientations (see below). In contrast, the remaining components are searched relative to the pose of their predecessor in the search tree within a restricted search space that is computed from the relations (recursive search). The index of the root component can be passed in RootComponent. To what extent a model component is suited to act as 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 root component. The behavior of the operator when dealing with a missing or strongly occluded root component can be set with IfRootNotFound (see below). Also, 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 of the operator create_trained_component_model or create_component_model, respectively. If the complete ranking is passed in RootComponent, the first value RootComponent[0] is automatically selected as the root component. The domain of the image Image determines the search space for the reference point, i.e., the allowed positions, of the root component. The parameters AngleStartRoot and AngleExtentRoot specify the allowed angle range within which the root component is searched. If necessary, the range of rotations is clipped to the range given when the component model was created with create_trained_component_model or create_component_model, respectively. The angle range for each component can be queried with get_shape_model_params after requesting the corresponding shape model handles with get_component_model_params.

The position and rotation of the model components of all found component model instances are returned in RowComp, ColumnComp, and AngleComp. The coordinates RowComp and ColumnComp are the coordinates of the origin (reference point) of the component in the search image. If the component model was created with create_trained_component_model by training, the origin of the component is the center of gravity of the respective returned contour region in ModelComponents of the operator train_model_components. Otherwise, if the component model was created manually with create_component_model, the origin of the component is the center of gravity of the corresponding passed component region ComponentRegion of the operator create_component_model. Since the relations between the components in ComponentModelID refer to this reference point, the origin of the components must not be modified by using set_shape_model_origin.

Additionally, the score of each found component instance is returned in ScoreComp. The score is a number between 0 and 1, and is an approximate measure of how much of the component is visible in the image. If, for example, half of the component is occluded, the score cannot exceed 0.5. While ScoreComp represents the score of the instances of the single components, Score contains the score of the instances of the entire component model. More precisely, Score contains the weighted mean of the associated values of ScoreComp. The weighting is performed according to the number of model points within the respective component.

In order to assign the values in RowComp, ColumnComp, AngleComp, and ScoreComp to the associated model component, the index of the model component (see create_component_model and train_model_components, respectively) is returned in ModelComp. Furthermore, for each found instance of the component model its associated component matches are given in ModelStart and ModelEnd. Thus, the matches of the components that correspond to the first found instance of the component model are given by the interval of indices [ModelStart[0],ModelEnd[0]]. The indices refer to the parameters RowComp, ColumnComp, AngleComp, ScoreComp, and ModelComp. Assume, for example, that two instances of the component model, which consists of three components, are found in the image, where for one instance only two components (component 0 and component 2) could be found. Then the returned parameters could, for example, have the following elements: RowComp = [100,200,300,150,250], ColumnComp = [200,210,220,400,425], AngleComp = [0,0.1,-0.2,0.1,0.2,0], ScoreComp = [1,1,1,1,1], ModelComp = [0,1,2,0,2], ModelStart = [0,3], ModelEnd = [2,4], Score = [1,1]. The operator get_found_component_model can be used to visualize the result of the search and to extract the component matches of a certain component model instance.

In general, the components are searched at image positions, where the components lie completely within the image. This means that the components will not be found if they extend beyond the borders of the image, even if they would achieve a score greater than MinScoreComp (see below).

The parameter MinScore determines what score a potential match of the component model must at least have to be regarded as an instance of the component model in the image. If the component model can be expected never to be occluded in the images, MinScore may be set as high as 0.8 or even 0.9. If a missing or strongly occluded root component must be assumed, and hence IfRootNotFound is set to 'select_new_root' (see below), the search is faster the larger MinScore is chosen. Otherwise, the value of this parameter only slightly influences the computation time.

The maximum number of model instances to be found can be determined with NumMatches. If more than NumMatches instances with a score greater than MinScore are found in the image, only the best NumMatches instances are returned. If fewer than NumMatches are found, only that number is returned, i.e., the parameter MinScore takes precedence over NumMatches. If all model instances exceeding MinScore in the image should be found, NumMatches must be set to 0.

In some cases, found instances only differ in the pose of one or a few components. The parameter MaxOverlap determines by what fraction (i.e., a number between 0 and 1) two instances may at most overlap in order to consider them as different instances, and hence to return them separately. If two instances overlap each other by more than MaxOverlap only the best instance is returned. The calculation of the overlap is based on the smallest enclosing rectangles of arbitrary orientation (see smallest_rectangle2) of the found component instances. If MaxOverlap = 0, the found instances may not overlap at all, while for MaxOverlap = 1 no check for overlap is performed, and hence all instances are returned.

The parameter IfRootNotFound specifies the behavior of the operator when dealing with a missing or strongly occluded root component. This parameter strongly influences the computation time of the operator. If IfRootNotFound is set to 'stop_search', it is assumed that the root component is always found in the image. Consequently, for instances for which the root component could not be found the search for the remaining components is not continued. If IfRootNotFound is set to 'select_new_root', different components are successively chosen as the root component and searched within the full search space. The order in which the selection of the root component is performed corresponds to the order passed in RootRanking. The poses of the found instances of all root components are then used to start the recursive search for the remaining components. Hence, it is possible to find instances even if the original root component is not found. However, the computation time of the search increases significantly in comparison to the search when choosing 'stop_search'. The number of root components to search depends on the value specified for MinScore. The higher the value for MinScore is chosen the fewer root components must be searched, and thus the faster the search is performed. If the number of elements in RootComponent is less than the number of required root components during the search, the root components are completed by the automatically computed order (see create_trained_component_model or create_component_model).

The parameter IfComponentNotFound specifies the behavior of the operator when dealing with missing or strongly occluded components other than the root component. Here, it can be stated in which way components that must be searched relative to the pose of another (predecessor) component should be treated if the predecessor component was not found. If IfComponentNotFound is set to 'prune_branch', such components are not searched at all and are also treated as 'not found'. If IfComponentNotFound is set to 'search_from_upper', such components are searched relative to the pose of the predecessor component of the predecessor component. If IfComponentNotFound is set to 'search_from_best', such components are searched relative to the pose of the already found component from which the relative search can be performed with minimum computational effort.

The parameter PosePrediction determines whether the pose of components that could not be found should be estimated. If PosePrediction is set to 'none', only the poses of the found components are returned. In contrast, if PosePrediction is set to 'from_neighbors' or 'from_all', the poses of components that could not be found are estimated and returned with a score of ScoreComp = 0.0. The estimation of the poses is then either based on the poses of the found neighboring components in the search tree ('from_neighbors') or on the poses of all found components ('from_all').

Internally, the shape-based matching is used for the component-based matching in order to search the individual components (see find_shape_model). Therefore, the parameters MinScoreComp, SubPixelComp, NumLevelsComp, and GreedinessComp have the same meaning as the corresponding parameters in find_shape_model. These parameters must either contain one element, in which case the parameter is used for all components, or must contain the same number of elements as model components in ComponentModelID, in which case each parameter element refers to the corresponding component in ComponentModelID. NumLevelsComp may also contain two elements or twice the number of elements as model components. The first value determines the number of pyramid levels to use. The second value determines the lowest pyramid level to which the found matches are tracked. If different values should be used for different components, the number of pyramid levels and the lowest pyramid level must be specified interleaved in NumLevelsComp. If, for example, two components are contained in ComponentModelID, and the number of pyramid levels is 5 for the first component and 4 for the second component, and the lowest pyramid level is 2 for the first component and 1 for the second component, NumLevelsComp = [5,2,4,1] must be selected. Further details can be found in the documentation of find_shape_models.

If the parameter values are correct, the operator find_component_model returns the value 2 (H_MSG_TRUE). If the input is empty (no input image available) the behavior can be set via set_system('no_object_result',<Result>). If necessary, an exception is raised.

find_component_model is reentrant and processed without parallelization.

create_trained_component_model, create_component_model, read_component_model

get_found_component_model

find_shape_models

find_shape_model, find_shape_models, get_shape_model_params, get_component_model_params, train_model_components, set_shape_model_origin, smallest_rectangle2

Matching