Halcon五种清晰度评价函数实现与自动对焦峰值定位

简介：面向工业视觉与机器视觉开发者的图像清晰度评估资料，围绕相机自动对焦与图像质量量化展开，适合已掌握Halcon基础算子、希望把对焦评价用到实际工作的中级读者。压缩包内只有1个docx文档，约22KB，用图文与代码混排的方式讲解方差法、拉普拉斯能量函数法、能量梯度函数法和Brenner函数法的原理，以及这些方法如何组合算子。文档给出evaluate_definition自定义评价函数的完整实现，逐段说明均值化、拉普拉斯滤波、区域裁剪与灰度统计等算子的调用逻辑，并配合pcb_focus系列121张不同焦距图像的遍历脚本，用直方图归一化呈现评价值曲线，定位峰值对应的最清晰帧；代码注释清晰，可直接对照复现。文中还说明了图像滤波、增强与分割在清晰度评估前如何预处理图像。目前已有6172人学习，可作为自动对焦与图像预处理环节的参考范例。

1. 从一张跑焦的 PCB 图说起：清晰度评价函数值不值得单独拆一遍

用 Halcon 做对焦，最难受的不是写不出评价函数，而是明明写出来了，跑完 121 张图发现峰值落在第 40 张，可人眼看上去第 60 张才最清晰。这个落差，我在啃 Halcon 对焦 最清晰 这条链路时踩过不止一次。手上是一批远心镜头拍的 PCB 序列图，焦距从虚到实再到虚，共 121 张，同一工位、同一套光源，唯一变量就是镜头和 CCD 之间的距离。要回答的问题很具体：怎么用一段能直接跑的代码，把这一串图的清晰度量化成一条曲线，并且让曲线的峰值和肉眼判断对得上。

这份资源就是把这件事拆开的一组 Halcon 算子——五种清晰度评价函数的完整实现，加一个扫焦主程序。它不解决对焦马达怎么驱动，只解决“怎么判断这一帧够不够清晰”这个前置问题。适合正在做工业相机选型、变焦镜头人工调焦、或者想给视觉测量系统加一道图像质量门禁的人。如果你只是想知道 Halcon 有没有现成算子，那没有，得自己写，这正是它值得单独拆一遍的原因。

2. 五种评价函数到底在算什么：从一阶差分到二阶能量

自动对焦的本质是把“清晰”这个主观感受变成一个可以求极值的标量。镜头离像面越远，高频细节衰减越厉害，图像在空间域上表现为相邻像素灰度差变小、边缘变钝。所有评价函数都在抓这个变化，区别只在于用一阶差分还是二阶差分、统计全图还是只统计边缘。先把这层数学底子捋清，后面调参数才知道自己在动什么。

2.1 方差法：整幅图的灰度离散度

方差法的假设很朴素：清晰图像的灰度分布更“散”，模糊图像因为邻域平均效应，灰度会向均值聚拢，方差自然变小。实现上是三步——求全图均值、逐像素减均值、平方后取平均。

对一幅灰度图 $I$，评价值就是

$$V = \frac{1}{W \cdot H}\sum_{x,y}\left(I(x,y) - \bar{I}\right)^2$$

Halcon 里的region_to_mean把整幅图替换成均值图像，sub_image做差，mult_image自乘，最后intensity取均值。注意sub_image和mult_image的最后一个参数是偏移量，这里填 0，因为平方后不需要再加回什么。

这个方法最大的问题是把“对比度”和“清晰度”混为一谈。一块纯白背景加一条黑边的图，方差极大，但它可能完全没对上焦；反过来，一张整体低对比度但细节锐利的图，方差反而不高。工业现场光照一波动，方差曲线就跟着漂移。我一般只在两种情况下用它：一是作为其他方法的对照基线，二是图像内容极其单一、只关心全局离散度的粗筛阶段。

2.2 拉普拉斯能量：二阶算子加邻域加权

拉普拉斯是二阶微分算子，对灰度变化的“变化率”敏感，也就是对边缘和细节敏感，对缓慢过渡的平坦区域几乎无响应。这正好是清晰度评价想要的——平坦区域本来就不该贡献分数。

