create_ncc_model (算子)

create_ncc_model (算子)

名称
create_ncc_model — 创建用于匹配的归一化互相关（NCC）模型。

签名
create_ncc_model(Template : : NumLevels, AngleStart, AngleExtent, AngleStep, Metric : ModelID)

描述
算子 create_ncc_model 用于准备一个模板，该模板通过图像 Template 传入，作为一个使用​​归一化互相关系数 (Normalized Cross Correlation, NCC)​​ 进行匹配的模型。模型的感兴趣区域 (ROI) 通过 Template 的域 (Domain) 传入。

该模型是通过在多个图像金字塔层级上，对每一层级进行多次旋转预先生成的，并存储在内存中。输出参数 ModelID 是这个模型的句柄 (Handle)，在后续调用 find_ncc_model 时使用。

• 金字塔层级数 (NumLevels)：
  金字塔层级数由参数 NumLevels 决定。此值应尽可能设大，因为这将​​显著减少 (significantly reduced)​​ 查找对象所需的时间。另一方面，NumLevels 的选择必须确保即使在最高金字塔层级上模型仍然可识别且包含足够数量的点（至少八个点）。这可以通过检查 gen_gauss_pyramid 输出图像的域来验证。如果生成的模型点不足，则系统将​​内部降低 (reduced internally)​​ 金字塔层级数，直到在最高层级上找到足够多的模型点。如果此过程会导致模型没有任何金字塔层级（即如果在最低层级上模型点数量已经太少），create_ncc_model 将返回错误消息。若将 NumLevels 设为 'auto' 或 0，则 create_ncc_model 会自动确定金字塔层级数。自动计算的金字塔层级数可通过 get_ncc_model_params 查询。在极少数情况下，create_ncc_model 自动确定的层级数可能过大或过小。若层级数过大，模型可能无法在图像中被识别，或者需要在 find_ncc_model 中选择非常低的 MinScore 参数才能找到模型。若层级数过小，在 find_ncc_model 中查找模型所需的时间可能会增加。在这些情况下，应通过检查 gen_gauss_pyramid (使用参数 Mode = 'constant' 和 Scale = 0.5) 输出来手动选择合适的金字塔层级数。

• 旋转范围与步长 (AngleStart, AngleExtent, AngleStep)：
  参数 AngleStart 和 AngleExtent 确定了模型在图像中可能出现的旋转范围。请注意，find_ncc_model 只能在此角度范围内找到模型。参数 AngleStep 决定了选定角度范围内的​​步长 (step length)​​。因此，如果在 find_ncc_model 中未指定亚像素精度，此参数就决定了 find_ncc_model 中可达到的角度精度。AngleStep 应根据对象的大小选择。较小的模型在图像中不具备许多不同的离散旋转角度，因此对于较小的模型，AngleStep 应设得更大。如果 AngleExtent 不是 AngleStep 的整数倍，AngleStep 会相应修改。为了确保对可能旋转的采样独立于给定的 AngleStart，可能旋转的范围按如下方式修改：如果不存在一个正整数 n 使得 AngleStart + n * AngleStep 恰好等于 0.0，则会将 AngleStart 最多减小一个 AngleStep，并将 AngleExtent 增加一个 AngleStep。

  存储与内存考量： 该模型会为选定的角度范围预先生成并存储在内存中。存储模型所需的内存与角度步数以及模型中的点数成正比。因此，如果 AngleStep 过小或 AngleExtent 过大，模型可能会无法放入（虚拟）内存。在此情况下，必须增大 AngleStep 或减小 AngleExtent。在任何情况下，强烈建议 (desirable) 模型完全装入主内存，因为这可以避免 (avoids) 操作系统进行分页 (paging)，从而大大缩短查找对象所需的时间。由于 find_ncc_model 可以亚像素分辨率确定角度，对于直径小于约200像素的模型，可以选择 AngleStep >= 1。如果选择 AngleStep = 'auto' 或 0，则 create_ncc_model 会根据模型大小自动确定合适的角度步长。自动计算的角度步长可通过 get_ncc_model_params 查询。

