Comment convertir COCO au YOLO

Formation Ultralytics YOLO nécessitent des annotations au YOLO , mais de nombreux outils d'annotation courants exportent plutôt au format COCO . Ce guide vous explique comment convertir vos COCO au YOLO et commencer à entraîner des modèles de détection d'objets, de segmentation d'instances et d'estimation de pose.

Pourquoi passer de COCO YOLO?

Le format COCO stocke toutes les annotations dans un seul fichier, tandis que YOLO utilise un fichier texte par image avec des coordonnées normalisées. La conversion est nécessaire car :

• YOLO nécessitent .txt fichiers d'étiquettes avec un fichier par image, contenant class x_center y_center width height en coordonnées normalisées.
• COCO JSON utilise des coordonnées de pixels dans [x_min, y_min, width, height] format utilisant un seul fichier JSON pour toutes les images.
• Les ID de classe diffèrent — COCO des valeurs arbitraires category_id valeurs, tandis que YOLO des identifiants de classe indexés à partir de zéro.

Démarrage rapide

La manière la plus rapide de convertir COCO et de commencer l'entraînement :

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
)

Après la conversion, organisez votre structure de répertoires, créez un fichier dataset.yaml, et démarrez l'entraînement. Consultez le guide étape par étape complet ci-dessous.

Guide de conversion étape par étape

1. Préparez votre jeu de données COCO

Un jeu de données typique au format COCO exporté des outils d'annotation a la structure suivante :

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

Chaque fichier JSON suit le Format de données COCO spécification comportant trois champs obligatoires — images, annotations, et 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. Convertissez les annotations

Utilisez la convert_coco() fonction permettant de convertir vos annotations COCO au format YOLO .txt format :

from ultralytics.data.converter import convert_coco

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

from ultralytics.data.converter import convert_coco

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

from ultralytics.data.converter import convert_coco

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

3. Organiser la structure des répertoires

Après la conversion, les fichiers d'étiquettes doivent être placés à côté de vos images. YOLO s'attend à un labels/ répertoire qui reflète le images/ répertoire :

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))

La structure finale de votre ensemble de données devrait ressembler à ceci :

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

4. Créer dataset.yaml

Créer un fichier dataset.yaml fichier de configuration qui mappe vos catégories COCO aux noms de classes YOLO. Ce fichier indique à YOLO où se trouvent vos données et quelles classes detecter :

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)

Le fichier YAML obtenu :

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

Pour plus d'informations sur le format YAML des ensembles de données, consultez le guide de configuration des ensembles de données.

5. Entraîner votre modèle YOLO

Une fois votre ensemble de données converti prêt, entraînez un 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)

yolo detect train model=yolo26n.pt data=my_dataset/dataset.yaml epochs=100 imgsz=640

Pour obtenir des conseils et des bonnes pratiques en matière d'entraînement, consultez le guide d'entraînement des modèles.

6. Vérifiez votre conversion

Avant l'entraînement, vérifiez quelques fichiers d'étiquettes pour confirmer que les ID de classe et les coordonnées sont corrects :

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}"

Dépannage des problèmes courants

Identifiants de classe erronés après la conversion

Si votre modèle fonctionne mais détecte des classes d'objets erronées, vous utilisez probablement cls91to80=True (par défaut) sur un jeu de données personnalisé. Cela mappe votre category_id valeurs via la table de conversion COCO , qui n'est valable que pour la norme Ensemble de données COCO.

Solution: Toujours utiliser cls91to80=False pour les ensembles de données personnalisés.

Aucune étiquette n'a été trouvée pendant la formation

Si les entraînements montrent WARNING: No labels found ou 0 images, N backgrounds, vos fichiers d'étiquettes ne se trouvent pas dans le répertoire attendu. convert_coco() enregistre les étiquettes dans un répertoire de sortie distinct (par exemple, save_dir/labels/train/), mais YOLO attend labels/ parallèlement à images/ dans le répertoire de votre ensemble de données.

Solution: Déplacez les fichiers d'étiquettes pour correspondre au format attendu structure de répertoires. Assurez-vous labels/train/ est un équivalent de images/train/.

Erreur KeyError lors de la conversion

