Halcon_二维测量_Apply_distance_transform_xld

主要功能：演示distance_contours_xld与apply_distance_transform_xld之间的区别，两者的共同点为均是逐点计算两个轮廓之间距离的算子，但是前者可以随时使用，而后者更适合有一个轮廓为固定的用于做对照的情景，在这种情况下，一些耗时的计算可以提前离线完成，这样apply_distance_transform_xld会快得多
主要函数：
一、distance_contours_xld(ContourFrom, ContourTo : ContourOut : Mode : )
功能：计算两个轮廓之间的距离
参数说明：
1、ContourFrom：要计算距离的轮廓
2、ContourTo:用于比较的轮廓
3、ContourOut:输出的轮廓，实际就是ContourFrom的一个副本，但是包含了距离的attribute数组，可以通过get_contour_attrib_xld获取距离
4、Mode：计算距离的模式：a.point_to_point点到点，速度快
b.point_to_segment点到段，精度高

二、get_contour_attrib_xld(Contour : : Name : Attrib)
功能：从Contour中获取所需的属性
参数说明：
1、Contour：用于计算的轮廓
2、Name：要获取的属性类型，包括 ‘angle’-角度, ‘edge_direction’-方向, ‘width_right’-左侧轮廓, ‘width_left’-右侧轮廓, ‘response’-边缘梯度的大小, ‘contrast’-对比度, ‘asymmetry’-图像在边缘两侧的梯度。如果非对称部分，即梯度较弱的部分在直线的右侧，则为正，如果非对称部分在直线的左侧，则为负, ‘distance’-到参考轮廓的距离
3、Attrib：输出的获取得到的值

三、segment_contour_attrib_xld(Contour : ContourPart : Attribute, Operation, Min, Max : )
功能：对局部属性满足给定条件的XLD轮廓零件进行分割。
参数说明：
1、Contour：输入的轮廓
ContourPart：经过条件约束后，输出的满足条件的的轮廓
Attribute：用于作为约束条件的属性
Operation：如果操作被设置为"and"，那么每个给定的属性都必须在限制之内。如果操作设置为’or’，则至少有一个属性必须在限制范围内。处理属性的顺序与属性中给出的顺序相同。
Min ：最小值,参数Min和Max可以设置为’ Min ‘或’ Max '，以便分别打开底限和顶限。
Max ：最大值

四、create_distance_transform_xld(Contour : : Mode, MaxDistance : DistanceTransformID)
功能：通过参考轮廓生成距离模型
参数说明：
1、Contour：模板轮廓
2、Mode：计算距离的模式：a.point_to_point点到点，速度快
b.point_to_segment点到段，精度高
3、MaxDistance：计算的最大距离，具体说明如图

虚线说明了从左侧的测试轮廓的点1开始计算的距离。距离d1对应于‘point_to_point’模式，而距离d2对应于‘point_to_segment’模式。
灰色区域说明了在参考轮廓周围的最大距离范围内的区域，为其计算距离。
测试轮廓点2的距离将被设置为MaxDistance，因为它在这个区域之外。
4、DistanceTransformID：用于存储模型的句柄

五、apply_distance_transform_xld(Contour : ContourOut : DistanceTransformID : )
功能：应用create_distance_transform_xld生成的模型进行轮廓到模板轮廓的距离
参数说明：
1、Contour：要计算的轮廓
2、ContourOut：返回的轮廓轮廓由包含计算距离的属性“distance”的轮廓组成。可以通过使用get_contour_attrib_xld查询属性“distance”来访问它们。若距离超过模型中的MaxDistance则裁切为MaxDistance
3、DistanceTransformID：用于计算的模型句柄

源码及注释如下：