• 匹配度量条件 (Metric)：
  参数 Metric 决定了模型在图像中被识别的条件。

  • 若 Metric = 'use_polarity'，则图像中的对象与模型必须具有相同的对比度 (must have the same contrast)。例如，如果模型是一个亮背景上的暗对象 (bright object on a dark background)，则只能在对象同样比背景亮的图像中找到它。
  • 若 Metric = 'ignore_global_polarity'，则即使全局对比度发生反转 (reverses globally)，也能在图像中找到对象。在上述例子中，即使对象比背景暗也能被找到。在此情况下，find_ncc_model 的运行时间将略有增加 (will increase slightly)。

模型图像 Template 的域（区域）的重心被用作模型的原点 (origin)（参考点 (reference point)）。可以使用 set_ncc_model_origin 设置不同的原点。

执行信息

• 多线程类型：可重入 (reentrant)（可与非独占算子 (non-exclusive operators) 并行运行）。
• 多线程范围：全局 (global)（可从任何线程调用）。
• 处理：无并行化。
• 重要提示： 该算子返回一个句柄。请注意，即使句柄作为输入参数 (even though the handle is used as an input parameter) 传递给某些特定算子，该句柄实例的状态仍可能被这些算子更改。

参数

• Template (输入参数，单通道图像 (singlechannelimage)) → 对象 (byte / uint2)

  用于创建模型的输入图像，其域（ROI）将被使用。

• NumLevels (输入控制) → 整数 / 字符串 (integer / string)

  最大金字塔层级数。
  默认值: ‘auto’
  可选值: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ‘auto’

• AngleStart (输入控制) → 角度.弧度 (angle.rad / real)

  图案的最小旋转角度（弧度）。
  默认值: -0.39 (-≈22.5°)
  建议值: -3.14 (-180°), -1.57 (-90°), -0.79 (-45°), -0.39 (-22.5°), -0.20 (-11.5°), 0.0 (0°)

• AngleExtent (输入控制) → 角度.弧度 (angle.rad / real)

  旋转角度的范围（弧度）。
  默认值: 0.79 (≈45°)
  建议值: 6.29 (360°), 3.14 (180°), 1.57 (90°), 0.79 (45°), 0.39 (22.5°)
  ​​约束：​​ AngleExtent >= 0

• AngleStep (输入控制) → 角度.弧度 / 字符串 (angle.rad / real / string)

  角度步长（弧度，分辨率）。
  默认值: ‘auto’
  建议值: ‘auto’, 0.0 (0°), 0.0175 (1°), 0.0349 (2°), 0.0524 (3°), 0.0698 (4°), 0.0873 (5°)
  ​​约束：​​ AngleStep >= 0 && AngleStep <= pi / 16 (即 <= 11.25°)

• Metric (输入控制) → 字符串 (string)

  匹配度量条件。
  默认值: ‘use_polarity’
  可选值: ‘ignore_global_polarity’, ‘use_polarity’

• ModelID (输出控制) → NCC模型句柄 (ncc_model / handle)

  模型的句柄。

结果
如果参数有效，算子 create_ncc_model 返回整数值 2 (表示 H_MSG_TRUE)。如果参数 NumLevels 的选择导致模型包含过少的点，将引发错误 8506。

可能的前序算子
draw_region, reduce_domain, threshold

可能的后序算子
find_ncc_model, get_ncc_model_params, clear_ncc_model, write_ncc_model, set_ncc_model_origin, set_ncc_model_param, find_ncc_models

备选方案
create_generic_shape_model (创建通用的形状模型)

所属模块
匹配 (Matching)

HDevelop例程

• ncc_matching_workflow.hdev - 使用基于相关性的匹配查找对象（最小化工作流示例）
• find_ncc_model_exposure.hdev - 使用基于相关性的匹配，在存在线性光照变化时查找对象
• find_ncc_model_defocused_precision.hdev - 检查镜头不同焦点图像中的NCC匹配结果 (离焦精度)
• find_ncc_model_defocused.hdev - 使用基于相关性的匹配，在纹理和焦点 (texture and focus) 发生变化时查找对象
• check_cable_labels.hdev - 使用基于相关性的匹配（NCC）检查电缆类型和必需标记是否存在 (Check type of cables and presence of required imprints)