有一个深夜,我在做一批零件外观检测程序的联调,同一样品连续跑了两遍,检测出来的“缺陷区域”数量却差了一百多个。查了半天,问题出在某个分支里把灰度图转成了彩色图,下游代码还在按单通道逻辑访问像素。这种低级错误其实很常见,而它暴露出来的本质问题,是对连通性检测理解决不够透——它不是一个“扔张图进去、出来一堆结果”的现成功能,它的输入、数据结构、参数约定都藏着不少细节。
今天这篇就用 OpenCVSharp 着重聊连通性检测。如果你用过 C++ 或者 Python 版的 OpenCV,再转过来写 C#,最舒服的一点就是 OpenCvSharp 的 API 几乎原样对齐了原生 OpenCV,ConnectedComponentsWithStats、connectedComponents 这一套都能直接映射过来。但舒服归舒服,真正落到自己的业务里,从图像类型、通道排布到标签数据的读取方式,处处是坑。
这篇适合以下几类人:刚开始接触 OpenCVSharp、想用连通性分析做目标计数或区域提取的;已经在用但被 labels、stats 这些返回值搅得头痛的;以及想在工程里把连通域检测做成一个稳定工具函数、少踩几次重复坑的。我会按照“概念 -> Demo -> 数据结构 -> 场景化过滤 -> 实战排坑 -> 工程封装”的顺序讲,尽量让每个结论都能直接复现。
1. 连通性检测在图像分析里到底扮演什么角色
1.1 从“一堆像素”到“一个个物体”的转变
图像经过阈值化、边缘检测或颜色筛选之后,得到的往往是一个个离散的像素集合。以最常见的二值图为例,白色像素代表我们关心的目标,黑色像素是背景,但像素本身是没有“物体”概念的。我们想知道图里到底有几个目标、每个目标大概有多大、每一块有没有独立边界,就必须把这些像素按照空间上的相邻关系分组。
连通性检测干的就是这件事。它把“相互连通的白色像素”归为同一个区域,给每个区域分配一个唯一的编号标签,再附加统计信息。这种操作在计算机视觉领域被称为连通区域标记,英文叫 Connected Component Analysis,简称 CCA。你盯着屏幕看时,能一眼分清图片里有三个圆、两个矩形,是因为人脑天然具备空间分组能力;而计算机没有这个能力,连通性检测就是补上这层分组能力最基础、最常用的一把钥匙。
用生活里的场景来类比:一箱子积木倒在地上,你按“有没有碰在一起”把它们分成几堆,碰在一起算一堆,不碰就算另一堆。连通性检测干的正是这个“碰不碰在一起”的判断,只不过判断对象是像素,标准则是像素之间是否共享边界或角点。
1.2 OpenCVSharp 里连通性检测的三种常见打开方式
在 OpenCVSharp 中,连通性检测的功能主要落在三个 API 上:
Cv2.ConnectedComponents:只做区域标记,输出一张和原图同样大小的标签图。适合最基础的“数个数”场景。Cv2.ConnectedComponentsWithStats:除了标记图之外,还会输出每个区域的边界框、面积、质心等统计信息。这是实际项目中最常用、最值得优先掌握的版本。Cv2.ConnectedComponentsWithAlgorithm:允许显式指定使用的算法类型,在性能极端敏感的场景下会用到。
这三个函数在输出层面有一点相同:标签图里像素值不再代表灰度,而是代表“这个像素属于第几个区域”。如果你打开一张标签图直接显示,看到的通常是黑色背景上随机深浅的形状,那并不代表真实的灰度信息,而是区域编号的可视化结果。
我建议初学者把主要精力放在 ConnectedComponentsWithStats 上。因为工程里几乎不存在“只需要计数”而完全不需要区域位置和面积的情况。哪怕是简单的细胞计数,你也往往需要统计每个细胞的大小、位置、颗粒度,单纯数个数只是最粗糙的第一步。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 跑通第一个连通性检测 Demo:从载入图像到可视化结果
2.1 环境准备和 NuGet 包选择
在动手写代码之前,先把环境准备踏实,这一块翻车率反而最高。新建 .NET 项目之后,通过 NuGet 安装以下两个包:
OpenCvSharp4:核心程序集,包含Cv2静态类以及各类Mat、Rect、Scalar类型。OpenCvSharp4.runtime.win:Windows 运行库。它会自动把 OpenCV 原生依赖文件复制到输出目录。
如果你的项目要部署到 Linux 服务器上跑,就不要用 OpenCvSharp4.runtime.win,而是安装 OpenCvSharp4.runtime.ubuntu 之类的对应包,或者直接在服务器上用 OpenCV 的 CI 构建产物做本地依赖。这个细节在开发机上一切正常、部署后却报 DllNotFoundException 时尤其值得排查。
2.2 二值化预处理 —— 连通性检测的输入要求
聊完环境,直接上一个最小 Demo。假设我有一张工件表面的灰度图 sample.jpg,目标是统计图中有几个明显的瑕疵区域。第一步要先把灰度图变成二值图。
csharp复制using OpenCvSharp;
Mat gray = new Mat("sample.jpg", ImreadModes.Grayscale);
Mat binary = new Mat();
Cv2.Threshold(gray, binary, 0, 255, ThresholdTypes.Otsu | ThresholdTypes.Binary);
为什么不能把原始灰度图直接喂给连通性检测?核心原因在于,连通性检测处理的是“是否属于前景”的二值语义。灰度图里的每个像素有 0 到 255 共 256 种取值,如果直接当作输入,算法无法区分“低灰度目标”和“背景中较暗的干扰”。OpenCV 官方接口在设计时也没有规定死必须输入二值图,但大多数场景下直接传入灰度图得到的结果并不可靠,甚至因为噪声过多导致区域数量爆炸。
所以正确姿势是:先用 Cv2.Threshold、Cv2.AdaptiveThreshold、Cv2.Canny 之类的操作,把非黑即白的前景信息提取出来。一般推荐 Otsu 自动阈值,对于光照相对均匀的图像效果非常稳,我上面代码里就是这么处理的。
如果你处理的是彩色图,想只根据颜色提取前景,建议用 Cv2.InRange 或 Cv2.Split + 通道阈值,先
