halcon例程 -- 逐字细究（一）

* ------------------------------------------------------------------------------------------------
* This example program uses shape-based matching to align ROIs for the measure
* tool, which then inspects individual razor blades.
* The program can be run in two modes: (1) with the full affine transformation
*                                                                (2) using translate_measure
* Modify the next line to switch between the modes.
USING_TRANSLATE_MEASURE := 0
* ------------------------------------------------------------------------------------------------
* general configuration of HDevelop
dev_update_window ('off') 
*关闭窗口的刷新
* image acquisition and window size
read_image (ModelImage, 'razors1')
*读取图像
get_image_pointer1 (ModelImage, Pointer, Type, Width, Height)
*获取图像的指针
dev_close_window ()
*关闭当前窗口
dev_open_window (0, 0, Width, Height, 'white', WindowHandle)
*重新打开一个和当前图像尺寸一样的窗口，背景色为白色
dev_set_part (0, 0, Height - 1, Width - 1)
*设置显示图像区域大小
dev_display (ModelImage)
*显示图像
* colors and other settings for the visualization
dev_set_color ('cyan')
*设置颜色输出
dev_set_draw ('margin')
*定义区域填充模式
dev_set_line_width (2)
*设置区域图像里的轮廓线的宽度
stop ()
*运行停止
* -------------------  start of the application  ----------------
* -> select the model object
Row1 := 46
Column1 := 57
Row2 := 79
Column2 := 94
gen_rectangle1 (ROIPart1, Row1, Column1, Row2, Column2)
*生成一个平行于坐标轴的矩形,它可以生成一个或多个矩形
gen_rectangle1 (ROIPart2, Row1 + 364, Column1 + 13, Row2 + 364, Column2 + 13)
union2 (ROIPart1, ROIPart2, ModelROI)
*返回两个区域之间的联合
area_center (ModelROI, Area, CenterROIRow, CenterROIColumn)
**函数原型：area_center(Regions:::Area,Row,Column)
*功能：
*测得区域的面积和中心位置。面积是由区域的像素个数决定，中心是由区域的行列坐标平均值所决定。
*如果输入区域是多个，则输出变量分索引号也是多个，并且一一对应。如果区域为空，则所以参数的值为0.0。
*参数列表：
*第1个参数Regions是输入对象，即被测区域
*第2个参数Area是输出变量，即被测区域的面积
*第3个参数Row是输出变量，即被测区域中心的行索引
*第4个参数Column是输出变量，即被测区域中心的列索引
dev_display (ModelImage)
dev_display (ModelROI)
stop ()
* -> create the model
reduce_domain (ModelImage, ModelROI, ImageROI)
*用于截取所画出的ROI
create_shape_model (ImageROI, 4, 0, 0, 'auto', 'none', 'use_polarity', 30, 10, ModelID)
*准备一个不可缩放比例的匹配轮廓模型
*函数参数：
*第一个参数Template：输入的图像模板名称；用来产生模型的图像
*第二个参数NumLevels：最大的金字塔（分析数）层数，默认‘auto’
*第三个参数AngleStart：输入匹配时的起始角度
*第四个参数AngleExtent：输入匹配时的角度范围
*第五个参数AngleStep：输入匹配旋转角度的步长，默认‘auto’
*第六个参数Optimization：设置模板优化和模板创建方法
*第七个参数Metric：设置匹配方法
*第八个参数Contrast：设置对比度
*第九个参数MinContrast：输入图像中匹配物体的最小差别（对比度）
*第十个参数ModelID：输出模型句柄
inspect_shape_model (ImageROI, ShapeModelImage, ShapeModelRegion, 1, 30)
**创建一个轮廓模型基于金字塔的影像
*函数参数：
*第一个参数：输入图像
*第二个参数：输出图像基于金字塔的影像
*第三个参数：输出模型区域
*第四个参数：使用金字塔层数
*第五个参数：设置对比度
get_shape_model_contours (ShapeModel, ModelID, 1)
**返回一个轮廓模型的外形轮廓
*函数参数：
*第一个参数：输出外形轮廓
*第二个参数：输入匹配模型句柄
*第三个参数：输入复制外形轮廓的金字塔层数
dev_clear_window ()
dev_set_color ('blue')
dev_display (ShapeModelRegion)
stop ()
* step 1: create variables describing  the measurement ROIs and display them
Rect1Row := 244
Rect1Col := 73
DistColRect1Rect2 := 17
Rect2Row := Rect1Row
Rect2Col := Rect1Col + DistColRect1Rect2
RectPhi := rad(90)
RectLength1 := 122
RectLength2 := 2
gen_rectangle2 (MeasureROI1, Rect1Row, Rect1Col, RectPhi, RectLength1, RectLength2)
*创建任意矩形区域
gen_rectangle2 (MeasureROI2, Rect2Row, Rect2Col, RectPhi, RectLength1, RectLength2)


