Halcon局部阈值分割dyn_threshold：原理、参数调试与缺陷检测实战

1. 从一次失败的分割说起

三年前我接过一个光伏板表面缺陷检测的小项目，甲方要求找出电池片上指甲盖大小的隐裂。第一批图用threshold跑下来，效果惨不忍睹——光照从图片左边到右边有一个明显的渐变，固定阈值把左边一半硅片全切成了“缺陷”，而真正的手指印、隐裂却因为局部对比度不足被漏掉了。

那是我第一次认真去翻Halcon的dyn_threshold文档。当时只知道它比threshold“聪明”，能跟随背景亮度变化自动调整分割标准，但真正理解它的原理，还是被实际数据教育了一轮之后。

如果你也在做工业视觉、缺陷检测，或者被光照不均、背景渐变、表面反光这类问题折磨过，这篇文章就是为你写的。我会把dyn_threshold的算法逻辑拆开讲透，配合实操代码和调试经验，尽量让你看完就能直接上手用，少走我当年踩过的那堆坑。

2. 为什么固定阈值不够用，dyn_threshold是什么

2.1 固定阈值是“一锤子买卖”，局部阈值是“随行就市”

理解dyn_threshold之前，你得先知道它解决的问题是什么。

threshold算子是设定一个全局灰度范围，比如灰度在100到255之间的都算目标。这在灰度分布稳定、光照均匀的图上是没问题的，类似于用一把固定刻度的尺子去量所有零件。但实际产线上的图很少这么理想：光源角度稍微偏一点、相机视野边缘有暗角、工件表面本身有弧度造成反光不均，整张图的背景灰度可能从一端的150渐变到另一端的80。这时候一个固定阈值就会出错——按150切，暗处的真目标被淹掉；按80切，亮处背景被误判成目标。

dyn_threshold的思路完全不一样：它不为整张图设定一个统一的灰度值，而是为每个像素点“单独划线”。这个划线依据是该像素周围邻域的灰度统计结果，说白了就是“跟随性强”。

2.2 dyn_threshold的数学本质：两幅图的逐像素比较

dyn_threshold的操作对象不是一张图，而是两张图：

• 原始图像（就是你拍的那张）；
• 阈值图像（通常是原始图像经过平滑/均值/中值滤波后的结果）。

算子执行的是逐像素比较：如果原始图像中某个像素的灰度值明显大于（或小于）阈值图像对应位置的灰度值，就把它划进目标区域。这个“明显”的程度由参数Offset控制。

为什么要这么做？这里的关键假设是：背景的灰度变化是缓慢的、低频的，比如光照渐变、表面起伏、背景纹理；而目标的灰度变化是尖锐的、局部的，比如缺陷、划痕、字符边缘。用滤波得到的阈值图像相当于“背景估计量”——它把快速变化的目标抹掉了，留下平滑的背景趋势。然后用原图减去背景估计，剩下的差值就是“相对背景的偏离程度”。超过Offset的偏离像素，就判定为目标。

它和Canny边缘检测在哲学上有些相似，但侧重点更偏区域分割而非纯边缘提取，而且它天然把光照不均这个干扰给摆脱掉了。

2.3 LightDark参数到底在表达什么

Halcon的dyn_threshold签名是：

dyn_threshold(OrigImage, ThresholdImage, Region, Offset, LightDark)

前两个是输入图，第三个是输出区域，Offset是灰度偏移量，最后一个LightDark很关键，它决定你要从哪种对比关系中提取目标：

• 'dark'：提取比背景暗的区域，即原图灰度比阈值图灰度低Offset以上的像素；
• 'light'：提取比背景亮的区域，即原图灰度比阈值图灰度高Offset以上的像素；
• 'equal'：提取和背景基本一致的像素，即两者灰度差绝对值小于Offset的区域；
• 'not_equal'：和前一个相反，差异绝对值大于Offset就选中。

