老读者应该知道这个系列是我在 Linux 环境下做视觉应用时的实践记录编号到 43 的时候正好卡在 OpenCV 两个出镜率极高的函数上cvtColor和putText。一个负责把图像从一种颜色空间搬到另一种一个负责在图像上写字。听起来都不难但我在这两个函数上翻过的车比很多复杂算法都多。这篇就把它们讲透包括原理、参数、实操代码以及我踩过的坑。适合刚入门 OpenCV 的 Linux 学习者也适合要在嵌入式 Linux 板卡上做视觉排查的老手。1. 两个函数在视觉项目里的真实定位1.1 为什么单独拎出这两个函数看一眼工业界和开源项目里的代码cvtColor几乎出现在每一条视觉处理链路上。摄像头采集的原始帧通常是BGR但做目标检测前要灰度化减少计算量做颜色识别时要转到HSV避开光照干扰保存结果时还要考虑YUV、Lab这些不同标准。而putText看似不起眼实际是调试阶段最有力的工具之一。算法跑不通的时候与其对着终端里的日志发呆不如直接把帧率、检测框坐标、置信度画在画面上一目了然。这两个函数组合在一起就是一个“能看、能写”的最小视觉调试闭环。我在嵌入式 Linux 项目里排查问题时经常先接一个推流或者保存帧再用putText把内存里可疑变量的值打到图上几秒钟就能定位是上游采集问题还是下游算法问题。这个习惯帮我节省了大量用 gdb 打断点的时间。1.2 这两个函数都能用在什么场景先说cvtColor的场景。工业质检里经常要按颜色分拣转到 HSV 空间后用inRange抠出目标色块自动驾驶或者机器人项目里车道线检测、路牌识别几乎都从灰度图开始视频编码、推流环节则常见BGR2YUV的转换因为 YUV 是 H.264/H.265 编码器最喜欢的输入格式。putText则多用于调试信息叠加、ROI 区域标注、以及往生成的结果图里写时间戳。做数据集标注工具的人也会高频使用比如给每一帧自动打上类别标签。我自己还常用这两个函数配合做“可视化回归测试”把输入图片、中间特征、输出结果用putText标好文字说明再用imwrite存成一个对比图。这样算法改一版我瞟一眼对比图就知道有没有引入新问题。这个方法在 Linux 无显示器的服务器环境里尤其好用。2. cvtColor 颜色空间转换原理、参数与常见坑2.1 颜色空间到底在转什么颜色空间本质上是“用一组数字描述颜色”的坐标系。RGB 用红绿蓝三个分量合成颜色直观但不能很好地分离亮度和色彩灰度用单个通道表示亮度计算量最小但对颜色信息完全是破坏性的压缩HSV 则用色相、饱和度、明度来描述颜色抗光照变化能力远强于 BGR所以做颜色识别时大家都爱用它。OpenCV 里的cvtColor就是对像素点的数学映射。灰度化不是简单取平均而是按照人眼对绿色更敏感、对蓝色最不敏感的特性做了加权标准公式是Y 0.299R 0.587G 0.114B对应 BT.601 标准。这个细节很多人不知道但他们调的参数其实已经在用这个权重了。转到 HSV 时H 代表色调S 代表饱和度V 代表明度OpenCV 为了能在 8 位无符号整数里流畅存储把 H 的范围压缩到了 0 到 179S 和 V 保持 0 到 255。2.2 函数签名与核心参数先看函数原型void cvtColor(InputArray src, OutputArray dst, int code, int dstCn 0);src是要转换的输入图像dst是输出。code是转换编码比如COLOR_BGR2GRAY、COLOR_BGR2HSV、COLOR_BGR2RGB。dstCn是目标图像的通道数默认填 0 表示跟随code自动决定。如果你特意要生成一个特定通道数的结果才需要手动指定。这里有个容易忽略的点code里的第一个单词是输入格式。比如COLOR_RGB2BGR和COLOR_BGR2RGB是两个不完全相同的编码虽然效果上都是交换 R 和 B 两个通道但 OpenCV 内部对数据排布的处理是有明确约定的。写代码时最好按照实际输入输出选择正确的枚举避免阅读代码的人产生误解。2.3 BGR 与 RGB最容易翻车的地方很多从其他语言或框架转过来的朋友第一次用 OpenCV 读图片后发现显示出来偏蓝几乎都是栽在通道顺序上。OpenCV 的imread默认读进来的就是 BGR 排列而很多显示库、深度学习框架习惯用 RGB。比如你用 matplotlib 的imshow直接显示 OpenCV 读进来的图红色和蓝色会互换画面看起来像是调反了色。解决办法是用cvtColor(src, dst, COLOR_BGR2RGB)显式转换后再交给其他库。反过来如果你需要往 OpenCV 里喂一张来自 RGB 来源的图像也要先转成 BGR。这个顺序错误在 Linux 下尤其常见因为很多服务器端的库会跟 OpenCV 混合用而且不会报错只会在颜色上悄悄给你“上眼药”。排查思路很简单看到红色变蓝、蓝色变红十有八九就是通道顺序问题。2.4 HSV 的区间陷阱想用inRange做颜色识别的人大概率会被 HSV 的区间坑一次。在 GIMP、Photoshop 这类软件里H 的取值范围通常是 0 到 360而 OpenCV 里是 0 到 179。同一个红色的色相值在别的软件里可能是 350在 OpenCV 里就成了 175。我见过很多人在 OpenCV 里直接写Scalar(300, 100, 100)作为红色下界结果inRange直接输出一张全黑图。正确做法是先查一遍 OpenCV 的区间约定或者自己写一个小工具不断调整 H 的上下限来观察掩膜变化。需要提醒的是OpenCV 的 S 和 V 范围仍是 0 到 255如果从 0 到 1 的浮点表示法转过来的人也需要重新适应。做颜色识别时的常见策略是把 H 范围分成两段比如红色既在 0 附近存在又在 179 附近存在不能只写一个区间。3. putText 文字绘制参数详解与中文难题3.1 函数签名与坐标系putText的原型如下void putText(InputOutputArray img, const String text, Point org, int fontFace, double fontScale, Scalar color, int thickness 1, int lineType LINE_8, bool bottomLeftOrigin false);img是目标图像text是字符串org是文字的左下角基准点fontFace是字体fontScale是字体缩放color是颜色thickness是笔画粗细lineType是线型bottomLeftOrigin表示基准点是否为左下角。坐标系是很多人第一次用就翻车的点。OpenCV 的图像原点在左上角x 轴向右y 轴向下所以org的 y 坐标越大文字越靠近图像下方。而bottomLeftOrigin默认是false也就是说org是文字的左下角不是左上角。如果你习惯性把org当成文字左上角来用会发现文字整体比预期靠下一些尤其是字号大的时候特别明显。3.2 字体选择、大小与居中对齐OpenCV 自带一组 Hershey 字体常用的有FONT_HERSHEY_SIMPLEX、FONT_HERSHEY_PLAIN、FONT_HERSHEY_COMPLEX等。SIMPLEX 是最常见的常规字体可读性好PLAIN 更细更小适合在空间紧张时使用。fontScale是一个无单位的缩放比例1.0 的情况下小字号不明显需要跟着图像分辨率调整。图像是 1920 宽的帧时1.0 看起来还可以但如果分辨率缩到 640 宽1.0 就显得很突兀。想要把文字整齐地放在画面中心或者某个 ROI 中心不能靠瞎猜大小应该用getTextSize拿到文字的实际像素宽高int baseline 0; Size textSize getTextSize(text, fontFace, fontScale, thickness, baseline); Point org((img.cols - textSize.width) / 2, (img.rows textSize.height) / 2); putText(img, text, org, fontFace, fontScale, color, thickness);baseline是文字底部到基线的距离排版对齐时非常有用。lineType推荐直接用LINE_AA抗锯齿效果好很多虽然速度稍慢一点但画文字这种低频操作完全感受不到差别。3.3 Linux 下的中文乱码问题这是被问得最多的问题。OpenCV 自带的 Hershey 字体只包含拉丁字符直接用putText写中文会得到一屏问号。网上很多人说“换字体就行”但实际上putText的fontFace并不支持加载 TTF 字体文件。想正常显示中文主流方案有三个。第一个方案是使用 OpenCV 的 freetype 模块它属于 opencv_contrib 扩展包编译时要单独开启。用法是创建一个cv::freetype::FreeType2对象加载系统里的中文字体文件比如思源黑体或者文泉驿微米黑然后调用它的putText。这个方案性能好适合 C 项目。注意一些发行版默认只装主包不带 freetype需要自己编译或安装带 contrib 的包。第二个方案是 Python 配合 PIL/Pillow。先把 OpenCV 图像从 BGR 转成 RGB交给ImageDraw画中文再转回来。这个方案代码量小、最省事适合快速验证。缺点是每次都要做格式转换帧率敏感的场景不太合适。第三个方案是纯图像叠加用别的工具把文字预先渲染成带透明通道的 PNG再用addWeighted或copyTo叠到目标图上。这个方案灵活性最高连图案、Logo 都能叠缺点是需要额外维护素材。我自己在嵌入式 Linux 板卡上的做法是能不用中文就不用中文。调试信息尽量用英文一方面是字体支持好另一方面是很多终端和采集软件对 UTF-8 的处理并不统一。非要在画面上显示中文时再引入 freetype。4. 实操从环境准备到编译运行4.1 Linux 下安装 OpenCV在 Ubuntu/Debian 系系统上最简单的安装方式是直接用包管理器sudo apt update sudo apt install -y libopencv-dev装完可以用下面命令确认版本pkg-config --modversion opencv4如果要用到 freetype、dnn 这些扩展功能建议自己从源码编译或者找带 contrib 的预编译包。编译安装其实不复杂我就踩过一次 cmake 配置漏掉模块的低级坑后面写了条命令作为参考git clone https://github.com/opencv/opencv.git git clone https://github.com/opencv/opencv_contrib.git cd opencv mkdir build cd build cmake -D CMAKE_BUILD_TYPERELEASE \ -D CMAKE_INSTALL_PREFIX/usr/local \ -D OPENCV_EXTRA_MODULES_PATH../../opencv_contrib/modules .. make -j$(nproc) sudo make install编译耗时比较长但对嵌入式 Linux 开发来说自己编译往往才是唯一选择因为发行版仓库里的 OpenCV 不一定匹配你的交叉编译工具链。另外服务器上如果只做离线处理不需要imshow那可以不用关心 GUI 依赖问题但如果你确实要用imshow调试就需要注意系统有没有装 GTK 或者 Qt 的相关开发库不然会运行时报错。4.2 C 完整示例与 CMake 配置下面这个示例演示了cvtColor和putText的基本配合读图、转灰度、转 HSV、叠加文字、保存结果。#include opencv2/opencv.hpp #include iostream using namespace cv; using namespace std; int main(int argc, char** argv) { if (argc 2) { cerr Usage: argv[0] image_path endl; return -1; } Mat src imread(argv[1]); if (src.empty()) { cerr Failed to load image: argv[1] endl; return -1; } Mat gray, hsv; cvtColor(src, gray, COLOR_BGR2GRAY); cvtColor(src, hsv, COLOR_BGR2HSV); string label Linux43: cvtColor putText; putText(src, label, Point(30, 60), FONT_HERSHEY_SIMPLEX, 1.0, Scalar(0, 255, 0), 2, LINE_AA); imwrite(output_src.jpg, src); imwrite(output_gray.jpg, gray); imwrite(output_hsv.jpg, hsv); cout Done. gray channels: gray.channels() , hsv channels: hsv.channels() endl; return 0; }注意putText里Scalar(0, 255, 0)是 BGR 顺序的绿色。如果你刚转完 HSV 图千万别直接用 HSV 的像素值作为 BGR 颜色去画文字那会得到一个看起来很诡异的颜色。再来一个配套的CMakeLists.txtcmake_minimum_required(VERSION 3.10) project(cvtcolor_demo) find_package(OpenCV REQUIRED) add_executable(demo tutorial.cpp) target_link_libraries(demo ${OpenCV_LIBS})编译cmake -B build cmake --build build ./build/demo test.jpg如果 cmake 找不到 OpenCV多半是没装开发包或者装了但环境变量没配好。可以在终端先手动pkg-config --cflags --libs opencv4看看有没有输出再排查。4.3 Python 快速脚本Python 写法更短适合快速验证想法import cv2 src cv2.imread(test.jpg) if src is None: raise FileNotFoundError(cannot load image) gray cv2.cvtColor(src, cv2.COLOR_BGR2GRAY) hsv cv2.cvtColor(src, cv2.COLOR_BGR2HSV) label Linux43: cvtColor putText cv2.putText(src, label, (30, 60), cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 0), 2, cv2.LINE_AA) cv2.imwrite(output_src.jpg, src) cv2.imwrite(output_gray.jpg, gray) cv2.imwrite(output_hsv.jpg, hsv)在 Python 里踩过最深的一个坑是想用 matplotlib 显示灰度图直接plt.imshow(gray)结果画面全是蓝色调的伪彩色。原因很简单matplotlib 默认用 colormap 渲染单通道图必须显式指定cmapgray才不吓人。5. 常见问题排查与速查表5.1 高频错误对照表现象根本原因解决方案图像红蓝互换BGR/RGB 通道顺序错误使用COLOR_BGR2RGB转换灰度图在 matplotlib 里发蓝单通道图被默认 colormap 渲染plt.imshow(gray, cmapgray)inRange结果全黑HSV 的 H 范围写错确认 OpenCV 中 H 范围是 0–179putText 中文全是问号内置字体不支持中文使用 freetype 或 PIL文字跑到画面外面org坐标理解错误确认org是左下角先用getTextSize量尺寸imshow直接报错系统缺少 GUI 依赖安装 GTK/Qt 开发库或改用imwritecvtColor报错 assertion failed输入通道数与转换码不匹配检查图像通道数必要时先reshape或转换位深5.2 颜色识别调参技巧实录做颜色识别时我建议先用下面这段代码把 HSV 上下界调出来再固化到项目里import cv2 import numpy as np image cv2.imread(color_sample.jpg) hsv cv2.cvtColor(image, cv2.COLOR_BGR2HSV) # 临时调参用的滑块 def nothing(x): pass cv2.namedWindow(mask) cv2.createTrackbar(H min, mask, 0, 179, nothing) cv2.createTrackbar(H max, mask, 179, 179, nothing) cv2.createTrackbar(S min, mask, 0, 255, nothing) cv2.createTrackbar(S max, mask, 255, 255, nothing) cv2.createTrackbar(V min, mask, 0, 255, nothing) cv2.createTrackbar(V max, mask, 255, 255, nothing) while True: h_min cv2.getTrackbarPos(H min, mask) h_max cv2.getTrackbarPos(H max, mask) s_min cv2.getTrackbarPos(S min, mask) s_max cv2.getTrackbarPos(S max, mask) v_min cv2.getTrackbarPos(V min, mask) v_max cv2.getTrackbarPos(V max, mask) lower np.array([h_min, s_min, v_min]) upper np.array([h_max, s_max, v_max]) mask cv2.inRange(hsv, lower, upper) cv2.imshow(mask, mask) key cv2.waitKey(100) 0xFF if key in (27, ord(q)): break cv2.destroyAllWindows()调好后把滑块停下来的参数写进代码。真实场景中光照会变建议采集多个时段、多个角度的样本去调不要只拿一张干净的示例图。5.3 实时视频里叠加文字的经验在视频流里用putText时有一种做法容易让画面越来越花直接对frame这个 Mat 不断叠加文字而且文字内容变化很快结果上一帧的文字和下一帧的文字叠在一起。正确做法是在每一帧处理时要么基于原始帧frame.clone()再画文字要么先对画面做处理再 copy 到输出层上画。文字叠加本身开销不大真正要关注的是别把大量中文字体渲染放进 hot path不然帧率下降是立竿见影的。还有一个经验调试时我会在左上角写当前帧号右上角写处理耗时底部写当前算法状态。这样即使没有录屏回看保存的视频也能完整还原运行过程。配合putText的thickness参数在暗色背景上用 2 像素的白色文字外再加一层 1 像素的黑色文字底边可读性会大幅提升具体做法是同一个文字画两次第一次用黑色粗一点第二次用目标颜色整体向上偏移一点。这个项目做到最后我自己比较深的体会是cvtColor和putText看似是 API 调用实际涉及的是颜色理论基础、坐标系理解、字体渲染兼容性这些底层认知。在 Linux 下干活没有 IDE 帮你兜底报错也经常是含糊的一句话把这两个函数吃透等于把视觉调试的地基打牢了。后面不管是做深度学习预处理还是嵌入式板卡上的实时检测都会顺很多。