基于形状的模板匹配，Halcon例程adapt_shape_model_high_noise学习

一、代码的主要思路为：

这个例程展示了如何使用形状模型（Generic Shape Model）在含有高噪声的图像中进行对象检测。代码分为几个主要部分，包括模型的创建、训练、参数设置、搜索参数配置以及在线搜索过程。以下是详细的步骤和功能解释：

初始化与环境设置

• 关闭并重新初始化设备（窗口）。
• 读取一个示例图像crosses_01用于后续展示和说明。
• 设置显示窗口的字体、颜色和线宽，为可视化做准备。
• 显示图像描述信息和样本图像，暂停程序让用户查看。

创建形状模型（离线步骤）

• 使用create_generic_shape_model创建一个形状模型对象。

定义模型模板（离线步骤）

• 读取一个定义好的模型轮廓（ModelContour），这是模型匹配的基础。

设置模型参数（离线步骤）

• 调整尺度不变性参数（最小和最大比例），以适应不同大小的对象。

训练形状模型（离线步骤）

• 使用train_generic_shape_model根据提供的轮廓训练模型。

设置匹配度量（离线步骤）

• 创建一个极性图像（PolarityImage）以辅助匹配，通过填充区域并根据轮廓反转部分区域的像素值。
• 根据匹配结果计算单应性矩阵，并设置模型匹配度量，使用极性图像增强匹配效果。

估计最低金字塔级别（离线步骤）

• 针对高噪声情况，使用一个样本搜索图像来自动估计搜索时应使用的最低金字塔级别，这有助于在噪声较大的情况下仍能有效匹配。

设置搜索参数（在线/离线均可）

• 限制旋转角度范围、设置最大匹配数、允许的最大重叠以及贪婪度等，以优化搜索性能和结果质量。贪婪度设置为0意味着尽可能全面的搜索，不急于收敛。

在图像中查找模型（在线步骤）

• 循环读取一系列测试图像（crosses_02至crosses_11），在每张图像中使用训练好的模型进行匹配。
• 对于每次匹配，获取所有匹配结果的轮廓，并在原图像上显示这些轮廓，同时提供匹配结果的文本说明。
• 每处理完一张图片后，暂停一段时间以便观察。

清理与结束

• 清空显示窗口，显示结束信息，重新开启设备更新，完成程序。

 二、具体代码注释如下

* 
* ***********************************************************
* This example shows how to use the 'high_noise_sample'     *
* parameter from the set_generic_shape_model_object         *
* operator to improve the matching rate for images          *
* containing very high noise. The operator estimates the    *
* lowest pyramid level automatically based on a provided    *
* sample search image. 
*查找图像中一个或多个形状模型的最佳匹配此示例演示如何使用“high_noise_sample”    
*参数 from the set_generic_shape_model_object        
*运算符，以提高图像的匹配率         
*包含非常高的噪音。运算符估计   
*最低金字塔级别自动基于提供的   
*示例搜索图像。                                     *
* ***********************************************************
* 
* Initialization.
dev_update_off ()
dev_close_window ()
* 
* Initialization of the display window using automatic size.
read_image (Image, 'crosses/crosses_01')
*打开一个新的图形窗口，以保留给定图像的纵横比。
dev_open_window_fit_image (Image, 0, 0, 640, 640, WindowHandle)
*设置窗口的字体大小为14，格式为'mono'，加粗，不倾斜
set_display_font (WindowHandle, 14, 'mono', 'true', 'false')
*设置输出颜色
dev_set_color ('lime green')
*设置轮廓边缘的宽度
dev_set_line_width (3)
* 
* Visualization.
*显示描述文本
dev_display_description_text (WindowHandle)
stop ()
*显示例程图片
dev_display_sample_image (Image, WindowHandle)
stop ()
* 
* ***********************************************************
* Create the shape model (offline step)                     *
*创建形状模型（离线步骤）
* ***********************************************************
* 创建未被训练模型的句柄
create_generic_shape_model (ModelID)
* 
* ***********************************************************
* Define the model template (offline step)                  *
*定义模型模板
* ***********************************************************
* 
* The quality of the model contour is crucial.
*模型轮廓的质量至关重要
*从model_contour中读取ModelContour（模型轮廓）标志性对象
read_object (ModelContour, 'model_contour')
* 
* ***********************************************************
* Set the model parameters (offline step)                   *
*设置模型参数（离线步骤）
* ***********************************************************
* 设置模型搜索匹配对象时的缩放比例最小为75%最大为125%
set_generic_shape_model_param (ModelID, 'iso_scale_min', 0.75)
set_generic_shape_model_param (ModelID, 'iso_scale_max', 1.25)
* 
* ***********************************************************
* Train the shape model (offline step)                      *
*训练形状模型（离线步骤）  
* ***********************************************************
* 训练用于匹配的形状模型
*在模型ModelID训练查找ModelContour（模型轮廓）
train_generic_shape_model (ModelContour, ModelID)
* 
* ***********************************************************
* Set the metric (offline step)                             *
* 设置度量（离线步骤）
* ***********************************************************
* 
* 创建极性图像
*创建宽高为512,1字节的图像PolarityImage
gen_image_const (PolarityImage, 'byte', 512, 512)
*将PolarityImage整体填充为白色
paint_region (PolarityImage, PolarityImage, PolarityImage, 255, 'fill')
*将ModelContour（模型轮廓）以黑色写入到PolarityImage中
paint_xld (ModelContour, PolarityImage, PolarityImage, 0)
* 
* Determine the associated homography and set the metric.
* 确定关联的单向度并设置指标。