Halcon 的laplace算子签名是laplace(Image : ImageLaplace : ResultType, MaskSize, FilterType : )。ResultType取'signed'时保留正负号，取'absolute'时取绝对值；MaskSize只能取 3、5、7；FilterType在 3×3 下可选'n_4'（四邻域，只含上下左右）和'n_8'（八邻域，含对角）。资源里的写法是同时算n_4和n_8两版，然后按3×L4 + L8加权组合再平方求均值。

为什么要加权而不是简单相加？四邻域算子对水平垂直边缘响应强，八邻域补上了对角方向，但八邻域的核里中心系数是 -8，边缘响应幅度更大，直接相加会让对角纹理主导评分。用 3 倍权重抬四邻域、1 倍权重收八邻域，是一个经验配比，实测在 PCB 这种以正交走线为主的图上比较稳。换到织物、铸造件这类各向纹理，这个配比就得重调。

二阶算子对噪声的放大是平方级的。原图有一点传感器噪声，拉普拉斯之后会被放大成明显的孤立亮点，平方求和后直接污染均值。所以这条分支前面如果没做滤波，评价值会在噪声大的帧上虚高，峰值位置乱跳。这也是我后面要单独讲避坑的原因之一。

2.3 能量梯度与 Brenner：一阶差分的两种裁剪方式

能量梯度函数用的是灰度梯度平方和，水平和垂直两个方向都算：

$$V = \frac{1}{N}\sum_{x,y}\left[\left(I(x+1,y)-I(x,y)\right)^2 + \left(I(x,y+1)-I(x,y)\right)^2\right]$$

实现上靠crop_part把图裁成四份互相错开一个像素的子图，两两相减再平方相加。crop_part的参数顺序是Row, Column, Width, Height，这一点极其容易写反，写反的直接后果是尺寸对不上、sub_image报错，或者更隐蔽地裁到图像外面去，Halcon 直接抛“控制参数值错误”。

Brenner 函数本质上是一阶差分的简化版，只算水平方向，而且步长取 2 而不是 1：

$$V = \frac{1}{N}\sum_{x,y}\left(I(x+2,y)-I(x,y)\right)^2$$

步长 2 的用意是跳过相邻像素间那些由噪声引起的微小波动，只抓真正有跨度的灰度跳变。代价是它完全无视垂直方向的边缘——一张只有横向走线的 PCB 图，Brenner 表现很好；换成竖排文字或者垂直刻线，曲线会变得很平，峰值定位精度掉一个档次。现场用之前一定要看一眼被测物的纹理主方向。

2.4 Tenegrad：Sobel 幅值加阈值门限

Tenegrad 走的是另一条路：先用 Sobel 算梯度幅值，再设一个阈值只保留强边缘，最后对保留下来的梯度平方求和。Halcon 里sobel_amp(Image, EdgeAmplitude, 'sum_sqrt', 3)的第三个参数是梯度合成方式，'sum_sqrt'就是 $\sqrt{G_x^2 + G_y^2}$，也就是标准幅值；另外还有'sum_abs'、'x'、'y'等选项。

加阈值这一步是这个方法的核心差异点。模糊图像的梯度幅值普遍偏低，如果一视同仁地累加，弱边缘的噪声也会计入；卡一个门限之后，只有明确是边缘的像素参与评分，抗噪能力明显强于拉普拉斯。代价是阈值本身成了需要标定的参数——资源里写死 11.8，这个数在特定光源和曝光下能跑，换个工位基本要重调。

region_to_bin那一步是把阈值分割出的区域转成二值图当掩膜，再和梯度幅值相乘，等于把非边缘区域的梯度清零。这个套路在 Halcon 里很常见，比用reduce_domain更直接，因为掩膜是图像不是区域，后续mult_image不用做类型转换。

五种方法放一起对比，选型时我心里大概有这么一张表：

3. 把 evaluate_definition 写成可复用的算子：骨架、归一化与五个分支

