COCO Annotasyonlarını YOLO Formatına Nasıl Dönüştürürsün#

Ultralytics YOLO modellerini eğitmek, YOLO formatında etiketler gerektirir, ancak birçok popüler etiketleme aracı bunun yerine COCO JSON formatında dışa aktarım yapar. Bu kılavuz, COCO etiketlerini YOLO formatına nasıl dönüştüreceğinizi ve nesne algılama, örnek bölütleme ve poz kestirimi modellerini eğitmeye nasıl başlayacağınızı gösterir.

Neden COCO'dan YOLO'ya Dönüştürmelisin?#

COCO JSON formatı tüm etiketleri tek bir dosyada saklarken, YOLO normalize edilmiş koordinatlarla her görsel için bir metin dosyası kullanır. Dönüştürme işlemi gereklidir çünkü:

• YOLO modelleri, normalize koordinatlarda class x_center y_center width height içeren, her görsel için bir dosya olacak şekilde .txt etiket dosyaları gerektirir.
• COCO JSON, tüm görseller için tek bir JSON dosyası ile birlikte [x_min, y_min, width, height] formatında piksel koordinatları kullanır.
• Sınıf kimlikleri farklıdır — COCO rastgele category_id değerleri kullanırken, YOLO sıfırdan başlayan sınıf kimlikleri gerektirir.

Hızlı Başlangıç#

COCO annotasyonlarını dönüştürmenin ve eğitime başlamanın en hızlı yolu:

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="my_dataset/annotations/",  # directory containing your JSON files
    save_dir="my_dataset/converted/",  # where to save converted labels
    cls91to80=False,  # set False for custom datasets (see warning below)
)

Dönüştürmeden sonra dizin yapını organize et, bir dataset.yaml oluştur ve eğitime başla. Aşağıdaki tam adım adım kılavuza göz at.

Adım Adım Dönüştürme Rehberi#

1. COCO Veri Setini Hazırla#

Annotasyon araçlarından dışa aktarılan tipik bir COCO formatlı veri seti şu yapıdadır:

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

Her JSON dosyası, üç zorunlu alan içeren COCO veri formatı spesifikasyonunu takip eder — images, annotations ve 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. Annotasyonları Dönüştür#

COCO JSON ek açıklamalarınızı YOLO .txt formatına dönüştürmek için convert_coco() fonksiyonunu kullanın:

from ultralytics.data.converter import convert_coco

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

convert_coco(), ek açıklama eklenmiş her görüntü için .txt dizini altında her JSON dosyasının adıyla ve labels/ ön eki kaldırılmış (instances_ dosyası instances_train.json üretir) bir labels/train/ dosyası yazar. Ek açıklaması olmayan görüntüler atlanır ve etiket dosyası almaz; bu nedenle labels/ ağacı her görüntüyü yansıtmayabilir:

my_dataset/converted/
└── labels/
    ├── train/   # from instances_train.json
    │   ├── img_001.txt
    │   └── ...
    └── val/     # from instances_val.json
        └── ...

3. Dizin Yapısını Düzenle#

Dönüşümden sonra, etiket dosyalarının görsellerinizle birlikte yerleştirilmesi gerekir. YOLO, images/ dizinini yansıtan bir labels/ dizini bekler:

import shutil
from pathlib import Path

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

# convert_coco names each subdirectory after its JSON file (minus the "instances_" prefix),
# so iterate the actual subdirectories instead of assuming "train"/"val".
for src in converted_dir.iterdir():
    if not src.is_dir():
        continue
    dst = dataset_dir / "labels" / src.name
    dst.mkdir(parents=True, exist_ok=True)
    for f in src.glob("*.txt"):
        shutil.move(str(f), str(dst / f.name))

Nihai veri seti yapın şuna benzer olmalıdır:

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

4. dataset.yaml Oluştur#

COCO kategorilerini YOLO sınıf adlarıyla eşleyen bir dataset.yaml yapılandırma dosyası oluştur. Bu dosya YOLO'ya verilerinin nerede olduğunu ve hangi sınıfları algılayacağını söyler:

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)

Oluşan YAML dosyası:

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

Veri seti YAML formatı hakkında daha fazla ayrıntı için veri seti yapılandırma kılavuzuna bakın.

5. YOLO Modelini Eğit#

Dönüştürülmüş veri setin hazır olduğunda bir YOLO modelini eğit:

from ultralytics import YOLO

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

Eğitim ipuçları ve en iyi uygulamalar için model eğitimi kılavuzuna bakın.

6. Dönüştürmeni Doğrula#

Eğitimden önce, sınıf ID'lerinin ve koordinatların doğru olduğunu teyit etmek için birkaç etiket dosyasını rastgele kontrol et:

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

Yaygın Sorunları Giderme#

Dönüştürme Sonrası Yanlış Sınıf ID'leri#

Eğer modelin eğitiliyor ancak yanlış nesne sınıflarını algılıyorsa, büyük ihtimalle özel bir veri setinde cls91to80=True (varsayılan) kullanıyorsundur. Bu, category_id değerlerini, yalnızca standart COCO veri seti için doğru olan COCO 91'den 80'e arama tablosu üzerinden eşler.

Çözüm: Özel veri setleri için her zaman cls91to80=False kullan.

Eğitim Sırasında Etiket Bulunamadı#

Eğitim sırasında WARNING: No labels found veya 0 images, N backgrounds hatası alıyorsanız, etiket dosyalarınız beklenen dizinde değil demektir. convert_coco(), etiketleri ayrı bir çıktı dizinine kaydeder (ör. save_dir/labels/train/), ancak YOLO, veri seti dizininizin içinde images/ ile paralel bir labels/ bekler.

Çözüm: Etiket dosyalarını beklenen dizin yapısıyla eşleşecek şekilde taşı. labels/train/ öğesinin images/train/ ile kardeş olduğundan emin ol.

Dönüştürme Sırasında KeyError#

convert_coco() çalıştırırken KeyError: 'bbox' veya benzer hatalar alıyorsanız, labels_dir'niz muhtemelen farklı bir açıklama yapısına sahip örnek dışı JSON dosyaları (ör. captions_train2017.json) içeriyordur.

Çözüm: labels_dir içine yalnızca örnek açıklama JSON dosyalarını (ör. instances_train2017.json) yerleştirin.

Dönüştürme Sonrası Boş Etiket Dosyaları#

Dönüştürme tamamlanır ancak .txt dosyaları boş veya eksikse, tüm etiketlerin iscrowd: 1 değeri olabilir (SAM tarafından üretilen maskelerde yaygındır) veya sınırlayıcı kutuların sıfır genişliği veya yüksekliği vardır.

Çözüm: iscrowd değerleri için JSON etiketlerini incele. SAM maskeleri kullanıyorsan, iscrowd: 0 değerini ayarlamak için JSON'ı önceden işle.

Mask Etiketlerinden Kutu Şeklindeki Çokgenler#

Eğer use_segments=True annotations without a usable polygon kaydederse, bazı etiketler herhangi bir segmentation değerine sahip değildir veya bu değer en az üç koordinat çiftinden oluşan bir liste değildir. Yaygın nedenler, alanı eksik veya boş bırakan yalnızca algılama dışa aktarımları ve SAM gibi bit maskesi dışa aktarıcılarının yazdığı COCO çalışma uzunluğu kodlamasıdır ({"counts": ..., "size": ...}); çevreleyen çokgen listesi olmayan düz bir koordinat listesi, bir ve iki noktalı dış hatlar ve diğer bozuk değerler aynı şekilde ele alınır. Bir etiket kalan çokgenleri korur ve hiçbiri kalmadığında sınırlayıcı kutusu şeklinde bir segment satırına geri döner, böylece etiketler geçerli kalır ancak bu satırlar maske detayı içermez.

Çözüm: Etiketleri çokgen segmentasyonlarıyla yeniden dışa aktar, convert_coco() çalıştırmadan önce RLE maskelerini çokgenlere dönüştür veya bozuk segmentation değerlerini düzelt.

Dönüştürülmüş Etiketlerde Sınıf ID Boşlukları#

Etiket dosyalarındaki sınıf kimlikleri ardışık değilse (örn. 0, 1, 2 yerine 0, 4, 9), etiketleme aracın ardışık olmayan category_id değerleri kullanıyordur.

Çözüm: .txt dosyalarınızdaki sınıf kimliklerinin dataset.yaml içindeki names sözlüğüyle eşleştiğini doğrulayın. Gerekirse kimlikleri ardışık değerlere yeniden eşleyin.

Tam API detayları ve parametre açıklamaları için convert_coco API referansına göz at.

SSS#