*在PolarityImage搜索ModelID，结果句柄为PolarityMatchResultID，返回了NumMatchResult个匹配项
find_generic_shape_model (PolarityImage, ModelID, PolarityMatchResultID, NumMatchResult)
*从形状匹配的结果中获取数值，形状模型PolarityMatchResultID，查询第一个匹配的结果中的同形变换矩阵并存入HomMat2D
get_generic_shape_model_result (PolarityMatchResultID, 0, 'hom_mat_2d', HomMat2D)
*设置从 XLD 等值线创建的形状模型的度量。
*给定的形状模型（ModelID）设置匹配度量标准，使之在匹配过程中利用提供的极性图像（PolarityImage）
*和预先计算的单应性矩阵（HomMat2D）进行匹配
set_shape_model_metric (PolarityImage, ModelID, HomMat2D, 'use_polarity')
* 
* Visualization.
*可视化
*展示在PolarityImage上通过PolarityMatchResultID标识的匹配结果的评估指标或匹配质量
dev_display_metric (PolarityImage, PolarityMatchResultID, WindowHandle)
stop ()
* 
* ***********************************************************
* Estimate the lowest pyramid level (offline step)          *
*估计最低金字塔层级（离线步骤）
* ***********************************************************
* 
* Estimate the lowest pyramid level based on a sample
*基于样本搜索图像估计最低金字塔层级
* search image.
*查找图像
*创建一个平行于坐标轴的矩形。
gen_rectangle1 (Rectangle, 97, 355, 222, 455)
*在Image中分割Rectangle到ImageReduced中
reduce_domain (Image, Rectangle, ImageReduced)
*设置根据ImageReduced样本，以及匹配的ModelID模型来自动调整形状模型的某些内部设置
set_generic_shape_model_object (ImageReduced, ModelID, 'high_noise_sample')
*返回'pyramid_level_lowest'（金字塔层数最低）的值到PyramidLevelLowest中
get_generic_shape_model_param (ModelID, 'pyramid_level_lowest', PyramidLevelLowest)
* 
* Visualization.
* 可视化
* 显示高噪音的例程图片
dev_display_high_noise_sample (ImageReduced, PyramidLevelLowest, WindowHandle)
stop ()
* 
* ***********************************************************
* Set the search parameters                                 *
*设置搜索参数 
* ***********************************************************
* 
* The search parameters can be set before or in the
* online phase.
*搜索参数可以在在线阶段之前或在在线阶段设置
*设置模型的开始搜索模型的可能旋转范围的起点为rad(50)
set_generic_shape_model_param (ModelID, 'angle_start', rad(-50))
* As the object is (almost) symmetric, we limit the
* allowed angle range to prevent multiple, almost equally
* good matches on the same object at different angles.
*由于对象（几乎）对称，我们限制允许的角度范围以防止在不同角度的同一对象上出现多个几乎同样好的匹配。
*设置模型的开始搜索模型的可能旋转范围的结束点为rad(50)
set_generic_shape_model_param (ModelID, 'angle_end', rad(50))
*设置最大的返回实例数为5
set_generic_shape_model_param (ModelID, 'num_matches', 5)
*设置模型的匹配区域不能有任何重叠
set_generic_shape_model_param (ModelID, 'max_overlap', 0.0)
*设置搜索匹配的贪婪度为0，会全面和详尽地搜索所有可能的匹配位置、尺度和旋转角度，但搜索速度可能较慢
set_generic_shape_model_param (ModelID, 'greediness', 0.0)
* 
* ***********************************************************
* Find the model (online step)                              *
*查找模型（在线步骤）
* ***********************************************************
* 
* Use the model to search in new images.
*使用模型在新图像中搜索
dev_set_color ('lime green')
NumImages := 10
for Index := 1 to NumImages by 1
    read_image (Image, 'crosses/crosses_' + Index$'02')
    *查找Image中以ModelID搜索的最佳匹配项，匹配结果在中，匹配到的个数为NumMatchResult
    find_generic_shape_model (Image, ModelID, MatchResultID, NumMatchResult)
    *在找到的结果MatchResultID中，找到所有的匹配结果中的'contours'（轮廓）存放在Contours中
    get_generic_shape_model_result_object (Contours, MatchResultID, 'all', 'contours')
    * 
    * Visualization.
    dev_display (Image)
    dev_display (Contours)
    dev_disp_text ('Detection results in search image.', 'window', 'top', 'left', 'black', 'box', 'true')
    dev_disp_text ('Image ' + Index + '/' + 10, 'window', 'top', 'right', 'black', 'box', 'true')
    wait_seconds (0.75)