我一开始总把LightDark和“提取亮目标还是暗目标”搞混，实际上它描述的是“原图和滤波图之间的灰度关系”，不是“目标在整张图中亮还是暗”。不过大多数场景下，亮目标对应'light'，暗缺陷对应'dark'，直观理解也没毛病。

• 'dark'模式，像素判定条件：OrigImage - ThresholdImage <= -Offset
• 'light'模式，判定条件：OrigImage - ThresholdImage >= Offset
• 'not_equal'是两条条件的并集。

明白这个之后，很多莫名其妙的输出就能解释了——比如你明明想找暗缺陷，结果选错模式输出一大片亮噪点。

3. dyn_threshold的3个核心参数，调试顺序比调数值更重要

3.1 Offset：灵敏度旋钮，配噪点与漏检的平衡

Offset是一个非负整数，灰度单位。它的核心作用是压制滤波后残余的微小波动，避免把噪声选进来。数值越大，提取条件越严格，目标区域越小、越干净，但也越容易漏掉对比度低的真缺陷；数值越小，提取的条件越宽松，区域越碎片化、噪点越多。

实操中我习惯把Offset和滤波核大小一起调，顺序是先粗后细：

1. 先用一个较大的Offset（比如10到20）跑一遍，目的是确认目标大致能出来一部分；
2. 按结果逐渐减小Offset，观察噪声什么时候开始大量冒出来；
3. 把噪声开始冒头之前那个值作为候选，再微调±2到±3。

这个顺序保证你不会一开始就被噪声带偏，也能快速判断算法在当前数据上有没有可行性。

3.2 阈值图怎么产生：mean_image / median_image / gauss_filter

dyn_threshold不负责生成第二张图，阈值图需要你自己用平滑算子生成。不同的滤波方式对结果影响极大，这是很多人刚学时最容易忽略的一点。

• mean_image(Image, ImageMean, MaskWidth, MaskHeight)：均值滤波，速度快，适合背景亮度渐变平缓的图。但均值滤波对孤立噪点不够鲁棒——一个极亮或极暗的噪点会把局部均值拉偏，导致误判。
• median_image(Image, ImageMedian, MaskType, Radius, Margin)：中值滤波，抗噪性能好。如果你图上有椒盐噪声（黑白点状噪点），中值滤波比均值滤波稳得多。代价是速度偏慢，且对边缘位置处理不如均值那么“顺”。
• gauss_filter(Image, ImageGauss, Size)：高斯滤波，平滑效果比均值自然，不容易产生振铃现象，在需要保留一定形状边缘细节时更合适。缺点是参数Size直接控制模糊半径，调起来没有mean_image那么直观。

我自己的偏好是：如果目标边缘需要尽量光滑、噪声中等水平，用高斯；如果图上有稀疏的极亮/极暗噪点，用中值；如果只是模拟“局部背景”、“跟随亮度”，用均值就够，而且快。

* 推荐做法：均值滤波作为第一选择 mean_image(Image, ImageMean, 15, 15) dyn_threshold(Image, ImageMean, Region, 8, 'dark') * 抗噪更强：中值滤波 median_image(Image, ImageMedian, 'circle', 7, 'mirrored') dyn_threshold(Image, ImageMedian, RegionDark, 6, 'dark')

3.3 滤波核大小和目标尺寸的匹配逻辑

滤波核尺寸决定了“背景估计”的尺度。核太小，背景估计也跟着目标变化，会把真正的目标误认为背景的一部分，导致目标中心被掏空；核太大，背景估计过度平滑，无法反映真实的局部亮度变化，又变相回到了固定阈值。

一个非常朴素的调参准则：滤波核大小至少为目标宽度的2到3倍。比如检测PCB板上直径约10像素的焊点缺陷，建议均值滤波核取15到30，比如21。如果目标是长条形的划痕，宽度只有5像素，长度有50像素，建议按照宽度去匹配核尺寸，否则核太小会吃掉暗弱划痕。

