roLabelImg2yolo：高效旋转目标标注转换工具实战指南

最新推荐文章于 2026-06-13 14:40:10 发布

原创最新推荐文章于 2026-06-13 14:40:10 发布 · 1k 阅读

本内容遵循CC 4.0 BY-SA版权协议

1. 为什么你需要roLabelImg2yolo这个工具？

如果你正在做遥感影像分析、自动驾驶中的交通标志识别，或者工业质检里那些歪七扭八的零件检测，那你肯定对“旋转目标检测”不陌生。和普通的水平矩形框不同，旋转框能更精确地框住那些斜着的、躺着的目标，比如斜放的车辆、任意方向的文字或者飞机跑道。roLabelImg是标注这类数据的神器，但它生成的XML格式，YOLO系列算法（比如YOLOv5-OBB、YOLOv8-OBB）可读不懂。这就好比你的朋友用方言给你讲了个笑话，你每个字都听到了，但就是不明白笑点在哪。

这时候，你就需要一个靠谱的“翻译官”，把roLabelImg的“方言”（XML）精准地翻译成YOLO能听懂的“普通话”（TXT格式）。网上虽然有一些零散的代码片段，但要么缺胳膊少腿，要么藏着一些新手容易踩的“坑”，比如角度转换错误、长宽顺序搞反，导致你训练出来的模型根本对不上。我刚开始做旋转目标检测时，就因为这个转换问题折腾了好几天，模型死活不收敛，最后才发现是转换脚本里一个不起眼的逻辑判断写反了。

所以，今天我就把自己实战中打磨出来的这套roLabelImg2yolo转换工具和心得分享给你。这不仅仅是一个能跑通的脚本，我会把里面的转换原理、每个参数的含义、可能遇到的坑以及怎么优化都掰开揉碎了讲清楚。目标就一个：让你拿到手就能用，用了就能成，快速把精力投入到更重要的模型调优和业务逻辑中去。

2. 环境准备与工具初探

工欲善其事，必先利其器。在动手写代码之前，我们先得把“战场”布置好。整个过程非常简单，不需要复杂的深度学习框架，你的电脑只要有Python环境就能跑。

2.1 创建你的项目文件夹

我强烈建议你为每个项目建立一个清晰独立的文件夹结构，这能避免后期文件混乱带来的麻烦。你可以完全按照下面的方式来：

你的项目文件夹/
├── roLabelImg2yolo.py      # 我们的核心转换脚本
├── xmllabels/              # 用于存放roLabelImg生成的原始XML文件
│   ├── image1.xml
│   ├── image2.xml
│   └── ...
└── labels/                 # 转换后生成的YOLO格式TXT文件将自动放在这里

怎么创建呢？如果你在Windows上，直接在桌面右键新建文件夹，然后重命名就行。我更推荐用命令行（CMD或PowerShell）或者终端（Mac/Linux）来操作，感觉更“极客”一点，也方便后续自动化。打开终端，依次输入下面几行命令：

mkdir rotation_detection_project
cd rotation_detection_project
mkdir xmllabels labels
touch roLabelImg2yolo.py

这几行命令的意思是：创建一个叫rotation_detection_project的文件夹，进入它，然后在里面创建xmllabels和labels两个子文件夹，最后创建一个空的Python脚本文件。现在，你的文件夹骨架就搭好了。

2.2 理解两种标注格式的“语言差异”

在写转换器之前，我们必须搞清楚双方在“说”什么。这就像翻译，你得懂源语言和目标语言的语法。

roLabelImg的XML格式：它用一个叫<robndbox>的标签来描述旋转框。里面包含了五个核心信息：

cx, cy: 旋转矩形中心点的x和y坐标。
w, h: 旋转矩形的宽度和高度（注意，这里的宽高是旋转前，沿着矩形自身坐标轴的长度）。
angle: 旋转角度，单位是弧度。这个角度是矩形顺时针旋转的角度，范围通常是(-π/2, π/2]。这是最容易出错的点之一。

YOLO OBB的TXT格式：每一行代表一个目标。它的格式是： class_id x_center y_center width height angle

class_id: 类别的整数索引（从0开始）。
x_center, y_center: 目标中心点的坐标，但这里是归一化后的值（即坐标除以图片的宽和高，范围在0到1之间）。
width, height: 目标的宽度和高度，同样是归一化后的值。
angle: 旋转角度，但单位是度，并且范围是[0, 180)。这个角度通常定义为矩形长边与x轴正方向的夹角。