endfor
stop ()
* 
* ***********************************************************
* Clean up                                                  *
* ***********************************************************
dev_clear_window ()
dev_disp_text ('End of program', 'window', 'bottom', 'right', 'black', [], [])
dev_update_on ()

三、关键算子解释

（1）create_generic_shape_model(ModeID)

 ModeID：返回模型的句柄

算子说明：创建一个新的、空白的形状模型结构，用该模型结构接收和处理后续用于学习特定形状特征的数据。该算子不涉及模型训练，模型训练常用train_generic_shape_model算子来完成

（2）read_object( : Object : FileName : )

Object：输出参数，可以是XLD、Region或者其他的几何对象，储存从FileName中读取的对象数据。

FileName：输入参数，类型为字符串，指定要从中读取对象信息的文件路径和名称。

算子说明：从FileName文件中读取已经定义好的几何对象或轮廓数据，并将其加载到变量Object中，以便在后续的图像处理或匹配操作中使用。

（3） set_generic_shape_model_param( : : ModelID, GenParamName, GenParamValue : )

 ModelID：输入参数，一般为创建的模型或训练模型的句柄，create_shape_model（创建模型）或train_shape_model（训练模型）。

GenParamName：输入参数，指定想要设置的通用参数的名称。这些参数控制着模型的创建或匹配行为，例如采样点的数量、角度步长、比例范围等。（具体参数参考官方手册）

GenParamValue：输入参数，要设置的GenParamName参数的具体值。

算子说明：用来设置通用形状模型（Generic Shape Model）参数，允许用户自定义或调整与形状模型相关的各种参数，以优化模型的创建或匹配过程。

（4）train_generic_shape_model(Template : : ModelID : )

Template: 输入参数，类型为XLD或 Region，表示用于训练模型的模板或样本轮廓，这个轮廓应当准确描绘了你想要模型学习和识别的形状 。

ModelID：输入和输出参数，模型的句柄会被用于存储训练过程中形成的模型，训练完成后，ModelID就包含了完整的形状模型，可用于后续的匹配操作。

