Halcon入门（一）shape-based matching

Matching步骤：Acquire Image、Create (Train) Model、Find Model、Destroy Model

1、实例：读取图形->建模->匹配->销毁（Halcon10.0）

read_image (Image, 'clip')
*创建以（124，181）为中心，弧度0.653，长129*2，宽47*2的矩形
gen_rectangle2 (ROI, 124, 181, 0.653, 129, 47)
reduce_domain (Image, ROI, ImageReduced)
*创建以ImageReduced为模板的模型，0~360，
*NumLevels决定模型的（pyramid levels）层数（0代表‘auto’）
create_shape_model (ImageReduced, 0, 0, rad(360), 0, 'no_pregeneration', \
'use_polarity', 40, 10, ModelID)
*获取模型参数
get_shape_model_params (ModelID, NumLevels, AngleStart, AngleExtent, \
AngleStep, ScaleMin, ScaleMax, ScaleStep, Metric, MinContrast)

*查找匹配图形，
find_shape_model (Image, ModelID, 0, rad(360), 0.7, 13, 0.5, 'interpolation', \
0, 0.9, Row, Column, Angle, Score)

*获取模型的轮廓contours
get_shape_model_contours (ModelContours, ModelID, 1)
for i := 0 to |Row|-1 by 1
*计算刚性反射变换，得到齐次变换矩阵
vector_angle_to_rigid (0, 0, 0, Row[i], Column[i], Angle[i], HomMat2D)
*从获得的模型轮廓旋转到匹配的轮廓
affine_trans_contour_xld (ModelContours, ContoursAffinTrans, HomMat2D)
endfor
clear_shape_model (ModelID)

例程通过截取ROI建立model，匹配，并通过匹配得到的Row，Column，Angel将轮廓旋转得到每次匹配得到的轮廓。

模型参数：使用get_shape_model_params得到如下

2、算子 create_shape_model理解

create_shape_model — Prepare a shape model for matching.

Signature：（输入图像：输出图像：输入参数：输出参数）

create_shape_model(Template : : NumLevels, AngleStart, AngleExtent, AngleStep, Optimization, Metric, Contrast, MinContrast : ModelID) 

• NumLevels：number of pyramid levels

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.
另一方面，必须选择numlevel，这样模型仍然可以识别，并且在 最高的金字塔层次上包含足够多的点(至少4个)。
This can be checked using the output of inspect_shape_model.
可以使用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.
如果模型点的数量 在最低的金字塔级别上已经太小，create_shape_model会 返回一个错误消息。
If NumLevels is set to 'auto' (or 0 for backwards compatibility), create_shape_model determines the number of pyramid levels automatically.
如果将numlevel设置为“auto”(或向后兼容的0)，create_shape_model将自动确定金字塔级别的数量。
The automatically computed number of pyramid levels can be queried using get_shape_model_params.
可以使用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.
在极少数情况下，create_shape_model可能会为金字塔级别的数量确定一个值。
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.
如果选择的金字塔数量太大，模型可能无法在图像中得到识别，或者需要在find_shape_model中为MinScore或Greediness选择非常低的参数，以找到模型。
If the number of pyramid levels is chosen too small, the time required to find the model in find_shape_model may increase.
如果金字塔级别的数量选择得太少，那么在find_shape_model中找到模型所需的时间可能会增加。
In these cases, the number of pyramid levels should be selected using the output of inspect_shape_model.

在这些情况下，应该使用inspect_shape_model的输出来选择金字塔级别的数量

• • AngleStart 、AngleExtent：    模型创建在内存中，只有在给定角度范围内的模型才被创建，不同的角度范围匹配的图形不同。
    

  • The parameters AngleStart and AngleExtent determine the range of possible rotations, in which the model can occur in the image.

    参数角度开始和角度范围决定了可能的旋转范围，其中模型可以出现在图像中。
  • 
    
  • 在下图中设置如下：create_shape_model (ImageReduced, 0, 0, rad(90), 0, 'no_pregeneration', \
    'use_polarity', 40, 10, ModelID)
    

  • 

  • 可见匹配的图形变少了。

  
  