资源里最值得抄的不是主程序，是那个自定义算子evaluate_definition。它把五种算法收进一个Method字符串开关，对外只暴露“输入图像 + 方法名 → 输出一个标量”，调用侧完全不用关心内部用了哪个算子。这种封装方式在需要横向比对多种评价函数时特别省事，改一个字符串就能换算法，扫焦主程序一行不用动。

3.1 算子签名与 scale_image_max 的位置

先看签名：

* Method：算法名，字符串，可选 'Deviation' / 'laplace' / 'energy' / 'Brenner' / 'Tenegrad' * Value ：输出标量，越大表示越清晰，量纲随算法变化，只用于同序列内比较 evaluate_definition (Image : : Method : Value)

第一个位置是输入图像，中间是控制参数Method，最后是输出参数Value。注意这里没有输出图像对象，冒号后面直接跟控制参数，所以调用时是evaluate_definition (Image, 'Brenner', Value)，三个实参。

函数体第一行是scale_image_max (Image, Image)，把图像灰度线性拉伸到 0~255 满量程。放第一行的理由很实在：不同帧之间曝光可能有微小抖动，如果不先统一量纲，方差法算出来的值会同时受“清晰度”和“整体亮度”两个因素影响，曲线会出现与焦距无关的起伏。这一步在函数内部做，等于给所有分支加了个统一的前置条件。

但这一步也是后面要重点讲的坑——它对每一帧独立做拉伸，拉伸系数逐帧不同，跨帧的数值可比性其实被破坏了。稳妥做法是把拉伸系数固定成序列第一帧算出来的那一组，后面所有帧复用。资源里的写法是逐帧拉伸，在光照极稳的实验环境下影响不大，挪到产线上就得改。

3.2 方差法与拉普拉斯分支的实现细节

方差法分支：

if (Method = 'Deviation') * 求全图均值图像，用于后续减均值 region_to_mean (Image, Image, ImageMean) * 减法和平方必须在 real 类型下做，byte 会截断负值和溢出 convert_image_type (ImageMean, ImageMean, 'real') convert_image_type (Image, Image, 'real') sub_image (Image, ImageMean, ImageSub, 1, 0) mult_image (ImageSub, ImageSub, ImageResult, 1, 0) * intensity 的第二个输出是标准差，这里不用，用均值当评价值 intensity (ImageResult, ImageResult, Value, Deviation)

convert_image_type那两行不能省。原始图是 byte，sub_image遇到负值会被截断到 0，平方之后偏差全部变成正的，方差被系统性低估。转成 real 之后负值能保留，平方后才还原成真正的平方差。sub_image和mult_image的最后两个参数是“乘数”和“偏移”，标准用法是 1 和 0，只有在需要做线性变换时才改。

intensity的签名容易被误解：intensity(Regions : : Image : Mean, Deviation)。第一个位置要的是区域，第二个位置才是图像。资源里两处都传了图像，在 Halcon 里这是合法的——传图像等价于传它的整个 domain，效果就是对全图统计。但如果哪天想只统计 ROI，就得把第一个参数换成真正的 region，这个灵活性留着有用。

拉普拉斯分支：

elseif (Method = 'laplace') * 分别取四邻域和八邻域，signed 保留正负号，mask 尺寸 3 laplace (Image, ImageLaplace4, 'signed', 3, 'n_4') laplace (Image, ImageLaplace8, 'signed', 3, 'n_8') * 组合成 3*L4 + L8：先 2*L4，再 +L4 得 3*L4，再 +L8 add_image (ImageLaplace4, ImageLaplace4, ImageResult1, 1, 0) add_image (ImageLaplace4, ImageResult1, ImageResult1, 1, 0) add_image (ImageLaplace8, ImageResult1, ImageResult1, 1, 0) * 平方后取均值，得到拉普拉斯能量 mult_image (ImageResult1, ImageResult1, ImageResult, 1, 0) intensity (ImageResult, ImageResult, Value, Deviation)

