1. 为什么在 Ubuntu 18.04 上还要折腾 roLabelImg
如果你做过目标检测相关的标注工作，大概率绕不开 LabelImg 这个工具。它足够简单、足够直接，画框、打标签、导出 XML，一套流程下来很顺手。但问题也很明显：它只能画水平矩形框，遇到航拍图像、遥感影像、文档版面分析、工业质检里的倾斜目标，就彻底没辙了。你只能眼睁睁看着一个斜着的飞机、一个旋转的零件、一段倾斜的文字，被迫用一个巨大的水平框把它包进去，框里塞满了背景噪声，模型训练出来效果自然好不到哪去。
roLabelImg 就是冲着这个痛点来的。它在 LabelImg 的基础上做了扩展，支持**旋转矩形框（Oriented Bounding Box，简称 OBB）**的标注，可以画出带角度信息的框，导出格式也兼容常见的旋转目标检测训练框架。我第一次接触它是在处理一批遥感图像的时候，图像里的船只、飞机、储油罐全是任意方向的，用水平框标注简直是灾难。换成 roLabelImg 之后，标注效率和质量都上了一个台阶。
这篇文章面向的是需要在 Ubuntu 18.04 环境下使用 roLabelImg 做旋转框标注的从业者，不管你是刚入门的新手，还是已经用过 LabelImg 想迁移过来的老手，都能从中找到可以直接复现的步骤和踩坑经验。我会从环境准备讲起，一直讲到实际标注操作、格式解析、常见问题排查，把整个流程拆开揉碎说清楚。
提示：Ubuntu 18.04 虽然已经不是最新版本，但在很多工业现场和实验室环境里仍然是主力系统，Python 版本、Qt 库版本、依赖包版本都有其特殊性，这也是为什么单独拿出来讲的原因。
2. 环境准备与依赖安装的完整思路
2.1 为什么 Ubuntu 18.04 的环境需要特别对待
Ubuntu 18.04 默认自带的是 Python 3.6，系统级的 Qt 库版本也比较老。roLabelImg 基于 PyQt5 开发，而 PyQt5 在不同版本之间 API 差异不小，尤其是和 Python 3.6 搭配的时候，稍不注意就会遇到版本冲突。我在第一次安装的时候就因为 pip 直接拉取了最新版 PyQt5，结果运行时报了一堆sip相关的错误，折腾了大半天才定位到是版本不匹配的问题。
所以核心思路是：不要盲目追求最新版本，而是选择与 Python 3.6 兼容的稳定版本组合。这是整个安装过程中最重要的一条原则。
2.2 系统级依赖的安装
在开始装 Python 包之前，先把系统层面的依赖补齐。roLabelImg 运行需要 Qt 的图形界面支持，如果你的 Ubuntu 是最小化安装的，可能缺少一些基础库。
sudo apt update sudo apt install -y python3-pip python3-pyqt5 python3-pyqt5.qtsvg \ python3-dev libxml2-dev libxslt1-dev python3-lxml \ libqt5gui5 libqt5core5a libqt5widgets5这里解释一下几个关键包的作用。python3-pyqt5是 Qt5 的 Python 绑定，roLabelImg 的整个界面都靠它；python3-lxml用于解析和生成 XML 标注文件，LabelImg 系列的标注格式都是 Pascal VOC 风格的 XML，lxml 处理起来比标准库的 ElementTree 更高效；libxml2-dev和libxslt1-dev是 lxml 编译时需要的头文件，如果你用 pip 安装 lxml 而不是 apt 安装，这两个就必不可少。
注意：如果你打算用 apt 安装 python3-pyqt5，那 pip 里就不要再装 PyQt5 了，两者会冲突。我建议统一用 apt 管理 Qt 相关的包，pip 只用来装 roLabelImg 本身和纯 Python 的依赖。
2.3 roLabelImg 的获取与安装
roLabelImg 的源码托管在代码仓库上，直接克隆下来即可。这里不指定具体地址，你可以在常用的代码托管平台上搜索项目名找到它。
cd ~ git clone <roLabelImg仓库地址> cd roLabelImg克隆下来之后，先别急着运行。看一下目录结构，通常会有labelImg.py作为主入口，libs/目录下放着核心逻辑，resources.py是 Qt 资源文件。有些版本还需要先把.ui文件编译成.py，不过大多数维护良好的版本已经帮你编译好了。
安装 Python 依赖的时候，我建议用虚拟环境隔离，避免污染系统 Python。但 Ubuntu 18.04 的 python3-venv 有时候不太好使，如果你嫌麻烦，直接在当前用户下用pip3 install --user也可以。
pip3 install --user pyqt5==5.10.1 lxmlPyQt5 的版本我特意锁在 5.10.1，这是经过实测在 Python 3.6 上比较稳定的一个版本。如果你装的是 5.15 以上的版本，很可能会遇到QtCore.Qt枚举访问方式变化导致的报错，因为新版本把很多枚举改成了 scoped enum，老代码里直接写Qt.AlignCenter这种用法就会失效。
2.4 验证安装是否成功
装完之后，进入 roLabelImg 目录，直接运行：
python3 labelImg.py如果界面正常弹出来，说明环境没问题。如果报错，大概率是以下几类：ModuleNotFoundError: No module named 'PyQt5'说明 PyQt5 没装好或者装到了错误的 Python 环境下；ImportError: cannot import name 'uic'说明 PyQt5 的工具模块缺失，需要额外安装pyqt5-tools；symbol lookup error这种一般是系统 Qt 库和 pip 装的 PyQt5 冲突了，需要卸载 pip 版本改用 apt 版本。
3. 旋转框标注的核心操作与界面解析
3.1 界面布局与基本操作逻辑
roLabelImg 的界面和原版 LabelImg 非常相似，左侧是文件列表，中间是图像显示区，右侧是标签和标注列表，顶部是工具栏。区别在于工具栏上多了几个和旋转相关的按钮，标注列表里每个框也会多出角度信息。
打开一张图像之后，默认的绘制模式还是水平矩形框。要切换到旋转框模式，需要点击工具栏上的旋转框按钮，或者用快捷键。不同版本的快捷键可能不一样，常见的是Ctrl+R或者R。我建议你先在设置里确认一下当前版本的快捷键映射，因为有些 fork 版本改过键位。
绘制旋转框的操作方式和水平框类似：在目标的一个角点按下鼠标左键，拖到对角位置松开，就生成了一个初始的旋转矩形。生成之后，框的四个角上会出现控制点，你可以拖动控制点调整大小，也可以拖动框中间的旋转手柄来调整角度。
3.2 旋转框的角度定义与坐标系
这是整个工具里最容易让人困惑的地方，必须重点讲清楚。roLabelImg 导出的旋转框通常用中心点坐标、宽、高、角度这五个参数来表示，也就是常说的(cx, cy, w, h, angle)。但角度的定义方式在不同版本、不同训练框架里是不一样的。
常见的有两种约定：一种是角度表示矩形长边与水平轴的夹角，范围是[-90, 0)或者[0, 90)；另一种是用弧度表示，范围是[-π/2, 0)。roLabelImg 默认导出的 XML 里，角度通常以角度制存储，但有些版本会存弧度，这个一定要在标注前确认清楚，否则训练时角度全错，模型根本学不到东西。
我踩过的坑是这样的：标注了几百张图之后才发现导出的角度是弧度制，而训练代码里按角度制解析，结果所有框的旋转都是乱的。后来我在标注前先拿一张图测试，画一个明显倾斜的框，导出 XML 看一眼数值，确认角度单位之后再批量标注。这个习惯救了我很多次。
提示：判断角度单位有个简单方法，画一个大约 45 度的框，如果导出值是 0.78 左右就是弧度，如果是 45 左右就是角度。
3.3 标注过程中的实用技巧
标注旋转框比水平框费时得多，因为你要同时控制位置、大小和角度。我总结了几条能显著提速的经验。
第一，先画水平框再旋转。不要一上来就试图直接拖出带角度的框，那样很难控制。先把目标用水平框大致框住，然后再旋转到贴合目标的方向，最后微调四个角点。这样操作步骤虽然多一步，但精度和速度都更好。
第二，善用键盘微调。很多版本支持用方向键微调框的位置，用Shift+方向键微调角度。对于只需要小幅调整的情况，键盘比鼠标精确得多。
第三，角度归一化要统一。对于同一个类别的目标，尽量保持角度定义的一致性。比如船头朝向，你可以约定所有框的角度都表示长边方向，避免同一个目标一会儿用长边一会儿用短边，导致角度值跳变。
第四，标注顺序有讲究。我习惯按类别分批标注，先把所有 A 类目标标完，再标 B 类。这样切换标签的次数少，思路也更连贯。
4. 标注文件格式解析与格式转换
4.1 XML 标注文件的结构
roLabelImg 导出的标注文件是 XML 格式，整体结构继承自 Pascal VOC，但在每个object节点里增加了旋转相关的字段。一个典型的标注文件长这样：
<annotation> <folder>images</folder> <filename>demo_001.jpg</filename> <size> <width>1024</width> <height>768</height> <depth>3</depth> </size> <object> <name>ship</name> <pose>Unspecified</pose> <truncated>0</truncated> <difficult>0</difficult> <robndbox> <cx>512.0</cx> <cy>384.0</cy> <w>120.0</w> <h>40.0</h> <angle>0.785</angle> </robndbox> </object> </annotation>关键就在robndbox这个节点，它替代了普通 LabelImg 里的bndbox。cx和cy是中心点坐标，w和h是宽高，angle是旋转角度。注意这里的angle是弧度值，0.785 约等于 45 度。
4.2 角度单位与坐标系的坑
前面提到角度单位的问题，这里再深入说一下。不同版本的 roLabelImg 对angle的定义可能有差异，有的用弧度，有的用角度；有的以水平轴为基准逆时针为正，有的顺时针为正。你在拿到标注文件之后，第一件事应该是写个小脚本把几个框画出来可视化一下，确认解析方式和你的训练代码一致。
我常用的验证方法是用 OpenCV 把旋转框画到原图上：
import cv2 import numpy as np import xml.etree.ElementTree as ET def draw_robndbox(img, cx, cy, w, h, angle): rect = ((cx, cy), (w, h), np.degrees(angle)) box = cv2.boxPoints(rect) box = np.int0(box) cv2.drawContours(img, [box], 0, (0, 0, 255), 2) img = cv2.imread('demo_001.jpg') tree = ET.parse('demo_001.xml') root = tree.getroot() for obj in root.findall('object'): rbox = obj.find('robndbox') cx = float(rbox.find('cx').text) cy = float(rbox.find('cy').text) w = float(rbox.find('w').text) h = float(rbox.find('h').text) angle = float(rbox.find('angle').text) draw_robndbox(img, cx, cy, w, h, angle) cv2.imwrite('vis.jpg', img)如果画出来的框和目标贴合，说明解析正确；如果框歪了或者方向反了，就要检查角度单位和正负方向。这个验证步骤花不了几分钟，但能避免后面大量的返工。
4.3 转换到常见训练框架格式
标注完成之后，通常需要把 XML 转换成训练框架能直接读取的格式。不同框架要求不一样，这里说几个常见的。
DOTA 数据集格式用的是(x1, y1, x2, y2, x3, y3, x4, y4, category, difficult)这样的八点坐标加类别。从 roLabelImg 的 XML 转过去，需要把中心点宽高角度转换成四个角点坐标。转换逻辑是先用角度算出旋转矩阵，再把矩形的四个角旋转过去。
import math def robndbox_to_polygon(cx, cy, w, h, angle): dx = w / 2.0 dy = h / 2.0 cos_a = math.cos(angle) sin_a = math.sin(angle) points = [] for sx, sy in [(-dx, -dy), (dx, -dy), (dx, dy), (-dx, dy)]: px = cx + sx * cos_a - sy * sin_a py = cy + sx * sin_a + sy * cos_a points.extend([px, py]) return pointsCOCO 格式本身不直接支持旋转框，但有些扩展版本会用[cx, cy, w, h, angle]的形式存在bbox字段里。如果你的训练框架用的是这种格式，转换就简单多了，直接读取即可。
注意：转换的时候要特别小心坐标系的 y 轴方向。图像坐标系里 y 轴向下，而数学坐标系里 y 轴向上，角度正方向的定义会因此不同。转换前一定要确认清楚，否则框会上下翻转。
5. 常见问题排查与避坑经验实录
5.1 启动与运行类问题
问题一：运行时报qt.qpa.plugin: Could not load the Qt platform plugin "xcb"。
这是 Ubuntu 上跑 Qt 程序最经典的错误。原因通常是 Qt 找不到平台插件，或者插件依赖的库缺失。解决方法先试export QT_DEBUG_PLUGINS=1然后重新运行，看详细报错。常见的是缺libxcb-xinerama0，装一下就好：
sudo apt install -y libxcb-xinerama0如果还不行，检查一下是不是 pip 装的 PyQt5 和系统 Qt 冲突了，卸载 pip 版本改用 apt 版本通常能解决。
问题二：界面能打开但显示乱码或者字体极小。
这是 Qt 在高分屏或者缺少中文字体时的表现。装一下中文字体，然后设置 Qt 的缩放：
sudo apt install -y fonts-wqy-zenhei export QT_AUTO_SCREEN_SCALE_FACTOR=15.2 标注操作类问题
问题三：旋转框拖不动或者角度跳变。
这种情况多半是鼠标灵敏度或者版本 bug。先试试用键盘微调，如果键盘正常说明是鼠标事件处理的问题。有些版本在图像缩放比例不是 100% 的时候，坐标换算会有偏差，建议标注时把缩放调到 100%。
问题四：保存的 XML 里角度值全是 0。
检查一下是不是在水平框模式下标注的。只有用旋转框工具画的框才会带角度信息，水平框转成 robndbox 时角度默认是 0。另外确认一下保存格式设置，有些版本需要在设置里手动勾选“保存旋转框信息”。
5.3 数据一致性类问题
问题五：多人协作标注时角度定义不统一。
这是团队标注里最头疼的问题。解决办法是提前制定标注规范，明确角度的基准方向和正负号，并且用几张典型图做示例。标注前先让每个人标同一张图，对比结果，确认一致之后再批量开工。
问题六：标注文件里的类别名拼写不一致。
比如一会儿写ship一会儿写Ship，训练时会被当成两个类别。建议在 roLabelImg 的预定义类别文件里把类别名固定好，标注时只从下拉列表选，不要手动输入。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 启动报 xcb 插件错误 | 缺 libxcb 依赖 | 安装 libxcb-xinerama0 |
| 界面乱码 | 缺中文字体 | 安装 fonts-wqy-zenhei |
| 角度值全为 0 | 用了水平框模式 | 切换到旋转框工具重新标注 |
| 框位置偏移 | 图像缩放非 100% | 调整缩放比例后重新标注 |
| 类别重复 | 手动输入拼写不一致 | 使用预定义类别列表 |
| 保存后文件为空 | 权限问题或路径含中文 | 检查目录权限，避免中文路径 |
6. 提升标注效率的进阶技巧
6.1 预标注与半自动流程
纯手工标注旋转框效率很低，尤其是目标密集的图像。一个可行的优化思路是先用已有的水平框检测模型做一遍预标注，把结果转成旋转框格式导入 roLabelImg，人工只需要微调角度和位置。虽然预标注的框不一定准，但至少省去了从零画框的时间。
具体做法是：用水平框模型推理得到(xmin, ymin, xmax, ymax)，然后转换成(cx, cy, w, h, 0)的旋转框格式，写成 roLabelImg 能读取的 XML。导入之后，标注人员只需要旋转和微调，效率能提升不少。
6.2 快捷键自定义与批量操作
roLabelImg 支持自定义快捷键，把常用的操作映射到顺手的位置能明显提速。我通常会把“下一张图”“保存”“复制上一个框”这几个操作设成单键，减少手在鼠标和键盘之间切换的频率。
另外，对于尺寸和角度都相近的目标，可以用“复制框”功能。先标好一个，复制之后平移到下一个目标位置，再微调角度。这在标注排列整齐的目标（比如停车场里的车、货架上的商品）时特别有用。
6.3 标注质量的抽检方法
标注完成之后一定要抽检，不能直接拿去训练。抽检的方法是随机选一批图，把标注框可视化出来，肉眼检查是否贴合。我一般会抽 5% 到 10% 的样本，重点看边界情况：特别小的目标、特别密集的区域、角度接近 90 度的目标。这些地方最容易出错。
如果发现系统性偏差，比如所有框都偏右几个像素，那可能是标注工具的坐标换算有问题，需要整体修正而不是逐个改。
7. 我在实际项目中的几点体会
用 roLabelImg 做旋转框标注，工具本身不算复杂，真正花时间的是标注规范的制定和质量控制。我经历过最惨的一次是标了三千多张图之后发现角度定义和训练代码不一致，只能全部返工。从那以后，我养成了一个习惯：任何标注任务开始之前，先标十张图，走一遍完整的训练流程，确认数据格式、角度定义、类别映射全部对齐之后，再大规模铺开。
另一个体会是，旋转框标注对标注人员的要求比水平框高不少。水平框只要框住目标就行，旋转框还要考虑角度是否合理、长宽是否对应目标的主轴方向。培训标注人员的时候，一定要把角度规范讲透，最好准备一份带正反例的文档，让大家对“什么算标得好”有统一的认知。
最后说一个工具层面的小技巧：roLabelImg 的某些版本在打开大图（比如 4000x3000 以上）时会比较卡，标注体验很差。如果遇到这种情况，可以先把图像切分成小块分别标注，最后再合并标注文件。虽然多了一步，但操作流畅度会好很多。