• 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.
  Contrast也可以包含一个具有两个值的tuple。
  In this case, the model is segmented using a method similar to the hysteresis threshold method used in edges_image.
  在本例中，使用与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.
  这个最小大小的阈值为每一个连续的金字塔级别除以2。
  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.
  可以使用inspect_shape_model提前检查这个参数的效果。
  If Contrast is set to 'auto', create_shape_model determines the three above described values automatically.
  如果将对比度设置为“auto”，则create_shape_model自动确定上述三个值。
  Alternatively, 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.
  还允许各种组合:例如，如果传递['auto_contrast'，'auto_min_size']，则自动确定对比度和最小大小。
  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.
  如果通过['auto_min_size'，20,30]，则自动确定最小尺寸，同时将滞后阈值设置为20和30等。在某些情况下，可能会出现对比度阈值的自动确定不满足的情况。
  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.
  因此，在调用create_shape_model之前，应该使用determine_shape_model_params自动确定对比度阈值，然后使用inspect_shape_model进行验证。
  
•  MinContrast：With MinContrast, it can be determined which contrast the model must at least have in the recognition performed by find_shape_model.
  与此相反，可以确定模型必须至少在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.
  例如，如果灰度值在10个灰度范围内波动，则应将MinContrast设置为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 below) the noise in one channel must be multiplied by the square root of the number of channels to determine MinContrast.
  如果模型和搜索图像使用多通道图像，如果参数指标设置为“ignore_color_极性”(见下文)，则一个通道中的噪声必须乘以确定最小对比度的通道数的平方根。
  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.（√3约为1.7）
  例如，如果灰度值在单个通道的10个灰度级范围内波动，并且图像是三通道图像，则应将对比度设置为17。
  Obviously, MinContrast must be smaller than Contrast.
  显然，MinContrast的对比必须小于 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.
  如果模型被严重遮挡也要识别，那么最小对比度要略大于噪声产生的灰度值波动范围，以确保用find_shape_model对模型的位置和旋转进行稳健、准确的提取。
  If MinContrast is set to 'auto', the minimum contrast is determined automatically based on the noise in the model image.
  如果将MinContrast设置为“auto”，则根据模型图像中的噪声自动确定最小对比度。
  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.
  可以使用get_shape_model_params查询自动计算的最小对比度。
  
• 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.
  如果度规= ' use_极性'，图像中的对象和模型必须具有相同的对比度。
  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.
  如果度规= ' ignore_global_极性'，如果对比度全局颠倒，则在图像中也会发现该对象。
  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.
  在这种情况下，find_shape_model的运行时将略有增加。
  If Metric = 'ignore_local_polarity', the model is found even if the contrast changes locally.
  如果指标= ' ignore_local_极性'，即使对比度在本地发生变化，也会找到模型。
  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.
  因为在这种情况下，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.
  如果度规= ' ignore_color_极性'，即使颜色对比在局部发生变化，也会找到模型。
  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.
  在这种模式下，find_shape_model的运行时也会显著增加。
  The metric 'ignore_color_polarity' can be used for images with an arbitrary number of channels.
  指标“ignore_color_极性”可以用于具有任意数量通道的图像。
  If it is used for single-channel images it has the same effect as 'ignore_local_polarity'.
  如果用于单通道图像，则其效果与“ignore_local_极性”相同。
  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.
  应该注意的是，对于度量= ' ignore_color_'，使用create_shape_model创建模型的通道数和find_shape_model的搜索可能会有所不同。
  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).
  此外，应该注意的是，通道不需要包含光的光谱细分(如RGB图像)。
  The channels can, for example, also contain images of the same object that were obtained by illuminating the object from different directions.
  例如，通道还可以包含同一对象的图像，这些图像是通过从不同方向对该对象进行照明而获得的。