这里add_image连用三次完成加权，写法有点绕但省了一个乘法算子。第一次add_image(L4, L4, R1)得到 2×L4；第二次add_image(L4, R1, R1)得 3×L4；第三次加 L8 得 3×L4 + L8。每一步都在 int 类型上做，3 倍放大后如果原图是 byte 且边缘陡峭，累加有可能溢出 int16 的范围，实际跑的时候如果发现某些帧的评价值异常为负或跳变，先把中间结果转 real 再说。

3.3 能量梯度、Brenner、Tenegrad 分支与参数

能量梯度分支：

elseif (Method = 'energy') * 四份子图互相错开一个像素：00 基准，01 右移一列，10 下移一行 crop_part (Image, ImagePart00, 0, 0, Width-1, Height-1) crop_part (Image, ImagePart01, 0, 1, Width-1, Height-1) crop_part (Image, ImagePart10, 1, 0, Width-1, Height-1) convert_image_type (ImagePart00, ImagePart00, 'real') convert_image_type (ImagePart10, ImagePart10, 'real') convert_image_type (ImagePart01, ImagePart01, 'real') * 水平方向差分平方 sub_image (ImagePart10, ImagePart00, ImageSub1, 1, 0) mult_image (ImageSub1, ImageSub1, ImageResult1, 1, 0) * 垂直方向差分平方 sub_image (ImagePart01, ImagePart00, ImageSub2, 1, 0) mult_image (ImageSub2, ImageSub2, ImageResult2, 1, 0) add_image (ImageResult1, ImageResult2, ImageResult, 1, 0) intensity (ImageResult, ImageResult, Value, Deviation)

crop_part的四个数值参数是Row, Column, Width, Height，不是宽高在前。ImagePart10里那行crop_part (Image, ImagePart10, 1, 0, Width-1, Height-1)是行偏移 1、列偏移 0，表示向下移一行；ImagePart01是行偏移 0、列偏移 1，表示向右移一列。裁出来的三份尺寸都是(Width-1) × (Height-1)，所以能逐像素对齐相减，不会出现尺寸不匹配。

Brenner 分支的正确写法：

elseif (Method = 'Brenner') * 列方向偏移 2，宽度减 2，保证两份子图尺寸一致且不越界 crop_part (Image, ImagePart00, 0, 0, Width-2, Height) convert_image_type (ImagePart00, ImagePart00, 'real') crop_part (Image, ImagePart20, 0, 2, Width-2, Height) convert_image_type (ImagePart20, ImagePart20, 'real') sub_image (ImagePart20, ImagePart00, ImageSub, 1, 0) mult_image (ImageSub, ImageSub, ImageResult, 1, 0) intensity (ImageResult, ImageResult, Value, Deviation)

注意这里和资源原文的差异。原文写的是crop_part (Image, ImagePart00, 0, 0, Width, Height-2)和crop_part (Image, ImagePart20, 2, 0, Width, Height-2)，把偏移量放在了行参数上，而且第二份从第 2 行开始、高Height-2，加起来正好超出图像下边界一行，运行时会报控制参数越界。Brenner 的定义是列方向跨两个像素，所以偏移必须落在 Column 位置上，同时宽度减 2。这个修正后面还会在避坑章展开。

Tenegrad 分支：

elseif (Method = 'Tenegrad') * Sobel 梯度幅值，3×3 核，sum_sqrt 即 sqrt(Gx^2+Gy^2) sobel_amp (Image, EdgeAmplitude, 'sum_sqrt', 3) * 门限 11.8 是经验值，换光源/曝光必须重标 threshold (EdgeAmplitude, Region1, 11.8, 255) region_to_bin (Region1, BinImage, 1, 0, Width, Height) * 掩膜掉弱梯度，只保留强边缘区域 mult_image (EdgeAmplitude, BinImage, ImageResult4, 1, 0) mult_image (ImageResult4, ImageResult4, ImageResult, 1, 0) intensity (ImageResult, ImageResult, Value, Deviation)

region_to_bin的参数是Region, BinImage, ForegroundGray, BackgroundGray, Width, Height，前景填 1 背景填 0，宽高要和原图一致，否则mult_image尺寸不匹配。min_max_gray那两行在原文里算了Min、Max、Range但没参与后续计算，属于调试残留，可以删，也可以留着当观察窗口——如果Max长期贴着实测噪声底，说明 11.8 这个门限设高了，边缘被大面积滤掉，评分会失真。

