COCOアノテーションをYOLOフォーマットに変換する方法

YOLOUltralytics YOLOモデルのトレーニングにはYOLOフォーマットのアノテーションが必要ですが、多くの一般的なアノテーションツールは代わりにCOCO JSONフォーマットでエクスポートします。このガイドでは、COCOアノテーションをYOLOフォーマットに変換し、トレーニングを開始する方法を説明します。物体検出, インスタンスセグメンテーション、および姿勢推定モデルに基づいてファインチューニングされます。

COCOからYOLOに変換する理由

COCO JSONフォーマットはすべての情報を1つのファイルに格納しますが、YOLOは画像ごとに1つのテキストファイルを使用し、正規化された座標で管理します。変換が必要な理由は以下の通りです：

• YOLOモデルは.txtラベルファイルを必要とし、画像ごとに1つのファイルで、class x_center y_center width heightを正規化された座標で含める必要があります。
• COCO JSONはピクセル座標内の[x_min, y_min, width, height]フォーマットを使用し、すべての画像に対して単一のJSONファイルを使用します。
• クラスIDの相違 — COCOは任意のcategory_id値を使用しますが、YOLOはゼロから始まるインデックスのクラスIDを必要とします。

クイックスタート

COCOアノテーションを変換してトレーニングを開始する最速の方法：

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="path/to/annotations/",  # directory containing your JSON files
    save_dir="path/to/output/",  # where to save converted labels
    cls91to80=False,  # IMPORTANT: set False for custom datasets
)

変換後、ディレクトリ構造を整理, dataset.yamlを作成、およびトレーニングを開始してください。完全なステップバイステップガイドを以下で確認してください。

ステップバイステップ変換ガイド

1. COCOデータセットの準備

アノテーションツールからエクスポートされた一般的なCOCOフォーマットのデータセットは、以下の構造になっています：

my_dataset/
├── images/
│   ├── train/
│   │   ├── img_001.jpg
│   │   ├── img_002.jpg
│   │   └── ...
│   └── val/
│       ├── img_100.jpg
│       └── ...
└── annotations/
    ├── instances_train.json
    └── instances_val.json

各JSONファイルはCOCOデータフォーマット仕様に従い、3つの必須フィールドが必要です — images, annotations、およびcategories:

{
    "images": [{ "id": 1, "file_name": "img_001.jpg", "width": 640, "height": 480 }],
    "annotations": [
        {
            "id": 1,
            "image_id": 1,
            "category_id": 1,
            "bbox": [100, 50, 200, 150],
            "area": 30000,
            "iscrowd": 0
        }
    ],
    "categories": [
        { "id": 1, "name": "helmet" },
        { "id": 2, "name": "vest" }
    ]
}

2. アノテーションの変換

コマンドを使用してトレーニングを開始する。（各convert_coco()関数を使用して、COCO JSONアノテーションをYOLO.txtフォーマットに変換します：

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="my_dataset/annotations/",
    save_dir="my_dataset/converted/",
    cls91to80=False,
)

3. ディレクトリ構造の整理

変換後、ラベルファイルを画像と同じ場所に配置する必要があります。YOLOはlabels/ディレクトリがimages/ディレクトリを反映することを期待します：

import shutil
from pathlib import Path

# Paths
converted_dir = Path("my_dataset/converted/labels")
dataset_dir = Path("my_dataset")

# Move labels next to images for each split
for split in ["train", "val"]:
    src = converted_dir / split  # convert_coco strips "instances_" prefix from JSON filename
    dst = dataset_dir / "labels" / split
    dst.mkdir(parents=True, exist_ok=True)
    for f in src.glob("*.txt"):
        shutil.move(str(f), str(dst / f.name))

最終的なデータセット構造は以下のようになる必要があります：

my_dataset/
├── images/
│   ├── train/
│   │   ├── img_001.jpg
│   │   └── ...
│   └── val/
│       └── ...
├── labels/
│   ├── train/
│   │   ├── img_001.txt
│   │   └── ...
│   └── val/
│       └── ...
└── dataset.yaml

