Halcon中的测量工具（找边找圆等）——Metrology系列

Halcon中的测量工具（找边找圆等）——Metrology系列

1. Halcon中的工具助手

对于使用Halcon的小伙伴们来说，在菜单栏上的“助手”一栏中可以找到一些可以快捷使用的工具。

以18.11版本为例，助手工具栏里有五种工具，分别是：

• Image Acquisition ：图片获取工具，包括基于Halcon的图像采集接口等；
• Calibration：标定工具，用于对图像进行标定；
• Matching: 匹配工具，包括形状及灰度匹配等；
• Measure: 卡尺工具，注意这里只包括卡尺工具；
• OCR：字符识别工具。

对于Measure工具，小白给出的翻译是“卡尺工具”。但是按照英文原意，应该叫“测量工具”。

这里是Halcon的设计上一个非常让小白想不通的地方。因为助手这里的所谓“测量工具”，其实只包含了卡尺这一种功能——即只能查找边缘，或者查找边缘对。所谓的“测量”无非就是测量边缘对之间的距离。
而通常意义上，基于边缘卡尺工具之上的一些找边、找圆等常用的测量工具，却并未包含在这个Measure工具之中。

2. Metrology工具系列

在Halcon中，真正的“测量工具”，却是来自一系列名称中带有“Metrology”的算子。下面以表格的形式给出：

序号	算子名称	算子作用	备注
1	create_metrology_model	创建一个几何测量句柄
2	add_metrology_object_circle_measure	添加一个找圆工具
3	add_metrology_object_ellipse_measure	添加一个找椭圆工具
4	add_metrology_object_generic	添加一个测量工具	可以添加找圆、找边、找椭圆、找矩形等多种工具
5	add_metrology_object_line_measure	添加一个找边工具
6	add_metrology_object_rectangle2_measure	添加一个找矩形工具
7	get_metrology_model_param	获取对整个测量模型有效的参数
8	get_metrology_object_indices	获取一个测量模型中测量对象的索引序号
9	get_metrology_object_measures	获取一个测量模型中的测量区域以及得到的边缘位置
10	get_metrology_object_model_contour	在图像坐标中查询计量对象的模型轮廓
11	get_metrology_object_num_instances	获取测量模型的测量对象的实例数量
12	get_metrology_object_param	获取测量模型的一个或多个参数
13	get_metrology_object_result	获取测量模型的测量结果
14	get_metrology_object_result_contour	获取测量对象的结果轮廓
15	apply_metrology_model	测量和拟合测量模型的所有测量对象的几何形状	顾名思义就是执行测量
16	align_metrology_model	将测量工具与平移旋转绑定	通常与模版匹配联合使用
17	clear_metrology_object	删除测量对象并释放分配的内存
18	clear_metrology_model	删除测量模型并释放分配的内存
19	clear_all_metrology_models	此运算符不可操作。它具有以下功能：删除所有测量模型并释放分配的内存	即将从Halcon中删除，不建议使用
20	get_metrology_object_fuzzy_param	获取测量模型中的模糊参数
21	copy_metrology_model	复制测量模型
22	copy_metrology_object	复制测量对象
23	set_metrology_model_image_size	设置测量对象的图像大小
24	set_metrology_model_param	设置对整个测量模型有效的参数
25	set_metrology_object_fuzzy_param	为测量模型设置模糊参数或模糊函数
26	set_metrology_object_param	为测量模型的测量对象设置参数
27	reset_metrology_object_fuzzy_param	重置测量模型的所有模糊参数和模糊函数
28	reset_metrology_object_param	重置测量模型的所有参数
29	transform_metrology_object	转换测量模型的测量对象，例如用于绑定
30	read_metrology_model	从文件中读取测量模型
31	write_metrology_model	将测量模型写入到文件中
32	serialize_metrology_model	将测量模型序列化
33	deserialize_metrology_model	将测量模型反序列化

总体来说，Halcon的测量工具类，包含有找边、找圆、找椭圆、找矩形四种功能，另外还可以通过模糊函数的定义实现模糊测量。

下面我们来看看Metrology工具的一些实例。

3. Metrology工具实例

3.1 实例1 找边工具