实操上还有一个实用办法：先把图缩小到一个小窗口里，在HDevelop里做快速实验，滤波核按目标尺寸比例估算，再用真实图验证，能省下大量调参时间。

3.4 dyn_threshold的三个使用禁忌

• 不要用原图减去原图的整体均值代替阈值图，那是“全局”不是“局部”，等于还是固定阈值；
• 不要对有大面积高光反射的金属件直接用dyn_threshold。镜面反射产生的局部极亮区域不是缓慢变化，滤波根本抹不掉，会留下一整块假缺陷；
• 不要迷信单一参数组合。换一批图、换一个光照条件，至少要重新检查Offset和滤波核，这不是一劳永逸的算子。

4. 从阈值图生成到区域后处理：一条可直接套用的流水线

4.1 实操案例：带渐变的背景上提取暗色字符

假设我要在一张塑料外壳图上提取激光打标字符，背景左侧亮、右侧暗，字符灰度比周围略低。

第一步：读取图像，生成阈值图。

read_image(Image, 'plastic_case.png') * 先转灰度 rgb1_to_gray(Image, GrayImage) * 使用高斯滤波估计背景 gauss_filter(GrayImage, ImageGauss, 11)

这里为什么用高斯而不用均值？因为塑料外壳的表面有轻微纹理，均值滤波的矩形窗口在这种纹理下容易产生方块边缘痕迹，高斯圆的核函数过渡更自然，不容易把纹理残留当作背景波动。

第二步：用dyn_threshold提取暗字符。

dyn_threshold(GrayImage, ImageGauss, RegionDark, 5, 'dark')

第三步：区域后处理——这一步几乎是必须的。

* 连接邻近区域，把断裂的字符笔画接上 connection(RegionDark, ConnectedRegions) * 去掉面积过小的噪声块 select_shape(ConnectedRegions, SelectedRegions, 'area', 'and', 100, 99999) * 填充字符内部的小洞 fill_up(SelectedRegions, RegionFillUp) * 最终拿到干净的文字区域

实际调试时Offset=5是我试出来的192组参数中的一个临时值：全图尺寸约2000×1500像素，字符笔画宽度约15像素，灰度差大约在10到12个灰度级之间。Offset取5能在“容忍表面纹理差异”和“提取弱对比边缘”之间维持平衡。如果Offset取3，纹理噪声和微小的划痕全被带进来；取8，部分笔画较细的字符脚就没了一半。

4.2 案例二：用dark和light模式同时做双侧检测

有一些场景，目标同时包含比背景暗和比背景亮的部分，比如电池表面既有凹陷（暗）又有凸起颗粒（亮）。你可以分别调用两次dyn_threshold，再把结果求并集。

mean_image(GrayImage, ImageMean, 15, 15) dyn_threshold(GrayImage, ImageMean, RegionDark, 6, 'dark') dyn_threshold(GrayImage, ImageMean, RegionLight, 6, 'light') union2(RegionDark, RegionLight, RegionUnion)

注意两次调用使用同一个ThresholdImage，保证两次比较的背景模型一致，才方便求并集。这里朴实而有效，很多标定板、面板检测项目就用这个思路。

4.3 案例三：和提取“背景均等区”结合，做划痕增强

dyn_threshold里经常被忽略的'equal'模式，在处理“灰度均匀性”比较时非常好用。

例如检测透明薄膜上的局部厚度不均，这种区域很可能表现为局部的灰度均匀区域和周围背景有明显差异。因为差异方向不固定，用'not_equal'可以抓出所有“不服从局部背景”的像素，再用形态学打通，能直接提取出肉眼都不好分辨的区域。

median_image(GrayImage, ImageMedian, 'circle', 5, 'mirrored') dyn_threshold(GrayImage, ImageMedian, RegionDiff, 8, 'not_equal')

