文章目录
一、前言
在HALCON算子手册中，对算子的介绍通常包含HALCON原生程序、C#、C++以及C四种语言的介绍。
本文以介绍HALCON原生程序下的 create_scaled_shape_model 算子（用其它语言联合HALCON开发，肯定要能看懂HALCON原生示例程序）的形式来学习该算子。虽然标题的CreateScaledShapeModel是大驼峰命名法，是C#和C++采用的命名，但这是因为我以往文章标题是以下划线分段的，为了美观和避免歧义，我才使用了驼峰式命名（不然标题就变成了 机器视觉_HALCON_模板匹配_create_scaled_shape_model ，虽然现在的命名引入了HALCON和其它语言混淆的另一个歧义）。
二、create_scaled_shape_model 算子
2.1 名称
create_scaled_shape_model 该算子会准备一个等轴性的（isotropically）缩放模型用于匹配。
从名称直译也可知，它会创建一个可按比例缩放的形状模型，该模型可以作为一个模板图案，用于后续图像中寻找类似对象。
2.2 算子/函数签名
create_scaled_shape_model(Template : : NumLevels, AngleStart, AngleExtent, AngleStep, ScaleMin, ScaleMax, ScaleStep, Optimization, Metric, Contrast, MinContrast : ModelID)
2.3 描述
该算子会创建一个模板，该模板作为一个等轴性缩放的形状模型传递到图像模板中，用于匹配。模型的ROI作为模板的域（domain）进行传递。
输出参数ModelID是该模型的句柄，用于后续调用 find_scaled_shape_model 。模型图像模板（Template）的域的重心（center of gravity）用作模型的原点origin（或者说参考点，reference point）。用 set_shape_model_origin 可以设置不同原点。模型是使用多个图像金字塔级别生成的，并存储在内存中。
2.3.1 输入参数详述
-
NumLevels，（金字塔）级别数量
金字塔级别的数量由 NumLevels 确定。它的值应该尽可能的大，这样可以显著减少寻找对象所需的时间。另一方面，NumLevels 也必须选择得当，以使模型在最高金字塔级别仍是可识别的，且包含足够数量的点（至少四个）。这点可通过 inspect_shape_model 的输出来检查。如果没有生成足够的模型点，系统会在内部减少金字塔级别的数量，直到在最高金字塔级别上找到足够的模型点。如果该过程导致一个模型没有金字塔级别生成，即在最低金字塔级别上模型的数量还是太少，则 create_scaled_shape_model 会返回一条错误信息。如果 NumLevels 设置为’auto’（或为了向后兼容设置为0）， create_scaled_shape_model 会自动确定金字塔级别的数量。用 get_shape_model_params 可以查询到自动计算的金字塔级别数量。在极少数情况下， create_scaled_shape_model 可能会确定一个过大或过小的金字塔级别数量。如果金字塔级别数量过大，图像中的模型可能无法识别，或者可能需要在 find_scaled_shape_model 中为MinScore或Greediness设置非常低的参数才能找到模型。如果选择过小的金字塔级别数量，find_scaled_shape_model 寻找模型所需的时间可能会增加。在这些情况下，应使用 inspect_shape_model 的输出来选择金字塔级别数量。
-
AngleStart,AngleExtent和AngleStep，旋转角度相关
参数 AngleStart，初始角度 和 AngleExtent，角度范围 决定模型在图像中可能出现的旋转角度的范围。请注意， find_scaled_shape_model 只能在该角度范围内找到模型。参数 AngleStep 确定了所选角度范围内的步长。因此，如果在 find_scaled_shape_model 中未指定亚像素精度（subpixel accuracy），该参数会指定其中角度的可达精度。应根据物体的大小选择 AngleStep，角度步长 。较小的模型在图像中没有很多不同的离散旋转。因此对于较小的模型，应选择较大的 AngleStep （这一点应该是从受影响的像素来看的，小模型转动很小的角度，像素变化不大，视觉效果不明显，所以步长要拉长）。
如果 AngleExtent 不是 AngleStep 的整数倍，AngleStep 会做相应修改。为确保 find_scaled_shape_model 返回的旋转角度值不完全为0.0的模型实例，可能的旋转范围会做如下修改：如果没有正整数值n，使得 AngleStart 加上n乘以 AngleStep 恰好为0.0，则AngleStart减少到AngleStep，而AngleExtent增加到AngleStep。 -
ScaleMin,ScaleMax和ScaleStep，缩放比例相关
ScaleMin 和 ScaleMax 决定了模型的缩放（大小）范围。scale（译成比例好点）为1时，模型为原始大小。参数ScaleStep决定了所选缩放范围内的步长。因此，如果在 find_scaled_shape_model 中未指定亚像素精度，该参数指定 find_scaled_shape_model 中缩放的可达精度。与AngleStep一样，应根据物体的大小选择ScaleStep。如果缩放范围不是ScaleStep的整数倍，ScaleStep会做相应修改。为确保对于未缩放的模型实例，find_scaled_shape_model 返回的比例值正好是1.0，可能的比例范围会做如下修改：如果没有正整数值n使得ScaleMin加上n乘以ScaleStep恰好为1.0，则ScaleMin会减少到ScaleStep，ScaleMax会增加到ScaleStep，从而使可能的缩放范围增加到ScaleStep。 -
Optimization，优化
对于一些特别大的模型，通过将Optimization设置为非’none’的值以减少模型点的数量也许会很有用。如果Optimization=‘none’（即关掉优化），则会存储所有点。在其他情况下，根据Optimization的值的不同，点的数量会相应减少。如果点数减少，在 find_scaled_shape_model 中可能需要将Greediness参数设置为更小的值，如0.7或0.8。对于小模型，减少模型点的数量并不会加快搜索。因为该情况下，通常需要检查更多潜在的模型实例（模型小了，图像中存在的可能就更多了）。如果将Optimization设置为’auto’， create_scaled_shape_model 将自动确定模型点数的减少。
-
Metric，度量/标准
参数 Metric 确定模型在图像中被识别的条件/标准。如果 Metric = ‘use_polarity’ ，则图像中的对象必须和模型具有相同的对比度（Contrast）。比如，如果模型是一个在暗/深色背景上的明亮物体，则仅当物体比背景更亮时才会被找到。
如果 Metric = ‘ignore_global_polarity’ ，即使对比度在全局范围内反转（即模型中原本与背景相比更亮的物体，变的更暗），对象也会被找到。该情况下， find_scaled_shape_model 的运行时间会略有增加。
如果 Metric = ‘ignore_local_polarity’ ，即使局部对比度发生改变，模型也会被发现。比如，若某部分是中等灰度的（既不亮也不暗），这种情况下该模式会很有用，在其中较暗或较亮的子对象都能被发现。由于这种情况下， find_scaled_shape_model 的运行时间会显著增加，因此通常最好使用 create_scaled_shape_model 创建多个模型，来反映对象可能的对比度变化，并用 find_scaled_shape_models 同时去匹配它们。
以上三种metric仅适用于单通道图像（single-channel image）。如果将多通道图像用作模型图像或搜索图像，仅第一个通道会被使用（并且不会返回错误信息）。
如果 Metric = ‘ignore_color_polarity’ ，即使色彩对比度局部改变，模型也会被找到。例如，如果对象的某些部分是可以改变颜色的，如从红色变为绿色。特别是在事先不知道对象在哪些通道中可见的情况下，这种模式非常有用。该模式下，find_scaled_shape_model 的运行时间也许会显著增加。metric ‘ignore_color_polarity’ 可用于具有任意数量通道的图像。如果将其用于单通道图像，其效果与’ignore_local_polarity’相同。应注意的是，对于 Metric = ‘ignore_color_polarity’ ，在使用 ‘create_scaled_shape_model’ 创建模型时和使用 ‘find_scaled_shape_model’ 搜索模型时，通道的数量可以不同。例如，这可以用于从合成生成的单通道图像创建一个模型。此外，应注意通道不需要包含光的光谱（如RGB图像中）。通道也可以包含从不同方向照亮对象获得的同一对象的图像。
-
Contrast，对比度
参数 Contrast 确定模型点必须具有的对比度。。对比度应该被选择来将模板的重要特征用于模型。Contrast还可以包含一个有两个值的元组。该情况下，模型使用类似于 edges_image 中使用的滞后阈值方法进行分割。此处，元组的第一个元素确定较低阈值，第二个元素确定较高阈值。可选地，Contrast可以包含第三个值作为元组的最后一个元素。该值确定用于基于组件大小，选择重要的模型组件的阈值，即具有比指定的最小大小少的点的组件将被抑制。对于每个连续的金字塔级别，最小尺寸的阈值除以2。如果小模型组件应该被抑制，但仍不执行滞后阈值， -
MinContrast，最小对比度
使用 MinContrast ，可以确定在 find_scaled_shape_model 执行的识别中模型至少具备的对比度。换句话说，该参数将模型与图像中的噪声分开。因此，一个好的选择是图像中由噪声引起的灰度值变化范围。例如，如果灰度值在10灰度级内波动， MinContrast 应设为10。如果模型和搜索图像使用多通道图像，并且 Metric = ‘ignore_color_polarity’ ，则必须将一个通道中的噪声乘以通道数的平方根来确定 MinContrast 。例如，在单通道图像中的灰度值在10个灰度级范围内波动，且图像是一个三通道图像， MinContrast 应设为17。显然， MinContrast 必须小于 Contrast 。如果模型要在非常低的对比度图像中被识别， MinContrast 必须设置为相应较小的值。如果模型要在严重遮挡的情况下仍能被识别， MinContrast 应略大于噪声产生的灰度值波动范围，以确保 find_scaled_shape_model 能够稳定、准确地提取模型的位置和旋转情况。
若将 MinContrast 设为 ‘auto’ ，则最小对比度将根据模型图像中的噪声自动确定。因此，仅在识别过程中的图像噪声与模型图像中的噪声类似时，自动确定才有意义。此外，在某些情况下，建议增加自动确定的值，以便提高抗遮挡能力。可以使用 get_shape_model_params 查询自动计算的最小对比度。
2.3.2 完整的预生成模型
可选地，在 Optimization 中可以传入第二个值。该值决定了模型是否被完全预生成。要达到预生成效果， Optimization 的第二个值必须设置为 ‘pregeneration’ 或 ‘no_pregeneration’ 。如果没有使用第二个值（只传入了一个值），则用 set_system(‘pregenerate_shape_models’, …) 设置的模式。使用默认值 （‘pregenerate_shape_models’ = ‘false’）时，模型不会被完全预生成。模型的完全预生成通常会导致更低的运行时间，因为在运行时不需要转换模型。然而，在该情况下，创建模型所需的内存和时间会显著增加。还应注意，由于在运行时转换模型必然导致转换后的模型的内部数据与预生成的转换模型不同，因此不能期望两种模式返回相同的结果。例如，如果模型没有完全预生成， find_scaled_shape_model 通常会返回较低的分数（score），这可能需要为完全预生成模型设置较低的 MinScore 值。此外，两种模式下插值（interpolation）获得的姿势可能略有不同。如果需要最大精度，应通过最小二乘（least-squares）调整确定模型的姿势。
如果选中了模型的完整预生成，则根据所选角度和缩放/比例范围预生成模型并存储在内存中。存储模型所需内存与角度步长、缩放步长和模型中的点数成正比。因此，如果 AngleStep 或 ScaleStep 太小，又或者 AngleExtent 或 缩放范围太大，则可能会发生模型不再适配（虚拟）内存的情况。在该情况下，必须增大旋转角度或缩放的步长，或者缩小角度范围和缩放范围。无论何种情况，模型都尽量适配主内存，因为这避免了操作系统的分页，使得找到对象的时间大大缩短。由于通过 find_scaled_shape_model 可以以亚像素分辨率确定角度，因此对于直径小于200像素的模型，可以选择 AngleStep ≥ 1° 和 ScaleStep ≥ 0.02 。
如果选择 AngleStep = ‘auto’ 或 ScaleStep = ‘auto’ （或两种情况都为0以实现向后兼容）， create_scaled_shape_model 会自动根据模型的大小确定合适的角度或缩放步长。自动计算的角度和缩放步长可以使用 get_shape_model_params 查询。
如果不选中完全预生成模型，则该模型仅在每个金字塔级别上以参考姿势创建。在这种情况下， find_scaled_shape_model 中必须在运行时将模型转换为不同的角度和比例。因此，模型的识别可能需要更长的时间。
请注意，预生成的形状模型是针对特定图像大小量身定制的。由于运行时的原因，在使用同一模型并行搜索不同大小的图像时不支持。该情况下，必须使用相同模型的副本，否则程序可能崩溃。
2.4 执行信息
- 多线程类型：reentrant，可重入的（可与非独占算子并行运行）
- 多线程范围：global，全局的（可被任意线程调用）
- 无法并行化处理
该算子会返回一个句柄。注意，这种句柄类型的实例的状态可能被特定算子更改，即使句柄用作这些算子的输入参数。
2.5 参数
- Template(input_object)
- 输入图像，其域用来创建模型。 NumLevels(input_control)
- 金字塔级别的最大数量。
默认值：‘auto’
可能的值：0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ‘auto’ AngleStart(input_control) - 图案/模板的最小旋转角度
默认值：-0.39
建议值：-3.14, -1.57, -0.79, -0.39, -0.20, 0.0 AngleExtent(input_control) - 旋转角度的范围
默认值：0.79
建议值：6.29, 3.14, 1.57, 0.79, 0.39
限制： AngleExtent >= 0 AngleStep(input_control) - 角度的步长（分辨率/精度）
默认值：‘auto’
建议值： ‘auto’, 0.0175, 0.0349, 0.0524, 0.0698, 0.0873
限制： AngleStep >= 0 && AngleStep <= pi / 16 ScaleMin(input_control) - 图案/模板的最小比例
默认值：0.9
建议值：0.5, 0.6, 0.7, 0.8, 0.9, 1.0
限制： ScaleMin > 0 ScaleMax(input_control) - 图案/模板的最大比例
默认值：1.1
建议值：1.0, 1.1, 1.2, 1.3, 1.4, 1.5
限制： ScaleMax >= ScaleMin ScaleStep(input_control) - 缩放步长（分辨率/精度）
默认值：‘auto’
建议值：‘auto’, 0.01, 0.02, 0.05, 0.1, 0.15, 0.2
限制： ScaleStep >= 0 Optimization(input_control) - 优化的类型和生成模型所用的方法
默认值：‘auto’
可能的值： ‘auto’, ‘no_pregeneration’, ‘none’, ‘point_reduction_high’, ‘point_reduction_low’, ‘point_reduction_medium’, ‘pregeneration’ Metric(input_control) - 匹配的标准/条件
默认值：‘use_polarity’
可能值： ‘ignore_color_polarity’, ‘ignore_global_polarity’, ‘ignore_local_polarity’, ‘use_polarity’ Contrast(input_control) - 模板图像中对象对比度的阈值或滞后阈值以及对象部分的可选最小尺寸。
默认值：‘auto’
建议值：‘auto’, ‘auto_contrast’, ‘auto_contrast_hyst’, ‘auto_min_size’, 10, 20, 30, 40, 60, 80, 100, 120, 140, 160 MinContrast(input_control) - 搜索图像中对象的最小对比度。
默认值：‘auto’
建议值：‘auto’, 1, 2, 3, 5, 7, 10, 20, 30, 40
限制： MinContrast < Contrast
ModelID(output_control)
模型的句柄。
2.6 执行结果
若参数均有效， create_scaled_shape_model 返回值为2（H_MSG_TRUE）。如有必要，将引发异常。如果选择的参数 NumLevels 和 Contrast 使得模型包含的点太少，则会引发错误 8510。
2.7 可能的前驱算子
draw_region, reduce_domain, threshold
2.8 可能的后继算子
find_scaled_shape_model, find_scaled_shape_models, get_shape_model_params, clear_shape_model, write_shape_model, set_shape_model_origin
2.9 替代选择
create_shape_model, create_aniso_shape_model