Si vous obtenez KeyError: 'bbox' ou des erreurs similaires lors de l'exécution convert_coco(), votre labels_dir contient probablement des fichiers JSON non liés à une instance (par exemple, captions_train2017.json) qui ont une structure d'annotation différente.

Solution: Placez uniquement les fichiers JSON d'annotation d'instance (par exemple, instances_train2017.json) dans le labels_dir.

Fichiers d'étiquettes vides après la conversion

Si la conversion s'achève mais .txt si les fichiers sont vides ou manquants, toutes les annotations peuvent avoir iscrowd: 1 (courant avec SAM-masques générés), ou boîtes englobantes ont une largeur ou une hauteur nulle.

Solution: Inspectez vos annotations JSON pour iscrowd valeurs. Si vous utilisez SAM , prétraitez le fichier JSON pour définir iscrowd: 0.

Écarts d'ID de classe dans les étiquettes converties

Si les identifiants de classe dans les fichiers d'étiquettes ne sont pas contigus (par exemple, 0, 4, 9 au lieu de 0, 1, 2), votre outil d'annotation utilise des identifiants non contigus category_id valeurs.

Solution: Vérifiez les ID de classe dans votre .txt les fichiers correspondent au names dictionnaire dans dataset.yaml. Re-mapper les ID à des valeurs contiguës si nécessaire.

Pour obtenir des informations complètes sur l'API et la description des paramètres, consultez le convert_coco Référence de l'API.

FAQ

Comment convertir les annotations COCO au YOLO ?

Utilisez la convert_coco() fonction d'Ultralytics convertir les annotations COCO au format YOLO .txt format. Définir cls91to80=False pour les ensembles de données personnalisés :

from ultralytics.data.converter import convert_coco

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

Après la conversion, réorganisez vos fichiers d'étiquettes afin que labels/ reflète le images/ répertoire, puis créez un dataset.yaml fichier. Voir le guide étape par étape pour le flux de travail complet.

Pourquoi YOLO affiche-t-il « Aucune étiquette trouvée » après COCO ?

Cela s'explique par le fait que convert_coco() enregistre les étiquettes dans un sous-répertoire situé à l'intérieur de save_dir/labels/ (par exemple, save_dir/labels/train/) plutôt que directement dans le labels/train/ à côté de images/train/. YOLO s'attend à ce que les étiquettes soient parallèles aux images — par exemple, images/train/img.jpg besoins labels/train/img.txt. Déplacez vos étiquettes converties pour qu'elles correspondent à cette structure. Voir définition de la structure des répertoires.

Que signifie cls91to80 faire dans convert_coco()?

L'argument cls91to80 Ce paramètre détermine comment COCO category_id les valeurs sont associées aux identifiants YOLO . Lorsque True (par défaut), il utilise une table de correspondance conçue pour le standard Ensemble de données COCO, qui comporte 80 classes avec des ID non contigus (1-90). Pour jeux de données personnalisés, toujours défini cls91to80=False — cela revient simplement à soustraire 1 de chaque category_id pour créer des identifiants de classe à indexation zéro.

Puis-je entraîner YOLO directement sur du JSON COCO sans conversion ?

Ce n'est pas le cas avec le pipeline YOLO actuel : les annotations doivent être au format YOLO .txt format avec un fichier par image. Utilisez convert_coco() Commencez par convertir votre COCO , puis suivez ces instructions guide pour organiser et former. Pour en savoir plus sur les formats pris en charge, consultez formats de jeu de données.

Puis-je convertir les annotations de segmentation COCO au format YOLO ?

Oui, utilisez use_segments=True lors de l'appel convert_coco() pour inclure des masques de segmentation polygonale dans les YOLO converties. Cela permet d'obtenir des fichiers d'étiquettes compatibles avec Modèles YOLO:

from ultralytics.data.converter import convert_coco

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

Comment convertir les annotations COCO au YOLO ?

Utilisez use_keypoints=True pour convertir les annotations COCO pour estimation de pose formation :

from ultralytics.data.converter import convert_coco

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

Notez que si les deux use_segments et use_keypoints sont définis à True, seuls les points clés seront écrits dans les fichiers d'étiquettes — les segments sont silencieusement ignorés.

📅 Créé il y a 7 jours ✏️ Mis à jour il y a 7 jours

Commentaires