4. dataset.yamlの作成

dataset.yamlCOCOカテゴリをYOLOクラス名にマッピングする設定ファイルです。このファイルは、データがどこにあるか、どのクラスを検出するかをYOLOに伝えます：

import json
from pathlib import Path

import yaml

# Read categories from your COCO JSON
with open("my_dataset/annotations/instances_train.json") as f:
    coco = json.load(f)

# Build class names matching convert_coco output (category_id - 1)
categories = sorted(coco["categories"], key=lambda x: x["id"])
names = {cat["id"] - 1: cat["name"] for cat in categories}
# NOTE: convert_coco maps class IDs as category_id - 1, so category_id must
# start from 1. If your categories start from 0, add 1 to each ID first.

# Create dataset.yaml
dataset = {
    "path": str(Path("my_dataset").resolve()),
    "train": "images/train",
    "val": "images/val",
    "names": names,
}

with open("my_dataset/dataset.yaml", "w") as f:
    yaml.dump(dataset, f, default_flow_style=False)

作成されたYAMLファイル：

path: /absolute/path/to/my_dataset
train: images/train
val: images/val
names:
    0: helmet
    1: vest

データセットYAMLフォーマットの詳細については、データセット設定ガイド.

5. YOLOモデルのトレーニング

変換されたデータセットの準備ができたら、YOLOモデルをトレーニングします：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # load a pretrained model
results = model.train(data="my_dataset/dataset.yaml", epochs=100, imgsz=640)

トレーニングのヒントとベストプラクティスについては、モデルトレーニングガイド.

6. 変換の検証

トレーニングの前に、いくつかのラベルファイルをチェックして、クラスIDと座標が正しいことを確認してください：

from pathlib import Path

label_file = Path("my_dataset/labels/train/img_001.txt")
for line in label_file.read_text().strip().splitlines():
    parts = line.split()
    cls_id = int(parts[0])
    coords = [float(v) for v in parts[1:5]]
    assert cls_id >= 0, f"Negative class ID {cls_id} — category_id in your JSON may start from 0"
    assert all(0 <= v <= 1 for v in coords), f"Coordinates out of [0, 1] range: {coords}"

よくある問題のトラブルシューティング

変換後のクラスIDの誤り

モデルはトレーニングされるが誤ったオブジェクトクラスを検出する場合、カスタムデータセットでcls91to80=True(デフォルト) を使用している可能性が高いです。これはcategory_id値をCOCO 91-to-80ルックアップテーブルでマッピングしますが、これは標準のデータセットに対してのみ正しいです。COCOデータセット.

解決策: カスタムデータセットには常にcls91to80=Falseを使用してください。

トレーニング中にラベルが見つからない

トレーニング中にWARNING: No labels foundや0 images, N backgroundsと表示される場合、ラベルファイルが予期されたディレクトリにありません。convert_coco()はラベルを別の出力ディレクトリ（例：save_dir/labels/train/）に保存しますが、YOLOはlabels/と並列のimages/をデータセットディレクトリ内で期待します。

解決策: ラベルファイルを予期されたディレクトリ構造。必ずlabels/train/がimages/train/.

変換中のKeyError

を実行中にKeyError: 'bbox'や同様のエラーが発生した場合、convert_coco()にはlabels_dir（例：captions_train2017.json）など、アノテーション構造が異なる非インスタンスのJSONファイルが含まれている可能性があります。

解決策：インスタンスアノテーションのJSONファイル（例：instances_train2017.json）のみをlabels_dir.

変換後にラベルファイルが空になる

変換は完了しても.txtファイルが空であるか存在しない場合、すべてのアノテーションがiscrowd: 1（SAMで生成されたマスクで一般的）であるか、バウンディングボックスの幅や高さがゼロである可能性があります。