这一步做完通常结果很碎，我一般紧接着用closing_circle把缝隙、断裂处搭桥，然后用select_shape筛掉面积过小的孤立点。

4.4 区域后处理：分割之后必做的四件事

dyn_threshold输出的Region是原始的分割掩膜，很多情况下需要进一步清理才能给测量和检测用。我整理的固定套路是：

1. connection：把阻断的多个区域拆开，便于逐目标分析；
2. select_shape：按面积、宽度、高度、圆形度等筛掉噪声；
3. fill_up或fill_up_shape：填补目标内部由于灰度波动产生的空洞；
4. closing_circle或opening_circle：做连通性整理——closing用于搭桥、合并断裂部分，opening用于去除毛刺和孤立颗粒。

这一套流程听起来基础，但实际项目里90%的“效果不好”都是因为跳过了第2步或第3步，直接拿原始Region去算特征，结果自然一塌糊涂。

5. dyn_threshold vs. 其他阈值分割方案，怎么选

5.1 一张表看懂适用边界

我整理了一张对比表，方便你根据实际图况快速选型：

5.2 为什么工业现场偏好dyn_threshold

工业视觉区别于学术图像处理，最核心的一点是不确定性来源集中：光照可能偏、工件可能有轻微倾斜、表面可能有氧化或脏污。dyn_threshold的思路符合“亮暗都是相对的”这个直觉，工程实现上也几乎没有需要训练的部分，因此成为缺陷检测方向的分割标配。

另一个被低估的优势是它的可解释性。你可以很直观地向产线工程师解释：“这个算子是拿每个像素跟它周围比，如果明显更暗就认为有问题。”这种解释在验收项目、对齐预期时非常有用。深度学习模型虽然在某些复杂缺陷上更强，但你很难用三句话把注意力机制讲清楚，也很难快速现场调参。

5.3 什么时候你应该放弃dyn_threshold

dyn_threshold不是银弹。如果你的目标和背景的灰度差异方向不稳定，且目标形状复杂到比背景还“大”，即目标本身占据了画面的大部分面积，那滤波得到的背景估计会被目标“污染”。比如检测一条贯穿整个视野的大型暗带，它已经大幅改变了局部均值，这时候用dyn_threshold往往会把暗带中间部分误判为背景，导致目标不完整。

更合适的方案是var_threshold或基于频率的纹理分割，甚至直接上深度学习。另外，如果目标边缘要求亚像素级别，dyn_threshold的分割结果也需要配合sub_pix或轮廓处理的子步骤，单纯输出区域轮廓往往不满足测量精度。

6. 六个高频问题，看一眼就能定位

下面这些坑，我几乎每一轮项目都会遇到，直接列成速查表给你。

6.1 案例复盘：我花了两个通宵排查“中心被掏空”

有一次检测金属垫圈上的小坑，模板上印了个圆环，结果dyn_threshold输出一个“甜甜圈”——边缘被提取了，但坑的中心是空的。

原因很简单：垫圈金属表面的局部镜面反射让中心区域在滤波图中与原始图几乎相等，灰度差小于Offset，被判定为背景。解决办法不是盲目调参，而是：

1. 先把原图裁剪到只包含坑的区域；
2. 用median_image替代mean_image，因为中值对镜面反射点不敏感；
3. 把Offset从10降为6；
4. 最后用fill_up把结果填成完整区域。

这三个步骤做完效果立竿见影，也说明了先诊断再调整的重要性——光调Offset是解决不了假轮廓问题的。

6.2 给新手的三个调试建议

• 一定要在HDevelop的灰度图窗口里同时显示原图、滤波图和差值图。差值图可以直接用sub_image得到，它帮助你直观看到哪些像素差异足够大。
• 用inspect工具观察滤波核在不同大小下对目标的影响——不要凭感觉选核尺寸，用图说话。
• 建议固定一个“基准图”，每次调参后对同一张图反复运行，横向对比区域面积和位置，这样能快速发现参数对分割稳定性的影响。

