set_local_deformable_model_metric — Set the metric of a local deformable model that was created from XLD
set_local_deformable_model_metric changes the value of the
Metric that was selected during the creation of the
ModelID from XLD contours. Because no information
about the polarity of the model contours is available for XLD contours, the
polarity is determined based on a representative
Image. For this,
the model contours are mapped to the respective position where the object
appears in the
Image, which is done with the
which must be of the semantic type 'vector_field_absolute' and which can be
obtained by a previous call to
Here, the returned
VectorField is used for the deformable
transformation. Note, that the 'expand_border' option should not be used in
find_local_deformable_model, because then the returned
VectorField has the wrong image size.
Metric then determines the conditions under which the
model is recognized later in the search image. If
'use_polarity', the object in the image and the model must have the
same contrast. If, e.g., the model is a bright object on a dark
background, the object is found only if it is also brighter than the
Metric = 'ignore_global_polarity', the
object is found in the image also if the contrast reverses globally. In the
above example, the object hence is also found if it is darker than the
background. The runtime of
will increase slightly in this case.
It must be ensured that the object contours in the
Image have the
same (or inverse) polarity as the object contours in the image in which the
object must be searched later. Especially, the object must not be occluded in
Image and the background must be either brighter than the object
or darker. Otherwise, the determined polarity of the model contour will not
represent the polarity of the object contour during the search. Note that
only the polarity of the contours is determined, not their contrast. Note
also that the polarity is determined from a single-channel image, only. If a
multi-channel image is passed in
Image, only the first channel will
be used (and no error message will be returned).
A typical proceeding is to read the XLD contours from file. Since these XLD
contours do not provide polarity information, the model must be created
from the XLD contours by setting the parameter
'ignore_local_polarity'. Then, in a first search image the model
is recognized. The transformation that maps the model contours to the
position of the object in the search image is provided in
VectorField, which is of the semantic type 'vector_field_absolute'.
If the matching result is correct, the value of the parameter
Metric can be changed, e.g., to 'use_polarity'. This leads
to a faster and more robust recognition in the following images.
set_local_deformable_model_metric can only be used with deformable
models that were created from XLD contours.
This operator modifies the state of the following input parameter:
During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.
→object (byte / uint2)
Input image used for the determination of the polarity.
Vector field of the local deformation.
ModelID(input_control, state is modified) deformable_model
Handle of the model.
Default value: 'use_polarity'
List of values: 'ignore_global_polarity', 'use_polarity'
If the parameters are valid, the operator
set_local_deformable_model_metric returns the value 2 (H_MSG_TRUE).
If necessary, an exception is raised.