dev_display (ModelImage)


dev_set_color ('yellow')


dev_display (MeasureROI1)


dev_display (MeasureROI2)


* translate measurement ROIs to lie on XLD model (without clipping!)
get_system ('clip_region', OriginalClipRegion)
*根据HALCON系统参数获取关于当前的信息
*函数参数：
*第一个参数：输入需要质疑的参数
*第二个参数：输出系统参数的对应值
set_system ('clip_region', 'false')
*HALCON系统参数的设置
*第一个参数：输入要设置的参数名称
*第二个参数：输入对应参数的值
move_region (MeasureROI1, MeasureROI1Ref, -CenterROIRow, -CenterROIColumn)
*对区域进行水平垂直方向移动
*函数参数：
*第一个参数：输入需要移动的区域
*第二个参数：输出移动后的区域
*第三个参数：y值方向移动距离（-512 <= row <=512）
*第四个参数：x值方向移动距离（-512 <= column <=512）
move_region (MeasureROI2, MeasureROI2Ref, -CenterROIRow, -CenterROIColumn)


set_system ('clip_region', OriginalClipRegion)


DistRect1CenterRow := Rect1Row - CenterROIRow


DistRect1CenterCol := Rect1Col - CenterROIColumn
DistRect2CenterRow := Rect2Row - CenterROIRow
DistRect2CenterCol := Rect2Col - CenterROIColumn
if (USING_TRANSLATE_MEASURE != 0)
    * -> measure objects are created only once in advance and then translated later
    gen_measure_rectangle2 (Rect1Row, Rect1Col, RectPhi, RectLength1, RectLength2, Width, Height, 'bilinear', MeasureHandle1)
    gen_measure_rectangle2 (Rect2Row, Rect2Col, RectPhi, RectLength1, RectLength2, Width, Height, 'bilinear', MeasureHandle2)
