模板匹配——create_shape_model

The operator create_shape_model prepares a template, which is passed in the image Template, as a shape model used for matching. The ROI of the model is passed as the domain of Template.

运算符create_shape_model准备一个模板，该模板在图像模板中传递，作为用于匹配的形状模型。模型的 ROI 作为 Template 的域传递。

The output parameter ModelID is a handle for this model, which is used in subsequent calls to find_shape_model. The center of gravity of the domain (region) of the model image Template is used as the origin (reference point) of the model. A different origin can be set with set_shape_model_origin.

输出参数 ModelID 是此模型的句柄，用于对find_shape_model的后续调用。模型图像模板的域（区域）的重心用作模型的原点（参考点）。可以使用set_shape_model_origin设置不同的原点。

The model is generated using multiple image pyramid levels and is stored in memory. If a complete pregeneration of the model is selected (see below), the model is generated at multiple rotations on each level. The model can be extended by clutter parameters with set_shape_model_clutter.

该模型使用多个图像金字塔级别生成，并存储在内存中。如果选择了模型的完整预生成（见下文），则模型将在每个级别上多次旋转生成。该模型可以通过带有set_shape_model_clutter的杂波参数进行扩展。

NumLevels:
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_shape_model returns with an error message.

金字塔级别的数由参数 NumLevels 确定。它应该选择尽可能大，因为这样可以大大减少找到对象所需的时间。另一方面，必须选择 NumLevels，以便模型仍可识别，并在最高金字塔级别上包含足够数量的点（至少四个）。这可以使用 inspect_shape_model 的输出进行检查。如果生成的模型点数不足，则在内部减少金字塔级别的数量，直到在最高金字塔级别上找到足够的模型点。如果此过程将导致模型没有金字塔级别，即，如果最低金字塔级别的模型点数已经太小，则create_shape_model返回错误消息。

If NumLevels is set to 'auto' (or 0 for backwards compatibility), create_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_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_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_shape_model may increase. In these cases, the number of pyramid levels should be selected using the output of inspect_shape_model.

如果 NumLevels 设置为“auto”（或 0 表示向后兼容），则create_shape_model自动确定金字塔级别的数。可以使用get_shape_model_params查询自动计算的金字塔级别数。在极少数情况下，可能会发生create_shape_model确定的金字塔级别数值过大或过小的情况。如果金字塔级别的数量选择得太大，则可能无法在图像中识别模型，或者可能需要在find_shape_model中为 MinScore 或 Greediness 选择非常低的参数才能找到模型。如果选择的金字塔级别数太小，则在find_shape_model中找到模型所需的时间可能会增加。在这些情况下，应使用 inspect_shape_model 的输出来选择金字塔级别的数目。

AngleStart, AngleExtent and AngleStep:
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_shape_model. The parameter AngleStep determines the step length within the selected range of angles. Hence, if subpixel accuracy is not specified in find_shape_model, this parameter specifies the accuracy that is achievable for the angles in find_shape_model. AngleStep should be chosen based on the size of the object. Smaller models do not possess 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. To ensure that for model instances without rotation angle values of exactly 0.0 are returned by find_shape_model, the range of possible rotations is modified as follows: If there is no positive integer value n such that AngleStart plus n times AngleStep is exactly 0.0, AngleStart is decreased by up to AngleStep and AngleExtent is increased by AngleStep.

参数 AngleStart 和 AngleExtent 确定模型在图像中可能出现的旋转范围。请注意，模型只能通过find_shape_model在此角度范围内找到。参数 AngleStep 确定所选角度范围内的步长。因此，如果未在find_shape_model中指定亚像素精度，则此参数指定角度可实现的精度（以find_shape_model为单位）。应根据对象的大小选择 AngleStep。较小的模型在图像中没有许多不同的离散旋转，因此对于较小的模型，应选择较大的 AngleStep。如果 AngleExtent 不是 AngleStep 的整数倍，则会相应地修改 AngleStep。为确保find_shape_model返回的旋转角度值恰好为 0.0 的模型实例，可旋转的范围修改如下：如果没有正整数值 n，使得 AngleStart 加上 n 乘以 AngleStep 正好为 0.0，则 AngleStart 最多减少 AngleStep，AngleExtent 增加 AngleStep。

Optimization:
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_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.

