Link to this sectionCOCO Annotasyonlarını YOLO Formatına Nasıl Dönüştürürsün#

Ultralytics YOLO modellerini eğitmek, annotasyonların YOLO formatında olmasını gerektirir, ancak birçok popüler annotasyon aracı bunun yerine COCO JSON formatında çıktı verir. Bu rehber, COCO annotasyonlarını YOLO formatına nasıl dönüştüreceğini ve nesne algılama, örnek bölümleme ve poz tahmini modellerini eğitmeye nasıl başlayacağını gösterir.

Link to this sectionNeden COCO'dan YOLO'ya Dönüştürmelisin?#

COCO JSON formatı tüm açıklamaları tek bir dosyada saklarken, YOLO her görsel için normalleştirilmiş koordinatlara sahip bir metin dosyası kullanır. Dönüştürme işlemi şu nedenlerle gereklidir:

• YOLO modelleri, .txt etiket dosyaları gerektirir. Her görsel için bir dosya olmalı ve bu dosya normalize edilmiş koordinatlarda class x_center y_center width height bilgilerini içermelidir.
• COCO JSON, piksel koordinatlarını [x_min, y_min, width, height] formatında kullanır ve tüm görseller için tek bir JSON dosyası içerir.
• Sınıf ID'leri farklıdır — COCO rastgele category_id değerleri kullanırken, YOLO sıfır tabanlı (zero-indexed) sınıf ID'leri gerektirir.

Link to this sectionHı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ı düzenle, bir dataset.yaml oluştur ve eğitime başla. Aşağıdaki tam adım adım rehbere göz at.

Link to this sectionAdım Adım Dönüştürme Rehberi#

Link to this section1. 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" }
    ]
}

Link to this section2. Annotasyonları Dönüştür#

Use the convert_coco() function to convert your COCO JSON annotations to YOLO .txt format:

from ultralytics.data.converter import convert_coco

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

convert_coco() writes one .txt file per annotated image into a labels/ subdirectory named after each JSON file, with the instances_ prefix removed (so instances_train.json produces labels/train/). Images with no annotations are skipped and get no label file, so the labels/ tree may not mirror every image:

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

Link to this section3. Dizin Yapısını Düzenle#

After conversion, label files need to be placed alongside your images. YOLO expects a labels/ directory that mirrors the images/ directory:

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 şu şekilde görünmelidir:

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

Link to this section4. dataset.yaml Oluştur#

COCO kategorilerini YOLO sınıf isimlerine eşleyen bir dataset.yaml yapılandırma dosyası oluştur. Bu dosya, YOLO'ya verinin nerede olduğunu ve hangi sınıfların algılanacağı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 rehberine bak.

Link to this section5. 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 rehberine bak.

Link to this section6. 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}"

Link to this sectionYaygın Sorunları Giderme#

Link to this sectionDö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-80 arama tablosu üzerinden eşler.

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

Link to this sectionEğitim Sırasında Etiket Bulunamadı#

If training shows WARNING: No labels found or 0 images, N backgrounds, your label files are not in the expected directory. convert_coco() saves labels to a separate output directory (e.g., save_dir/labels/train/), but YOLO expects labels/ parallel to images/ inside your dataset directory.

Çözüm: Etiket dosyalarını, beklenen dizin yapısına uyacak şekilde taşı. labels/train/ dizininin images/train/ dizininin kardeşi olduğundan emin ol.

Link to this sectionDönüştürme Sırasında KeyError#

If you get KeyError: 'bbox' or similar errors when running convert_coco(), your labels_dir likely contains non-instance JSON files (e.g., captions_train2017.json) that have a different annotation structure.

Solution: Only place instance annotation JSON files (e.g., instances_train2017.json) in the labels_dir.

Link to this sectionDönüştürme Sonrası Boş Etiket Dosyaları#

Dönüştürme tamamlanıyor ancak .txt dosyaları boş veya eksikse, tüm annotasyonlar iscrowd: 1 değerine sahip olabilir (SAM tarafından oluşturulan maskelerde yaygındır) veya sınırlayıcı kutuların genişliği veya yüksekliği sıfırdır.

Çözüm: JSON annotasyonlarını iscrowd değerleri açısından incele. SAM maskeleri kullanıyorsan, iscrowd: 0 olarak ayarlamak için JSON'u önceden işle.

Link to this sectionDönüştürülmüş Etiketlerde Sınıf ID Boşlukları#

Etiket dosyalarındaki sınıf ID'leri ardışık değilse (örneğin 0, 1, 2 yerine 0, 4, 9 gibi), annotasyon aracın ardışık olmayan category_id değerleri kullanıyordur.

Solution: Verify the class IDs in your .txt files match the names dictionary in dataset.yaml. Remap IDs to contiguous values if needed.

Tam API detayları ve parametre açıklamaları için convert_coco API referansına bak.

Link to this sectionSSS#

Link to this sectionCOCO JSON annotasyonlarını YOLO formatına nasıl dönüştürürüm?#

Use the convert_coco() function from Ultralytics to convert COCO JSON annotations to YOLO .txt format. Set cls91to80=False for custom datasets:

from ultralytics.data.converter import convert_coco

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

Dönüştürmeden sonra, labels/ dizininin images/ dizinini yansıtması için etiket dosyalarını yeniden düzenle, ardından bir dataset.yaml dosyası oluştur. Tam iş akışı için adım adım rehbere bak.

Link to this sectionYOLO eğitimi neden COCO dönüştürmesinden sonra "No labels found" hatası verir?#

This happens because convert_coco() saves labels to a subdirectory inside save_dir/labels/ (e.g., save_dir/labels/train/) rather than directly into your dataset's labels/train/ alongside images/train/. YOLO expects labels to sit parallel to images — for example, images/train/img.jpg needs labels/train/img.txt. Move your converted labels to match this structure. See fixing the directory structure.

Link to this sectionWhat does cls91to80 do in convert_coco()?#

The cls91to80 parameter controls how COCO category_id values are mapped to YOLO class IDs. When True (default), it applies the coco91_to_coco80_class() lookup table designed for the standard COCO dataset, which has 80 classes with non-contiguous IDs (1-90). For custom datasets, always set cls91to80=False — this simply subtracts 1 from each category_id to create zero-indexed class IDs.

Link to this sectionYOLO'yu dönüştürmeden doğrudan COCO JSON üzerinde eğitebilir miyim?#

Mevcut YOLO eğitim hattıyla hayır; annotasyonların her görsel için bir dosya olacak şekilde YOLO .txt formatında olması gerekir. Önce COCO JSON dosyanı dönüştürmek için convert_coco() kullan, ardından düzenlemek ve eğitmek için bu rehberi takip et. Desteklenen formatlar hakkında daha fazla bilgi için veri seti formatlarına bak.

Link to this sectionCOCO bölümleme (segmentation) annotasyonlarını YOLO formatına dönüştürebilir miyim?#

Yes, use use_segments=True when calling convert_coco() to include polygon segmentation masks in the converted YOLO labels. This produces label files compatible with YOLO segmentation models:

from ultralytics.data.converter import convert_coco

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

Link to this sectionCOCO anahtar nokta (keypoint) annotasyonlarını YOLO formatına nasıl dönüştürürüm?#

Use use_keypoints=True to convert COCO keypoint annotations for pose estimation training:

from ultralytics.data.converter import convert_coco

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

Hem use_segments hem de use_keypoints True olarak ayarlanırsa, etiket dosyalarına sadece anahtar noktaların yazılacağını ve segmentlerin sessizce göz ardı edileceğini unutma.