1. 做文本检测为什么我抛弃了矩形框标注先说结论paperclip是一个专门用来标注文本检测数据集的开源工具核心用途就是给 OCR 训练任务画多边形标注框。它解决的痛点很直白——文本在图片里很少是规规矩矩的水平矩形产品包装上的字可能是斜的路牌上的字可能带弧度广告海报上的字甚至排成不规则形状。如果你用 LabelImg 那种只能画矩形框的工具去标这些数据很快就会意识到一个问题矩形框会把大量背景像素包进来训练出来的模型在检测倾斜文本、弯曲文本时精度会明显下降。我最早做 OCR 数据准备时用的也是矩形框方案后来发现模型在验证集上 mAP 怎么都上不去排查半天才意识到是标注形式的问题——矩形框对水平文本没问题但对旋转文本它的 IoU 计算会产生巨大的噪声正负样本边界变得模糊。换了 paperclip 之后同样一套训练流程mAP 提升了差不多十个百分点而且模型的边缘定位能力肉眼可见地变好了。这个工具适合谁来用如果你是做 OCR、场景文本检测、文档分析这类视觉任务的工程师或研究者需要自己标注训练数据集那 paperclip 几乎是绕不开的选项。如果你只是偶尔标几张图那它可能有点杀鸡用牛刀但了解它的思路对你理解文本检测数据格式仍然很有帮助。这个项目虽然是老牌工具UI 也谈不上现代但在多边形文本标注这个细分领域它的交互设计至今仍然很能打。它本身是一个 C 编写的桌面程序基于 wxWidgets 构建完全离线运行数据不会上传到任何服务器这一点对需要标注敏感数据、医学影像或保密文档的场景来说是相当重要的优势。2. 工具选型解析为什么文本检测偏偏需要多边形标注而不是框2.1 矩形框在文本检测里的天然缺陷先说清楚一个问题为什么很多开源标注工具不适合文本检测。LabelImg、LabelStudio 这类通用标注工具默认的标注单元是 axis-aligned 的矩形框也就是边与图像坐标轴平行的矩形。这种框的表达方式很简单——一个中心点加宽高或者左上角加右下角。但真实世界的文本不是这样分布的。你去拍一张街景照片门牌号可能因为拍摄角度略微倾斜车身广告的文字沿着车身线条走饮料瓶上的标签是环绕圆柱的弧形排布。矩形框无法表达这些几何信息一个倾斜的长方形文本区域用矩形框表示的话你只能把框放大去包住整个文字区域结果就是框里有大量非文本区域。这在训练时会发生什么模型会学到这些背景像素跟文本标签是一起的于是推理时它倾向于输出更大的检测框把背景也包含进来。我自己的一组对照实验数据可以说明同一份 ICDAR2015 风格的文本检测数据用矩形框标注训练出的模型与用多边形标注训练出的模型相比在旋转文本子集上的 recall 低了 7% 左右precision 也明显下降。2.2 多边形标注的核心意义paperclip 用的标注形式是任意多边形。你可以沿着文本区域的轮廓点出一组顶点这些顶点首尾相连形成一个闭合多边形。对于倾斜文本一个四边形就够了对于带弧度的弯曲文本你甚至可以标成五六边形让检测框更贴合文字本身。为什么说这很重要因为文本检测模型的输出层通常有两种设计一种是回归四个角点如 DBNet、S4Net 的方式另一种是回归密集多边形点如 PAN、PSENet 的方式。不管哪种训练数据的 ground truth 都必须是多边形或多点序列。如果你的标注是矩形框这两种模型就算结构上支持多边形输出也没有数据去学习那种贴合文字边缘的几何输出能力。生活化类比矩形框标注像是用方形相框去裱一幅圆形画要么把画裁掉一部分要么把框做得巨大、周围全是空白多边形标注则是直接按照画的实际轮廓做切割边缘干净利落。放到模型训练里这个差异会直接反映在检测框的贴合度和分类置信度上。2.3 同类工具对比我实际用过的文本标注工具不少这里做一个横向对比方便你选型时参考。工具标注形式文本检测场景适配度备注LabelImg矩形框低仅适合水平文本太通用无法处理旋转文本labelme任意多边形中但交互偏重支持多边形但没针对文本做优化RectLabel旋转矩形/多边形中高收费OCR 功能要买扩展包paperclip任意多边形高交互为文本标注量身定制开源、离线、轻量重点说一下 labelme 和 paperclip 的区别。labelme 是通用标注工具多边形绘制本身没问题但它的交互流程是为分割任务设计的每一步操作都需要先选工具、再调整坐标、再确认效率很低。一天标几百张图的时候这些交互开销会累积成巨大的时间成本。paperclip 在这方面做了针对性的优化——所有常用操作都能用快捷键完成点顶点、拉角点、对齐边缘全部可以在几秒内完成一个文本区域的多边形标注。我个人的体会如果只是标一百张图做 demo用什么都行但如果是正经启动一个 OCR 数据项目少则几千、多则数万张的训练数据标注工具的交互效率必须优先考虑。paperclip 就是为这种大规模标注场景设计的。3. 安装与工程编译全过程3.1 从源码编译是必经之路paperclip 没有发布预编译的 binary至少在 Linux 环境下你需要从源码编译。这个过程本身不算复杂但有几个坑值得提前给你打个预防针。它依赖 wxWidgets 和 wxFormBuilder 生成的基础 UI 框架。wxWidgets 是一个跨平台 GUI 库当年选它是因为它在 Linux 和 Windows 下都有相对一致的编程接口而且不依赖 Web 运行时。这也意味着编译前你必须先把 wxWidgets 的开发库装好。以 Ubuntu 系统为例安装依赖的命令大概是这样sudo apt-get update sudo apt-get install build-essential libwxgtk3.0-gtk3-dev # Ubuntu 18.04/20.04 适用 sudo apt-get install cmake git如果你的发行版是 Ubuntu 22.04 或更新的版本建议检查一下软件源里有没有libwxgtk3.2-dev之类的包。wxWidgets 的版本差异在编译时很容易让人卡住——有些高版本头文件路径变了报错信息又不直观第一次编译失败很常见。3.2 编译流程与踩坑记录克隆代码并编译的完整流程如下git clone https://github.com/PRImA-Research-Lab/paperclip.git cd paperclip mkdir build cd build cmake .. make -j4顺利的话编译完成后会在 build 目录下生成一个可执行文件名字大概是Paperclip。但我第一次编译时在make阶段遇到了几个典型报错这里列出排查方法。第一个坑是缺少libgl1-mesa-dev和libglu1-mesa-dev。wxWidgets 的 OpenGL 相关组件需要这些库如果没装会在链接阶段报undefined reference to glXGetProcAddressARB一类的错误。解决办法就是补齐依赖后重新 cmakesudo apt-get install libgl1-mesa-dev libglu1-mesa-dev rm -rf build mkdir build cd build cmake .. make -j4第二个坑是GTK_VERSION不匹配。有些比较新的系统默认装了 GTK3而 paperclip 代码里用的某些方法在 GTK3 的 API 里已经废弃了编译时会出现deprecated declaration警告这个通常不影响生成但如果编译直接中断你需要看一下是不是wxWidgets库选择了 GTK2 版本的头文件。这个问题可以用wx-config --version检查当前 wxWidgets 的配置来定位。编译完成之后建议先跑一下./Paperclip --help确认程序能正常启动。如果界面起不来大概率还是 wxWidgets 运行库的问题检查一下LD_LIBRARY_PATH是否包含了 wxWidgets 的库目录。还有一个冷门但实用的提示在某些高分屏上paperclip 的默认 dpi 适配做得很差界面字体会变得特别小。我的处理方法是给启动命令加上环境变量缩放export GDK_SCALE2 export GDK_DPI_SCALE0.5 ./Paperclip这个不算 bug只是 wxWidgets 程序在老的高分屏环境下的通病知道就行。4. 实操过程从导入图片到导出数据集全流程4.1 文件组织规则必须提前规划paperclip 的标注流程沿用了科研工具的老派设计一张图片对应一个 ground truth 文件文件名格式是gt_图片名.xml。这个命名规则看起来简单但很多人刚开始用的时候都会在这里栽跟头。你必须在图片所在的目录里为每一张要标注的图片创建对应的空 XML 文件。比如你有一张image_001.jpg就要在同一目录下先创建gt_image_001.xml。这个 XML 文件的内容可以是一个最小骨架?xml version1.0? tagset filenamegt_image_001.xml imageimage_001.jpg /tagset如果你不建这个文件程序打开图片后会提示找不到 ground truth无法进入标注状态。这一步是 paperclip 的核心机制它不是像现代工具那样先标完再导出而是从一开始就递归读取已有的 gt 文件来决定本图片的标注状态。批量创建空 gt 文件我推荐用一行 shell 搞定for file in *.jpg; do touch gt_${file%.jpg}.xml; done注意这里先检查一下touch是否真的创建了非空文件因为后面程序需要读取文件里的 XML 骨架如果文件是空的打开时同样会报错。稳妥做法是先用一个模板文件再批量生成echo ?xml version1.0?tagset/tagset template.xml for file in *.jpg; do sed s/gt/${file%.jpg}/g template.xml gt_${file%.jpg}.xml; done4.2 界面操作与标注流程详解启动程序之后界面左边是图片预览区右边是标注属性面板。打开一张图片后你会看到读入的 ground truth 文件中的已有多边形区域以绿色线条显示在图上。标注一个文本区域的步骤是在图片上直接左键点击每点一下就会添加一个顶点顶点之间自动连线。沿着文本区域的轮廓按顺序把顶点全部标出来。对于水平文本标四个顶点左上、右上、右下、左下即可对于倾斜文本或弧形文本顶点数可以相应增加。标完后在右侧属性面板里填入该区域的标签class比如text、title、description等按实际业务需求定。点击多边形内部选中该区域后可以用拖拽的方式微调顶点的位置。保存然后切换到下一张图片。如果只有一个文本区域等级所有标注统一填同一个类名即可如果文档结构比较复杂比如合同扫描件要区分标题、正文、签名区那这里的 class 就承担了多分类的职责。这里有一个极其重要的操作细节多边形的顶点顺序必须一致。我建议所有标注都按顺时针或逆时针统一因为很多深度学习训练框架在读取多边形坐标时默认顶点是按固定顺序排列的比如 ICDAR2015 是四个角点按左上、右上、右下、左下。如果你标注的时候一会儿顺时针一会儿逆时针后续转训练格式时坐标就会错乱轻则训练报错重则模型学到完全错误的几何对应关系。4.3 快捷键与批量标注提效paperclip 的快捷键设计思路跟传统绘图软件类似但更强调单键操作因为标注员的精力集中在鼠标上。实测下来我总结出了几组最顺手的键位功能快捷键说明添加顶点左键点击在图片上直接点删除顶点中键点击顶点鼠标中键直接点顶点移动顶点右键拖拽对已有点位做微调保存当前标注CtrlS保存为 XML下一张图片CtrlPageDown切图并自动加载 gt撤销CtrlZ撤销最近的操作实际操作中你会发现效率瓶颈往往在顶点微调上。第一次标注的区域很容易出现边缘贴合不紧的情况——多边形的某个顶点偏了把相邻的背景像素包进来。我的习惯是先粗标再把所有顶点切换到拖动模式下逐点微调这个过程大概每个区域要多花十几秒但导出的数据质量完全是另一个档次。批量标注方面paperclip 没有现代工具的自动保存并跳转按钮但你可以配合操作系统的快捷键映射工具把某个组合键映射成 CtrlS 再加 CtrlPageDown实现一键保存并切换几千张图处理下来能省出不少时间。4.4 导出与数据格式标注完成后点击菜单栏的 Export 或快捷键导出程序会把当前图片的标注区域输出成 XML 格式。导出的格式是 paperclip 自己的 tagset 格式跟 Pascal VOC 的格式不完全一样。一个典型的导出结果长这样tagset filenamegt_sample.jpg imagesample.jpg object nametext/name polygon x123/xy45/y x298/xy47/y x301/xy132/y x127/xy130/y /polygon /object /tagset看到这里你可能会问这不就是一个点的列表吗对核心就是这些坐标点的集合。实际训练时绝大多数 OCR 框架如 PaddleOCR、MMOCR、Detectron2用的训练数据格式都是一行的文本区域 多边形坐标点。所以只需要写一个简单的解析脚本把 paperclip 导出的 XML 转成目标框架的格式。以 PaddleOCR 的 det 训练格式为例每张图的标注文件是一个 txt每行表示一个文本框格式是[ [x1,y1], [x2,y2], [x3,y3], [x4,y4] ], label转的时候注意PaddleOCR 要求坐标是浮点数组包裹的列表且点序与标注顺序一致。实战中转出来的数据基本可以直接丢进训练管线但因为 paperclip 导出的是整型坐标有的框架期望归一化后的浮点坐标这个记得在脚本里顺手处理掉。5. 常见问题与排查技巧实录5.1 编译与运行时的典型报错下面是几个我实际遇到过以及从社区高频问题里收集到的典型案例直接整理成速查表。问题现象根本原因解法打开图片后提示找不到 gt 文件图片目录下没有gt_图片名.xml按 4.1 的 shell 命令批量创建有 gt 文件但打开后显示空白无法标注gt 文件内容为空写入最小 XML 骨架后再打开标注顶点无法删除鼠标中键在 Linux 下没有映射为 paste检查系统鼠标设置或改用 Del 键导出 XML 中没有内容当前图片尚未保存最新标注先 CtrlS 保存再导出界面文字太小高分屏 dpi 适配问题启动时用GDK_SCALE2环境变量编译时报fatal error: wx/wx.h: No such file or directory缺少 wxWidgets 开发包sudo apt-get install libwxgtk3.0-gtk3-dev这里特别说一下 Del 键删除顶点的操作。有些版本的 paperclip 里用中键删除顶点时容易误触把旁边正常顶点也删掉。我的做法是中键只用来查看真正删除顶点用 Del 键配合鼠标悬停来操作。这个细节看起来小实际标注中很影响心情。5.2 标注质量与效率的平衡经验标注工具用熟了之后决定项目进度的往往不再是工具本身而是数据准备的流程和标准。我在这里分享几个个人项目里总结出的经验。第一同一批数据的标注标准必须写到标注说明文档里。如果你的项目是团队协作团队里每个标注员对文字区域边界的理解很难天然一致。有人把字符外面留一个像素的空隙算进框里有人会贴得很紧。这种差异会让模型训练时置信度分布变得混乱。我的做法是写一份标注规范文档用几个典型例子定义边界——标点时必须落在字符外轮廓外侧不能穿过任何笔画文字之间有较大间隙时按单词或词组分而不是一整行框死。第二顶点数量宁多勿少但也不要过度。对于水平文本8 个以内的顶点足够对于形状复杂的文本区域可以增加顶点数让贴合度更高但顶点过多会让训练时网络回归的几何量变复杂影响收敛速度。一般来说一个文本区域 4 到 8 个顶点是比较合理的区间超过 12 个就要考虑是不是该拆分成多个区域了。第三先标一遍再统一回查修一遍。这个流程只有真正标过几千张图的人才会理解。第一轮标注时你的注意力集中在快速把所有图片都过一遍很多区域边缘贴得不够准。回查的时候专门调整顶点的位置把之前粗糙的标注全部精修一遍。这个回查环节表面上是多花了时间但比起训练模型后发现数据问题再回去排查代价小得多。我的个人经验是这样的两轮标注最终质量比单轮慢速精标还要高因为人的注意力集中度在前 40 分钟效率最高第一轮快速覆盖加上第二轮精修正好卡在这个高效窗口内。5.3 从标注到训练的一条龙衔接建议标注只是数据准备的一个环节你最终要把它变成模型能用的格式。我建议从一开始就设计好衔接脚本而不是等标注完再临时写。这里给一个最简 Python 脚本的示例作用是把 paperclip 导出的 XML 转成 PaddleOCR det 训练用的 txtimport xml.etree.ElementTree as ET import os def convert_paperclip_xml(xml_path, out_txt_path): tree ET.parse(xml_path) root tree.getroot() lines [] for obj in root.findall(.//object): name obj.find(name).text points [] xs obj.findall(polygon/x) ys obj.findall(polygon/y) for x_elem, y_elem in zip(xs, ys): points.append([int(x_elem.text), int(y_elem.text)]) lines.append(f{points}, {name}) with open(out_txt_path, w, encodingutf-8) as f: f.write(\n.join(lines)) # 目录下有 gt_img001.xml convert_paperclip_xml(gt_img001.xml, img001.txt)这个脚本只需要按实际框架的要求调整输出格式和坐标归一化逻辑就行。转换完之后建议做两步验证一是随机抽几张图把多边形画回原图肉眼确认坐标没有错位二是检查所有 txt 行数与 XML 中的 object 数量一致。这两步做完数据就可以放心喂给训练管线了。我自己在项目中还有一个习惯标注完成后先用一个 50 张图的 mini split 做一次快速训练迭代验证数据格式是否被框架正确解析。这一步能发现很多隐蔽问题比如坐标翻转、错误类名、多边形点数不一致这类坑在实际开始大训练前全部暴露出来。这个小成本会给你省下未来至少两天的排查时间。注意所有导出和转换的脚本强烈建议用 git 管理版本。标注数据项目周期长中途可能会有重新标注、加类别、改标准等情况脚本的可追溯性——知道每一版输出是哪个脚本生成的——是项目不崩塌的底线。6. 写在最后几个让我印象深刻的细节这篇分享没有做总结的习惯只想在最后再聊几个实操中让我对 paperclip 产生好感的小细节。一是它对文档分类场景的理解。你看它的名字——paperclip直译就是回形针设计者的初衷是用回形针把文档中的文本和表格区域夹出来做分类标签。所以它导出的 XML 天然带有 tagset 概念不像通用标注工具那样只有单纯的坐标框。这种为特定任务设计的思路让我在整理文档结构化数据时几乎不需要改代码。二是它读取 XML 的机制。只要你把 gt 文件准备好程序就自动按文件名把标注和图片关联起来导出时也无须额外指定输出目录。这个设计乍看很朴素但当你面对成百上千个文件时不需要任何清单和配置文件目录结构本身就是数据索引简洁到让人舒服。三是它老派但可靠的稳定性。它不联网、不依赖服务端、不会突然强制更新只要环境不变它就能一直稳定地工作。在数据标注这种长周期、重资产的工程任务里稳定性远比花哨的界面重要得多。如果你正在准备 OCR 或文本检测的数据集不妨花一两个小时把 paperclip 跑通亲手标一个文本区域感受一下再决定要不要正式采用。根据我的经验一旦你开始批量标注它的效率优势会越来越明显。希望这篇实操笔记能帮你少走点弯路把时间花在真正重要的训练和调参上。