简介roLabelImg 是一款面向目标检测数据生产的旋转框标注工具源码专为遥感影像、OCR 文字检测等需贴合旋转目标的场景设计适合计算机视觉研究者、算法工程师及标注工具二次开发人员使用。与普通矩形标注不同该工具支持任意角度的旋转框绘制与编辑能有效解决细长目标难以用水平框准确框选的问题。资源包共94个文件约16.44MB以 Python 源码.py与编译后的 pyc 为核心配合 png/svg 界面图标、xml 标注与资源定义、sh 构建脚本、cfg 配置等目录划分清晰主程序、libs 核心库、build-tools 构建目录一目了然。已有630人学习下载。通过这份源码读者可深入理解基于 PyQt 的标注界面实现、画布上的交互式旋转框绘制与调整逻辑、以及 Pascal VOC 格式的读写与类别管理流程还可参照预定义类别文件与构建脚本快速定制出适配自身业务的标注工具或将其集成到批量数据标注流水线中。1. roLabelImg 到底解决什么问题旋转框标注这件事做过旋转目标检测的人应该都有过这种经历用普通矩形框把斜着的飞机、船舶、文字区域框出来结果正负样本里全是背景map 怎么调都上不去。问题不在模型而在标注框把太多无关像素包进去了。roLabelImg 就是专门解决这个问题的标注工具它把 LabelImg 的矩形框扩展成支持任意角度的旋转框让你能用最小外接矩形准确贴合目标朝向而不是用轴对齐矩形硬套。适合所有需要做旋转框检测或 OCR 字级别标注的从业者也是目前开源社区里流传最广、上手成本最低的旋转标注方案之一。如果你手里的数据集还停留在普通矩形框阶段这篇会把安装、标注、格式和坑一次讲完确保拿源码包落得下来。2. 源码与运行环境先跑起来再谈其他2.1 项目结构里最重要的几个文件先快速拆一遍源码包的目录结构。解压之后你会发现整个项目继承自 LabelImg 的那套 wxPython 架构核心代码集中在几个 Python 文件里。打开主目录libs文件夹下是各种工具函数包括形状管理、画布渲染、文件格式解析labelImg.py是程序入口负责界面和交互逻辑真正处理旋转标注逻辑的地方在labelImg.py里的shape类以及libs/shape.py中定义的旋转矩形数据结构。还有一个容易被人忽略的文件是libs/ pascal_voc_io.py读写 XML 全靠它后面讲格式坑的时候会重点提到这个文件。2.2 环境要求Python 版本和依赖库在动手安装之前先对一下环境。这个源码包是典型的 Python 2/3 过渡期产物官方仓库最早的版本跑在 Python 2 上后续社区才拉了 Python 3 兼容分支。我的建议是直接上 Python 3.6 到 3.8因为太高版本的 Python 在编译某些 wxPython 依赖时会出现兼容性问题太低版本又容易碰到编码错误。依赖库方面核心只有三样wxPython、Pillow、lxml。其中 wxPython 是整个 GUI 的底层Pillow 负责读图lxml 负责 XML 解析与生成。没有其他隐藏依赖这对一个标注工具来说已经相当克制了。提示如果你用的是 Python 3.9 及以上版本安装 wxPython 时可能会遇到没有预编译 wheel 包的情况。这时候不要硬刚编译直接切到 Python 3.8 环境是最快的路径。2.3 安装命令与常见卡点最稳的安装方式是先建虚拟环境再装依赖。以 Ubuntu 或 macOS 环境为例按下面的步骤走conda create -n rolabelimg python3.8 conda activate rolabelimg pip install wxpython pillow lxml装完依赖之后进到源码目录直接启动cd roLabelImg python labelImg.py如果一切正常会弹出主窗口。这里有一个非常关键的细节pip install wxpython这一条命令在部分 Linux 发行版上会非常慢原因是在下载较大的 wheel 包如果你发现进度条长时间不动先确认网络源换国内镜像源再装pip install wxpython -i https://pypi.tuna.tsinghua.edu.cn/simple还有更省事的一步如果你不想配环境源码包里通常带requirements.txt直接pip install -r requirements.txt就能把依赖一次装齐。我看过好几个版本的资源包requirements.txt 里的版本范围写得比较宽松没有锁死小版本所以基本不会出现依赖冲突。3. 核心交互流程图像加载到旋转框快捷键全部用起来3.1 第一次启动设置默认标注目录与图像目录现在的默认工作流和 LabelImg 几乎一样左侧是图像列表中间是画布右侧是标签列表。但有两点不同第一点是界面顶部多了一个旋转角度显示第二点是默认快捷键没有开启旋转功能你需要先知道旋转功能对应的操作是什么。在正式标注前建议先通过菜单设置好默认目录不然每次都要手动翻路径。具体在File菜单里点击Open Dir选择图像集所在目录点击Change Save Dir选择 XML 输出目录。为什么不直接按 LabelImg 的习惯用Open单张打开因为旋转标注通常是批量任务单张打开会让目录切换变得极其麻烦一步到位设置两个目录能省掉大量重复操作。3.2 画旋转框从快捷键到鼠标操作接下来就是核心操作了。roLabelImg 的快捷键设计基本复用了 LabelImgW创建框D下一张A上一张CtrlS保存。创建旋转框的方式有细微差别按W进入标注模式后按住鼠标左键拖出一个初始矩形松开时它会生成一个带四条边控制点的旋转矩形你可以拖动任意一条边或者控制点来改变方向角。还有一组快捷键容易忽略Z和X用来在创建框时逆时针、顺时针旋转参考方向E和C微调旋转角度。实际标注中Z和X更常用因为绝大多数目标的朝向是固定的一次旋转到位之后直接拖大小就行。保存快捷键也有讲究。CtrlS是保存当前图片的标注结果CtrlD是保存并跳到下一张。如果整个批次标注完成File菜单里的Save All会把所有待保存的 XML 一次性写盘。建议养成每完成一张就CtrlD的习惯不要攒到最后再批量保存因为 roLabelImg 在长时间运行后有概率丢失未保存状态这点后面避坑章会细讲。3.3 预览与验证旋转方向显示在左上角当画完一个框之后界面左上角会实时显示当前框的中心点坐标、宽度、高度以及旋转角度和旋转方向。这些信息不是摆设。我一般会对着目标朝向人工比对一次如果目标主体长轴和横轴夹角是 30 度框上显示的角度却差得很远那就说明拖拽控制点时方向理解错了应该用Z/X先把参考方向调到目标朝向再拉伸. 这一步的校验价值在于角度偏差一旦在标注阶段积累后续训练时模型需要重新学习角度拟合收敛速度差很多。4. 标注格式全解析从 XML 里的 rotation 到坐标系约定4.1 旋转框 XML 结构逐字段拆解用 roLabelImg 保存出来的 XML 看起来和 LabelImg 的 PASCAL VOC 格式非常接近但多了一行关键字段rotation。一个典型的标注片段长这样object nameship/name poseUnspecified/pose truncated0/truncated difficult0/difficult bndbox xmin120/xmin ymin80/ymin xmax260/xmax ymax140/ymax /bndbox rotation15.0/rotation /object注意看这里的逻辑bndbox里的四个值并不是旋转框的四个角坐标而是旋转框轴对齐外接矩形的坐标。真正决定旋转框朝向的是rotation字段它表示矩形框绕中心点逆时针旋转的角度单位是度。也就是说当你画完一个旋转矩形roLabelImg 会自动计算出它的外接矩形坐标然后记录旋转角度。这是一个非常重要的理解点XML 中存储的从来不是角点坐标而是外接矩形加角度的表示法。4.2 旋转框的坐标系约定逆时针为正还是顺时针为正把这个约定搞清楚能少踩很多坑。roLabelImg 的旋转方向定义是顺时针为正还是逆时针为正实际源码里rotation字段的符号约定和图像坐标系直接相关。图像坐标系的原点在左上角x 轴向右y 轴向下。在这个坐标系下roLabelImg 定义的是顺时针方向为正角度值。也就是说XML 中rotation为正值表示标注框相对水平方向顺时针旋转了相应的度数。这个约定和数学坐标系里逆时针为正的习惯正好相反如果是刚从纯几何背景转来做标注的人很容易在这上面理解偏差。我平时会把一个目标先旋转到视觉上“正确”的贴合状态然后看左上角角度显示再和图像上目标的长边走向对比。如果你发现目标朝向是往右下方倾斜角度值显示为正往右上方倾斜角度值显示为负那就说明当前符合顺时针为正的约定。等到做 DOTA 格式转换时这个符号方向必须再次检查因为 DOTA 用的是四点坐标存储不涉及角度符号但转换时你需要根据角度重新计算四个角点的数学顺序符号错了四点坐标就乱了。4.3 旋转框与普通框混存的处理方式实际项目中常遇到一个情况一张图里既有旋转框又有普通框。roLabelImg 对普通框的保存方式是完全兼容的普通框保存时rotation默认是 0.0。这会带来一个潜在问题当你用目标检测框架读取 XML 时如果框架的逻辑是只认bndbox的四点那旋转框就退化成了轴对齐框角度信息丢了如果框架的逻辑是只要有rotation就做旋转框处理那普通框反而会被当成角度为 0 的旋转框参与角度回归。从工程角度说混存本身没问题关键是训练时统一处理策略。我建议训练前把所有框统一成旋转框格式普通框也写成 rotation0这样模型的角度回归头不会在“有角度框”和“无角度框”之间摇摆。4.4 批处理时保存的 XML 文件名匹配规则roLabelImg 保存 XML 的时候文件名默认和图片名保持一致后缀从.jpg换成.xml。这个规则看似简单但目录里如果有同名不同格式的图片比如a.jpg和a.png同时存在roLabelImg 可能不知道把标注对应到哪张图保存时会产生歧义。我处理这种情况的做法是在标注之前先批量清理图片目录把同一张图像的不同格式版本只保留一个。另外如果图像文件名里带中文或特殊字符lxml 解析 XML 的时候在某些系统语言环境下会报编码错误建议在标注前就把文件名改成纯英文加下划线的风格不要等标到一半再返工。5. 避坑与排错标注过程中最容易踩的五个坑5.1 标注中途程序崩溃已画框全部丢失现象连续标注几十张之后程序突然卡死或直接闪退重新启动发现最后几张图的 XML 根本没保存。原因roLabelImg 的自动保存机制做得很保守它默认只在你手动按保存快捷键时写盘长时间挂机后内存里的标注数据可能因为未保存而丢失加上 wxPython 在长时间运行后内存占用会逐渐升高触发异常退出。解决把标注节奏改成每完成五张就手动点一次CtrlS同时把图像目录控制在 200 张以内不要一个目录塞上千张图分目录处理。5.2 打开源码包后提示无法导入 libs 模块现象拉源码到自己机器上运行python labelImg.py直接报ModuleNotFoundError: No module named libs。原因这个项目并不是用标准包结构组织的labelImg.py在导入libs时依赖相对路径如果你从源码根目录以外的位置启动程序Python 解释器找不到libs包。解决进入源码根目录再运行启动命令cd roLabelImg python labelImg.py或者用绝对路径方式运行python /path/to/roLabelImg/labelImg.py也有效。更稳妥的方案是把根目录临时加入环境变量PYTHONPATH但这属于绕路做法直接切目录启动最简单。5.3 旋转框显示正常保存后再打开角度变了现象标注时旋转框贴合得很好重新加载 XML 后同一个框的角度和位置对不上偏了十几度。原因在 4.2 节提到过两个坐标系下的角度符号约定不一致。如果源码版本里存在不同时期代码混用的情况某些版本存储角度时做了符号反转加载时又没做逆变换就会导致角度读取错误。解决用同一份源码包完成标、存、读全流程不要拿 A 版本标注、B 版本读取如果你修改过pascal_voc_io.py中的读写逻辑要同时检查写入和读取两条路径的符号变换是否对称。5.4 旋转 90 度后宽度和高度被交换现象目标是竖直细长条旋转 90 度贴合之后XML 里width和height的数值关系对不上目标的视觉长宽比。原因旋转前外接矩形的宽度高度和旋转后的外接矩形宽度高度在数学上会发生交换roLabelImg 在计算外接矩形时只更新了坐标没有同步维护宽高字段的物理语义。解决不要依赖 XML 里的 width/height 做目标长宽统计直接根据四个角点坐标计算真实的长和宽。批量统计数据集长宽分布时重新解析角点坐标计算一次不要直接用bndbox的宽高。5.5 中文目录无法打开图像现象图像放在中文目录下程序能启动但右侧文件列表空白打开单张图片报错。原因wxPython 底层对非 ASCII 路径的处理在部分发行版上存在编码问题字符串先按照系统默认编码做了转换中文路径在转换过程中被破坏。解决把整个项目和数据目录全部放到纯英文路径下路径中不要出现中文、空格和特殊符号。这是最万无一失的方式虽然粗暴但有效我曾经为了测试特意把路径改成纯中文后续所有读取和保存都会出问题所以现在一律用安全路径。6. 进阶用法一键把 roLabelImg 输出转换为 DOTA 四点坐标格式旋转框训练通常不只用一个框架。标签格式转换是绕不开的环节最常见的场景是把 roLabelImg 产出的外接矩形加角度格式转成 DOTA 社区用的四点坐标格式。转换脚本的核心逻辑是三角函数运算给定中心点坐标、宽度、高度和角度计算出旋转矩形的四个角点坐标。以下是我在模拟项目 X 中反复用的一段转换函数每次处理数据集都会强制走一遍验证流程import math def rot_rect_to_corners(cx, cy, w, h, angle_deg): 将 roLabelImg 的中心点宽高角度转为四个角点 angle_deg 遵循 XML 中的顺时针为正约定 ang math.radians(angle_deg) cos_a, sin_a math.cos(ang), math.sin(ang) # 先计算未旋转矩形的四个半宽半高偏移 dx, dy w / 2.0, h / 2.0 corners [ (-dx, -dy), (dx, -dy), (dx, dy), (-dx, dy) ] # 按图像坐标系做旋转变换 rotated [] for px, py in corners: rx cx px * cos_a - py * sin_a ry cy px * sin_a py * cos_a rotated.append((round(rx, 2), round(ry, 2))) return rotated这段代码的核心在旋转矩阵那一行。图像坐标系下顺时针旋转正角度对应的变换公式是 x x * cosθ - y * sinθy x * sinθ y * cosθ这里的 x 和 y 是相对中心点的偏移量。如果你在转换后拿四个角点去图上画线发现目标角点顺序不对或者整体方向翻转了最常见的原因就是角点排序方式和 DOTA 的要求不一致。DOTA 格式要求角点按顺时针顺序存储而上面代码输出的角点顺序在初始定义时也是顺时针排列的但由于旋转方向的不同输出顺序可能与目标格式相反验证时一旦发现反序需要调整初始化顺序。验证方法也很简单。转换完之后随机挑五张图把转换得到的四点坐标画回原图上人工对比是否和标注框贴合。我一般直接用 OpenCV 的polylines画出来检查如果五个图全部贴合再进下一步批量转换。批量转换时注意两点第一rotation字段的读取要在解析 XML 时先确认符号第二宽度和高度取的是旋转框自身的长和宽不是外接矩形的宽高。如果这两点没确认好批量转换后所有框的长宽比都会是镜像错误的。从实际标注到格式转换我踩过最多的坑还是角度符号问题。从那以后我每次跑完转换脚本都会强制走一遍画图验证把所有转换后的角点可视化检查一轮再进训练流程可视化通过的那批数据才敢放心用。希望这篇拆解能帮你把 roLabelImg 用顺把标注数据这一步做扎实省下在训练阶段反复排查数据问题的时间。本文还有配套的精品资源点击获取