| Table of Contents / Matching / Shape-Based | Operators |
find_shape_model — Find the best matches of a shape model in an image.
find_shape_model(Image : : ModelID, AngleStart, AngleExtent, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels, Greediness : Row, Column, Angle, Score)
The operator find_shape_model finds the best NumMatches instances of the shape model ModelID in the input image Image. The model must have been created previously by calling create_shape_model or read_shape_model.
The position and rotation of the found instances of the model is returned in Row, Column, and Angle. The coordinates Row and Column are the coordinates of the origin of the shape model in the search image. By default, the origin is the center of gravity of the domain (region) of the image that was used to create the shape model with create_shape_model. A different origin can be set with set_shape_model_origin.
Note that the coordinates Row and Column do not exactly correspond to the position of the model in the search image. Thus, you cannot directly use them. Instead, the values are optimized for creating the transformation matrix with which you can use the results of the matching for various tasks, e.g., to align ROIs for other processing steps. The example below shows how to create this matrix and use it to display the model at the found position in the search image and to calculate the exact coordinates.
Additionally, the score of each found instance is returned in Score. The score is a number between 0 and 1, which is an approximate measure of how much of the model is visible in the image. If, for example, half of the model is occluded, the score cannot exceed 0.5.
The domain of the image Image determines the search space for the reference point of the model, i.e., for the center of gravity of the domain (region) of the image that was used to create the shape model with create_shape_model. A different origin set with set_shape_model_origin is not taken into account. The model is searched within those points of the domain of the image, in which the model lies completely within the image. This means that the model will not be found if it extends beyond the borders of the image, even if it would achieve a score greater than MinScore (see below). This behavior can be changed with set_system('border_shape_models','true'), which will cause models that extend beyond the image border to be found if they achieve a score greater than MinScore. Here, points lying outside the image are regarded as being occluded, i.e., they lower the score. It should be noted that the runtime of the search will increase in this mode.
The parameters AngleStart and AngleExtent determine the range of rotations for which the model is searched. If necessary, the range of rotations is clipped to the range given when the model was created with create_shape_model. In particular, this means that the angle ranges of the model and the search must truly overlap. The angle range in the search is not adapted modulo 2*pi. To simplify the presentation, all angles in the remainder of the paragraph are given in degrees, whereas they have to be specified in radians in find_shape_model. Hence, if the model, for example, was created with AngleStart = -20° and AngleExtent = 40° and the angle search space in find_shape_model is, for example, set to AngleStart = 350° and AngleExtent = 20°, the model will not be found, even though the angle ranges would overlap if they were regarded modulo 360°. To find the model, in this example it would be necessary to select AngleStart = -10°.
Furthermore, it should be noted that in some cases instances with a rotation that is slightly outside the specified range of rotations are found. This may happen if the specified range of rotations is smaller than the range given when the model was created.
The parameter MinScore determines what score a potential match must at least have to be regarded as an instance of the model in the image. The larger MinScore is chosen, the faster the search is. If the 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 the matches are not tracked to the lowest pyramid level (see below) it might happen that instances with a score slightly below MinScore are found.
The maximum number of 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 the model exhibits symmetries it may happen that multiple instances with similar positions but different rotations are found in the image. 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 be returned 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 rectangle of arbitrary orientation (see smallest_rectangle2) of the found instances. If MaxOverlap=0, the found instances may not overlap at all, while for MaxOverlap=1 all instances are returned.
The parameter SubPixel determines whether the instances should be extracted with subpixel accuracy. If SubPixel is set to 'none' (or 'false' for backwards compatibility) the model's pose is only determined with pixel accuracy and the angle resolution that was specified with create_shape_model. If SubPixel is set to 'interpolation' (or 'true') the position as well as the rotation are determined with subpixel accuracy. In this mode, the model's pose is interpolated from the score function. This mode costs almost no computation time and achieves an accuracy that is high enough for most applications. In some applications, however, the accuracy requirements are extremely high. In these cases, the model's pose can be determined through a least-squares adjustment, i.e., by minimizing the distances of the model points to their corresponding image points. In contrast to 'interpolation', this mode requires additional computation time. The different modes for least-squares adjustment ('least_squares', 'least_squares_high', and 'least_squares_very_high') can be used to determine the accuracy with which the minimum distance is being searched. The higher the accuracy is chosen, the longer the subpixel extraction will take, however. Usually, SubPixel should be set to 'interpolation'. If least-squares adjustment is desired, 'least_squares' should be chosen because this results in the best tradeoff between runtime and accuracy.
Objects that are slightly deformed with respect to the model, in some cases cannot be found or are found but only with a low accuracy. For such objects it is possible to additionally pass a maximal allowable object deformation in the parameter SubPixel. The deformation must be specified in pixels. This can be done by passing the optional parameter value 'max_deformation ' followed by an integer value between 0 and 32 (in the same string), which specifies the maximum deformation. For example, if the shape of the object may be deformed by up to 2 pixels with respect to the shape that is stored in the model, the value 'max_deformation 2' must be passed in SubPixel. Passing the value 'max_deformation 0' corresponds to a search without allowing deformations, i.e., the behavior is the same as if no 'max_deformation ' is passed. Note that higher values for the maximum deformation often result in an increased runtime. Furthermore, the higher the deformation value is chosen, the higher is the risk of finding wrong model instances. Both problems mainly arise when searching for small objects or for objects with fine structures. This is because such kinds of objects for higher deformations lose their characteristic shape, which is important for a robust search. Also note that for higher deformations the accuracy of partially occluded objects might decrease if clutter is present close to the object. Consequently, the maximum deformation should be chosen as small as possible and only as high as necessary. When specifying a deformation higher than 0 the computation of the score depends on the chosen value for the subpixel extraction. In most cases, the score of a match changes if 'least_squares', 'least_squares_high', or 'least_squares_very_high' (see above) is chosen for the subpixel extraction (in comparison to 'none' or 'interpolation'). Furthermore, if one of the least-squares adjustments is selected the score might increase when increasing the maximum deformation because then for the model points more corresponding image points can be found. To get a meaningful score value and to avoid erroneous matches, we recommend to always combine the allowance of a deformation with a least-squares adjustment.
The number of pyramid levels used during the search is determined with NumLevels. If necessary, the number of levels is clipped to the range given when the shape model was created with create_shape_model. If NumLevels is set to 0, the number of pyramid levels specified in create_shape_model is used. Optionally, NumLevels can contain a second value that determines the lowest pyramid level to which the found matches are tracked. Hence, a value of [4,2] for NumLevels means that the matching starts at the fourth pyramid level and tracks the matches to the second lowest pyramid level (the lowest pyramid level is denoted by a value of 1). This mechanism can be used to decrease the runtime of the matching. It should be noted, however, that in general the accuracy of the extracted pose parameters is lower in this mode than in the normal mode, in which the matches are tracked to the lowest pyramid level. Hence, if a high accuracy is desired, SubPixel should be set to at least 'least_squares'. If the lowest pyramid level to use is chosen too large, it may happen that the desired accuracy cannot be achieved, or that wrong instances of the model are found because the model is not specific enough on the higher pyramid levels to facilitate a reliable selection of the correct instance of the model. In this case, the lowest pyramid level to use must be set to a smaller value.
In input images of poor quality, i.e., in images that are, e.g., defocused, deformed, or noisy, often no instances of the shape model can be found on the lowest pyramid level. The reason for this behavior is the missing or deformed edge information which is a result of the poor image quality. Nevertheless, the edge information may be sufficient on higher pyramid levels. But keep in mind the above mentioned restrictions on accuracy and robustness if instances that were found on higher pyramid levels are used. The selection of the suitable pyramid level, i.e., the lowest pyramid level on which at least one instance of the shape model can be found, depends on the model and on the input image. This pyramid level may vary from image to image. To facilitate the matching on images of poor quality, the lowest pyramid level on which at least one instance of the model can be found can be determined automatically during the matching. To activate this mechanism, i.e., to use the so-called 'increased tolerance mode', the lowest pyramid level must be specified negatively in NumLevels. If, e.g., NumLevels is set to [4,-2], the matching starts at the fourth pyramid level and tracks the matches to the second lowest pyramid level. This means that an instance of the shape model is searched on the pyramid level 2. If no instance of the model can be found on this pyramid level, the lowest pyramid level is determined on which at least one instance of the model can be found. The instances of this pyramid level will then be returned.
The parameter Greediness determines how “greedily” the search should be carried out. If Greediness=0, a safe search heuristic is used, which always finds the model if it is visible in the image. However, the search will be relatively time consuming in this case. If Greediness=1, an unsafe search heuristic is used, which may cause the model not to be found in rare cases, even though it is visible in the image. For Greediness=1, the maximum search speed is achieved. In almost all cases, the shape model will always be found for Greediness=0.9.
Using the operator set_shape_model_param you can specify a 'timeout' for find_shape_model. If find_shape_model reaches this 'timeout', it terminates without results and returns the error code 9400 (H_ERR_TIMEOUT).
Input image in which the model should be found.
Handle of the model.
Smallest rotation of the model.
Default value: -0.39
Suggested values: -3.14, -1.57, -0.78, -0.39, -0.20, 0.0
Extent of the rotation angles.
Default value: 0.78
Suggested values: 6.29, 3.14, 1.57, 0.78, 0.39, 0.0
Restriction: AngleExtent >= 0
Minimum score of the instances of the model to be found.
Default value: 0.5
Suggested values: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical range of values: 0 ≤ MinScore ≤ 1
Minimum increment: 0.01
Recommended increment: 0.05
Number of instances of the model to be found.
Default value: 1
Suggested values: 0, 1, 2, 3, 4, 5, 10, 20
Maximum overlap of the instances of the model to be found.
Default value: 0.5
Suggested values: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical range of values: 0 ≤ MaxOverlap ≤ 1
Minimum increment: 0.01
Recommended increment: 0.05
Subpixel accuracy if not equal to 'none'.
Default value: 'least_squares'
List of values: 'none', 'interpolation', 'least_squares', 'least_squares_high', 'least_squares_very_high', 'max_deformation 1', 'max_deformation 2', 'max_deformation 3', 'max_deformation 4', 'max_deformation 5', 'max_deformation 6'
Number of pyramid levels used in the matching (and lowest pyramid level to use if |NumLevels| = 2).
Default value: 0
List of values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
“Greediness” of the search heuristic (0: safe but slow; 1: fast but matches may be missed).
Default value: 0.9
Suggested values: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical range of values: 0 ≤ Greediness ≤ 1
Minimum increment: 0.01
Recommended increment: 0.05
Row coordinate of the found instances of the model.
Column coordinate of the found instances of the model.
Rotation angle of the found instances of the model.
Score of the found instances of the model.
create_shape_model (ImageReduced, 0, rad(-45), rad(180), 0, \
'none', 'use_polarity', 30, 10, ModelID)
get_shape_model_contours (ModelXLD, ModelID, 1)
find_shape_model (SearchImage, ModelID, rad(-45), rad(180), \
0.5, 1, 0.5, 'interpolation', \
0, 0, Row, Column, Angle, Score)
vector_angle_to_rigid (0, 0, 0, Row, Column, Angle, HomMat2DObject)
affine_trans_contour_xld (ModelXLD, ObjectXLD, HomMat2DObject)
affine_trans_pixel (HomMat2DObject, 0, 0, RowObject, ColObject)
If the parameter values are correct, the operator find_shape_model returns the value 2 (H_MSG_TRUE). If the input is empty (no input images are available) the behavior can be set via set_system('no_object_result',<Result>). If necessary, an exception is raised.
create_shape_model, read_shape_model, set_shape_model_origin
find_scaled_shape_model, find_aniso_shape_model, find_scaled_shape_models, find_shape_models, find_aniso_shape_models, best_match_rot_mg
set_system, get_system, set_shape_model_param
Matching
| Table of Contents / Matching / Shape-Based | Operators |
| HALCON Reference Manual 10.0.2 | Copyright © 1996-2011 MVTec Software GmbH |