endif
stop ()
* step 2: find the objects in another image
read_image (SearchImage, 'razors2')
dev_display (SearchImage)
find_shape_model (SearchImage, ModelID, 0, 0, 0.8, 0, 0.5, 'least_squares', 0, 0.7, RowCheck, ColumnCheck, AngleCheck, Score)
*函数说明：在函数图像中找出一个（不可缩放比例的）最佳匹配轮廓
*函数参数：
*第一个参数Image：输入匹配模型的图像
*第二个参数ModelID：输入模型句柄
*第三个参数AngleStart：输入匹配时的起始角度
*第四个参数AngleExtent：输入匹配时的角度范围
*第五个参数MinScore：输入最小的匹配值（匹配质量），考虑到模板的一半被遮挡，默认为0.5
*第六个参数NumMatches：在图像上找到模板的最大个数，默认1个
*第七个参数MaxOverlap：定义了找到的两个目标区域最多重叠的系数如果MaxOverlap=0,找到的目标区域不能存在重叠，如果MaxOverlap=1，所有找到的目标区域都是要返回。
*第八个参数SubPixel：确定找到的目标是否使用亚像素精度提取，默认值：'least_squares'
*第九个参数NumLevels：搜索时使用的金字塔层数
*第十个参数Greediness：搜索时的"贪婪程度"(0:safe but slow 慢而安全；1：fast but matches may be missed 快而可能匹配失败)默认值为：0.9
*第十一个参数Row：输出目标外形轮廓的y坐标（轮廓中心位置）
*第十二个参数Column：输出目标外形轮廓的x坐标（轮廓中心位置）
*第十三个参数Angle：输出目标物体模型旋转后对应的角度
*第十四个参数ScoreR：输出y值方向的比例大小
*第十五个参数ScoreC：输出x值方向的比例大小
*第十六个参数Score：输出目标物体的匹配（也是大概有多匹配）
if (|Score| > 0)
    for i := 0 to |Score| - 1 by 1
        * step 3: determine the affine transformation
        vector_angle_to_rigid (0, 0, 0, RowCheck[i], ColumnCheck[i], AngleCheck[i], MovementOfObject)
        *函数说明：通过点和角度方面来计算一个仿射变换矩阵
        *函数参数：
        *第一个参数：输入点y值坐标
        *第二个参数：输入点x值坐标
        *第三个参数：输入初始点y值坐标
        *第四个参数：输入初始点x值坐标
        *第五个参数：输入初始点对应的角度（方位）
        *第六个参数：输入变换点的y值坐标
        *第七个参数：输入变换点的x值坐标
        *第八个参数：输入变换点的角度（方位）
        *第九个参数：输出对应的点阵变换矩阵
        affine_trans_contour_xld (ShapeModel, ModelAtNewPosition, MovementOfObject)
        *函数说明：对XLD轮廓进行一个任意二维仿射变换
        *函数参数：
        *第一个参数：输入等高线轮廓
        *第二个参数：输出被变换后的等高线或轮廓
        *第三个参数：输入变换矩阵
        dev_display (ModelAtNewPosition)
        * step 4: measure width and distance of the teeth
        * -> display the moved ROIs
        affine_trans_region (MeasureROI1Ref, MeasureROI1AtNewPosition, MovementOfObject, 'true')
        *函数说明：对区域进行任意的二维变换
        *函数参数：
        *第一个参数：输入需要进行旋转或比例放大的区域
        *第二个参数 ：输出转换后的区域
        *第三个参数：输入转换矩阵
        *第四个参数：转换被当作插入（篡改）使用，默认为："false"
        affine_trans_region (MeasureROI2Ref, MeasureROI2AtNewPosition, MovementOfObject, 'true')
        dev_display (MeasureROI1AtNewPosition)
        dev_display (MeasureROI2AtNewPosition)
        affine_trans_pixel (MovementOfObject, DistRect1CenterRow, DistRect1CenterCol, Rect1RowCheck, Rect1ColCheck)
        *函数说明：对像素坐标轴进行任意的仿射二维变换
        *第一个参数：输入一个二维变换矩阵
        *第二个参数：输入图像点阵的y值坐标
        *第三个参数：输入图像点阵的x值坐标
        *第四个参数：输出转换后的图像点阵的y值坐标
        *第五个参数：输出转换后的图像的x值坐标
        affine_trans_pixel (MovementOfObject, DistRect2CenterRow, DistRect2CenterCol, Rect2RowCheck, Rect2ColCheck)
        if (USING_TRANSLATE_MEASURE != 0)
            * -> translate the already created measure objects
            translate_measure (MeasureHandle1, Rect1RowCheck, Rect1ColCheck)
            *函数说明：转化（解释）一个测量对象，准确的说，我们在一个测量句柄里面的多个测试点时，需要通过该函数来分解多个测试对象，它一般和find_shape_model()匹配函数组合使用，来获取新测试对象的参考点，也就是find_shape_model()对应的Rpw和Column对应数组中的一个值。
            *第一个参数:输入测量句柄
            *第二个参数：新测试对象的y值参考点
            *第三个参数：新测试对象的x值参考点
            translate_measure (MeasureHandle2, Rect2RowCheck, Rect2ColCheck)
            measure_pairs (SearchImage, MeasureHandle1, 2, 25, 'negative', 'all', RowEdge11, ColEdge11, Amp11, RowEdge21, ColEdge21, Amp21, Width1, Distance1)
            measure_pairs (SearchImage, MeasureHandle2, 2, 25, 'negative', 'all', RowEdge12, ColEdge12, Amp12, RowEdge22, ColEdge22, Amp22, Width2, Distance2)
        else
            * -> create new measure objects and destroy them after the measurement
            RectPhiCheck := RectPhi + AngleCheck[i]
            gen_measure_rectangle2 (Rect1RowCheck, Rect1ColCheck, RectPhiCheck, RectLength1, RectLength2, Width, Height, 'bilinear', MeasureHandle1)
            gen_measure_rectangle2 (Rect2RowCheck, Rect2ColCheck, RectPhiCheck, RectLength1, RectLength2, Width, Height, 'bilinear', MeasureHandle2)
            * step 5: perform the measurement
            measure_pairs (SearchImage, MeasureHandle1, 2, 25, 'negative', 'all', RowEdge11, ColEdge11, Amp11, RowEdge21, ColEdge21, Amp21, Width1, Distance1)
            **提取与矩形或环状弧垂直的直线边缘。
            *第一个参数： Image 输入图像
            *第二个参数： MeasureHandle 输入测量句柄
            *第三个参数： RowEdgeFirst 输出匹配边沿起点的y值坐标
            *第四个参数： ColumnEdgeFirst 输出匹配边沿起点的x值坐标
            *第五个参数： AmplitudeFirst 输出匹配边沿起点的幅值
            *第六个参数： RowEdgeSecond 输出匹配边沿终点的y值坐标
            *第七个参数： ColumnEdgeSecond 输出匹配边沿终点的x值坐标
            *第八个参数： AmplitudeSecond 输出匹配边沿终点的幅值
            *第九个参数： IntraDistance  输出匹配起点和终点的距离
            *第十个参数： InterDistance  输出匹配终点到下一匹配起点之间的距离 
            measure_pairs (SearchImage, MeasureHandle2, 2, 25, 'negative', 'all', RowEdge12, ColEdge12, Amp12, RowEdge22, ColEdge22, Amp22, Width2, Distance2)
            close_measure (MeasureHandle1)
            close_measure (MeasureHandle2)
        endif
        * step 6: check for too short or missing teeth
        NumberTeeth1 := |Width1|
        NumberTeeth2 := |Width2|
        dev_set_color ('red')
        if (NumberTeeth1 < 37)
            for j := 0 to NumberTeeth1 - 2 by 1
                if (Distance1[j] > 4.0)
                    RowFault := round(0.5 * (RowEdge11[j + 1] + RowEdge21[j]))
                    ColFault := round(0.5 * (ColEdge11[j + 1] + ColEdge21[j]))
                    disp_rectangle2 (WindowHandle, RowFault, ColFault, 0, 4, 4)
                    dev_open_window (0, Width + 20, 80, 80, 'black', WindowHandleZoom)
                    dev_set_part (RowFault - 10, ColFault - 10, RowFault + 10, ColFault + 10)
                    dev_display (SearchImage)
                    disp_rectangle2 (WindowHandleZoom, RowFault, ColFault, 0, 4, 4)
                    stop ()
                    dev_close_window ()
                    dev_set_part (0, 0, Height - 1, Width - 1)
                endif
            endfor
        endif
        if (NumberTeeth2 < 37)
            for j := 0 to NumberTeeth2 - 2 by 1
                if (Distance2[j] > 4.0)
                    RowFault := round(0.5 * (RowEdge12[j + 1] + RowEdge22[j]))
                    ColFault := round(0.5 * (ColEdge12[j + 1] + ColEdge22[j]))
                    disp_rectangle2 (WindowHandle, RowFault, ColFault, 0, 4, 4)
                    dev_open_window (0, Width + 20, 80, 80, 'black', WindowHandleZoom)
                    dev_set_part (RowFault - 10, ColFault - 10, RowFault + 10, ColFault + 10)
                    dev_display (SearchImage)
                    disp_rectangle2 (WindowHandleZoom, RowFault, ColFault, 0, 4, 4)
                    stop ()
                    dev_close_window ()
                    dev_set_part (0, 0, Height - 1, Width - 1)
                endif
            endfor
        endif
        dev_set_color ('yellow')
        stop ()
    endfor
endif
* -------------------  end of the application  -----------------
* clean up
if (USING_TRANSLATE_MEASURE != 0)
    close_measure (MeasureHandle1)
    close_measure (MeasureHandle2)
endif
dev_update_window ('on')
clear_shape_model (ModelID)