算子说明：基于提供的模板或样本轮廓，训练出一个能够识别具有相似形状特征的对象的模型。这个模型能够处理尺度、旋转等变化，适用于在复杂场景中寻找和匹配目标形状。

（5）paint_region(Region, Image : ImageResult : Grayval, Type : )

Region：输入参数，待处理的图像。

Image：输入参数，要被填充的区域。

ImageResult：输出参数，输出的图像结果。

Grayval：填充颜色的灰度值。

Type：'fill'为填充，'margin'为边缘。

算子说明：用于对图像中的特定区域进行填充操作，改变这些区域的像素值。

（6）paint_xld(XLD, Image : ImageResult : Grayval : )

XLD：输入参数，表示要绘制的轮廓。

Image：输入图像，类型为灰度图或彩色图，是绘制轮廓的背景图像。

ImageResult：输出图像，包含了绘制的轮廓。

Grayval: 输入参数，表示绘制轮廓时使用的灰度值或颜色的强度，默认为255白色。

算子说明：将XLD轮廓描绘在指定的图像上，生成一个包含轮廓的图像结果。

（7）find_generic_shape_model(SearchImage : : ModelID : MatchResultID, NumMatchResult)

SearchImage：输入参数，表示要在其中搜索形状模型的图像。

ModelID：输入参数，表示之前创建并训练好的通用形状模型的标识符。

MatchResultID：输出参数，类型为句柄，用于存储找到的匹配结果。

NumMatchResult：输出参数，表示找到的匹配结果的数量。

算子说明：用来查找图像中与预定义的通用形状模型匹配的对象，这个算子是基于形状的匹配方法，适用于寻找图像中的特定形状实例。

（8）get_generic_shape_model_result( : : MatchResultID, MatchSelector, GenParamName : GenParamValue)

MatchResultID：输入参数，是通过find_generic_shape_model调用后返回的匹配结果的标识符。

MatchSelector：输入参数，用于指定从匹配结果集中提取哪一个或哪几项匹配信息。如果是整数，表示匹配结果的索引（从0开始）；如果是'all'，则表示获取所有匹配的结果。

GenParamName：输入参数，指定你想要获取的匹配结果的具体属性名称。可能的属性包括但不限于'row', 'column', 'angle', 'scale', 'hom_mat_2d'（二维单应性矩阵）等，具体包含参数查看官方手册。

GenParamValue：输出参数，将接收从匹配结果中提取的特定属性值。

算子说明：用于从之前通过find_generic_shape_model函数找到的匹配结果中提取具体信息。

（9）set_shape_model_metric(Image : : ModelID, HomMat2D, Metric : )

Image：输入参数，是用于设置匹配度量时参考的图像。

ModelID：输入参数，代表之前创建并训练好的形状模型。

HomMat2D：输入参数，二维单应性矩阵，描述了模型坐标系到图像坐标系的几何变换。

Metric：输入参数，指定要设置的匹配度量类型，它定义了模型如何评估和选择最佳匹配。

算子说明：根据给定的图像、模型和单应性矩阵，配置形状模型的匹配评估标准，以优化在特定图像条件下的匹配性能。

（10）set_generic_shape_model_object(Object : : ModelID, GenParamName : )

Object：输入参数，给定的特征。

ModelID：输入参数，要进行匹配的模型。

GenParamName：输入参数，要设置的类型，包括有'high_noise_sample'，'clutter_region'等

算子说明：根据给定的 Object 设置形状模型 ModelID 的GenParamName参数。

（11）get_generic_shape_model_param( : : ModelID, GenParamName : GenParamValue)

ModelID：输入参数，训练模型标识符。

GenParamName：输入参数，指定你想要查询的模型参数的名称。这些参数可以包括但不限于模型训练时设置的尺度范围（如'iso_scale_min', 'iso_scale_max'）、旋转角度范围（如'angle_start', 'angle_end'）、贪婪度（'greediness'）等。

GenParamValue：输出参数，存储获取到的值。

算子说明：获取通用形状模型的特定参数。

四、形状匹配其他算子

＜Halcon＞ 浅学形状模板匹配_halcon模板匹配之形状匹配法-CSDN博客