find_shape_model(Image : : ModelID, AngleStart, AngleExtent, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels, Greediness : Row, Column, Angle, Score)
Note: There are 4 output parameters. They are the coordinates (Row, Column) of the target in the image - the coordinates of the center of gravity, the rotation angle of the target, and the matching score.
1. The coordinates of Row and Column are not the precise position of the template in the search image, so they cannot be used directly. These values are optimized for creating a transformation matrix, and you can use the matching results of this matrix for various tasks, such as adjusting the ROI for subsequent steps.
2. Score is a number between 0 and 1, which is an approximate measure of the proportion of the template visible in the search image. If half of the template is occluded, the value cannot exceed 0.5. The larger the parameter MinScore is set, the faster the search will be. If the template is not occluded in the image, MinScore can be set to 0.8, or even 0.9
3. The domain of the image defines the search area of the model reference point, which is the center of gravity of the domain area of the image used to create the model in create_shape_model. Different initial positions set using the function set_shape_model_origin are not considered. Models are searched within those points in the image domain region where the model belongs entirely to this image. This means that if the model exceeds the image boundary, the model cannot be found even if the obtained quality coefficient (score) is greater than MinScore. This performance can be changed by set_system('border_shape_models','true'), so that those models that exceed the border of the image and have a quality factor greater than MinScore can also be found. At this time, those points outside the image are regarded as being occluded, and the quality factor can be reduced. The search time will increase in this mode.
4. **The parameters AngleStart and AngleExtent determine the rotation angle of the template search. The angle should be as consistent as possible with the angle given in the create_shape_model operator. **The parameters AngleStart and AngleExtent determine the rotation angle of the model search. If necessary, the rotation range will be intercepted to become the rotation range given in the create_shape_model function. This means that the angular ranges for model creation and search must actually overlap. The range of angles during the search does not change modulo 2*pi. To simplify the presentation, in the remainder of this paragraph all angles are expressed in degrees, and in the find_shape_model function they are set in radians. Therefore, if AngleStart=-20°, AngleExtent=40° when creating a template, set AngleStart=350°, AngleExtent=20° in the search template function find_shape_model, even though the angle modulo 360 overlaps, the template will still not be found. In order to find the template, AngleStart=350° must be changed to AngleStart=-10° in this example.
5. The parameter MinScore defines at least what kind of quality coefficient is found in the image when the template is matched. The larger the MinScore is set, the faster the search will be. If the template is not occluded in the image, MinScore can be set as high as 0.8 or even 0.9.
6. NumMatches defines the maximum number of templates found on the image. If the matching quality coefficient is greater than MinScore and the number of targets is more than NumMatches, only return the NumMatches target positions with the best quality coefficient. If the matching targets found are less than NumMatches, then only the found ones will be returned. The parameter MinScore is better than NumMatches.
**If there is only 1 target in the Image, set NumMatches to 1 and set MinScore to a lower value, such as 0.5. This method is a more robust parameter setting for finding a matching target in an Image.
**
7. If the model has symmetry, multiple regions matching the target will be found at the same position and different angles of the search image. The parameter MaxOverlap is between 0 and 1, which defines the most overlapping coefficient of the two target areas found, so that they can be returned as two different target areas. Overlap is calculated based on finding the smallest bounding rectangle (see smallest_rectangle2) in any direction of the target area. If MaxOverlap=0, the found object areas cannot overlap, if MaxOverlap=1, all found object areas must be returned. If two target regions found overlap each other and are larger than MaxOverlap, only return the best one.
8.SubPixel determines whether the found object is extracted with sub-pixel precision. If SubPixel is set to 'none' (or 'false' for background compatibility), the model's position is only a pixel precision and angular resolution defined in create_shape_model. If SubPixel is set to 'interpolation' (or 'true'), both position and angle are sub-pixel accurate. In this mode the position of the model is interpolated in the mass coefficient function, this mode takes almost no computation time and achieves high enough accuracy to be widely used. However, in some applications with extremely high accuracy requirements, the position of the template should be determined by least squares adjustment, such as by minimizing the distance from the template point to the relevant image point. This mode requires additional computation time compared to 'interpolation'. Modes for least squares adjustment are: 'least_squares', 'least_squares_high', and 'least_squares_very_high'. They can be used to define the precision at which the minimum distance is searched, the higher the precision chosen, the longer the sub-pixel extraction. The higher its level, the longer it takes. In general, use 'least_squares' to achieve a balance between time and accuracy.
However, usually SubPixel is set to 'interpolation'. Select 'least_squares' if you wish to set least squares, as this ensures a trade-off between runtime and accuracy.
If the object is slightly deformed relative to the template, its matching score will be lower. For such a target, an additional parameter of the maximum allowable target deformation can be passed in the parameter SubPixel, 'max_deformation 1', and the value in the string is an integer value between 0 and 32. 0 means no deformation is allowed. ** Higher maximum allowable deformation values result in longer runtimes and carry a higher risk of matching errors. Therefore, the maximum deformation should be chosen as small as possible. **In order to obtain a meaningful score value and avoid matching errors, it is recommended to use admissible variables in combination with the least squares method.
9. NumLevels is the number of pyramid layers used in the search. The pyramid is to split the image into layers according to the image resolution. The more pyramid layers, the faster the matching speed. If necessary, the number of layers is truncated to the extent at which the model was created. If NumLevels=0, use the number of levels in the pyramid when creating the template. In addition, NumLevels can also contain a second parameter, which defines the lowest number of pyramid levels to find a matching template. NumLevels=[4,2] indicates that the match starts at the fourth level of the pyramid and finds a match at the second level of the pyramid (the lowest is set to 1). This method can be used to reduce the running time of matching, but the position accuracy in this mode is lower than that in normal mode. The so-called normal mode matches at the bottom of the pyramid. So if you need higher precision, you should set SubPixel to at least 'least_squares'. If the bottom layer of the pyramid is set too large, it may not achieve the desired accuracy, or find an incorrect matching region. This is because templates at higher levels of the pyramid are not specific enough to find reliable template best matches. In this case the lowest pyramid level should be set to the minimum value.
Note: When performing template matching when the image is out of focus or the lens is blurred, the value needs to be set to a negative value, such as [0,-1], and find_shape_model will return the matching item found on the lowest level of the pyramid to find the target to be tested.
Also, the pyramid levels may vary slightly from image to image. In order to facilitate the matching of poor quality images, the lowest pyramid level can be determined during matching. The trick here is that the lowest pyramid level can be specified with a negative number. For example, if NumLevels is [4,-2], matching starts at pyramid level 4 and traces down to the lowest pyramid level. If no matching target can be found in this level of pyramid, continue to lower the pyramid level to search, make the pyramid level where at least one matching target is found to be the lowest pyramid level, and return the found target.
10. The parameter Greediness determines the "greediness" when searching. If Greediness=0, use a safe search heuristic, as long as the template exists in the image, the template must be found, however, searching in this way is relatively time-consuming. If Greediness=1, use an unsafe search heuristic, so that there is a chance that the template will not be found even if it is present in the image, but only in rare cases. If you set Greediness=0.9, you can always find a match to the model in almost all cases.
Finally, the template search operator is time-consuming when the target cannot be found. The matching time can be set through the operator set_shape_model_param
(ModelID, 'timeout', 1000)
. If the find_shape_model reaches 'timeout', the execution will be terminated immediately, no matching result will be output, and an error code 9400 (H_ERR_TIMEOUT) will be returned.