3.4 返回值的类型统一

五个分支最后都落到intensity(...)取均值，输出都是单个实数，量纲各不相同：方差法在几百量级，拉普拉斯能量可能上万，Brenner 因为步长 2 通常更大。这意味着评价值只能在同一算法的同一序列内比较，跨算法比绝对值毫无意义。所以主程序里那步归一化不是可选项，是必需品。

末尾要留一个兜底分支，Method拼错时不至于让Value处于未定义状态：

else * 未知方法名，返回 0 并让调用侧能看出异常 Value := 0.0 endif return ()

return ()在 Halcon 自定义算子末尾必须写，哪怕没有输出图像。少了这行，算子编译能过但运行时报错。

4. 扫焦主程序：121 张图怎么变成一条能看的清晰度曲线

有了算子，剩下的事就是驱动一整个焦距序列跑一遍，把评价值收集起来，找出峰值对应的那一帧。逻辑很简单，坑都在细节里——文件编号格式化、tuple 拼接、索引偏移、可视化归一化，每一处都能让结果差出一张图。

4.1 文件命名与读图循环：Index$'03d' 的格式化

序列图的命名是pcb_focus_telecentric_001到pcb_focus_telecentric_121，三位补零。Halcon 里拼接路径靠 tuple 的$格式化：

* 先读一张拿到尺寸和窗口，同时确定 ROI 基准 read_image (Image, 'pcb_focus/pcb_focus_telecentric_106') dev_update_off () dev_close_window () dev_open_window_fit_image (Image, 0, 0, 752, 480, WindowHandle) set_display_font (WindowHandle, 16, 'mono', 'true', 'false') dev_set_color ('lime green') dev_set_line_width (3) Ret := [] get_image_size (Image, Width, Height) for Index := 1 to 121 by 1 * '03d' 表示十进制整数、最小宽度 3、不足补前导零 read_image (Image, 'pcb_focus/pcb_focus_telecentric_' + Index$'03d') * 换成 'Deviation' / 'laplace' / 'energy' / 'Tenegrad' 即可横向比对 evaluate_definition (Image, 'Brenner', Value) dev_display (Image) * tuple 追加，Ret 长度随循环增长 Ret := [Ret, Value] endfor

Index$'03d'是 Halcon 的 tuple 格式化语法，$后面跟 C 风格格式串。'03d'拆开看：0是补零标志，3是最小字段宽度，d是十进制整数。如果文件名是四位编号就写'04d'，没有补零就直接Index拼字符串，但那样排序会乱——10会排在2前面，这是血泪经验。

Ret := []初始化空 tuple，循环里Ret := [Ret, Value]每次追加一个元素。Halcon 的 tuple 是值语义，这种写法在 121 次的量级上完全没问题，但如果序列上千帧，预分配再按下标赋值会快不少。

循环里那句dev_display (Image)在dev_update_off ()之后其实不会刷新窗口。想看动画效果得在循环内临时dev_update_window ('on')，或者干脆把这句删掉，跑完再显示结果——121 帧逐个刷屏除了拖慢速度没有别的用处。

4.2 归一化与峰值定位：max、find 的返回值

跑完循环，Ret是一个长度 121 的 tuple，每个元素对应一帧的评价值。接下来两件事：归一化到统一量纲，找最大值的位置。

* 序列内极值，用于线性归一化到 0~100 VMax := max (Ret) VMin := min (Ret) * 注意分母：所有帧评价值完全相同时 VMax-VMin 为 0，会除零 if (VMax - VMin < 1e-9) GRet := gen_tuple_const (|Ret|, 0) else GRet := 100 * (Ret - VMin) / (VMax - VMin) endif * find 返回所有等于最大值的下标，索引从 0 开始 MaxIdx := find (Ret, VMax) * 取第一个命中的下标，转成 1-based 的文件编号 qxd := MaxIdx[0] + 1 read_image (GoodImage, 'pcb_focus/pcb_focus_telecentric_' + qxd$'03d')

