简介基于OpenCvSharp的HSV颜色识别C#示例工程面向希望在.NET环境中使用OpenCV进行颜色检测的开发者适合具备基础C#语法、刚接触图像处理的读者常用于自动化检测、机器人视觉与特定颜色目标提取。HSV模型将颜色拆分为色调、饱和度与亮度比RGB更贴近人对颜色的感知适合做颜色过滤。压缩包共59个文件约35.14MB主体包含17个C#源码文件、8个DLL运行库另有窗体资源、配置文件、项目工程文件及演示图片解压后可在Visual Studio中打开直接调试运行。目前已有1719人学习下载可作为颜色识别项目起步模板。工程内设计了多个功能窗体包括主界面、图像显示、HSV阈值设置和最大图像窗口并配有HSV颜色体系说明图代码完整覆盖BGR转HSV、InRange生成掩码、按颜色提取区域等关键步骤注释与界面结合便于理解色调、饱和度、亮度的实际调参逻辑修改颜色范围即可适配不同识别需求。1. 把颜色识别交给 HSV为什么你还在用 RGB 阈值“碰运气”做过颜色识别的人大概率遇到过这么一幕明明调好的 RGB 阈值在室内桌面下能框住目标把设备挪到窗边或者换个灯泡马上开始误报——蓝色袋子被认成绿色橙色工件大面积漏检。问题不在算法不够劲而是你选错了颜色空间。RGB 的 R、G、B 三个通道把亮度和色度混在一起光照一变三个数一起漂阈值怎么划都不稳。而 HSV 把“颜色本身”和“受光照影响的明暗”拆开了H 通道在光照变化下相对稳定工程上比 RGB 容易收敛得多。这份资源就是一个基于 OpenCvSharp 的 HSV 颜色识别最小工程C# 环境直接可用适合做工业分拣、机器人抓取定位、自动化测试里的视觉判色。读完你能得到一个带滑动条调参、能保存参数的完整示例而不是一个调完就丢的黑匣子。2. 从颜色空间到代码落点HSV 的工程语义与 OpenCvSharp 选型理由2.1 HSV 三个分量在工程里到底是什么HSV 全称 Hue色相、Saturation饱和度、Value明度。在 OpenCV 里H 的范围是 0~179不是 0~360S 和 V 都是 0~255。这个细节非常关键因为网上大量资料写的是 360 制色相你拿 180 直接填进 OpenCV 的 Scalar 里不会报错但结果完全不是你想要的颜色。我在模拟项目X里接过一个视觉分拣工位前任留下的代码把 H 上限定成了 200结果 inRange 之后经常出现莫名其妙的绿边查了半天才发现是量纲没换算。工程语义上H 管“这是什么颜色”S 管“这个颜色有多纯”V 管“整个区域有多亮”。你真正要调的核心其实只有 H 的下限和上限S 和 V 往往只要限制一个最小值和最大值筛掉背景、阴影、反光就够。比如识别红色的苹果H 低阈值设置在 165 附近按 OpenCV 的量纲高阈值给到 10——注意红色横跨 179 和 0 两端后面避坑章节会专门讲。S 最小值给 40 是为了把灰白色背景排除掉V 最小值给 50 是为了让阴影区域不参与判断。从代码角度读入的彩色图默认是 BGR 顺序直接用CvtColor转成 HSVusing OpenCvSharp; Mat src new Mat(input.jpg, ImreadModes.Color); Mat hsv new Mat(); Cv2.CvtColor(src, hsv, ColorConversionCodes.BGR2HSV);ColorConversionCodes.BGR2HSV这个名字本身值得多说一句OpenCvSharp 的转换枚举几乎完全对齐 C 版 OpenCVBGR 在前说明转换的输入顺序是 BGR 而不是 RGB。如果用Bitmap类加载图片再转 Mat像素顺序同样是 BGR不需要额外交换通道。第一步转换完成之后你会得到一张三通道图但它已经不是“普通彩色图”了。后面所有阈值操作都应该作用在 HSV 这个结果上而不是回到 BGR 上做判断。2.2 为什么是 OpenCvSharp 而不是 OpenCV Python如果你只是做一次性的图像实验Python 版 OpenCV 确实上手更快。但这份资源的场景是 C# 桌面端和产线软件集成要么接工业相机 SDK要么对接已有的设备控制逻辑C# 在整个自动化栈里占的比例比很多人想象的高。OpenCvSharp 的好处是它几乎面贴面地映射了原生 OpenCV 的 API函数名、参数顺序、枚举命名都和 C 版本保持高度一致。你以前写过 C 的 OpenCV 代码转过来基本不需要查文档直接用就好。这个库的底层是靠 DllImport 调用原生 OpenCV 的 C 接口而不是把 OpenCV 用纯 C# 重写一遍。所以在性能上它和原生库几乎一致不会有明显的额外开销。而这带来一个小习惯要养成Mat对象要在不再使用的时候及时释放。虽然 OpenCvSharp 自己也有一层IDisposable包装能靠垃圾回收兜底但高帧率场景下你不显式调用Dispose()或者用using块管理内存占用量会慢慢爬上去。我一般会写成using (Mat hsv new Mat())这种形式方法一退出图像内存立刻释放不给 GC 添负担。选它的另一个理由是它对 C# 语法的适配程度。比如inRange在 C 里需要传三个Scalar在 OpenCvSharp 里可以直接传Scalar或者Vec3b写法非常接近原生using (Mat mask new Mat()) { Cv2.InRange(hsv, new Scalar(hMin, sMin, vMin), new Scalar(hMax, sMax, vMax), mask); }这里的四个参数顺序容易搞混前三个是下限低 H、低 S、低 V后三个是上限高 H、高 S、高 V。不是 H、S、V 分开写两次而是按通道打包成两个Scalar向量。如果你只有一个颜色区间要识别这种方式够用了要识别多个颜色区间就得循环调用InRange再把 mask 做Or合并后面红色边界部分会看到具体写法。3. 用 OpenCvSharp 跑通一条单帧识别管线预处理、二值化与轮廓输出3.1 最小可运行的原型读图 → 转 HSV → inRange → 二值化先不碰摄像头也不碰实时视频流从一张静态图片开始验证。这是最省事的排查路径图片是固定的识别效果变好变坏完全由参数决定不会掺入摄像头自动曝光之类的变量。我通常会先写一个最简管线四个步骤连起来读图、转 HSV、inRange、显示 mask。这一步能跑通整个颜色识别就算立住了。using OpenCvSharp; class SingleFrameDetector { public Mat ProcessFrame(string imagePath, int hMin, int hMax, int sMin, int sMax, int vMin, int vMax) { using (Mat src new Mat(imagePath, ImreadModes.Color)) using (Mat hsv new Mat()) { Cv2.CvtColor(src, hsv, ColorConversionCodes.BGR2HSV); Mat mask new Mat(); Cv2.InRange(hsv, new Scalar(hMin, sMin, vMin), new Scalar(hMax, sMax, vMax), mask); Mat result new Mat(); Cv2.BitwiseAnd(src, src, result, mask); return result; } } }这段代码背后的逻辑是InRange输出的是单通道的二值 mask像素值只有 0 和 255。255 的部分表示“这个像素的 HSV 同时落在六参数范围内”0 表示“不在范围内”。然后BitwiseAnd把原图和 mask 做按位与mask 为 0 的像素在原图上变成黑色mask 为 255 的像素保留原色这样你就能看到“被认出来的区域长什么样”。调用方式也很直白var detector new SingleFrameDetector(); using (Mat result detector.ProcessFrame(test.png, 35, 85, 60, 255, 40, 255)) { Cv2.ImShow(masked, result); Cv2.WaitKey(0); }这个参数H 35 到 85、S 60 到 255、V 40 到 255对应的是绿色物体比如草坪里的绿色球、绿色托盘。实际场景里第一个要调的永远是 H 区间S 和 V 的改动通常只是微调。先按“H 找大范围、S 留中高位、V 放松”的思路起手能少掉一半调试时间。3.2 接上轮廓提取从 mask 到可用的包围盒坐标二值化只是“看出有没有这颜色”大多数实际需求是“这颜色在哪”。所以下一步要拿 mask 去查轮廓拿到每个目标区域的最小外接矩形或者轮廓点集。用FindContours是最快的方式注意它只接受二值图。public Rect[] DetectRegions(Mat mask) { using (Mat binary new Mat()) { Cv2.Threshold(mask, binary, 10, 255, ThresholdTypes.Binary); Cv2.FindContours(binary, out Point[][] contours, out HierarchyIndex[] hierarchy, RetrievalModes.External, ContourApproximationModes.ApproxSimple); var rects contours .Where(c Cv2.ContourArea(c) 500) .Select(c Cv2.BoundingRect(c)) .ToArray(); return rects; } }这里多补了一步Threshold是因为有时候网上能找到的 mask 不是纯 0/255而是带一些中间灰度值。FindContours对阈值处理很敏感灰度值不干净会导致轮廓边缘多出一圈噪点。参数上RetrievalModes.External只取最外层轮廓适合颜色块相对独立、没有嵌套的情况如果你的目标物是被其他轮廓包着的就要改成RetrievalModes.CTree。ContourArea过滤阈值 500 是需要按图缩放的一张 1200x800 的图黄色小钮扣可能只有 40 像素而一个篮球有 20000 像素500 这个值是我做中尺寸物体时的经验值。具体项目里一般扫描一次所有轮廓的面积分布再看一眼直方图决定下限。BoundingRect返回的是左上角坐标和宽高画框直接用foreach (Rect r in rects) { Cv2.Rectangle(src, r, new Scalar(0, 0, 255), 2); }3.3 管线里的两个关键参数中值模糊核与形态学核很多初学者第一次跑通InRange以后会发现 mask 上满是雪花点。原因很常见摄像头噪声、压缩伪影、光线反射都会让相邻像素的 HSV 值跳跃。这种噪声在 mask 上的表现是零散的白点发炎。解决方案有两个它们针对的问题不同。中值模糊是用原图做预处理目的是抹掉单像素噪声。我记得第一次实际接摄像头时实际输出却是 mask 上有一层沙粒感。给原图加一个核尺寸 5 的中值模糊之后效果立刻干净了using (Mat blurred new Mat()) { Cv2.MedianBlur(src, blurred, 5); Cv2.CvtColor(blurred, hsv, ColorConversionCodes.BGR2HSV); }中值模糊和均值模糊的区别在于它取的是窗口内的中位数而不是平均值所以它能在去除椒盐噪声的同时不把边缘糊成一片。核尺寸必须是奇数常见值是 5 或 7。核太小等于没滤核太大明显边缘变形找轮廓时外接矩会比实物大一圈。形态学操作则是作用在 mask 上的。中值模糊能清掉像素级噪点但挡不住二值化后出现的大块离散碎片。这时候用开运算先腐蚀后膨胀把小块噪点消掉、把相邻区域断开的连接处补上using (Mat kernel Cv2.GetStructuringElement(MorphShapes.Rect, new Size(5, 5))) using (Mat morphed new Mat()) { Cv2.MorphologyEx(mask, morphed, MorphTypes.Open, kernel); Cv2.MorphologyEx(morphed, morphed, MorphTypes.Close, kernel); }开运算参数里最容易翻车的是核尺寸。5x5 对 720p 的监控画面够用但对 4K 工业相机拍出来的大图同样的核看起来就像没做一样。一个经验法则核尺寸约等于目标物体最小尺寸的 1/20。比如目标是 100 像素宽的圆形工件核就取 5 上下如果是 200 像素的大色块核吃到 11 也没问题太快会影响边缘细节。开运算和闭运算连用的顺序我习惯先开后闭先把独立小噪点清掉再把大色块内部的小黑洞补上。顺序反过来的话闭合会把小噪点先包进一个区域后面再开运算就很难把它们全剥掉了。4. 避坑调色板里看不见的边界问题4.1 红色把 H 分成两段0 和 179 是同一个色环的邻居现象使用 H 区间 160~180 识别红色结果框不全改成 0~10 又框不全而且两个区间会互相打架。原因HSV 的色相是一个环红色恰好落在 0 度附近所以它横跨最小值 0 和最大值 179 两端。单凭一个连续区间永远无法完整覆盖红色这是 OpenCV 的 H 范围设计决定的不是你的代码写错了。解决把红色拆成两段先分别生成 mask再做按位或合并Mat maskRed1 new Mat(); Mat maskRed2 new Mat(); Mat maskRed new Mat(); Cv2.InRange(hsv, new Scalar(0, 80, 50), new Scalar(10, 255, 255), maskRed1); Cv2.InRange(hsv, new Scalar(160, 80, 50), new Scalar(179, 255, 255), maskRed2); Cv2.BitwiseOr(maskRed1, maskRed2, maskRed);两段区间合并之后再做形态学处理。这个写法对于“红绿灯识别”“红色指示灯状态判断”这类需求很常见你把两段阈值写在一块后面调参只需要动一处。4.2 低饱和区域误报白墙和灰布也被当成目标色现象识别蓝色工件时背景里一小块灰色橡胶垫也时不时被框出来。看 mask这块区域的 H 值居然和蓝色工件的 H 值一样。原因灰色、白色、黑色的色相根本不稳定。当 V 很低或者 S 很低时H 通道失去意义数值在 0~179 之间随机漂移于是产生“H 命中但颜色明明是灰的”的假象。解决给 S 和 V 各设一个下限。纯灰色像素的 S 通常在 0~10 附近把 S 的下限提到 50 就可以滤掉。V 下限提到 40 可以滤掉黑色阴影。这个阈值宁可往高调也不要低——识别目标是颜色鲜艳的物体时S 下限设到 80 依然能正常识别。4.3 不同摄像头白平衡差异导致颜色偏移现象同一套参数在摄像头 A 上稳定识别换到摄像头 B 上明显偏色红色变成了暗橘色。两个摄像头都是自动白平衡。原因自动白平衡会根据画面场景整体色调调整色温增益所以不同品牌、不同感光元件的摄像头输出的 RGB 值本来就不同。你在 HSV 里调出来的是“摄像头 A 的白平衡后的世界”而不是真实的物理颜色。解决开发阶段就把摄像头固定手动白平衡或者至少固定在同一场景下校准。工业上也有一种做法是放一张标准色卡每次启动先抓一帧色卡计算 H 通道偏移量等在代码里做补偿。这个思路能让你的参数在不同场景间迁移时少踩很多坑。4.4 OpenCvSharp 的 H 量纲与设计软件不一致现象在 Photoshop 或者网页取色器里看到 H 是 30 度填入 OpenCvSharp 的 H 值 30结果识别不到填 15 才对。原因OpenCV 为节省 byte 空间把色相 0~360 度压缩到 0~179。所以软件里的度数值要除以 2 再填进去。这不是 OpenCvSharp 的独有问题是 OpenCV 全系的一致规范。解决记住换算公式OpenCV_H 软件H / 2。而 S 和 V 在 OpenCV 里是 0~255跟大多数软件的 0~100 百分比又不一样也需要换算。我的习惯是写一段注释放在 HSV 参数定义旁边标明“上完课一整年后真人真事我拿着一个 24 色卡在 C# 里改了一晚上参数才发现是量纲问题”。从那之后每次新开项目我都先确认三件事H 有没有除 2、S 是不是 0~255、代码注释里有没有把这两个换算规则写下来。5. 进阶滑动条调参工具——让色域参数在一次扫描里收敛5.1 用 CvTrackbar 把六个参数暴露成滑块静态调参的痛点是每次修改 H、S、V 都要重新编译效率很低而且在连续改参数的过程中很难记住“上一次参数下效果好还是这次好”。更好的方式是做一个滑块窗口六个滑块分别对应 H 上下限、S 上下限、V 上下限再放一个滑块专调形态学核尺寸。拖动滑块画面实时刷新。这个工具在光源调试、换新场景标定的时候特别顶用比改一次编一次省太多时间。OpenCvSharp 里可以用Cv2.CreateTrackbar直接在窗口上生成滑块配一个回调函数。这个回调函数的签名固定是(int pos, IntPtr userData)不能自定义额外参数所以要靠窗口名称或者静态变量来传递当前滑块的值。我一般用类字段保存状态static int hMin 0, hMax 179; static int sMin 0, sMax 255; static int vMin 0, vMax 255; static int blurKernel 5; static void OnTrackbar(int pos, IntPtr userData) { string name (string)userData; if (name HMin) hMin pos; else if (name HMax) hMax pos; // 其余四个滑块同理 }然后创建窗口和滑块const string winName param; Cv2.NamedWindow(winName, WindowFlags.AutoSize); Cv2.CreateTrackbar(HMin, winName, ref hMin, 179, OnTrackbar, new IntPtr(123));ref关键字在这里很重要它把滑块当前值的存储位置直接绑定到 C# 的整型变量上回调函数对 pos 的赋值会同步写在绑定变量里。这样你在渲染循环里读这六个 int拿到的就是实时的滑块位置。主循环里直接调用前面写好的ProcessFramewhile (true) { using (Mat frame new Mat(test.jpg, ImreadModes.Color)) using (Mat result new Mat()) { result detector.ProcessFrame(frame, hMin, hMax, sMin, sMax, vMin, vMax); Cv2.ImShow(winName, result); } int key Cv2.WaitKey(30); if (key 27) break; // ESC 退出 }注意Cv2.ImShow和WaitKey一定要同时出现。WaitKey不只是等待按键它同时负责刷新窗口显示。没有它窗口会卡死或者不刷新新手最容易在这里卡住。5.2 把调好的参数固化到配置文件调参的目的不是一次现场调试爽完而是把最终结果保存下来换到别的项目时能直接载入。我用的格式是 JSON配置的目标是完整覆盖一行 HSV 参数加形态学参数{ hMin: 0, hMax: 179, sMin: 80, sMax: 255, vMin: 50, vMax: 255, blurKernel: 5, morphKernel: 5 }C# 里可以用System.Text.Json直接反序列化成一个配置类。加载之后把这些值填进滑块初始值界面上显示的就是上次调好的参数位置。这样就算中途换了机器新环境打开程序只要加载一下这个 JSON马上回到之前的工作点不用从零开始重新摸。把调参工具直接做到主程序里会带来一个额外的好处配置验证变得方便。你不需要一遍遍改代码、编译而是每次只动滑块看识别框有没有稳定锁住目标。等觉得效果可以了点一下保存参数固化。这种做法比手写常量再重新编译靠谱得多尤其在现场调试时客户就在旁边等着看效果编译等待时间是最大的浪费。从那以后我每次拿到新项目不管目标是识别螺丝颜色还是分拣塑胶件都强制先走一遍“加载图片 → 拖滑块 → 保存配置”的调试循环确认当前光照下的最优参数区间再切换到摄像头接管。这个习惯帮我省下了大量反复编译的黑匣子时间也让最终的识别效果可复现——任何一个人拿到那台设备加载同一份配置都能看到同样的识别结果。希望这个调试思路也能帮到你。本文还有配套的精品资源点击获取