对于特别大的模型，通过将“优化”设置为与“无”不同的值来减少模型点的数量可能很有用。如果 Optimization = 'none'，则存储所有模型点。在所有其他情况下，点数会根据优化的值减少。如果点数减少，find_shape_model可能需要将参数贪婪设置为较小的值，例如 0.7 或 0.8。对于小型模型，模型点数量的减少不会导致搜索速度加快，因为在这种情况下，通常必须检查模型的更多潜在实例。

If Optimization is set to 'auto', create_shape_model automatically determines the reduction of the number of model points.

如果“优化”设置为“自动”，则create_shape_model自动确定模型点数的减少。

Metric:
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.

如果 Metric = 'use_polarity'，则图像中的对象和模型必须具有相同的对比度。例如，如果模型是深色背景上的明亮对象，则仅当该对象也比背景亮时，才能找到该对象。

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_shape_model will increase slightly in this case.

如果 Metric = 'ignore_global_polarity'，则当对比度全局反转时，也会在图像中找到对象。在上面的例子中，如果物体比背景更暗，那么它也会被找到。在这种情况下，find_shape_model的运行时间将略有增加。

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_shape_model increases significantly, it is usually better to create several models that reflect the possible contrast variations of the object with create_shape_model, and to match them simultaneously with find_shape_models.

如果 Metric = 'ignore_local_polarity'，则即使对比度局部变化，也会找到模型。例如，如果对象由具有中等灰度值的部分组成，则此模式非常有用，其中有较暗或较亮的子对象。由于在这种情况下，find_shape_model的运行时间显着增加，因此通常最好创建多个模型来反映对象与create_shape_model可能的对比度变化，并将它们与find_shape_models同时匹配。

The above three metrics can only be applied to single-channel images. If a multichannel image is used as the model image or as the search image, only the first channel will be used (and no error message will be returned).

If Metric = 'ignore_color_polarity', the model is found even if the color contrast changes locally. This is, for example, the case if parts of the object can change their color, e.g., from red to green. In particular, this mode is useful if it is not known in advance in which channels the object is visible. In this mode, the runtime of find_shape_model can also increase significantly. The metric 'ignore_color_polarity' can be used for images with an arbitrary number of channels. If it is used for single-channel images it has the same effect as 'ignore_local_polarity'. It should be noted that for Metric = 'ignore_color_polarity' the number of channels in the model creation with create_shape_model and in the search with find_shape_model can be different. This can, for example, be used to create a model from a synthetically generated single-channel image. Furthermore, it should be noted that the channels do not need to contain a spectral subdivision of the light (like in an RGB image). The channels can, for example, also contain images of the same object that were obtained by illuminating the object from different directions.

以上三个指标只能应用于单通道图像。如果使用多通道图像作为模型图像或搜索图像，则仅使用第一个通道（不会返回错误消息）。

如果 Metric = 'ignore_color_polarity'，则即使颜色对比度局部变化，也会找到模型。例如，如果物体的某些部分可以改变它们的颜色，例如，从红色到绿色，就是这种情况。特别是，如果事先不知道物体在哪些通道中可见，则此模式很有用。在这种模式下，find_shape_model的运行时间也可以显着增加。度量“ignore_color_polarity”可用于具有任意数量通道的图像。如果它用于单通道图像，则具有与“ignore_local_polarity”相同的效果。应该注意的是，对于 Metric = 'ignore_color_polarity'，使用 create_shape_model 创建模型和使用 find_shape_model 进行搜索的通道数可能不同。例如，这可用于从合成生成的单通道图像创建模型。此外，应该注意的是，通道不需要包含光的光谱细分（如在RGB图像中）。例如，通道还可以包含通过从不同方向照亮物体而获得的同一物体的图像。

Contrast:
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. 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. The effect of this parameter can be checked in advance with inspect_shape_model.

参数“对比度”（Contrast） 确定模型点必须具有的对比度。对比度是对象与背景之间以及对象不同部分之间的局部灰度值差异的度量。应选择对比度，以便仅将模板的重要特征用于模型。对比度还可以包含具有两个值的元组。在这种情况下，使用类似于edges_image中使用的滞后阈值方法对模型进行分割。在这里，元组的第一个元素确定下限阈值，而第二个元素确定上限阈值。有关滞后阈值方法的详细信息，请参阅hysteresis_threshold。（可选）Contrast 可以包含第三个值作为元组的最后一个元素。此值确定根据组件大小选择重要模型组件的阈值，即，点数少于指定最小尺寸的组件将被抑制。由于最小尺寸应用于组件范围，因此派生的模型轮廓仍可能小于指定的最小尺寸。对于每个连续的金字塔级别，最小大小的阈值除以 2。如果应抑制小型模型分量，但不应执行滞后阈值，则必须在对比度中指定三个值。在这种情况下，可以简单地将前两个值设置为相同的值。该参数的效果可以提前用inspect_shape_model检查。

