计算机视觉 / 系统课时

转换常见标注格式

转换常见标注格式

训练 YOLO 前,真正需要统一的不是文件扩展名,而是类别编号、边界框坐标语义和归一化规则。本节用一个可运行脚本把 VOC 与 COCO 检测标注转换成 YOLO 文本标签,并说明如何验证结果,避免“格式能读但框已错位”。

学习目标

  • 说清 VOC、COCO 与 YOLO 三种检测框坐标的差异
  • 将 VOC XML 和 COCO JSON 批量转换为 YOLO 标签
  • 通过数量、范围与抽查验证转换是否可靠

先统一 YOLO 标签规则

YOLO 检测标签通常按“一张图片一个同名 .txt 文件”组织,每一行描述一个目标:

text
<class_id> <x_center> <y_center> <width> <height>

其中四个坐标都要按图像宽高归一化到 0~1。类别编号从 0 开始,并且训练、验证、推理阶段必须使用同一份类别顺序。

VOC 常用 (xmin, ymin, xmax, ymax);COCO 的 bbox 使用 (x, y, width, height),其中 (x, y) 是左上角。二者都要先换算成中心点表示,再归一化。

VOC、COCO 到 YOLO 的边界框坐标转换关系

用脚本完成批量转换

下面的脚本同时支持 VOC 与 COCO。VOC 模式通过 classes.txt 固定类别顺序;COCO 模式按 categories 中的类别 ID 排序后重新映射为从 0 开始的连续编号,并输出同样的 classes.txt。

python
import argparse
import json
import xml.etree.ElementTree as ET
from collections import defaultdict
from pathlib import Path

def to_yolo(x1, y1, x2, y2, image_w, image_h):
    # 在归一化前拒绝零面积框和越界框,避免把坏标注静默带入训练集。
    if image_w <= 0 or image_h <= 0:
        return None
    if x1 < 0 or y1 < 0 or x2 > image_w or y2 > image_h:
        return None
    if x2 <= x1 or y2 <= y1:
        return None

    cx = (x1 + x2) / 2 / image_w
    cy = (y1 + y2) / 2 / image_h
    bw = (x2 - x1) / image_w
    bh = (y2 - y1) / image_h
    return cx, cy, bw, bh

def convert_voc(input_dir, output_dir, classes_file):
    class_names = [
        line.strip()
        for line in Path(classes_file).read_text(encoding="utf-8").splitlines()
        if line.strip()
    ]
    class_to_id = {name: idx for idx, name in enumerate(class_names)}
    converted = 0

    for xml_path in sorted(Path(input_dir).glob("*.xml")):
        root = ET.parse(xml_path).getroot()
        image_w = int(root.findtext("size/width"))
        image_h = int(root.findtext("size/height"))
        lines = []

        for obj in root.findall("object"):
            name = obj.findtext("name")
            if name not in class_to_id:
                raise ValueError(f"unknown VOC class: {name}")
            box = obj.find("bndbox")
            x1 = float(box.findtext("xmin"))
            y1 = float(box.findtext("ymin"))
            x2 = float(box.findtext("xmax"))
            y2 = float(box.findtext("ymax"))
            normalized = to_yolo(x1, y1, x2, y2, image_w, image_h)
            if normalized is None:
                raise ValueError(f"invalid box in {xml_path.name}")
            cx, cy, bw, bh = normalized
            lines.append(
                f"{class_to_id[name]} {cx:.6f} {cy:.6f} {bw:.6f} {bh:.6f}"
            )

        (Path(output_dir) / f"{xml_path.stem}.txt").write_text(
            "\n".join(lines) + ("\n" if lines else ""), encoding="utf-8"
        )
        converted += 1

    (Path(output_dir) / "classes.txt").write_text(
        "\n".join(class_names) + "\n", encoding="utf-8"
    )
    return converted

def convert_coco(json_file, output_dir):
    data = json.loads(Path(json_file).read_text(encoding="utf-8"))
    categories = sorted(data["categories"], key=lambda item: item["id"])
    category_to_class = {item["id"]: idx for idx, item in enumerate(categories)}
    images = {item["id"]: item for item in data["images"]}
    annotations = defaultdict(list)

    for ann in data["annotations"]:
        annotations[ann["image_id"]].append(ann)

    for image_id, image in images.items():
        lines = []
        for ann in annotations.get(image_id, []):
            x, y, w, h = ann["bbox"]
            normalized = to_yolo(
                x, y, x + w, y + h, image["width"], image["height"]
            )
            if normalized is None:
                raise ValueError(f"invalid box in image_id={image_id}")
            cx, cy, bw, bh = normalized
            class_id = category_to_class[ann["category_id"]]
            lines.append(f"{class_id} {cx:.6f} {cy:.6f} {bw:.6f} {bh:.6f}")

        stem = Path(image["file_name"]).stem
        (Path(output_dir) / f"{stem}.txt").write_text(
            "\n".join(lines) + ("\n" if lines else ""), encoding="utf-8"
        )

    class_names = [item["name"] for item in categories]
    (Path(output_dir) / "classes.txt").write_text(
        "\n".join(class_names) + "\n", encoding="utf-8"
    )
    return len(images)

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--format", choices=["voc", "coco"], required=True)
    parser.add_argument("--input", required=True)
    parser.add_argument("--output", required=True)
    parser.add_argument("--classes")
    args = parser.parse_args()

    output_dir = Path(args.output)
    output_dir.mkdir(parents=True, exist_ok=True)

    if args.format == "voc":
        if not args.classes:
            parser.error("--classes is required for VOC")
        count = convert_voc(args.input, output_dir, args.classes)
    else:
        count = convert_coco(args.input, output_dir)

    print(f"converted_images={count}")
    print(f"output_dir={output_dir}")

if __name__ == "__main__":
    main()

VOC 转换命令:

bash
python convert_to_yolo.py --format voc --input <PATH>/Annotations --output <PATH>/labels --classes <PATH>/classes.txt

预期输出:

text
converted_images=<VALUE>
output_dir=<PATH>/labels

COCO 转换命令:

bash
python convert_to_yolo.py --format coco --input <PATH>/annotations/instances_train.json --output <PATH>/labels

预期输出:

text
converted_images=<VALUE>
output_dir=<PATH>/labels

<PATH> 与 <VALUE> 会随数据集实际位置和图片数量变化。

验证转换后的标签

不要只确认“生成了 txt 文件”。至少检查标签文件数量是否与图片对应、每行是否恰好 5 列、四个坐标是否处于 0~1 且宽高大于 0。抽查一条标签时,还要把它还原到原图确认框的位置没有偏移。

例如标签:

text
2 0.512500 0.437500 0.225000 0.350000

它表示类别 ID 为 2,目标中心位于图像宽度约 51.25%、高度约 43.75% 的位置,框宽约占 22.5%,框高约占 35%。

处理边界与异常标注

脚本遇到零面积框、越界框或未知类别时直接报错,而不是悄悄丢弃。这更适合训练数据准备,因为异常若被静默忽略,往往要到训练指标异常时才暴露。

COCO 中还可能出现 iscrowd、分割掩码或非连续类别 ID。只做目标检测时,要先明确哪些标注需要保留,再把原始类别映射为连续 YOLO 类别编号。部分 VOC 导出工具还可能采用不同的像素坐标约定,若抽查发现固定 1 像素偏移,应以原始标注工具的定义为准,而不是盲目统一加减 1。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

转换常见标注格式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通