max和min直接对 tuple 操作，返回标量。find(Ret, VMax)返回的是 tuple 里所有等于VMax的元素下标，类型还是 tuple，哪怕只有一个命中。所以取MaxIdx[0]才是标量。

索引偏移这一步是整段代码里最容易翻车的地方。Ret[0]对应的是Index = 1那一帧，所以文件编号永远是下标加 1。资源原文直接拿qxd去拼文件名，等于把峰值往前挪了一张——如果峰值在 106，实际读到的是 105。121 张图的序列里差一张，肉眼未必看得出来，但对焦精度要求高的场合这就是系统性偏差。修正方式就是上面那行MaxIdx[0] + 1。

gen_tuple_const (|Ret|, 0)里的|Ret|是取 tuple 长度，用来生成等长的全零 tuple，处理除零的退化情况。实际产线上如果真出现所有帧评价值完全一致，说明镜头根本没动或者图像全黑，这时候该报警而不是继续算。

4.3 曲线可视化：gen_region_histo 与它不擅长的地方

gen_region_histo能把一个数值序列画成柱状区域，签名是gen_region_histo(: Region : Histogram, Row, Column, Scale : )。Row、Column是柱状图的左上角原点，Scale是纵向缩放系数。

* 用归一化后的 GRet 画柱状图，Scale=1 时柱高就是 0~100 gen_region_histo (Region, GRet, 255, 255, 1) dev_display (GoodImage) dev_display (Region)

资源原文这里传的是未归一化的Ret。Brenner 的评价值动辄几万，Scale = 1时柱子会撑到窗口外，画面上根本看不到完整形状；就算勉强显示，柱子高度也被截断，峰值和次峰值的差异完全看不出来。前面辛苦算的GRet结果一行没用上，这是典型的“算了不用”。

Row = 255是柱状图基线的纵坐标，意思是让柱子从第 255 行往下长（Halcon 图像坐标向下为正，所以数值越大柱子越长，视觉上是向下延伸）。Column = 255是横向起始位置，配合 121 根柱子、每根宽度默认 1 像素，整体宽度 121，放在 752 宽的窗口里偏左。想让曲线居中，把Column改成(Width - 121) / 2就行。

gen_region_histo的局限在于它只能画柱状区域，没法加坐标轴、刻度、标注。要做一张能给同事看的对比图，我一般会把GRet用write_tuple落成文件，拿到外部工具里画折线——多条曲线叠在一张图上，哪个方法单峰性好、哪个方法有次峰，一眼就分得出。

* 把五组评价值分别落盘，方便外部做多曲线对比 write_tuple (GRet, 'focus_curve_Brenner.txt') * 换成其他 Method 再跑一轮，文件名跟着改

4.4 把不同 Method 的结果放到一起比

单跑一种方法只能知道峰值在哪，要判断哪种方法更靠谱，得把五条曲线放在同一坐标系里看。判断标准有三条：单峰性（除了主峰还有没有明显次峰）、半宽（峰值附近值下降的速度，越窄定位越精确）、单调性（峰值两侧应该单调下降，出现平台或抖动说明这个方法对这个场景不敏感）。

我的做法是外层再套一层方法名循环，把五组GRet收集到二维结构里，或者干脆分五次跑、每次改文件名。后者笨但可靠，不容易在 tuple 嵌套上出错。

Methods := ['Deviation', 'laplace', 'energy', 'Brenner', 'Tenegrad'] for M := 0 to |Methods| - 1 by 1 Ret := [] for Index := 1 to 121 by 1 read_image (Image, 'pcb_focus/pcb_focus_telecentric_' + Index$'03d') evaluate_definition (Image, Methods[M], Value) Ret := [Ret, Value] endfor VMax := max (Ret) VMin := min (Ret) GRet := 100 * (Ret - VMin) / (VMax - VMin) write_tuple (GRet, 'focus_curve_' + Methods[M] + '.txt') endfor

