Prepare a shape model for scale invariant matching.

The operator create_scaled_shape_model prepares a template, which is passed in the image Template, as a shape model used for scale invariant matching.

The model is generated using multiple image pyramid levels and multiple rotations and scales, and is stored in memory. The output parameter ModelID is a handle for this model, which is used in subsequent calls to find_scaled_shape_model.

The number of pyramid levels is determined with the parameter NumLevels. It should be chosen as large as possible because by this the time necessary to find the object is significantly reduced. On the other hand, NumLevels must be chosen such that the model is still recognizable and contains a sufficient number of points (at least four) on the highest pyramid level. This can be checked using the output of inspect_shape_model. If not enough model points are generated, the number of pyramid levels is reduced internally until enough model points are found on the highest pyramid level. If this procedure would lead to a model with no pyramid levels, i.e., if the number of model points is already too small on the lowest pyramid level, create_scaled_shape_model returns with an error message. If NumLevels is set to 0, create_scaled_shape_model determines the number of pyramid levels automatically. The automatically computed number of pyramid levels can be queried using get_shape_model_params. In rare cases, it might happen that create_scaled_shape_model determines a value for the number of pyramid levels that is too large or too small. If the number of pyramid levels is chosen too large, the model may not be recognized in the image or it may be necessary to select very low parameters for MinScore or Greediness in find_scaled_shape_model in order to find the model. If the number of pyramid levels is chosen too small, the time required to find the model in find_scaled_shape_model may increase. In these cases, the number of pyramid levels should be selected using the output of inspect_shape_model.

The parameters AngleStart and AngleExtent determine the range of possible rotations, in which the model can occur in the image. Note that the model can only be found in this range of angles by find_scaled_shape_model. The parameter AngleStep determines the step length within the selected range of angles. Hence, if subpixel accuracy is not specified in find_scaled_shape_model, this parameter specifies the accuracy that is achievable for the angles in find_scaled_shape_model. AngleStep should be chosen based on the size of the object. Smaller models do not have many different discrete rotations in the image, and hence AngleStep should be chosen larger for smaller models. If AngleExtent is not an integer multiple of AngleStep, AngleStep is modified accordingly.

The parameters ScaleMin and ScaleMax determine the range of possible scales (sizes) of the model. A scale of 1 corresponds to the original size of the model. The parameter ScaleStep determines the step length within the selected range of scales. Hence, if subpixel accuracy is not specified in find_scaled_shape_model, this parameter specifies the accuracy that is achievable for the scales in find_scaled_shape_model. Like AngleStep, ScaleStep should be chosen based on the size of the object. If the range of scales is not an integer multiple of ScaleStep, ScaleStep is modified accordingly.

The model is pre-generated for the selected angle and scale range and stored in memory. The memory required to store the model is proportional to the number of angle steps, the number of scale steps, and the number of points in the model. Hence, if AngleStep or ScaleStep are too small or AngleExtent or the range of scales are too big, it may happen that the model no longer fits into the (virtual) memory. In this case, either AngleStep or ScaleStep must be enlarged or AngleExtent or the range of scales must be reduced. In any case, it is desirable that the model completely fits into the main memory, because this avoids paging by the operating system, and hence the time to find the object will be much smaller. Since angles can be determined with subpixel resolution by find_scaled_shape_model, AngleStep >= 1° and ScaleStep >= 0.02 can be selected for models of a diameter smaller than about 200 pixels. If AngleStep = 0 or ScaleStep = 0 is selected, create_scaled_shape_model automatically determines a suitable angle or scale step length, respectively, based on the size of the model. The automatically computed angle and scale step lengths can be queried using get_shape_model_params.

For particularly large models, it may be useful to reduce the number of model points by setting Optimization to a value different from 'none'. If Optimization = 'none', all model points are stored. In all other cases, the number of points is reduced according to the value of Optimization. If the number of points is reduced, it may be necessary in find_scaled_shape_model to set the parameter Greediness to a smaller value, e.g., 0.7 or 0.8. For small models, the reduction of the number of model points does not result in a speed-up of the search because in this case usually significantly more potential instances of the model must be examined.

The parameter Contrast determines the contrast the model points must have. The contrast is a measure for local gray value differences between the object and the background and between different parts of the object. Contrast should be chosen such that only the significant features of the template 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. 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. The effect of this parameter can be checked in advance with inspect_shape_model.

With MinContrast, it can be determined which contrast the model must at least have in the recognition performed by find_scaled_shape_model. In other words, this parameter separates the model from the noise in the image. Therefore, a good choice is the range of gray value changes caused by the noise in the image. If, for example, the gray values fluctuate within a range of 10 gray levels, MinContrast should be set to 10. Obviously, MinContrast must be smaller than Contrast. If the model should be recognized in very low contrast images, MinContrast must be set to a correspondingly small value. If the model should be recognized even if it is severely occluded, MinContrast should be slightly larger than the range of gray value fluctuations created by noise in order to ensure that the position and rotation of the model are extracted robustly and accurately by find_scaled_shape_model.

The parameter Metric determines the conditions under which the model is recognized in the image. If Metric = 'use_polarity', the object in the image and the model must have the same contrast. If, for example, the model is a bright object on a dark background, the object is found only if it is also brighter than the background. If 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 find_scaled_shape_model will increase slightly in this case. If Metric = 'ignore_local_polarity', the model is found even if the contrast changes locally. This mode can, for example, be useful if the object consists of a part with medium gray value, within which either darker or brighter sub-objects lie. Since in this case the runtime of find_scaled_shape_model increases significantly, it is usually better to create several models that reflect the possible contrast variations of the object with create_scaled_shape_model, and to match them simultaneously with find_scaled_shape_models.

The center of gravity of the domain (region) of the model image Template is used as the origin (reference point) of the model. find_scaled_shape_model returns the coordinates of this point in the search image. A different origin can be set with set_shape_model_origin.

If the parameters are valid, the operator create_scaled_shape_model returns the value 2 (H_MSG_TRUE). If necessary an exception is raised. If the parameters NumLevels and Contrast are chosen such that the model contains too few points, the error 8510 is raised.

create_scaled_shape_model is processed completely exclusively without parallelization.

draw_region, reduce_domain, threshold

find_scaled_shape_model, find_scaled_shape_models, get_shape_model_params, clear_shape_model, write_shape_model, set_shape_model_origin

create_shape_model, create_template_rot

Template matching