7. C++ / C# 环境下如何调用dyn_threshold

7.1 C++调用示例

Halcon的C++接口中，dyn_threshold对应HRegion::DynThreshold，通常配合HImage::MeanImage使用。

#include "HalconCpp.h" using namespace HalconCpp; HImage image; image.ReadImage("plastic_case.png"); HImage gray, mean; rgb1_to_gray(image, &gray); gray.MeanImage(&mean, 21, 21); HRegion region = gray.DynThreshold(mean, 6, "dark"); HRegion connected = region.Connection(); HRegion selected = connected.SelectShape("area", "and", 100, 99999);

C++接口里LightDark同样是个字符串参数，注意别传错大小写，官方只接受小写形式。我见过C#同事把"dark"写成"Dark"导致运行时异常，排查了半天才发现是大小写问题。

7.2 C#调用示例

C#使用HalconDotNet，逻辑和C++几乎一致：

using HalconDotNet; HImage image = new HImage("plastic_case.png"); HImage gray = image.Rgb1ToGray(); HImage mean = gray.MeanImage(21, 21); HRegion region = gray.DynThreshold(mean, 6, "dark"); HRegion connected = region.Connection(); HRegion selected = connected.SelectShape("area", "and", 100, 99999);

注意C#里函数命名是PascalCase；HImage是IDisposable，建议在using里包一层，否则长任务跑批时内存上涨很可观的。这不是dyn_threshold本身的问题，而是Halcon.NET封装容易踩的内存陷阱。

7.3 性能提示：DynThreshold很“轻”，别在滤波上浪费

dyn_threshold本身做的是逐像素比较，不算重；性能瓶颈几乎全在生成阈值图那一步。2000×1500的灰度图，均值滤波21×21大概耗时10到15毫秒（取决于CPU和是否启用了SIMD），中值滤波则可能翻倍。实时性要求高的场景，建议：

1. 用mean_image替代median_image；
2. 滤波核尺寸不要盲目放大；
3. 优先用Halcon的并行版本，直接享受多核优化；C#里避免频繁创建HImage。

8. 和深度学习分割的取舍趋势

最近两年不少项目组开始用Halcon的深度学习工具做分割，也确实解决了几个dyn_threshold搞不定的案子，比如背景杂乱、目标灰度与背景几乎无差异、或者缺陷形态高度多样化。

我的取舍标准是：如果缺陷在灰度图上肉眼可见“有差异”，先试dyn_threshold，调参半天内无法收敛再上深度学习；如果缺陷特征是纹理级或语义级的，直接考虑深度学习。

因为dyn_threshold的优势在于透明可控、无需标注、部署轻量。它对项目初期验证非常有价值——先用它建立基线结果和量化标准，再去训练更复杂的模型，也更容易向客户解释效果提升来自哪里。

9. 最后分享一个我一直沿用的调试技巧

看dyn_threshold参数是否合理，我有个土办法：直接在HDevelop里生成差值图。

sub_image(Image, ImageMean, ImageDiff, 1, 0)

然后盯着ImageDiff看。如果差值图中目标的轮廓清晰，而背景区域几乎发灰（接近0），那么dyn_threshold就有机会做得不错。这个步骤5分钟就能完成，却能在真正调参前帮你判断算法方向的可行性，省掉大量盲目实验的时间。我在不少项目里用这个“预测”步骤筛掉过不适合dyn_threshold的场景，也帮同事排掉过因为图像本身模糊导致的假案例。

现在再翻回三年前那个光伏板隐裂项目，当时如果一开始就按“差值图诊断 → 选对滤波核 → 用Offset压噪点 → 区域后处理”这个顺序走，调试周期至少能缩短一半。dyn_threshold不难，难的是理解它背后“局部对比才是王道”的思想。希望这篇分享能让你少走几步弯路。