简介一份基于OpenCV的物体正样本标注工具源码包面向需要构建自定义识别数据集的计算机视觉初学者与开发者解决训练集中正样本边界框信息难以批量生成的问题。工具支持鼠标框选目标区域自动记录坐标并输出规范文本方便后续接入目标检测或图像分类模型的训练流程。压缩包内含10个文件、约1.01MB包括C源码、可直接运行的exe程序、OpenCV动态库、示例位图及说明文档在Windows环境打开即可体验完整标注流程也可对照源码理解具体实现。目前已有291人学习下载。对需要构建小众类别检测数据的开发者这份资源既提供可立即使用的标注工具也给出从鼠标交互到边界框坐标自动落盘的关键实现路径同时示例文件与说明文档能帮助理解信息记录格式缩短自研标注工具的上手时间。1. objectmarker把正样本描述生成从手工填表变成鼠标画框第一次用 OpenCV 训练级联分类器识别某个特定物体时我在最蠢的环节卡了整整一个晚上——手写正样本描述文件。每行都要填图片路径、目标个数、x、y、宽高标 300 张图等于复制粘贴 300 次稍有不慎坐标算错就要返工。objectmarker 就是为解决这个痛点写的在图片上用鼠标拖一个框松开自动写入一行描述按 n 换下一张、按 q 退出标完把描述文件直接丢给 opencv_createsamples 生成 .vec。它不是花哨的 GUI 工具而是一个把 OpenCV 识别正样本标注变成“画框”的轻量源码项目适合所有卡在数据集准备阶段的开发者也适合想研究 OpenCV 鼠标交互和训练数据管线的人。2. 定位与架构一个为级联分类器训练服务的小工具2.1 描述文件在整个训练管线中的位置用 OpenCV 做目标检测训练经典路线是四步准备正样本图片 → 生成正样本描述文件 → 用 opencv_createsamples 生成 .vec 向量文件 → 用 opencv_traincascade 训练级联分类器。objectmarker 干的是第二步也就是把“人眼看到目标”转成“训练器能读懂的文本描述”。这一步看起来简单实际是整条流水线里返工率最高的环节。描述文件的格式非常死板每一行对应一张图片中的一个目标img/pos_001.jpg 1 320 180 96 96 img/pos_002.jpg 1 128 64 80 80第一个字段是图片路径第二个字段是这张图里的目标数量后面每四个数字为一组分别代表目标的左上角 x、左上角 y、宽度、高度。手写这种文件时人眼在图片上定位坐标的误差极大尤其是目标一多或者图片分辨率一高框选的位置和填写的坐标经常对不上。objectmarker 的核心价值是让坐标由鼠标直接产生省掉“目测坐标”这层不靠谱的中间转换。这里要注意一个边界objectmarker 只负责生成描述文本不负责生成 .vec也不负责训练。后续的 opencv_createsamples 和 opencv_traincascade 是 OpenCV 自带的命令行工具描述文件只是它们的输入。理解了这个分工你就知道这个工具改起来为什么那么轻——它所有逻辑都围绕“怎么把鼠标轨迹变成一行格式正确的文本”展开。2.2 目录设计与交互模型为什么用 C highgui 而不是 Qt拿到这份源码第一眼会看到它没有引入任何 GUI 框架也没有数据库和配置文件整个工程就是一个典型的 C 命令行小工具。我一般会把这种项目的目录拆成下面这个样子鼠标交互和文件写出分开后续加功能不互相踩脚objectmarker/ ├── main.cpp # 入口参数解析、加载图片、注册回调 ├── marker.cpp/h # 鼠标框选逻辑、坐标状态 ├── writer.cpp/h # 描述文件写出、路径拼接 ├── CMakeLists.txt # 构建脚本 └── samples/ # 测试图片交互模型是基于 OpenCV 的 highgui 模块做的。highgui 的窗口系统虽然简陋但它有一个杀手级能力setMouseCallback 可以直接把鼠标事件绑定到窗口上回调里能拿到事件类型、坐标、按键状态。做标注工具正好够用——不需要菜单、不需要工具栏、不需要拖动缩放需要的只是一张图和一只鼠标。选 C 而不是 Python是因为 opencv_createsamples 和 opencv_traincascade 本身就是命令行工具用 C 写标注工具可以和它们编进同一个环境部署到采集机器上不用装 Python 解释器依赖只有一个 OpenCV 动态库。整个程序的事件模型是一个典型的“显示-回调-按键”循环主线程不断重绘画面鼠标回调修改内部状态键盘按键触发写出或切换图片。下面进入核心代码。3. 核心代码拆解鼠标回调、缩放映射与描述文件写出3.1 鼠标回调一次拖拽如何变成一组坐标objectmarker 最关键的一段代码是鼠标回调函数。setMouseCallback 要求回调是普通函数或静态函数没法直接捕获 lambda所以常见做法是把状态放在全局变量里或者用一个结构体指针通过 param 参数传进去。下面这段是核心逻辑struct MarkerState { cv::Mat src; // 原始图片 cv::Mat display; // 缩放后的显示图片 cv::Point start; // 拖拽起点 cv::Point end; // 拖拽终点 bool dragging; // 是否正在拖拽 double scale; // 显示缩放比例 std::vectorcv::Rect boxes; // 已框选的目标列表 }; void onMouse(int event, int x, int y, int flags, void* param) { auto* state static_castMarkerState*(param); if (event cv::EVENT_LBUTTONDOWN) { state-dragging true; state-start cv::Point(x, y); state-end state-start; } else if (event cv::EVENT_MOUSEMOVE state-dragging) { state-end cv::Point(x, y); // 移动时持续更新终点 } else if (event cv::EVENT_LBUTTONUP) { state-dragging false; // 直接用 Rect 构造它会自动归一化左上角和宽高 cv::Rect box(state-start, state-end); state-boxes.push_back(box); } }onMouse 的五个参数是 OpenCV 鼠标回调的固定签名event 是事件类型x 和 y 是当前鼠标在窗口中的坐标flags 表示是否按下 Ctrl/Shift 等组合键param 是 setMouseCallback 注册时传入的任意指针。回调里只在 MOUSEMOVE 时更新终点不做画图——画图交给主循环统一处理避免在回调里操作窗口造成重绘冲突。这里有个容易被忽视的细节cv::Rect(start, end) 的构造函数会自动处理拖拽方向。不管你从左上拖到右下还是从右下拖到左上得到的 Rect 的 x、y 永远是左上角width 和 height 永远是正值。如果自己用 end.x - start.x 这种方式算宽高拖反了就会出现负值写进描述文件后 opencv_createsamples 会直接报错。这段代码能帮你躲掉一个隐蔽的坑。3.2 主循环与按键逻辑实时预览、切换图片与写出鼠标回调只负责改状态真正让程序“动起来”的是主循环。每次循环里把当前所有已框选的矩形画到画面上让用户随时看到已经标了哪些目标如果正在拖拽还要画一个当前拖拽的临时矩形void run(MarkerState* state, const std::string imgPath) { cv::namedWindow(objectmarker, cv::WINDOW_NORMAL); cv::setMouseCallback(objectmarker, onMouse, state); while (true) { cv::Mat frame state-display.clone(); for (const auto r : state-boxes) { cv::rectangle(frame, r, cv::Scalar(0, 255, 0), 2); } if (state-dragging) { cv::rectangle(frame, cv::Rect(state-start, state-end), cv::Scalar(0, 0, 255), 1); } cv::imshow(objectmarker, frame); int key cv::waitKey(30); if (key q) break; // 退出程序 if (key n) { // 写出当前图片并清空列表 writeInfoFile(state, imgPath); state-boxes.clear(); } if (key z !state-boxes.empty()) { state-boxes.pop_back(); // 撤销上一个框 } } }waitKey(30) 的作用是让 OpenCV 处理窗口事件并返回用户按键30 表示最多阻塞 30 毫秒。返回值必须用 int 接收后面避坑章节会专门讲这一点。注意这里的重绘策略是每次全量重画所有矩形而不是只在鼠标移动时局部刷新——对标注这种交互频率不高的场景全量重绘代码简单得多性能也完全够用。3.3 描述文件写出坐标到 info.txt 的格式化细节写出逻辑是最后一个关键模块。这里最需要注意的是坐标映射如果原始图片分辨率太大显示时做了缩放鼠标回调拿到的坐标是窗口坐标而描述文件要求的是原始图片坐标。不乘回缩放比例标注位置会整体偏移。下面这段代码包含映射和格式化void writeInfoFile(MarkerState* state, const std::string imgPath) { FILE* fp fopen(info.txt, a); // 追加写支持多张图片累积 if (!fp) return; for (const auto r : state-boxes) { int x cvRound(r.x / state-scale); int y cvRound(r.y / state-scale); int w cvRound(r.width / state-scale); int h cvRound(r.height / state-scale); fprintf(fp, %s 1 %d %d %d %d\n, imgPath.c_str(), x, y, w, h); } fclose(fp); printf(wrote %zu boxes\n, state-boxes.size()); }fprintf 的格式串必须严格匹配描述文件规范路径、空格、目标数量 1、空格、x、空格、y、空格、w、空格、h、换行。目标数量写死为 1因为每张图片逐框追加一行每行只描述一个目标。如果一张图里标了多个目标就会有多个行指向同一张图片每行的目标数量都是 1。路径字段我建议用相对路径相对你后续运行 opencv_createsamples 的工作目录。这个细节看起来不起眼实际踩坑率极高——写绝对路径换台机器跑就废了写相对路径又容易和训练时的工作目录对不上。最稳的做法是启动训练前先把 info.txt 放在和图片目录同一级然后工作目录也切到这一级再跑 createsamples。4. 编译、运行与验证从源码到可训练的样本集4.1 CMake 构建与 OpenCV 依赖这个项目依赖只有一个 OpenCV编译用 CMake 就够了。CMakeLists.txt 写起来很常规核心是 find_package 找到 OpenCV 库然后链接进来cmake_minimum_required(VERSION 3.10) project(objectmarker) find_package(OpenCV REQUIRED) add_executable(objectmarker main.cpp marker.cpp writer.cpp) target_link_libraries(objectmarker ${OpenCV_LIBS})编译前先确认环境里装了 OpenCV 开发库。在 Debian/Ubuntu 系系统上常见做法是安装 libopencv-dev 这个包macOS 上用 Homebrew 装 opencvWindows 上则用 vcpkg 或官方预编译包。装好之后编译过程就是标准三步mkdir build cd build cmake .. make -j$(nproc)编译产物是一个名为 objectmarker 的可执行文件。如果在 make 阶段报找不到 OpenCV 头文件多半是 find_package 没找到库路径检查一下 OpenCV_DIR 环境变量有没有指向正确的安装位置。4.2 运行参数与标注操作流程这个工具的交互是参数驱动的。我设计的命令行接口足够简单任何图片文件路径可以直接作为第一个参数传入另外留了三个可选参数参数作用默认值图片路径要标注的原始图片必填-o 文件路径描述文件输出位置info.txt-s 数值显示缩放比例1.0-d 目录路径批量标注目录下所有图片关闭实际启动示例./objectmarker ../samples/001.jpg -o ../info.txt -s 0.5启动后窗口里显示图片操作流程是鼠标左键按下拖出矩形框住目标松开左键完成一次框选按 z 撤销上一个框按 n 把当前所有框写入描述文件并继续标注下一张按 q 退出。每按一次 ninfo.txt 里就追加一行格式是../samples/001.jpg 1 640 360 192 192注意这里的坐标已经被 scale 除过了写进文件的是原始图片坐标。如果后续发现坐标偏了先检查是不是忘记传 -s 参数导致映射失效。4.3 用 opencv_createsamples 验证描述文件描述文件写完不等于合格最直接的验证方法是用 OpenCV 自带的 opencv_createsamples 工具走一遍生成流程opencv_createsamples -info info.txt -vec pos.vec -w 24 -h 24 -num 200这条命令会读取 info.txt 里的每一行描述把对应图片的目标区域裁剪出来缩放到 24×24 的固定尺寸写入 pos.vec。如果描述文件有格式错误——坐标超出图片边界、宽高为 0、图片路径找不到——这个命令会立刻报错并提示具体是哪一行出了问题。这里有个关键认知-w 和 -h 是输出样本的归一化尺寸不是你在标注时框选的目标大小。训练级联分类器时所有正样本都会被缩放到这个尺寸所以它只和训练配置有关和标注框大小无关。很多新手在这里把 -w -h 填成框选的宽高导致样本被拉伸变形训练出来的分类器识别率一塌糊涂。提示验证时用 -num 参数控制生成的样本数量建议先用 -num 50 跑一个小批量测试确认格式无误后再全量生成。5. 避坑手册标注正样本时最容易翻车的 5 个细节5.1 拖拽方向导致负宽高现象框选时从右下角往左上角拖生成的描述行里出现负数宽高opencv_createsamples 报 “Invalid rectangle”。原因手工计算坐标时用 end.x - start.x 求宽高拖拽方向和预期相反时得到负值。解决用 cv::Rect(start, end) 构造矩形它会自动归一化。如果已经写进文件了写一个脚本按绝对值清洗一遍坐标或者直接在代码里判断 start.x 与 end.x 的大小关系再计算。这个坑在第一次使用任何标注工具时几乎必踩。5.2 显示缩放后坐标整体偏移现象高分辨率图片在窗口里缩小显示后框选位置看起来准生成的坐标却整体偏了目标实际框住的区域比标注的小一圈。原因鼠标回调拿到的是窗口坐标文件里需要的是原图坐标。没有把宽高乘回缩放比例或者乘反了除。解决在写文件前统一除以 scale。这里要注意 scale 的计算方式如果显示尺寸是原图的一半scale 就是 0.5写文件时要用 cvRound(r.x / scale) 也就是乘 2。建议在程序启动时打印 scale 的值第一次运行先标一张图打开文件对比坐标是否符合预期。5.3 中文路径与空格路径读取失败现象图片放在带中文或空格的目录下程序启动后窗口里一片黑imread 返回空 Mat但路径明明没错。原因OpenCV 的 imread 在 Windows 上默认使用窄字符编码中文路径会解析失败空格路径在某些平台下也会因为路径拼接问题读取失败。解决把所有标注图片路径统一改成纯 ASCII 字符目录名不要带空格。如果实在避免不了Linux 上可以对路径做 UTF-8 兼容处理Windows 上则要用 imread 的重载版本传入宽字符路径。血泪经验标注工作开始前先整理目录结构不要标到一半再改路径。5.4 一张图多个目标时描述行拆分错误现象一张图片里有 3 个目标info.txt 里生成了 3 行每行目标数量都是 1。训练时发现正样本数量暴增且同一张图被反复采样。原因逐框追加的策略和 opencv_createsamples 的采样逻辑不匹配。createsamples 会按行读取每行独立生成一个样本同一张图三行会导致一张图被采样三次样本之间高度相关影响分类器泛化能力。解决一张图的所有目标合并成一行写形如img.jpg 3 x1 y1 w1 h1 x2 y2 w2 h2 x3 y3 w3 h3。objectmarker 的源码里可以加一个合并逻辑按图片路径分组同一张图的框全部攒齐按 n 时一次性写出目标数量等于框的个数。5.5 waitKey 返回值类型导致按键失灵现象按 z 撤销没反应按 n 偶尔失效或者按一次 q 要两下才能退出。原因waitKey 返回 int如果代码里用 char 接收某些按键的高位会被截断导致按键值判断错误。这个坑非常隐蔽程序看起来在跑就是按键逻辑时灵时不灵。解决所有 waitKey 返回值统一用 int 声明接收判断时直接和字符常量比较。这是 OpenCV 初学者最容易忽视的类型问题排查时先看这里。6. 二次开发把「框选生成描述」扩展成半自动标注管线这份源码到手后第一件事不是去调框选的颜色而是往半自动化方向改。我建议按优先级做三个改造撤销功能已经在主循环里给了雏形批量目录标注是最实用的一步多尺度导出则能直接提升训练效果。批量目录标注的改法很直接把参数解析里的单图片入口改成目录遍历。用 cv::glob 读取目录下所有图片逐张进入标注循环按 n 自动跳到下一张所有描述追加到同一个 info.txt。这样标注 300 张图的操作从“启动 300 次程序”变成“一次启动标完喝水”。核心改动只有十来行std::vectorcv::String files; cv::glob(../images/*.jpg, files, false); for (const auto f : files) { loadImage(f); runMarkLoop(); // 按 n 时写文件并继续下一张 }多尺度导出是另一个值得动手的点同一个目标框按 0.8、1.0、1.2 三个比例各写一组坐标描述文件里同一目标就有三种尺寸的样本。OpenCV 传统的 Haar 和 LBP 特征对尺度变化敏感多尺度正样本能显著提升识别鲁棒性。改的时候在写文件函数里加一个倍数循环乘到宽高上再输出注意不要超图片边界。还有一个容易忽略的验证习惯改完代码后每标完一组样本先用 createsamples 跑一遍小批量验证再进训练环节。这样能把格式错误拦截在上游而不是让训练器报一屏看不懂的日志。从那以后我每次标完正样本都会强制走这一遍再没被训练器报错卡过整晚。希望帮到你。本文还有配套的精品资源点击获取