以下实例在一张虚拟工件图上添加一个找直线卡尺组工具（cyan色表示），并找到该工件的上边缘（red色表示）。从这张图我们也能初步得出一个结论：测量工具都是基于卡尺（边缘检测）工具开发的，通常的做法是在卡尺工具找到边缘点的基础上进行拟合。

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '形状模板图.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 113.427
Column1 := 152.106
Row2 := 111.438
Column2 := 336.028

* 添加找直线工具，给定参数，显示过程卡尺的轮廓
add_metrology_object_line_measure (MetrologyHandle, Row1, Column1, Row2, Column2, 20, 5, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找直线并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)
clear_metrology_model (MetrologyHandle)

所找到直线的相关参数信息存储在变量Parameter之中。

3.2 实例2 找圆工具

以下实例在一张虚拟工件图上添加一个找圆卡尺组工具（cyan色表示），并找到该工件的圆孔边缘（red色表示）。

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '形状模板图.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 149.248
Column1 := 321.116
Radius := 23.954

* 添加找圆工具，给定参数，显示过程卡尺
add_metrology_object_circle_measure (MetrologyHandle, Row1, Column1, Radius, 12, 3, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找圆并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)
clear_metrology_model (MetrologyHandle)

所找到圆的相关参数信息存储在变量Parameter之中。

3.3 实例3 找椭圆工具

以下实例在一张虚拟工件图上添加一个找椭圆卡尺组工具（cyan色表示），并找到该工件的内侧椭圆边缘（red色表示）。

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '椭圆测量图.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 167.02
Column1 := 246.855
Phi := -0.366964
Radius1 := 93.6498
Radius2 := 32.8862
* 添加找椭圆工具，给定参数，显示过程卡尺
add_metrology_object_ellipse_measure (MetrologyHandle, Row1, Column1, Phi, Radius1, Radius2, 12, 3, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找椭圆并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)
clear_metrology_model (MetrologyHandle)

所找到椭圆的相关参数信息存储在变量Parameter之中。

3.4 实例4 找矩形工具

以下实例在一张虚拟工件图上添加一个找矩形卡尺组工具（cyan色表示），并找到该工件的外侧边缘（red色表示）。

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '形状模板图.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 192.033
Column1 := 248.541
Length1 := 120.299
Length2 := 79.696
Phi := 0.00827113

* 添加找矩形工具，给定参数，显示过程卡尺
add_metrology_object_rectangle2_measure (MetrologyHandle, Row1, Column1, Phi, Length1, Length2, 12, 3, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找矩形并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)
clear_metrology_model (MetrologyHandle)

所找到矩形的相关参数信息存储在变量Parameter之中。

3.5 实例5 generic法添加测量工具

Halcon的Metrology工具主要功能就是完成以上四种测量，而使用generic时，可以添加任意的工具。以下实例通过generic向Metrology模型中添加找矩形（cyan色）和找圆工具（green色）。找到矩形的外侧边缘轮廓（red色），以及圆孔的边缘轮廓（red色）。

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '形状模板图.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 192.033
Column1 := 248.541
Length1 := 120.299
Length2 := 79.696
Phi := 0.00827113

* 添加找矩形工具，给定参数，显示过程卡尺
add_metrology_object_generic (MetrologyHandle, 'rectangle2', [Row1, Column1, Phi, Length1, Length2], 12, 3, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 0, 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 添加找圆工具，给定参数，显示过程卡尺
Row2 := 149.248
Column2 := 321.116
Radius := 23.954
add_metrology_object_generic (MetrologyHandle, 'circle', [Row2, Column2, Radius], 12, 3, 1, 30, [], [], Index1)
get_metrology_object_model_contour(Contour2, MetrologyHandle, 1, 1.5)
get_metrology_object_measures (Contours3, MetrologyHandle, 1, 'all', Row3, Column3)
dev_set_color ('green')
dev_display (Contour2)
dev_display (Contours3)

dev_set_line_width (3)
* 执行找矩形并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter1)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
get_metrology_object_result (MetrologyHandle, 1, 'all', 'result_type', 'all_param', Parameter2)
get_metrology_object_result_contour (Contour3, MetrologyHandle, 1, 'all', 1.5)
dev_set_color ('red')
dev_display (Contour1)
dev_display (Contour3)
clear_metrology_model (MetrologyHandle)

