Operator Reference
inspect_shape_model (Operator)
inspect_shape_model — Create the representation of a shape model.
Signature
inspect_shape_model(Image : ModelImages, ModelRegions : NumLevels, Contrast : )
Description
inspect_shape_model creates a representation of a shape
model. The operator is particularly useful in order to determine
the parameters NumLevels and Contrast, which are
used in create_shape_model,
create_scaled_shape_model, or
create_aniso_shape_model, quickly and conveniently. The
representation of the model is created on multiple image pyramid
levels, where the number of levels is determined by
NumLevels. In contrast to create_shape_model,
create_scaled_shape_model, and
create_aniso_shape_model, the model is only created for the
rotation and scale of the object in the input image, i.e.,
0° and 1. As output, inspect_shape_model
creates an image object ModelImages containing the images
of the individual levels of the image pyramid as well as a region in
ModelRegions for each pyramid level that represents the
model at the respective pyramid level. The individual objects can
be accessed with select_obj. If the input image
Image has one channel the representation of the model is
created with the method that is used in create_shape_model,
create_scaled_shape_model or
create_aniso_shape_model for the metrics
'use_polarity', 'ignore_global_polarity', and
'ignore_local_polarity'. If the input image has more than
one channel the representation is created with the method that is
used for the metric 'ignore_color_polarity'. As described
for create_shape_model, create_scaled_shape_model,
and create_aniso_shape_model, the number of pyramid levels
should be chosen as large as possible, while taking into account
that the model must be recognizable on the highest pyramid level and
must have enough model points. The parameter Contrast
should be chosen such that only the significant features of the
template object are used for the model. Contrast can also
contain a tuple with two values. In this case, the model is
segmented using a method similar to the hysteresis threshold method
used in edges_image. Here, the first element of the tuple
determines the lower threshold, while the second element determines
the upper threshold. For more information about the hysteresis
threshold method, see hysteresis_threshold. Optionally,
Contrast can contain a third value as the last element of
the tuple. This value determines a threshold for the selection of
significant model components based on the size of the components,
i.e., components that have fewer points than the minimum size thus
specified are suppressed. As the minimum size is applied on the
extent of the components, the derived model contours can still be
smaller than the specified minimum size. This threshold for the minimum
size is divided by two for each successive pyramid level. If small model
components should be suppressed, but hysteresis thresholding should
not be performed, nevertheless three values must be specified in
Contrast. In this case, the first two values can simply be
set to identical values. In its typical use,
inspect_shape_model is called interactively multiple times
with different parameters for NumLevels and
Contrast, until a satisfactory model is obtained. After
this, create_shape_model, create_scaled_shape_model,
or create_aniso_shape_model are called with the parameters
thus obtained.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Parameters
Image (input_object) (multichannel-)image → object (byte / uint2)
Input image.
ModelImages (output_object) (multichannel-)image-array → object (byte / uint2)
Image pyramid of the input image
ModelRegions (output_object) region-array → object
Model region pyramid
NumLevels (input_control) integer → (integer)
Number of pyramid levels.
Default: 4
List of values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Contrast (input_control) number(-array) → (integer)
Threshold or hysteresis thresholds for the contrast of the object in the image and optionally minimum size of the object parts.
Default: 30
Suggested values: 10, 20, 30, 40, 60, 80, 100, 120, 140, 160
Result
If the parameters are valid, the operator
inspect_shape_model returns the value 2 (
H_MSG_TRUE)
. If necessary an
exception is raised.
Possible Predecessors
Possible Successors
See also
Module
Foundation