外层循环用|Methods| - 1是因为 Halcon tuple 下标从 0 开始。Methods[M]取出字符串传给算子，整个内部逻辑一行不用改。跑完得到五个文本文件，导入表格软件画图，峰值位置和曲线形状的差异就很直观了。

5. 避坑与排查：五个让峰值偏移的坑

这套代码跑通不难，跑准很难。下面五条是我在实际调试中反复撞上的，每一条都足以让峰值位置偏移一到数张，或者让评价值失去可比性。按“现象 → 原因 → 解决”的顺序记下来，下次遇到同类症状可以直接对号。

5.1 现象：曲线整体起伏很小，峰值不明显

原因：evaluate_definition内部第一行的scale_image_max (Image, Image)对每一帧独立做了对比度拉伸。模糊帧的灰度范围窄，拉伸系数大；清晰帧范围宽，拉伸系数小。结果是每帧都被强行拉到 0~255 满量程，帧与帧之间的灰度差异被抹平，清晰度信号跟着被压缩。序列越长、光照越不稳，这个效应越明显。

解决：把拉伸系数固定成序列基准帧算出来的那一组，后续所有帧复用同一组参数。做法是先对第一帧scale_image_max并记录Min、Mult，或者干脆不做拉伸，改为在采集端锁定曝光和增益。实验环境下逐帧拉伸影响不大，产线上必须改成固定系数。

5.2 现象：Brenner 分支一跑就报“控制参数值错误”

原因：crop_part的参数顺序是Row, Column, Width, Height，资源原文把列偏移写到了行参数上，写成crop_part (Image, ImagePart20, 2, 0, Width, Height-2)，同时第二份子图起始行 2 加高度Height-2正好等于Height + 0，刚好越界一行。Halcon 对crop_part的越界检查是严格的，不会自动裁剪。

解决：列方向偏移的语义要落到 Column 上，同时宽度减 2 保证两份对齐：crop_part (Image, ImagePart00, 0, 0, Width-2, Height)配crop_part (Image, ImagePart20, 0, 2, Width-2, Height)。改完之后两份尺寸都是(Width-2) × Height，sub_image能正常对齐。

5.3 现象：找到的“最清晰帧”看上去总是比峰值模糊一点点

原因：find (Ret, max(Ret))返回的下标是从 0 开始的，而文件名编号是从 001 开始的。直接拿返回值拼文件名，等于整体往前偏移一张。峰值附近曲线平缓的时候，差一张在数值上只差千分之几，肉眼却看得出来。

解决：拼文件名之前统一加 1。写成qxd := find (Ret, VMax)[0] + 1，或者干脆在循环里就用 0-based 的文件名，从000开始编号，让下标和文件名对齐。后者更彻底，但要求采集端配合改命名规则。

5.4 现象：Tenegrad 在换了一批工件之后评价值集体塌陷

原因：threshold (EdgeAmplitude, Region1, 11.8, 255)里的 11.8 是硬编码门限。这个数是针对某一组光源强度、曝光时间和工件表面反射率标出来的。换工件之后整体梯度幅值下降，大量真实边缘卡在 11.8 以下被滤掉，参与评分的只剩零星几个强反射点，评价值失去意义。

解决：门限改成自适应。用min_max_gray先统计梯度幅值的分布，取Max的一个比例作为门限；或者用固定分位数，比如只保留梯度幅值前 20% 的像素。自适应门限的代价是每帧计算量增加，但换来的是跨批次的可比性。

5.5 现象：循环跑完窗口一片空白，或者只显示最后一帧

原因：dev_update_off ()关闭了窗口刷新，之后循环里的dev_display只是在缓冲区里改内容，不会真正重绘。等循环结束，窗口停在哪一帧取决于最后一次刷新时机，经常是空白或者中间某一帧。

解决：调试阶段在循环体内加dev_update_window ('on')，或者用wait_seconds (0.05)强制刷新。正式跑批的时候反过来，把dev_display从循环里拿出来，只在循环结束后显示峰值帧和曲线，速度能快好几倍。这个开关不是玄学，就是刷新策略的问题，搞清楚了就不会再被它耽误时间。