注意到get_metrology_object_result和get_metrology_object_result_contour中通过index参数的调整分别按顺序提取到矩形和圆的结果轮廓。
若index参数设置为'all'时，则可以一次性取出所有的结果轮廓。

3.6 实例6 set/reset测量工具模型参数

在卡尺工具中，如果想修改测量工具中的模型参数，则可以通过set/reset算子进行修改。以下实例通过set_metrology_object_param算子，修改了卡尺的搜索长度以及目标结果的个数，使一开始找到一个圆的操作，最终找到了两个圆的边缘。

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '同心圆选取.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 181.42
Column1 := 223.8
Radius := 89.2713

* 添加找圆工具，给定参数，显示过程卡尺
add_metrology_object_circle_measure (MetrologyHandle, Row1, Column1, Radius, 12, 3, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找圆并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)
stop()

* 修改找圆工具的参数，显示过程卡尺
dev_clear_window ()
dev_display (Image)
set_metrology_object_param (MetrologyHandle, 'all', 'num_instances', 2)
set_metrology_object_param (MetrologyHandle, 'all', 'measure_length1', 60)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找圆并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)

clear_metrology_model (MetrologyHandle)

注意到此例中，由于是对同一个卡尺工具进行修改，所以在找第二个圆时，其结果已经将原先的结果完全覆盖。
reset相当于把所有相关参数重置，这里就不做过多介绍。

3.7 实例7 模糊测量工具

以下实例可能有一些“拼凑”的嫌疑：如图所示，需要在同心圆图像中找到特定的圆边缘。这个实例图虽然是小白用Photoshop做出来的，但在实际检测中，对于摄像头区域的检测会经常遇到类似的场景。

由于图中存在多个位置接近的同心圆，如何从图像中找到从外向内的第四个圆边界呢？
我们很容易就能找到从外向内的第二个圆边界：

但当我们知道如何使用模糊函数，再加上极性选择，则可以轻松地找到从外向内的第四个圆边界：

让我们放大一些来看：

以下贴出全部的代码：

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '同心圆选取.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 181.42
Column1 := 223.8
Radius := 40

* 添加找圆工具，给定参数，显示过程卡尺
add_metrology_object_circle_measure (MetrologyHandle, Row1, Column1, Radius, 30, 3, 1, 8, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row, Column)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找圆并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)
stop()

* 添加模糊函数，添加模糊找圆
create_funct_1d_pairs ([5,12,20], [0.0,1.0,0.0], GrayFunction)
set_metrology_object_fuzzy_param (MetrologyHandle, 'all', 'function_contrast', GrayFunction)
set_metrology_object_fuzzy_param (MetrologyHandle, 'all', 'fuzzy_thresh', 0.5)
* set_metrology_object_param (MetrologyHandle, 'all', 'measure_transition', 'positive')
set_metrology_object_param (MetrologyHandle, 'all', 'measure_transition', 'negative')
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_clear_window ()
dev_display (Image)
dev_set_line_width (1)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)

clear_metrology_model (MetrologyHandle)

3.8 实例8 与模板匹配联合使用

以下实例也是非常常用的：首先建立一个形状匹配模板，然后放上测量的卡尺，这样可以在不同的随意摆放的工件图像中找到目标并完成测量。
如图，建立形状模板；

在形状模板建立后建立测量工具：

利用形状模板定位实现测量工具找圆：

完整代码如下所示：

* 清空屏幕，显式控制图像显示
dev_close_window ()
dev_update_off ()
read_image (Image, '形状模板图.png')
dev_open_window_fit_image (Image, 0, 0, -1, -1, WindowHandle)
dev_display (Image)

* 
* Matching 01: ************************************************
* Matching 01: BEGIN of generated code for model initialization
* Matching 01: ************************************************
set_system ('border_shape_models', 'false')