看到区别了吗？关键差异在于：坐标是否归一化、角度单位（弧度 vs 度）、角度范围定义。我们的转换脚本，核心工作就是解决这三个差异。

3. 核心转换脚本逐行详解

好了，铺垫了这么多，是时候亮出我们的“武器”了。下面这个脚本是我基于原始代码优化和注释后的版本，稳定性更高，也更容易理解。我会把关键行都解释清楚。

# -*- coding: utf-8 -*-
import xml.etree.ElementTree as ET
import os
import math
from os import getcwd

# 1. 定义你的类别列表
# 这里改成你自己的类别，比如 ['car', 'ship', 'airplane']
# 注意：列表的顺序决定了类别的ID（从0开始）
classes = ['pencil']  # 示例，请务必修改！

def convert(size, box):
    """
    将绝对坐标的框(cx, cy, w, h)转换为YOLO格式的归一化坐标(x_center, y_center, w, h)
    参数:
        size: 图片的 (width, height)
        box: 旋转框的 (cx, cy, w, h)
    返回:
        归一化后的 (x_center, y_center, w, h)
    """
    img_w, img_h = size
    # 归一化因子：1/图片宽度， 1/图片高度
    dw = 1. / img_w
    dh = 1. / img_h
    x_center, y_center, w_box, h_box = box
    # 执行归一化：坐标和尺寸都除以图片尺寸
    x = x_center * dw
    y = y_center * dw
    w = w_box * dw
    h = h_box * dh
    return x, y, w, h

def convert_annotation(image_id):
    """
    核心转换函数：处理单个XML文件，生成对应的TXT文件。
    参数:
        image_id: 图片文件的名称（不带后缀），例如 'image1'
    """
    # 2. 输入输出路径配置
    # 确保这里的路径和你的文件夹结构一致
    xml_path = os.path.join('xmllabels', f'{image_id}.xml')
    txt_path = os.path.join('labels', f'{image_id}.txt')

    # 打开文件
    with open(xml_path, 'r', encoding='UTF-8') as in_file:
        tree = ET.parse(in_file)
        root = tree.getroot()

    # 获取图片尺寸，用于归一化
    size_elem = root.find('size')
    img_width = int(size_elem.find('width').text)
    img_height = int(size_elem.find('height').text)

    # 准备写入TXT文件
    with open(txt_path, 'w') as out_file:
        # 遍历XML中的所有目标对象
        for obj in root.iter('object'):
            # 有些标注可能有‘difficult’标记，通常忽略困难样本
            difficult_elem = obj.find('difficult')
            difficult = difficult_elem.text if difficult_elem is not None else '0'

            cls_name = obj.find('name').text

            # 检查是否是我们关心的类别，以及是否标记为困难
            if cls_name not in classes or int(difficult) == 1:
                continue  # 跳过不关心的类别或困难样本

            # 获取类别ID
            cls_id = classes.index(cls_name)

            # 3. 提取旋转框参数 - 最关键的一步
            robndbox = obj.find('robndbox')
            # 读取中心点、宽高和角度（弧度）
            cx = float(robndbox.find('cx').text)
            cy = float(robndbox.find('cy').text)
            w = float(robndbox.find('w').text)  # 框的宽度
            h = float(robndbox.find('h').text)  # 框的高度
            angle_rad = float(robndbox.find('angle').text)  # 弧度制角度

            # 4. 角度处理逻辑（从弧度到度，并适配YOLO OBB格式）
            # YOLO OBB通常需要角度在[0, 180)度之间，且是长边与x轴的夹角。
            # roLabelImg的角度是顺时针弧度，范围(-π/2, π/2]。
            # 我们先将其转换为度。
            angle_deg = angle_rad * 180.0 / math.pi

            # 关键调整：确保角度在[0, 180)区间
            # 同时，如果宽度w小于高度h，意味着矩形是“竖着”的，我们需要交换w和h，并调整角度。
            if w < h:
                # 交换宽高，因为YOLO OBB格式要求w是长边（或至少是角度参考边）
                w, h = h, w
                # 角度加上90度，并对180取模，确保在0-180之间
                angle_deg = (angle_deg + 90) % 180
            else:
                # 如果w已经是长边，只需确保角度在0-180之间
                # 因为原始弧度角可能在负值，我们通过加180再取模来转换到[0,180)
                angle_deg = (angle_deg + 180) % 180

            # 5. 坐标归一化
            normalized_box = convert((img_width, img_height), (cx, cy, w, h))
            x_norm, y_norm, w_norm, h_norm = normalized_box

            # 6. 写入TXT文件，格式：cls_id x_center y_center width height angle
            line = f"{cls_id} {x_norm:.6f} {y_norm:.6f} {w_norm:.6f} {h_norm:.6f} {int(angle_deg)}\n"
            out_file.write(line)