6. 接到真实对焦流程：ROI、粗到精搜索与一个收敛判据

实验室里跑 121 张图，跑多久都无所谓；接到产线上，节拍是以毫秒算的。这时候全图计算清晰度就是浪费——PCB 板上有大片焊盘和丝印，真正能反映对焦状态的是走线密集区。我的做法是先框一个固定 ROI，把评价值限制在有纹理的区域，同时把计算量降一个量级。

* 固定 ROI：只覆盖走线密集的中部区域，坐标按实际视野标定 gen_rectangle1 (ROI, 120, 160, 360, 560) * 粗扫：步长 4，先锁定大概位置，避免全程精扫 BestValue := -1.0 BestIndex := -1 for Index := 1 to 121 by 4 read_image (Image, 'pcb_focus/pcb_focus_telecentric_' + Index$'03d') reduce_domain (Image, ROI, ImageROI) evaluate_definition (ImageROI, 'Tenegrad', Value) if (Value > BestValue) BestValue := Value BestIndex := Index endif endfor * 精扫：在粗扫结果 ±4 帧范围内逐帧比对 for Index := BestIndex - 4 to BestIndex + 4 by 1 if (Index < 1 or Index > 121) continue endif read_image (Image, 'pcb_focus/pcb_focus_telecentric_' + Index$'03d') reduce_domain (Image, ROI, ImageROI) evaluate_definition (ImageROI, 'Tenegrad', Value) if (Value > BestValue) BestValue := Value BestIndex := Index endif endfor

gen_rectangle1 (ROI, Row1, Column1, Row2, Column2)是四个坐标边界，不是中心加宽高，标定的时候别看错。reduce_domain把 ROI 之外的部分在 domain 层面剔除，后续所有算子只在这个 domain 内计算——注意get_image_size返回的还是原图尺寸，crop_part也仍然按原图坐标裁，所以 ROI 边缘几行几列在差分时会有跨界，实际使用中把 ROI 往内缩两三个像素就避开了。

粗到精这个套路能成立的前提是评价函数在峰值附近足够平滑，粗扫步长 4 不会直接跨过主峰。如果被测物的景深极浅、清晰区间只有两三帧，步长就得缩到 2。反过来，景深大、曲线平缓的场景，步长可以放大到 8，粗扫帧数从 121 降到 16，节拍立刻下来。

收敛判据我一般用两个条件并联：一是精扫区间的首尾帧评价值都低于区间最大值的一个比例（比如 95%），说明峰值确实被包在区间内；二是粗扫得到的最大值和次大值的比值超过 1.1，说明峰值足够突出，不是噪声顶出来的假峰。两个条件有一个不满足，就把搜索区间往外扩，扩到边界还不行就直接报错，让上位机重新走一遍全程扫描，别硬着头皮往下走。

不同算法在真实产线上的表现差异，比实验室里大得多。同一批工件，Brenner 在恒温恒湿的台面上跑得很好，搬到有振动的机台上就抖得厉害，因为只算水平差分，垂直方向的机械抖动它完全看不见。Tenegrad 抗振好一些，但门限得随光源老化周期性重标。我给一个工位定算法，从来不是选“理论上最好”的那个，而是把五种都跑一遍，看哪种在连续 8 小时的曲线漂移最小。

还有一个容易被忽略的点：评价值的绝对大小没有意义，只有同一序列内的相对关系有意义。所以别把某个阈值写死在判断逻辑里，比如“Value > 5000 就算对焦完成”。换个镜头、换个光源、甚至换个季节环境温度变化导致镜头热胀，这个数就全变了。正确做法是每次上电先跑一遍小范围扫描，拿到本批次的VMax和VMin，再用归一化后的 90% 作为判定线。

从那以后我每接一个新的对焦工位，都会先把整段焦距序列扫一遍，把五种方法的归一化曲线落到一张图上比对，再决定用哪个 Method、门限卡在哪个分位数、粗扫步长取多少。这个前置动作花不了半小时，但能省掉后面几天的反复返工。希望帮到你。

本文还有配套的精品资源，点击获取