简介ObjectMarker是一个基于OpenCV的正样本标注工具面向需要制作自定义物体识别数据集的开发者和学习者。它通过鼠标框选图像中的目标区域自动记录边界框坐标并生成info.txt描述文件为后续训练识别模型提供规范的正样本数据尤其适合难以在公开数据集中找到的小众类别对象。压缩包共10个文件大小约1.01MB包含可直接运行的exe程序、核心C源码、依赖的dll运行库、样例bmp图像以及readme和info说明文件结构简洁便于快速评估与二次开发。目前已有289人学习浏览使用者既能直接运行工具完成图像标注也能通过源码理解OpenCV鼠标交互与坐标记录的实现细节还可以参照info.txt文件格式扩展多图像批量标注流程进一步提升数据准备效率。对于刚接触OpenCV或正在构建私有训练数据集的读者这是一份轻量且可自定义的实用参考。 做目标检测项目的人都知道最磨人的环节往往不是搭模型、调参数而是准备数据。模型训练之前你必须先把每张图里哪里有目标、目标是什么类别、目标框怎么圈这些信息写清楚这就是正样本描述的来源。ObjectMarker这个名字很直白——它要做的事情就是帮你把图像里的正样本区域快速标出来然后自动生成训练框架能直接读取的描述文件。我最初写这个工具纯粹是因为手工编辑标注格式太容易出错了后来发现它对小批量数据、快速验证模型场景特别实用所以就把源码整理了出来。这篇文章适合正在学习目标检测、需要自己做数据标注或者想摆脱重复性标注工作的人阅读。如果你已经用LabelImg这类工具感觉很顺手看完这篇也能理解标注文件底层的字段逻辑后面碰到格式转换、批量修改类名这类需求自己写脚本会更有底气。1. 为什么偏偏要自己写一个正样本标注工具市面上并不缺标注工具LabelImg、LabelMe、CVAT都是成熟方案功能比我这个小工具丰富得多。但我实际用下来发现很多场景下它们其实有点杀鸡用牛刀。比如我只是想快速验证一个检测思路手上只有几十张图或者客户的图片命名规则很特殊类名需要在导出时统一映射成英文又或者我需要在没有图形界面的服务器上跑标注流程。这些情况下打开一个重型工具反而拖慢进度。另一个重要原因是手工改标注文件太容易出错了。我早期做数据集时曾经手写过YOLO格式的txt文件坐标是归一化小数六位有效数字稍不留神就把宽高算错或者把类别ID写歪。一个文件错了训练时模型要么直接忽略这张图要么产生一个离谱的预测框。标注工作看似简单实际是在跟格式、坐标、命名规则较劲。ObjectMarker的设计思路就是围绕正样本描述这四个字来的。它只做两件事第一我用鼠标在图上圈出目标区域第二它把圈出来的框自动换算成训练需要的描述格式保存到对应的文件里。目标检测任务的正样本是什么就是图像中真实存在待检目标的那块区域它包含完整的类别信息和边界信息。负样本则是纯背景区域训练时通常由数据加载器从图像中随机裁剪出来不需要人工标注。所以标注工作的核心产出就是一条条这个框属于哪个类、坐标是多少的描述也就是标题里说的正样本描述。我自己写工具还有个私心把一个标注器从零写一遍能逼着你把整个数据链路彻底搞清楚。鼠标拖动画框只是表面功夫真正核心的部分是坐标换算和文件序列化这两块搞明白了后面不管换什么训练框架数据准备对你来说都不是黑盒。2. 正样本描述长什么样三种主流格式的底层差异要理解ObjectMarker为什么要专门做格式生成先得知道我们最终产出的是什么。目前主流检测框架使用的正样本描述格式大致有三类它们的组织方式差别挺大。YOLO系列使用的txt描述文件是最紧凑的。每张图片对应一个同名txt文件文件里每一行代表一个正样本字段依次是类别ID、归一化中心点x坐标、归一化中心点y坐标、归一化宽度、归一化高度。所有坐标值都在0到1之间用浮点数表示。归一化的意思是把坐标除以图像宽高这样不同分辨率图片训练时尺度统一。它的优点是解析快、文件小缺点是可读性差人眼几乎看不出内容对不对。PASCAL VOC格式的XML文件则完全是另一种风格。它把整张图的各种信息包在一个树状结构里文件名、图像尺寸、物体类别、边界框的绝对像素坐标全部齐备。最外面是annotation根节点下面有filename、size再往下每个object节点对应一个正样本object里有name、pose、truncated、difficult这些描述字段边界框用xmin、ymin、xmax、ymax四个绝对坐标记录。这种格式适合人读也适合存额外的物体属性但文件体积大解析稍重。COCO格式的JSON文件是目前学术数据集的主流。它把图片信息、类别信息、标注信息分开存放通过ID互相关联。images数组存每张图的id和宽高categories数组存类别id和名称annotations数组存每个标注框所属的image_id、category_id、bbox四个值这里的bbox格式是x、y、width、height顺序和VOC的xmin、ymin、xmax、ymax不一样转换时特别容易踩坑。ObjectMarker默认输出YOLO和VOC两种格式原因是我日常用的检测框架基本都支持这两种。JSON格式通常由官方工具链统一生成个人小项目很少直接手写。掌握这三种格式的差别你就能明白为什么一个标注工具的核心不只是画框还包括怎样把像素坐标正确映射到不同格式。格式文件形态坐标体系类别表示文件体积适用场景YOLO txt每图一个txt归一化浮点类别ID极小快速训练、嵌入式部署VOC XML每图一个xml绝对像素类别名称较大数据可读性要求高、跨工具交换COCO JSON整个数据集一个json绝对像素类别ID 名称映射视规模而定大规模数据集、学术评测3. ObjectMarker源码拆解从鼠标画框到描述文件落地工具的核心逻辑其实不复杂我用的技术栈是Python加OpenCV依赖非常少。整个程序运行一个OpenCV窗口鼠标左键按下确定矩形的左上角拖动过程中动态画框松开后矩形自动锁定并归属于当前选中的类别。所有已画出的框以绿色显示最新待确认的框用红色显示。类别切换通过键盘数字键完成快捷键保存并跳到下一张图片。以下是核心类的主干代码import cv2 import os class ObjectMarker: def __init__(self, image_dir, output_dir, class_names): self.image_dir image_dir self.output_dir output_dir self.class_names class_names self.class_id 0 self.image_paths [ os.path.join(image_dir, f) for f in os.listdir(image_dir) if f.lower().endswith((.jpg, .jpeg, .png)) ] self.image_paths.sort() self.current_idx 0 self.rects [] self.drawing False self.start (0, 0) self.end (0, 0) def load_current_image(self): self.image cv2.imread(self.image_paths[self.current_idx]) self.canvas self.image.copy() self.rects [] def mouse_callback(self, event, x, y, flags, param): if event cv2.EVENT_LBUTTONDOWN: self.drawing True self.start (x, y) elif event cv2.EVENT_MOUSEMOVE: if self.drawing: self.canvas self.image.copy() for (x1, y1, x2, y2, cid) in self.rects: cv2.rectangle(self.canvas, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(self.canvas, self.class_names[cid], (x1, max(0, y1 - 5)), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) cv2.rectangle(self.canvas, self.start, (x, y), (0, 0, 255), 2) elif event cv2.EVENT_LBUTTONUP: self.drawing False self.end (x, y) x1, y1 min(self.start[0], self.end[0]), min(self.start[1], self.end[1]) x2, y2 max(self.start[0], self.end[0]), max(self.start[1], self.end[1]) if x2 - x1 5 and y2 - y1 5: self.rects.append((x1, y1, x2, y2, self.class_id))鼠标回调函数是交互的关键。EVENT_LBUTTONDOWN记录起点拖动时重绘画布确保之前标注的框不消失松手时再去掉误点击的小框。为什么过滤掉宽或高小于5像素的框因为实际标注中小于这个尺寸的矩形几乎都是误触直接丢弃可以避免生成大量噪声标注。类别切换和保存逻辑这样实现def key_callback(self, key): if ord(0) key ord(9): cid key - ord(0) if cid len(self.class_names): self.class_id cid print(f当前类别: {self.class_names[cid]}) elif key ord(s) or key ord(S): self.save_current() self.next_image() elif key 27: return False return True保存操作是整个工具的落点。程序会把内存里的矩形列表转换为YOLO或VOC格式并写入磁盘。这里最核心的是坐标换算下一节详细展开。4. 坐标归一化算错了模型根本训不好YOLO格式要求所有坐标归一化到0到1之间这个步骤看起来只是简单的除法但细节上至少有三个容易翻车的地方。第一中心点坐标计算。矩形左上角是(x1, y1)右下角是(x2, y2)中心点坐标是((x1 x2) / 2, (y1 y2) / 2)宽度是x2 - x1高度是y2 - y1。这个逻辑很简单但不少人会想当然地用x1加上宽度的一半写出来其实结果是一样的但形式容易错。我把换算函数写成下面这样确保所有除法都用浮点数def normalize_yolo_box(self, box, img_w, img_h): x1, y1, x2, y2 box x_center ((x1 x2) / 2.0) / img_w y_center ((y1 y2) / 2.0) / img_h w (x2 - x1) / float(img_w) h (y2 - y1) / float(img_h) x_center min(max(x_center, 0.0), 1.0) y_center min(max(y_center, 0.0), 1.0) w min(max(w, 0.0), 1.0) h min(max(h, 0.0), 1.0) return x_center, y_center, w, h第二归一化必须相对于原图尺寸。有的工具为了界面显示方便把大图缩放成固定宽度预览然后在缩放后的图上标注。如果保存时忘记把坐标映射回原图尺寸训练时框的位置就是偏移的。ObjectMarker直接在原图上操作不缩放所以不存在这个映射问题。但红花也要绿叶衬如果你拿到手的标注工具是基于预览图标注的导出前一定要确认内部是否做了反向换算。第三越界裁剪。目标贴着图像边缘时矩形框可能会超出图像范围。如果不做clip归一化后的坐标可能大于1或者小于0训练框架读到非法坐标会报错或者把这个框当作异常样本丢掉。所以上面函数里做了min(max())的截断处理。VOC格式的XML坐标是绝对像素相对简单但也有一套字段必须完整。保存XML我用的是Python标准库xml.etree.ElementTree核心片段如下import xml.etree.ElementTree as ET def save_voc_xml(self, image_path, rects, xml_path): img cv2.imread(image_path) h, w img.shape[:2] root ET.Element(annotation) ET.SubElement(root, filename).text os.path.basename(image_path) size ET.SubElement(root, size) ET.SubElement(size, width).text str(w) ET.SubElement(size, height).text str(h) ET.SubElement(size, depth).text 3 for x1, y1, x2, y2, cid in rects: obj ET.SubElement(root, object) ET.SubElement(obj, name).text self.class_names[cid] ET.SubElement(obj, pose).text Unspecified ET.SubElement(obj, truncated).text 0 ET.SubElement(obj, difficult).text 0 bndbox ET.SubElement(obj, bndbox) ET.SubElement(bndbox, xmin).text str(max(int(x1), 0)) ET.SubElement(bndbox, ymin).text str(max(int(y1), 0)) ET.SubElement(bndbox, xmax).text str(min(int(x2), w - 1)) ET.SubElement(bndbox, ymax).text str(min(int(y2), h - 1)) tree ET.ElementTree(root) tree.write(xml_path, encodingutf-8, xml_declarationTrue)写XML时有一个细节很多人会忽略xmax、ymax不能等于图像宽度和高度而应该是宽度减一、高度减一。因为像素坐标从0开始一幅宽度为w的图像有效横坐标是0到w-1。取w作为边界虽然数学上没错但严格来说超出了像素索引范围部分解析器会因此判定框越界。5. 用ObjectMarker跑一个真实的小样本训练闭环工具写出来不是拿来当摆件的我把它用在一个实际的小项目里做验证。项目内容是在传送带图片上检测两种金属零件——螺丝和垫片。图片是我用手机拍的总共120张分辨率是1920x1080内容包含单目标和多目标光照变化比较大。启动标注时我建立一个类名列表class_names [screw, washer] marker ObjectMarker(images/, labels/, class_names)标注过程没什么特殊的就是逐张图圈目标、按数字键切换类别、按s保存跳下一张。120张图大概花了四十分钟画了300多个框。保存之后labels目录下出现了120个txt文件对应120张图其中有11张图是空的。这里我要特别说明空txt文件是有意义的表示这张图里没有任何检测目标是标准的负样本图。在YOLO训练中这种空文件告诉加载器这张图不用采样正样本是合法状态。但如果你的数据集中目标很少、空图太多模型会倾向于把所有区域都预测为背景这时候需要调整数据组成比例或者使用难例挖掘策略。随后我用YOLOv8做了快速验证。训练命令很简单图片和标签按YOLO要求的目录结构放好即可yolo detect train datadataset.yaml modelyolov8s.pt epochs100 imgsz640 batch16dataset.yaml文件里指定训练、验证图片路径以及类别名称列表。关键字段如下path: ./dataset train: images/train val: images/val names: 0: screw 1: washer第一轮跑完mAP50在0.78左右。这个成绩不算高主要原因是部分螺丝和垫片在光照反射下特征接近人眼都容易看走眼。但是对比我之前手工标注时出现的格式问题这次训练过程一次通过没有出现坐标越界、类别映射错乱之类的低级错误说明描述文件生成这一环是稳的。6. 我在使用过程中踩过的坑和几个重要的优化方向第一个坑是中文路径问题。Windows下如果图片路径或者保存目录带中文OpenCV的imread经常读不出图返回None。脚本运行时不报错但后续保存尺寸时会直接抛异常。解决办法一是所有路径强制用英文二是在读图后加一个判空检查。我最后选择了在代码里增加检查逻辑这样路径万一有特殊字符立刻能发现是哪张图出了问题。第二个坑是EXIF旋转信息。手机拍的照片会自动记录拍摄时的朝向但OpenCV的imread默认不处理EXIF旋转。也就是说一张竖着拍的照片实际读入内存后可能变成横着的。这会导致我们看见的图像和保存的坐标基准不一致。我在标注前加了预处理用PIL的ImageOps.exif_transpose把图片统一转为正向再交给标注工具这样才能保证坐标映射正确。第三个坑是撤销功能缺失。画错的框如果没法撤销非常影响节奏。我后来又补了一个简单的撤销操作按z键移除最后一个框。实现起来就是一行列表pop操作但体验提升非常明显。再加上直接把整个工具做成翻页浏览模式标注完一张图后可以前后回看修改不用重新加载程序实用性上升了一个档次。还有几个可以继续完善的方向。一是自动保存每隔一定时间或者每切换一张图时自动触发保存防止程序崩溃丢数据。二是从已有txt文件反向加载框配合翻页浏览可以实现标注结果的快速检查和修正。三是生成描述时对目标框做轻微抖动增强在同一张图上生成多个略有差异的正样本描述这在数据量少的日子里能明显提升模型的鲁棒性。我实际用下来ObjectMarker这类按需手写的小工具和LabelImg最大的区别不在功能而在心智成本。遇到数据问题时我能直接打开源码定位是坐标算错了还是格式写反了而不是去查一个功能繁重工具的文档。标注工具本身不是一个值得炫耀的技术活但把标注描述这条流水线吃透后面的模型训练和推理部署都会顺利得多。如果你也需要批量准备正样本描述不妨照这个思路改造一把源码从我这边拿过去直接改class_names就能用。本文还有配套的精品资源点击获取
ObjectMarker：轻量级目标检测正样本标注与格式转换工具
简介ObjectMarker是一个基于OpenCV的正样本标注工具面向需要制作自定义物体识别数据集的开发者和学习者。它通过鼠标框选图像中的目标区域自动记录边界框坐标并生成info.txt描述文件为后续训练识别模型提供规范的正样本数据尤其适合难以在公开数据集中找到的小众类别对象。压缩包共10个文件大小约1.01MB包含可直接运行的exe程序、核心C源码、依赖的dll运行库、样例bmp图像以及readme和info说明文件结构简洁便于快速评估与二次开发。目前已有289人学习浏览使用者既能直接运行工具完成图像标注也能通过源码理解OpenCV鼠标交互与坐标记录的实现细节还可以参照info.txt文件格式扩展多图像批量标注流程进一步提升数据准备效率。对于刚接触OpenCV或正在构建私有训练数据集的读者这是一份轻量且可自定义的实用参考。 做目标检测项目的人都知道最磨人的环节往往不是搭模型、调参数而是准备数据。模型训练之前你必须先把每张图里哪里有目标、目标是什么类别、目标框怎么圈这些信息写清楚这就是正样本描述的来源。ObjectMarker这个名字很直白——它要做的事情就是帮你把图像里的正样本区域快速标出来然后自动生成训练框架能直接读取的描述文件。我最初写这个工具纯粹是因为手工编辑标注格式太容易出错了后来发现它对小批量数据、快速验证模型场景特别实用所以就把源码整理了出来。这篇文章适合正在学习目标检测、需要自己做数据标注或者想摆脱重复性标注工作的人阅读。如果你已经用LabelImg这类工具感觉很顺手看完这篇也能理解标注文件底层的字段逻辑后面碰到格式转换、批量修改类名这类需求自己写脚本会更有底气。1. 为什么偏偏要自己写一个正样本标注工具市面上并不缺标注工具LabelImg、LabelMe、CVAT都是成熟方案功能比我这个小工具丰富得多。但我实际用下来发现很多场景下它们其实有点杀鸡用牛刀。比如我只是想快速验证一个检测思路手上只有几十张图或者客户的图片命名规则很特殊类名需要在导出时统一映射成英文又或者我需要在没有图形界面的服务器上跑标注流程。这些情况下打开一个重型工具反而拖慢进度。另一个重要原因是手工改标注文件太容易出错了。我早期做数据集时曾经手写过YOLO格式的txt文件坐标是归一化小数六位有效数字稍不留神就把宽高算错或者把类别ID写歪。一个文件错了训练时模型要么直接忽略这张图要么产生一个离谱的预测框。标注工作看似简单实际是在跟格式、坐标、命名规则较劲。ObjectMarker的设计思路就是围绕正样本描述这四个字来的。它只做两件事第一我用鼠标在图上圈出目标区域第二它把圈出来的框自动换算成训练需要的描述格式保存到对应的文件里。目标检测任务的正样本是什么就是图像中真实存在待检目标的那块区域它包含完整的类别信息和边界信息。负样本则是纯背景区域训练时通常由数据加载器从图像中随机裁剪出来不需要人工标注。所以标注工作的核心产出就是一条条这个框属于哪个类、坐标是多少的描述也就是标题里说的正样本描述。我自己写工具还有个私心把一个标注器从零写一遍能逼着你把整个数据链路彻底搞清楚。鼠标拖动画框只是表面功夫真正核心的部分是坐标换算和文件序列化这两块搞明白了后面不管换什么训练框架数据准备对你来说都不是黑盒。2. 正样本描述长什么样三种主流格式的底层差异要理解ObjectMarker为什么要专门做格式生成先得知道我们最终产出的是什么。目前主流检测框架使用的正样本描述格式大致有三类它们的组织方式差别挺大。YOLO系列使用的txt描述文件是最紧凑的。每张图片对应一个同名txt文件文件里每一行代表一个正样本字段依次是类别ID、归一化中心点x坐标、归一化中心点y坐标、归一化宽度、归一化高度。所有坐标值都在0到1之间用浮点数表示。归一化的意思是把坐标除以图像宽高这样不同分辨率图片训练时尺度统一。它的优点是解析快、文件小缺点是可读性差人眼几乎看不出内容对不对。PASCAL VOC格式的XML文件则完全是另一种风格。它把整张图的各种信息包在一个树状结构里文件名、图像尺寸、物体类别、边界框的绝对像素坐标全部齐备。最外面是annotation根节点下面有filename、size再往下每个object节点对应一个正样本object里有name、pose、truncated、difficult这些描述字段边界框用xmin、ymin、xmax、ymax四个绝对坐标记录。这种格式适合人读也适合存额外的物体属性但文件体积大解析稍重。COCO格式的JSON文件是目前学术数据集的主流。它把图片信息、类别信息、标注信息分开存放通过ID互相关联。images数组存每张图的id和宽高categories数组存类别id和名称annotations数组存每个标注框所属的image_id、category_id、bbox四个值这里的bbox格式是x、y、width、height顺序和VOC的xmin、ymin、xmax、ymax不一样转换时特别容易踩坑。ObjectMarker默认输出YOLO和VOC两种格式原因是我日常用的检测框架基本都支持这两种。JSON格式通常由官方工具链统一生成个人小项目很少直接手写。掌握这三种格式的差别你就能明白为什么一个标注工具的核心不只是画框还包括怎样把像素坐标正确映射到不同格式。格式文件形态坐标体系类别表示文件体积适用场景YOLO txt每图一个txt归一化浮点类别ID极小快速训练、嵌入式部署VOC XML每图一个xml绝对像素类别名称较大数据可读性要求高、跨工具交换COCO JSON整个数据集一个json绝对像素类别ID 名称映射视规模而定大规模数据集、学术评测3. ObjectMarker源码拆解从鼠标画框到描述文件落地工具的核心逻辑其实不复杂我用的技术栈是Python加OpenCV依赖非常少。整个程序运行一个OpenCV窗口鼠标左键按下确定矩形的左上角拖动过程中动态画框松开后矩形自动锁定并归属于当前选中的类别。所有已画出的框以绿色显示最新待确认的框用红色显示。类别切换通过键盘数字键完成快捷键保存并跳到下一张图片。以下是核心类的主干代码import cv2 import os class ObjectMarker: def __init__(self, image_dir, output_dir, class_names): self.image_dir image_dir self.output_dir output_dir self.class_names class_names self.class_id 0 self.image_paths [ os.path.join(image_dir, f) for f in os.listdir(image_dir) if f.lower().endswith((.jpg, .jpeg, .png)) ] self.image_paths.sort() self.current_idx 0 self.rects [] self.drawing False self.start (0, 0) self.end (0, 0) def load_current_image(self): self.image cv2.imread(self.image_paths[self.current_idx]) self.canvas self.image.copy() self.rects [] def mouse_callback(self, event, x, y, flags, param): if event cv2.EVENT_LBUTTONDOWN: self.drawing True self.start (x, y) elif event cv2.EVENT_MOUSEMOVE: if self.drawing: self.canvas self.image.copy() for (x1, y1, x2, y2, cid) in self.rects: cv2.rectangle(self.canvas, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(self.canvas, self.class_names[cid], (x1, max(0, y1 - 5)), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) cv2.rectangle(self.canvas, self.start, (x, y), (0, 0, 255), 2) elif event cv2.EVENT_LBUTTONUP: self.drawing False self.end (x, y) x1, y1 min(self.start[0], self.end[0]), min(self.start[1], self.end[1]) x2, y2 max(self.start[0], self.end[0]), max(self.start[1], self.end[1]) if x2 - x1 5 and y2 - y1 5: self.rects.append((x1, y1, x2, y2, self.class_id))鼠标回调函数是交互的关键。EVENT_LBUTTONDOWN记录起点拖动时重绘画布确保之前标注的框不消失松手时再去掉误点击的小框。为什么过滤掉宽或高小于5像素的框因为实际标注中小于这个尺寸的矩形几乎都是误触直接丢弃可以避免生成大量噪声标注。类别切换和保存逻辑这样实现def key_callback(self, key): if ord(0) key ord(9): cid key - ord(0) if cid len(self.class_names): self.class_id cid print(f当前类别: {self.class_names[cid]}) elif key ord(s) or key ord(S): self.save_current() self.next_image() elif key 27: return False return True保存操作是整个工具的落点。程序会把内存里的矩形列表转换为YOLO或VOC格式并写入磁盘。这里最核心的是坐标换算下一节详细展开。4. 坐标归一化算错了模型根本训不好YOLO格式要求所有坐标归一化到0到1之间这个步骤看起来只是简单的除法但细节上至少有三个容易翻车的地方。第一中心点坐标计算。矩形左上角是(x1, y1)右下角是(x2, y2)中心点坐标是((x1 x2) / 2, (y1 y2) / 2)宽度是x2 - x1高度是y2 - y1。这个逻辑很简单但不少人会想当然地用x1加上宽度的一半写出来其实结果是一样的但形式容易错。我把换算函数写成下面这样确保所有除法都用浮点数def normalize_yolo_box(self, box, img_w, img_h): x1, y1, x2, y2 box x_center ((x1 x2) / 2.0) / img_w y_center ((y1 y2) / 2.0) / img_h w (x2 - x1) / float(img_w) h (y2 - y1) / float(img_h) x_center min(max(x_center, 0.0), 1.0) y_center min(max(y_center, 0.0), 1.0) w min(max(w, 0.0), 1.0) h min(max(h, 0.0), 1.0) return x_center, y_center, w, h第二归一化必须相对于原图尺寸。有的工具为了界面显示方便把大图缩放成固定宽度预览然后在缩放后的图上标注。如果保存时忘记把坐标映射回原图尺寸训练时框的位置就是偏移的。ObjectMarker直接在原图上操作不缩放所以不存在这个映射问题。但红花也要绿叶衬如果你拿到手的标注工具是基于预览图标注的导出前一定要确认内部是否做了反向换算。第三越界裁剪。目标贴着图像边缘时矩形框可能会超出图像范围。如果不做clip归一化后的坐标可能大于1或者小于0训练框架读到非法坐标会报错或者把这个框当作异常样本丢掉。所以上面函数里做了min(max())的截断处理。VOC格式的XML坐标是绝对像素相对简单但也有一套字段必须完整。保存XML我用的是Python标准库xml.etree.ElementTree核心片段如下import xml.etree.ElementTree as ET def save_voc_xml(self, image_path, rects, xml_path): img cv2.imread(image_path) h, w img.shape[:2] root ET.Element(annotation) ET.SubElement(root, filename).text os.path.basename(image_path) size ET.SubElement(root, size) ET.SubElement(size, width).text str(w) ET.SubElement(size, height).text str(h) ET.SubElement(size, depth).text 3 for x1, y1, x2, y2, cid in rects: obj ET.SubElement(root, object) ET.SubElement(obj, name).text self.class_names[cid] ET.SubElement(obj, pose).text Unspecified ET.SubElement(obj, truncated).text 0 ET.SubElement(obj, difficult).text 0 bndbox ET.SubElement(obj, bndbox) ET.SubElement(bndbox, xmin).text str(max(int(x1), 0)) ET.SubElement(bndbox, ymin).text str(max(int(y1), 0)) ET.SubElement(bndbox, xmax).text str(min(int(x2), w - 1)) ET.SubElement(bndbox, ymax).text str(min(int(y2), h - 1)) tree ET.ElementTree(root) tree.write(xml_path, encodingutf-8, xml_declarationTrue)写XML时有一个细节很多人会忽略xmax、ymax不能等于图像宽度和高度而应该是宽度减一、高度减一。因为像素坐标从0开始一幅宽度为w的图像有效横坐标是0到w-1。取w作为边界虽然数学上没错但严格来说超出了像素索引范围部分解析器会因此判定框越界。5. 用ObjectMarker跑一个真实的小样本训练闭环工具写出来不是拿来当摆件的我把它用在一个实际的小项目里做验证。项目内容是在传送带图片上检测两种金属零件——螺丝和垫片。图片是我用手机拍的总共120张分辨率是1920x1080内容包含单目标和多目标光照变化比较大。启动标注时我建立一个类名列表class_names [screw, washer] marker ObjectMarker(images/, labels/, class_names)标注过程没什么特殊的就是逐张图圈目标、按数字键切换类别、按s保存跳下一张。120张图大概花了四十分钟画了300多个框。保存之后labels目录下出现了120个txt文件对应120张图其中有11张图是空的。这里我要特别说明空txt文件是有意义的表示这张图里没有任何检测目标是标准的负样本图。在YOLO训练中这种空文件告诉加载器这张图不用采样正样本是合法状态。但如果你的数据集中目标很少、空图太多模型会倾向于把所有区域都预测为背景这时候需要调整数据组成比例或者使用难例挖掘策略。随后我用YOLOv8做了快速验证。训练命令很简单图片和标签按YOLO要求的目录结构放好即可yolo detect train datadataset.yaml modelyolov8s.pt epochs100 imgsz640 batch16dataset.yaml文件里指定训练、验证图片路径以及类别名称列表。关键字段如下path: ./dataset train: images/train val: images/val names: 0: screw 1: washer第一轮跑完mAP50在0.78左右。这个成绩不算高主要原因是部分螺丝和垫片在光照反射下特征接近人眼都容易看走眼。但是对比我之前手工标注时出现的格式问题这次训练过程一次通过没有出现坐标越界、类别映射错乱之类的低级错误说明描述文件生成这一环是稳的。6. 我在使用过程中踩过的坑和几个重要的优化方向第一个坑是中文路径问题。Windows下如果图片路径或者保存目录带中文OpenCV的imread经常读不出图返回None。脚本运行时不报错但后续保存尺寸时会直接抛异常。解决办法一是所有路径强制用英文二是在读图后加一个判空检查。我最后选择了在代码里增加检查逻辑这样路径万一有特殊字符立刻能发现是哪张图出了问题。第二个坑是EXIF旋转信息。手机拍的照片会自动记录拍摄时的朝向但OpenCV的imread默认不处理EXIF旋转。也就是说一张竖着拍的照片实际读入内存后可能变成横着的。这会导致我们看见的图像和保存的坐标基准不一致。我在标注前加了预处理用PIL的ImageOps.exif_transpose把图片统一转为正向再交给标注工具这样才能保证坐标映射正确。第三个坑是撤销功能缺失。画错的框如果没法撤销非常影响节奏。我后来又补了一个简单的撤销操作按z键移除最后一个框。实现起来就是一行列表pop操作但体验提升非常明显。再加上直接把整个工具做成翻页浏览模式标注完一张图后可以前后回看修改不用重新加载程序实用性上升了一个档次。还有几个可以继续完善的方向。一是自动保存每隔一定时间或者每切换一张图时自动触发保存防止程序崩溃丢数据。二是从已有txt文件反向加载框配合翻页浏览可以实现标注结果的快速检查和修正。三是生成描述时对目标框做轻微抖动增强在同一张图上生成多个略有差异的正样本描述这在数据量少的日子里能明显提升模型的鲁棒性。我实际用下来ObjectMarker这类按需手写的小工具和LabelImg最大的区别不在功能而在心智成本。遇到数据问题时我能直接打开源码定位是坐标算错了还是格式写反了而不是去查一个功能繁重工具的文档。标注工具本身不是一个值得炫耀的技术活但把标注描述这条流水线吃透后面的模型训练和推理部署都会顺利得多。如果你也需要批量准备正样本描述不妨照这个思路改造一把源码从我这边拿过去直接改class_names就能用。本文还有配套的精品资源点击获取