# 7. 主程序：批量处理所有XML文件
if __name__ == '__main__':
    # 确保输出文件夹存在
    os.makedirs('labels', exist_ok=True)

    # 获取xmllabels文件夹下所有XML文件名（不带后缀）
    xml_folder = 'xmllabels'  # 检查这里是否是你的XML文件夹路径
    if not os.path.exists(xml_folder):
        print(f"错误：文件夹 '{xml_folder}' 不存在！请检查路径。")
        exit(1)

    all_files = os.listdir(xml_folder)
    # 过滤出.xml文件，并去掉后缀
    image_ids = [os.path.splitext(f)[0] for f in all_files if f.endswith('.xml')]

    print(f"找到 {len(image_ids)} 个XML文件待转换。")
    print("文件列表：", image_ids)

    # 开始逐个转换
    for img_id in image_ids:
        try:
            convert_annotation(img_id)
        except Exception as e:
            print(f"转换文件 {img_id}.xml 时出错：{e}")

    print("所有文件转换完成！请检查 'labels' 文件夹下的TXT文件。")

我把最核心、最容易出错的部分用注释标了出来。特别是第4步的角度处理逻辑，这是保证你的旋转框方向正确的关键。原始代码中那个 if b3 < b4: 的判断，其实就是比较宽度w和高度h，确保我们总是用长边作为参考来计算与x轴的夹角，这是YOLO OBB格式的常见约定。如果你忽略这一步，可能会发现标注框的方向和实际目标对不上。

4. 实战演练：从标注到转换的全流程

光有脚本还不够，我们得真刀真枪地跑一遍。假设我们现在要做一个“空中飞机检测”的小项目。

第一步：使用roLabelImg进行标注。

安装并打开roLabelImg（安装过程这里不赘述，网上教程很多）。
加载你的飞机图片。
使用旋转框工具（通常是快捷键Ctrl + R或者界面上有专门按钮）仔细框住每一架飞机。标注时尽量让框的边与飞机的长轴方向平行。
为每个框选择类别，比如airplane。
保存后，roLabelImg会为每张图片生成一个同名的XML文件，里面就包含了我们刚才讨论的<robndbox>信息。

第二步：组织文件。 把你标注生成的所有XML文件（比如plane_001.xml, plane_002.xml...），统统复制到我们之前创建好的xmllabels文件夹里。

第三步：修改脚本配置。 用记事本或任何代码编辑器（推荐VS Code、PyCharm）打开roLabelImg2yolo.py脚本。

找到第8行左右的classes = ['pencil']，把它改成classes = ['airplane']。如果你的项目有多个类别，比如还有ship, car，那就写成classes = ['airplane', 'ship', 'car']。顺序很重要，airplane的ID是0，ship是1，以此类推。
检查第60行左右的xml_folder = 'xmllabels'，确保这个路径和你的文件夹名字一致。如果你的xmllabels文件夹不在脚本同级目录，而是别的路径，比如D:/project/annotations/，那你需要修改这里。

第四步：运行脚本。 打开终端（命令行），导航到你的项目文件夹，然后运行：

python roLabelImg2yolo.py

如果一切顺利，你会看到终端打印出找到的XML文件列表，最后显示“所有文件转换完成！”。现在，打开labels文件夹，你会发现里面出现了和XML文件同名的TXT文件。

第五步：验证结果（非常重要！）。 转换完千万别直接拿去训练，一定要验证。我吃过亏，曾经因为角度转换的一个小bug，白训练了两天模型。怎么验证呢？

肉眼检查：你可以写一个简单的可视化脚本，把TXT中的归一化坐标和角度读出来，在原图上画出来看看框的位置和方向对不对。网上有很多现成的YOLO格式可视化代码，稍微改改就能用。
工具检查：如果你用的是Ultralytics的YOLOv8-OBB，它自带一个验证数据集格式的命令，虽然不完全针对转换，但能帮你检查文件是否能被正确读取。
抽样核对：挑几个复杂的样本，手动计算一下。比如找一个倾斜角度大的飞机，用计算器根据TXT文件里的归一化坐标和角度，反算出它在图片上的四个角点，看看是不是和你标注时框的位置一致。