* 
* Matching 01: Build the ROI from basic regions
gen_rectangle1 (ModelRegion, 104.473, 124.269, 282.577, 376.789)
* 
* Matching 01: Reduce the model template
reduce_domain (Image, ModelRegion, TemplateImage)
* 
* Matching 01: Create the shape model
create_shape_model (TemplateImage, 5, rad(0), rad(360), rad(1), ['none','no_pregeneration'], 'use_polarity', [30,30,0], 10, ModelID)
* 
* Matching 01: Get the model contour for transforming it later into the image
get_shape_model_contours (ModelContours, ModelID, 1)
* 
* Matching 01: Get the reference position
area_center (ModelRegion, ModelRegionArea, RefRow, RefColumn)
vector_angle_to_rigid (0, 0, 0, RefRow, RefColumn, 0, HomMat2D)
affine_trans_contour_xld (ModelContours, TransContours, HomMat2D)
* 
* Matching 01: Display the model contours
dev_display (Image)
dev_set_color ('green')
dev_set_draw ('margin')
dev_display (ModelRegion)
dev_display (TransContours)
stop ()
* 
* Matching 01: END of generated code for model initialization
* Matching 01:  * * * * * * * * * * * * * * * * * * * * * * *
* Matching 01: BEGIN of generated code for model application
* Matching 01: The following operations are usually moved into
* Matching 01: that loop where the acquired images are processed
* 
* Matching 01: Find the model
find_shape_model (Image, ModelID, rad(0), rad(360), 0.5, 0, 0.5, 'least_squares', [5,1], 0.75, Row, Column, Angle, Score)
* 
* Matching 01: Transform the model contours into the detected positions
dev_display (Image)
for I := 0 to |Score| - 1 by 1
    hom_mat2d_identity (HomMat2D)
    hom_mat2d_rotate (HomMat2D, Angle[I], 0, 0, HomMat2D)
    hom_mat2d_translate (HomMat2D, Row[I], Column[I], HomMat2D)
    affine_trans_contour_xld (ModelContours, TransContours, HomMat2D)
    dev_set_color ('green')
    dev_display (TransContours)
    stop ()
endfor
* 
* Matching 01: *******************************************
* Matching 01: END of generated code for model application
* Matching 01: *******************************************
* 

* 创建测量模型
create_metrology_model (MetrologyHandle)
Row1 := 149.248
Column1 := 321.116
Radius := 23.954

* 添加找圆工具，给定参数，显示过程卡尺
add_metrology_object_circle_measure (MetrologyHandle, Row1, Column1, Radius, 12, 3, 1, 30, [], [], Index)
get_metrology_object_model_contour (Contour, MetrologyHandle, 0, 1.5)
get_metrology_object_measures (Contours, MetrologyHandle, 'all', 'all', Row3, Column3)
dev_set_color('cyan')
dev_display (Contour)
dev_display (Contours)

* 执行找圆并显示结果
apply_metrology_model (Image, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter)
get_metrology_object_result_contour (Contour1, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour1)

stop()

* 绑定测量卡尺到形状模板上
set_metrology_model_param (MetrologyHandle, 'reference_system', [Row, Column, 0])

* 读取另一幅图片
read_image (Image1, '形状模板图2.png')
find_shape_model (Image1, ModelID, rad(0), rad(360), 0.5, 0, 0.5, 'least_squares', [5,1], 0.75, Row2, Column2, Angle1, Score1)
align_metrology_model (MetrologyHandle, Row2, Column2, Angle1)
get_metrology_object_measures (Contours1, MetrologyHandle, 'all', 'all', Row4, Column4)
dev_clear_window ()
dev_display (Image1)
dev_set_line_width (1)
dev_set_color ('cyan')
dev_display (Contours1)

apply_metrology_model (Image1, MetrologyHandle)
get_metrology_object_result (MetrologyHandle, 0, 'all', 'result_type', 'all_param', Parameter1)
get_metrology_object_result_contour (Contour2, MetrologyHandle, 0, 'all', 1.5)
dev_set_line_width (3)
dev_set_color ('red')
dev_display (Contour2)
clear_metrology_model (MetrologyHandle)
clear_shape_model (ModelID)

代码中的要点是利用形状模板得到的Row和Column信息，通过set_metrology_model_param中的reference_system绑定测量工具，然后在再一次模板匹配定位后，通过align_metrolgy_model对测量工具进行位置变换。最后再执行测量，即可得到所需的结果。

4. 小结

以上就作为对Halcon中测量族工具的一个简单介绍。这个工具应该说还是非常重要的，只是不知道Halcon是出于什么样的考虑，一直不将这组工具封装成助手。至少小白是在学习Halcon很久以后才知道找边找圆工具是怎样工作的。

【创作不易，水平所限，若有错漏，轻喷勿骂】