*初始化窗口显示
dev_close_window ()
dev_open_window_fit_size (0, 0, 1280, 1024, -1, -1, WindowHandle)
set_display_font (WindowHandle, 16, 'mono', 'true', 'false')
*介绍两种算子之间的异同
Message := 'This example shows the speed difference between the operators'
Message[1] := 'distance_contours_xld and apply_distance_transform_xld.'
Message[2] := 'Both operators measure the pointwise distance between'
Message[3] := 'two contours.'
Message[4] := ' '
Message[5] := 'While distance_contours_xld can always be used,'
Message[6] := 'apply_distance_transform_xld is used if one of the contours'
Message[7] := 'is reused many times as an unchanging reference contour.'
Message[10] := 'In that case some time-consuming calculations can be done'
Message[11] := 'offline in advance so that apply_distance_transform_xld is'
Message[12] := 'much faster.'
disp_message (WindowHandle, Message, 'window', 12, 12, 'white', 'false')
disp_continue_message (WindowHandle, 'black', 'true')
stop ()
*两种Mode的选择方式，其中点到点的计算方式拥有更快的计算速度，而点到片段的计算方式精度更高
*注释掉其中一条，即表示选中另一种计算方式
Mode := 'point_to_point'
* Mode := 'point_to_segment'
*距离容差
Tolerance := 7
*循环次数
Loops := 4
*用于disp_message函数显示的内容，表示每种不同颜色线段的含义
Legend := ['Legend:','- template contour','- random test contour within tolerance','- random test contour outside of tolerance']
*第一部分：使用distance_contours_xld计算两个轮廓之间的距离
for I := 1 to Loops by 1
    *生成两个测试用的轮廓，其中一个为另一个轮廓偏置一定位置得到
    gen_test_contours (EdgeOriginal, EdgeWarped)
    * Calculate pointwise distance.
    * The distances from points of the first to the points of the second contour
    * are stored in the 'distance' attribute of the output contour.
    * Parts of the contour can be easily segmented based on the attributes.
	*记录时间S1
    count_seconds (S1)
	*获得轮廓1上面每个点到轮廓2上最近点的距离
    distance_contours_xld (EdgeWarped, EdgeOriginal, EdgeWarpedWithDistances, Mode)
	*记录时间S2
    count_seconds (S2)
	*获取计算得到距离数组
    get_contour_attrib_xld (EdgeWarpedWithDistances, 'distance', Distance)
	*对局部属性满足给定条件的XLD轮廓零件进行分割
    segment_contour_attrib_xld (EdgeWarpedWithDistances, ContourPart, 'distance', 'and', Tolerance, 99999)
	*显示结果
    display_result (EdgeOriginal, EdgeWarped, ContourPart)
    Message := 'Part 1: Calculate distances with distance_contours_xld'
    Message[1] := 'Execution time: ' + ((S2 - S1) * 1000)$'.2f' + ' ms'
    disp_message (WindowHandle, Message, 'window', 12, 12, 'black', 'true')
    disp_message (WindowHandle, Legend, 'image', 800, 12, ['gray','white','green','red'], 'false')
    disp_continue_message (WindowHandle, 'black', 'true')
    stop ()
endfor
*第二部分：使用apply_distance_transform_xld计算轮廓到某一固定轮廓的距离，为了达到加速计算的效果，部分信息通过预计算被储存在一个Handle中
dev_clear_window ()
disp_message (WindowHandle, 'Please wait while pre-calculating distance transform...', 'window', 42, 12, 'white', 'false')
MaxDistance := 8
*对参考的模板进行预计算，消耗时间与模板大小以及MaxDistance成正比
*其中MaxDietance用于限定最大距离值，大于该限定值的部分将不参与计算
create_distance_transform_xld (EdgeOriginal, Mode, MaxDistance, DistanceTransformID)
for I := 1 to Loops by 1
    gen_test_contours (NotUsedOriginal, TestContour)
    count_seconds (S1)
	*应用预计算的模型进行距离计算
    apply_distance_transform_xld (TestContour, TestContourOut, DistanceTransformID)
    count_seconds (S2)
	*获取计算得到的距离值，该距离值是被截断过的，最大值不超过MaxDistance
    get_contour_attrib_xld (TestContourOut, 'distance', DistanceClipped)
	*对局部属性满足给定条件的XLD轮廓零件进行分割
    segment_contour_attrib_xld (TestContourOut, ContourPart, 'distance', 'and', Tolerance, MaxDistance)
    * 结果显示
    display_result (EdgeOriginal, TestContour, ContourPart)
    Message := 'Part 2: Calculate distances with apply_distance_transform_xld'
    Message[1] := 'Execution time: ' + ((S2 - S1) * 1000)$'.2f' + ' ms'
    disp_message (WindowHandle, Message, 'window', 12, 12, 'black', 'true')
    disp_message (WindowHandle, Legend, 'image', 800, 12, ['gray','white','green','red'], 'false')
    if (I < Loops)
        disp_continue_message (WindowHandle, 'black', 'true')
        stop ()
    endif
endfor