COCO YOLO 변환하는 방법

교육 Ultralytics YOLO 모델은 YOLO 주석이 필요하지만, 많은 인기 있는 주석 도구는 COCO 형식으로 내보냅니다. 이 가이드에서는 COCO YOLO 변환하고, 물체 탐지, 인스턴스 분할 및 자세 추정 모델 훈련을 시작하는 방법을 안내합니다.

왜 COCO 에서 YOLO COCO 변환해야 할까요?

COCO 형식은 모든 주석을 단일 파일에 저장하는 반면, YOLO 는 정규화된 좌표가 포함된 이미지당 하나의 텍스트 파일을 사용합니다. 변환이 필요한 이유는 다음과 같습니다:

• YOLO 다음이 필요합니다 .txt 라벨 파일 이미지당 하나의 파일로 구성되며, 각 파일에는 다음 내용이 포함됩니다. class x_center y_center width height 정규화된 좌표계에서.
• COCO JSON은 픽셀 좌표를 사용합니다. 에서 [x_min, y_min, width, height] 모든 이미지를 단일 JSON 파일로 구성합니다.
• 클래스 ID가 다릅니다 — COCO 임의의 category_id 값을 사용하는 반면, YOLO 0부터 시작하는 클래스 ID를 YOLO .

빠른 시작

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 데이터 형식 세 개의 필수 입력란이 포함된 사양 — 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 어노테이션을 YOLO 형식으로 변환하는 함수 .txt 포맷:

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. 디렉터리 구조 구성

변환 후, 레이블 파일은 이미지와 함께 배치되어야 합니다. 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.yaml COCO 카테고리를 YOLO 클래스 이름에 매핑하는 구성 파일입니다. 이 파일은 YOLO에 데이터 위치와 detect할 클래스를 알려줍니다.

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)

yolo detect train model=yolo26n.pt 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 조회표를 통해 값을 산출하는데, 이는 표준 사양에 대해서만 정확합니다 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 아마도 인스턴스가 아닌 JSON 파일들이 포함되어 있을 것입니다 (예: captions_train2017.json)는 다른 어노테이션 구조를 가집니다.

솔루션: 인스턴스 주석 JSON 파일만 배치하십시오 (예: instances_train2017.json)에서 labels_dir.

변환 후 빈 레이블 파일

변환이 완료되었지만 .txt 파일이 비어 있거나 누락된 경우, 모든 주석이 iscrowd: 1 (일반적으로 SAM-생성된 마스크), 또는 bounding box 너비나 높이가 0입니다.

솔루션: JSON 주석을 검사합니다. iscrowd 값. SAM 사용하는 경우, JSON을 전처리하여 iscrowd: 0.

변환된 레이블의 클래스 ID 간격

라벨 파일의 클래스 ID가 연속적이지 않은 경우(예: 0, 1, 2 대신 0, 4, 9), 주석 도구는 연속적이지 않은 category_id 가치.

솔루션: 클래스 ID를 확인하십시오. .txt 파일이 다음 조건과 일치합니다 names 사전에서 dataset.yaml. 필요한 경우 ID를 연속 값으로 다시 매핑하십시오.

API에 대한 자세한 내용과 매개변수 설명은 다음을 참조하십시오. convert_coco API 참조.

FAQ

COCO 어노테이션을 YOLO 변환하려면 어떻게 해야 하나요?

다음을 사용하여 convert_coco() COCO 주석을 YOLO 형식으로 Ultralytics 함수 .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 결과에서 왜 “라벨을 찾을 수 없음”이라고 표시되나요?

이런 일이 발생하는 이유는 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을 뺀 것입니다 category_id 0을 첫 번째 인덱스로 하는 클래스 ID를 생성하려면.

변환 없이 COCO JSON에서 YOLO를 직접 훈련할 수 있나요?

현재의 YOLO 파이프라인에서는 불가능합니다. 라벨링 데이터는 YOLO 형식으로 되어 있어야 합니다. .txt 이미지당 하나의 파일로 구성하는 형식. 다음을 사용하십시오 convert_coco() 먼저 COCO 파일을 변환한 다음, 다음 단계를 따르세요 안내서 조직하고 교육하기 위해. 지원되는 형식에 대한 자세한 내용은 다음을 참조하십시오. 데이터셋 형식.

COCO segment 주석을 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)

COCO 주석을 YOLO 변환하려면 어떻게 해야 하나요?

다음을 사용합니다. use_keypoints=True 다음에 대한 COCO 주석을 변환하려면 포즈 추정 교육:

from ultralytics.data.converter import convert_coco

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

두 가지 모두 해당되는 경우 use_segments 및 use_keypoints ~로 설정됩니다 True, 레이블 파일에는 키포인트만 기록되며 — segment는 자동으로 무시됩니다.

📅 7일 전 생성 ✏️ 6일 전 업데이트

댓글