If Contrast is set to 'auto', create_shape_model determines the three above described values automatically. only the contrast ('auto_contrast'), the hysteresis thresholds ('auto_contrast_hyst'), or the minimum size ('auto_min_size') can be determined automatically. The remaining values that are not determined automatically can additionally be passed in the form of a tuple. Also various combinations are allowed: If, for example, ['auto_contrast','auto_min_size'] is passed, both the contrast and the minimum size are determined automatically. If ['auto_min_size',20,30] is passed, the minimum size is determined automatically while the hysteresis thresholds are set to 20 and 30, etc. In certain cases, it might happen that the automatic determination of the contrast thresholds is not satisfying. For example, a manual setting of these parameters should be preferred if certain model components should be included or suppressed because of application-specific reasons or if the object contains several different contrasts. Therefore, the contrast thresholds should be automatically determined with determine_shape_model_params and subsequently verified using inspect_shape_model before calling create_shape_model. Note that MinContrast influences the automatic contrast estimation, and hence also the estimation of the minimum size.

如果“对比度”设置为“自动”，create_shape_model会自动确定上述三个值。只能自动确定对比度 （'auto_contrast'）、迟滞阈值 （'auto_contrast_hyst'） 或最小尺寸 （'auto_min_size'）。未自动确定的其余值还可以以元组的形式传递。此外，还允许各种组合：例如，如果传递 ['auto_contrast'，'auto_min_size']，则会自动确定对比度和最小尺寸。如果通过 ['auto_min_size'，20,30]，则自动确定最小大小，同时将滞后阈值设置为 20 和 30，依此类推。在某些情况下，对比度阈值的自动确定可能不令人满意。例如，如果由于特定于应用程序的原因而应包含或隐含某些模型组件，或者对象包含多个不同的对比度，则应首选手动设置这些参数。因此，应使用 determine_shape_model_params 自动确定对比度阈值，并在调用 create_shape_model 之前使用 inspect_shape_model 进行验证。请注意，MinContrast 会影响自动对比度估计，因此也会影响最小尺寸的估计。

MinContrast:
With MinContrast, it can be determined which contrast the model must at least have in the recognition performed by find_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. If multichannel images are used for the model and the search images, and if the parameter Metric is set to 'ignore_color_polarity' (see above) the noise in one channel must be multiplied by the square root of the number of channels to determine MinContrast. If, for example, the gray values fluctuate within a range of 10 gray levels in a single channel and the image is a three-channel image MinContrast should be set to 17. 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_shape_model.

使用 MinContrast，可以确定模型在find_shape_model执行的识别中至少必须具有哪种对比度。换句话说，此参数将模型与图像中的噪声分开。因此，一个好的选择是由图像中的噪点引起的灰度值变化范围。例如，如果灰度值在 10 个灰度级别的范围内波动，则应将 MinContrast 设置为 10。如果模型和搜索图像使用多通道图像，并且参数 Metric 设置为“ignore_color_polarity”（见上文），则必须将一个通道中的噪声乘以通道数的平方根才能确定 MinContrast。例如，如果灰度值在单个通道中在 10 个灰度级别范围内波动，并且图像是三通道图像，则应将 MinContrast 设置为 17。显然，MinContrast 必须小于 Contrast。如果应在对比度非常低的图像中识别模型，则必须将 MinContrast 设置为相应的小值。如果即使模型被严重遮挡也能识别，则 MinContrast 应略大于噪声产生的灰度值波动范围，以确保通过find_shape_model稳健准确地提取模型的位置和旋转。

If MinContrast is set to 'auto', the minimum contrast is determined automatically based on the noise in the model image. Consequently, an automatic determination only makes sense if the image noise during the recognition is similar to the noise in the model image. Furthermore, in some cases it is advisable to increase the automatically determined value in order to increase the robustness against occlusions (see above). The automatically computed minimum contrast can be queried using get_shape_model_params.

如果 MinContrast 设置为“auto”，则根据模型图像中的噪声自动确定最小对比度。因此，只有当识别过程中的图像噪声与模型图像中的噪声相似时，自动确定才有意义。此外，在某些情况下，建议增加自动确定的值，以增加对遮挡的鲁棒性（见上文）。可以使用get_shape_model_params查询自动计算的最小对比度。