find_aniso_shape_modelT_find_aniso_shape_modelFindAnisoShapeModelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModel — Find the best matches of an anisotropically scaled shape model
in an image.
The coordinates RowRowRowRowRowrow and ColumnColumnColumnColumnColumncolumn are related to the
position of the origin of the shape model in the search image.
However, RowRowRowRowRowrow and ColumnColumnColumnColumnColumncolumn do not
exactly correspond to this position.
Instead, find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModel returns slightly modified values
that are optimized for creating a transformation matrix, that can be used for
alignment or visualization of the model contours.
(This has to do with the way HALCON transforms iconic objects,
see affine_trans_pixelaffine_trans_pixelAffineTransPixelaffine_trans_pixelAffineTransPixelAffineTransPixel).
The example below shows how to
create the transformation matrix for alignment and calculate the
exact coordinates of the found matches.
Additionally, the score of each found instance is returned in
ScoreScoreScoreScoreScorescore. 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.
Furthermore, it should be noted that in some cases instances with a
rotation or scale that is slightly outside the specified range are
found. This may happen if the specified range is smaller than the
range given when the model was created.
The parameter SubPixelSubPixelSubPixelSubPixelSubPixelsubPixel determines whether the instances
should be extracted with subpixel accuracy. If SubPixelSubPixelSubPixelSubPixelSubPixelsubPixel is
set to 'none'"none""none""none""none""none" (or 'false'"false""false""false""false""false" for backwards
compatibility) the model's pose is only determined with pixel
accuracy and the angle and scale resolution that was specified with
create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModel. If SubPixelSubPixelSubPixelSubPixelSubPixelsubPixel is set to
'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation" (or 'true'"true""true""true""true""true") the position as well
as the rotation and scale 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'"interpolation""interpolation""interpolation""interpolation""interpolation", this mode requires additional computation
time. The different modes for least-squares adjustment
('least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares", 'least_squares_high'"least_squares_high""least_squares_high""least_squares_high""least_squares_high""least_squares_high", and
'least_squares_very_high'"least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high""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, SubPixelSubPixelSubPixelSubPixelSubPixelsubPixel should be set to
'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation". If least-squares adjustment is desired,
'least_squares'"least_squares""least_squares""least_squares""least_squares""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
SubPixelSubPixelSubPixelSubPixelSubPixelsubPixel. The deformation must be specified in pixels. This
can be done by passing the optional parameter value
'max_deformation '"max_deformation ""max_deformation ""max_deformation ""max_deformation ""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'"max_deformation 2""max_deformation 2""max_deformation 2""max_deformation 2""max_deformation 2" must be passed
in SubPixelSubPixelSubPixelSubPixelSubPixelsubPixel in addition to the above described mode for the
subpixel extraction, i.e., for example ['least_squares',
'max_deformation 2']["least_squares",
"max_deformation 2"]["least_squares",
"max_deformation 2"]["least_squares",
"max_deformation 2"]["least_squares",
"max_deformation 2"]["least_squares",
"max_deformation 2"]. Passing the value 'max_deformation
0'"max_deformation
0""max_deformation
0""max_deformation
0""max_deformation
0""max_deformation
0" corresponds to a search without allowing deformations, i.e., the
behavior is the same as if no 'max_deformation '"max_deformation ""max_deformation ""max_deformation ""max_deformation ""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.
Approximately rotationally symmetric objects may not be found if
'max_deformation'"max_deformation""max_deformation""max_deformation""max_deformation""max_deformation" and AngleExtentAngleExtentAngleExtentAngleExtentAngleExtentangleExtent are both set to a value greater
than 0. In that case, ambiguities may occur that cannot be resolved,
and the match is rejected as false. If this happens, try to set either
'max_deformation'"max_deformation""max_deformation""max_deformation""max_deformation""max_deformation" or AngleExtentAngleExtentAngleExtentAngleExtentAngleExtentangleExtent to 0, or adjust the model such that
symmetries are reduced. 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""least_squares""least_squares""least_squares""least_squares",
'least_squares_high'"least_squares_high""least_squares_high""least_squares_high""least_squares_high""least_squares_high", or 'least_squares_very_high'"least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high"
(see above) is chosen for the subpixel extraction (in comparison to
'none'"none""none""none""none""none" or 'interpolation'"interpolation""interpolation""interpolation""interpolation""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.
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
NumLevelsNumLevelsNumLevelsNumLevelsNumLevelsnumLevels. If, e.g., NumLevelsNumLevelsNumLevelsNumLevelsNumLevelsnumLevels 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.
Using the operator set_shape_model_paramset_shape_model_paramSetShapeModelParamset_shape_model_paramSetShapeModelParamSetShapeModelParam you can specify a
'timeout'"timeout""timeout""timeout""timeout""timeout" for find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModel.
If find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModel reaches this 'timeout'"timeout""timeout""timeout""timeout""timeout", it
terminates without results and returns the error code 9400 (H_ERR_TIMEOUT).
Depending on the scaling ranges specified by ScaleRMinScaleRMinScaleRMinScaleRMinScaleRMinscaleRMin,
ScaleRMaxScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMax, ScaleCMinScaleCMinScaleCMinScaleCMinScaleCMinscaleCMin, and ScaleCMaxScaleCMaxScaleCMaxScaleCMaxScaleCMaxscaleCMax,
find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModel needs a significant
amount of time to free cached transformations if the shape model is not
pregenerated. As this transformations have to be freed after a timeout
occurs, the runtime of find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModel exceeds the value of
the specified 'timeout'"timeout""timeout""timeout""timeout""timeout" by this time.