这个验证步骤可能多花你半小时，但能避免后面几天甚至几周的无效工作。

5. 常见问题与深度优化技巧

在实际项目中，你肯定会遇到一些脚本本身没覆盖到的情况。这里我分享几个踩过的“坑”和对应的解决方案。

问题一：转换后框的角度总是差90度或者方向反了。 这是最常见的问题。根本原因在于对“角度”定义的理解不一致。roLabelImg、OpenCV、不同版本的YOLO-OBB对旋转角度的定义（0度起点、顺时针还是逆时针）可能略有不同。

解决方案：不要死记硬背公式。最好的办法是做一个单元测试。用roLabelImg标注一个你知道确切角度的矩形（比如一个水平放置的长方形，你认为它应该是0度）。然后运行转换脚本，看输出的角度是多少。如果输出是90度，说明你的脚本逻辑需要整体减去90度。根据测试结果，调整脚本中angle_deg的计算公式。我通常在最终写入TXT文件前，加一个修正参数：final_angle = (angle_deg + angle_correction) % 180，然后通过一两个样本调试出正确的angle_correction值（可能是0, 90, -90等）。

问题二：我的类别很多，每次修改classes列表容易出错。 手动维护一个类别列表确实麻烦，尤其是和团队协作时。

解决方案：让脚本自动从所有XML文件中收集类别。你可以在主程序里加一段代码，在转换前先遍历所有XML，用集合（set）收集所有不重复的<name>，然后排序，自动生成classes列表。这样即使你后续增加了新类别的标注，也无需手动修改脚本。不过要注意，自动生成的类别顺序可能每次运行都不同，这对于训练是不利的。因此，更稳健的做法是：让脚本读取一个外部的classes.txt配置文件，这个文件里固定写好类别顺序。

问题三：XML文件里有些目标我暂时不想用于训练。 roLabelImg标注的<difficult>标签或者你自己自定义的一些属性（比如<truncated>）可能标记了难以识别或被遮挡的目标。

解决方案：优化convert_annotation函数中的过滤逻辑。除了检查difficult，你还可以扩展。例如，在roLabelImg中标注时，你可以为某些目标添加一个额外的标签<ignore>1</ignore>。然后在脚本中，通过obj.find('ignore')来查找，如果找到且值为1，就跳过这个目标不转换。这为你提供了灵活的数据筛选能力。

问题四：转换速度慢，我有几万个标注文件。 纯Python的XML解析在数据量巨大时可能成为瓶颈。

优化技巧：
1. 使用并发：Python的concurrent.futures模块可以让你轻松实现多进程转换。因为每个XML文件的处理是独立的，并行化能大幅提升速度。注意，写入文件时要做好进程间的协调，避免冲突，最简单的就是让每个进程写入独立的临时文件，最后再合并。
2. 向量化操作（高级）：如果你对NumPy很熟，可以尝试将读取到的所有框的中心点、宽高、角度分别存储到数组里，然后利用NumPy的向量化运算一次性完成所有归一化和角度转换，最后再循环写入文件。这对于超大数据集能带来数量级的提升。

问题五：如何与YOLO训练流程无缝集成？ 转换出TXT只是第一步，你还需要创建YOLO要求的dataset.yaml配置文件。

实战步骤：在项目根目录创建一个data.yaml文件，内容如下：

# 数据集路径（相对路径或绝对路径）
path: /path/to/your/project
train: images/train  # 训练图片路径
val: images/val      # 验证图片路径

# 类别数量和名称
nc: 1  # 类别的数量，我们只有‘airplane’，所以是1
names: ['airplane']  # 类别名称，必须和转换脚本中的classes列表顺序一致！

# 旋转框模式
obb_format: thetaobb  # 或者 'le90'，取决于你使用的YOLO版本，v8通常用thetaobb

最关键的是names列表，一定要和转换脚本里classes列表的顺序完全对应。否则，标签文件里的class_id就全乱套了。

把这些优化点都考虑到，你的转换工具就从“能用”升级到了“好用且健壮”的级别。记住，好的工具不应该成为你的障碍，而应该是默默支撑你快速迭代的基石。这套roLabelImg2yolo的方案，我已经在好几个遥感图像和文档分析的项目里用过了，没再出过什么岔子。如果你在使用的过程中遇到了上面没提到的新问题，欢迎随时交流。

标签

#旋转目标检测 #roLabelImg #YOLO #数据标注