解決策：JSONアノテーションのiscrowd値を確認してください。SAMマスクを使用している場合は、JSONを前処理してiscrowd: 0.

変換後のラベルにおけるクラスIDの欠落

ラベルファイルのクラスIDが連続していない場合（0, 1, 2ではなく0, 4, 9など）、アノテーションツールが連続していないcategory_id値を使用しています。

解決策：.txtファイル内のクラスIDがnames内のdataset.yaml辞書と一致していることを確認してください。必要に応じてIDを連続した値に再マッピングしてください。

APIの詳細やパラメータの説明については、convert_coco APIリファレンスを参照してください。.

FAQ

COCO JSONアノテーションをYOLO形式に変換するにはどうすればよいですか？

コマンドを使用してトレーニングを開始する。（各convert_coco()Ultralyticsの関数を使用して、COCO JSONアノテーションをYOLO.txt形式に変換します。カスタムデータセットの場合はcls91to80=Falseを設定してください：

from ultralytics.data.converter import convert_coco

convert_coco(labels_dir="path/to/annotations/", save_dir="output/", cls91to80=False)

変換後、ラベルファイルを整理してlabels/がimages/ディレクトリを反映するようにし、その後dataset.yamlファイルを作成します。完全なワークフローについてはステップバイステップガイドを参照してください。

COCO変換後にYOLOのトレーニングで「No labels found」と表示されるのはなぜですか？

これは、convert_coco()がラベルをsave_dir/labels/(例: save_dir/labels/train/内のサブディレクトリに保存するためですlabels/train/ではなく、データセットのimages/train/と並べて保存してください。YOLOはラベルが画像と並列であることを想定しています。例えば、images/train/img.jpgにはlabels/train/img.txtが必要です。変換されたラベルを移動してこの構造に合わせてください。ディレクトリ構造の修正.

においてcls91to80は何を行いますか？convert_coco()?

このcls91to80パラメータは、COCOのcategory_id値がどのようにYOLOのクラスIDにマッピングされるかを制御します。True（デフォルト）の場合、標準のCOCOデータセット用に設計されたルックアップテーブルを使用します。これには不連続なID（1-90）を持つ80のクラスが含まれています。カスタムデータセットの場合は、常に設計を採用しています。物体検出、分類、回帰を個別の経路で処理することにより、学習中のモデルの収束が早まり、多様なを設定してください。これにより、各cls91to80=Falseから単純に1が引かれ、0から始まるクラスIDが作成されます。category_id。

変換せずに直接COCO JSONでYOLOのトレーニングはできますか？

現在のYOLOトレーニングパイプラインではできません。アノテーションは画像ごとに1つのファイルを持つYOLO.txt形式である必要があります。convert_coco()を使用して最初にCOCO JSONを変換し、その後このガイドに従って整理とトレーニングを行ってください。サポートされている形式の詳細については、データセット形式.

COCOセグメンテーションアノテーションをYOLO形式に変換できますか？

はい、use_segments=Trueを呼び出す際にconvert_coco()を使用して、ポリゴンセグメンテーションマスクを変換後のYOLOラベルに含めてください。これにより、YOLOセグメンテーションモデル:

from ultralytics.data.converter import convert_coco

convert_coco(labels_dir="annotations/", save_dir="output/", use_segments=True, cls91to80=False)

と互換性のあるラベルファイルが生成されます。

長い動画や大規模なデータセットを処理するには、メモリを効率的に管理するためにuse_keypoints=TrueCOCOキーポイントアノテーションをYOLO形式に変換するにはどうすればよいですか？姿勢推定を使用して、

from ultralytics.data.converter import convert_coco

convert_coco(labels_dir="annotations/", save_dir="output/", use_keypoints=True, cls91to80=False)

トレーニング用のCOCOキーポイントアノテーションを変換してください：use_segmentsとuse_keypointsなお、両方がTrueに設定されている場合、キーポイントのみがラベルファイルに書き込まれます。セグメントは無視されます。