YOLO Format

Ultralytics YOLO directory format for object detection

YOLO (Ultralytics-style) is a directory-based format commonly used for training YOLOv5, YOLOv8, and related models. Panlabel supports reading and writing YOLO datasets.

Overview

• Path type: Directory with images/ and labels/
• Lossiness: Lossy (see below)
• Bbox format: Normalized center-width-height [cx, cy, w, h] (0..1)
• Use case: YOLO model training, Ultralytics ecosystem

Directory Structure

dataset/
├── images/
│   ├── train/
│   │   ├── img1.jpg
│   │   └── img2.jpg
│   └── val/
│       └── img3.jpg
├── labels/
│   ├── train/
│   │   ├── img1.txt
│   │   └── img2.txt
│   └── val/
│       └── img3.txt
├── data.yaml
└── classes.txt (optional)

Key Components

• images/: Contains image files (.jpg, .png, .jpeg, .bmp, .webp)
• labels/: Contains label files (.txt), one per image
• data.yaml: Class map configuration (written by Panlabel)
• classes.txt: Alternative class map format (read by Panlabel)

Label File Format

Each .txt file in labels/ contains one line per bounding box:

<class_id> <x_center> <y_center> <width> <height>

All values are normalized (0.0 to 1.0 range):

• class_id: Integer class index (0-based)
• x_center: Center X coordinate (0..1)
• y_center: Center Y coordinate (0..1)
• width: Box width (0..1)
• height: Box height (0..1)

Example Label File

labels/train/img1.txt:

0 0.500000 0.500000 0.300000 0.200000
1 0.250000 0.750000 0.150000 0.100000

Interpretation:

• Line 1: Class 0, center at (50%, 50%), size 30% × 20%
• Line 2: Class 1, center at (25%, 75%), size 15% × 10%

Class Map

YOLO uses integer class IDs. Panlabel supports three class map sources:

1. data.yaml (preferred)

names:
  0: 'person'
  1: 'bicycle'
  2: 'car'

or sequence format:

names:
  - person
  - bicycle
  - car

2. classes.txt (fallback)

person
bicycle
car

Each line corresponds to a class ID (0-based).

3. Inferred from labels (last resort)

If neither data.yaml nor classes.txt exists, Panlabel infers class names as class_0, class_1, etc.

Precedence: data.yaml → classes.txt → inferred

Bounding Box Format

YOLO uses normalized center-width-height coordinates:

<cx> <cy> <w> <h>

Panlabel converts to/from IR pixel-space XYXY.

Conversion Example

YOLO label:

0 0.5 0.5 0.3 0.2

Image size: 640 × 480 pixels

Conversion to pixel XYXY:

1. cx = 0.5 × 640 = 320
2. cy = 0.5 × 480 = 240
3. w = 0.3 × 640 = 192
4. h = 0.2 × 480 = 96
5. xmin = cx - w/2 = 320 - 96 = 224
6. ymin = cy - h/2 = 240 - 48 = 192
7. xmax = cx + w/2 = 320 + 96 = 416
8. ymax = cy + h/2 = 240 + 48 = 288

IR bbox: [224.0, 192.0, 416.0, 288.0]

Reader Behavior

Input Path

Accepts:

• Dataset root containing images/ and labels/
• labels/ directory directly (expects sibling ../images/)

Reading Process

1. Discover directory layout
2. Read class map (data.yaml → classes.txt → inferred)
3. Scan all images in images/ (recursively)
4. Read image dimensions from file headers
5. Match each label file to corresponding image (same stem)
6. Parse label lines (reject segmentation/pose formats with >5 tokens)
7. Assign deterministic IDs:
   • Image IDs: by filename (lexicographic)
   • Category IDs: by class name (lexicographic)
   • Annotation IDs: by row order

Expected Image Extensions

Lookup order: jpg, png, jpeg, bmp, webp

Validation

• Each label file must map to a matching image file
• Label lines with >5 tokens are rejected (segmentation/pose not supported)
• Class IDs must be within range of class map

Writer Behavior

Output Structure

output/
├── images/  (empty, placeholder)
├── labels/
│   └── (label .txt files)
└── data.yaml

Writing Process

1. Create images/ and labels/ directories
2. Write data.yaml with class map (sorted by category ID)
3. For each image:
   • Create label file at labels/<stem>.txt
   • Write annotations sorted by annotation ID
   • Write empty .txt file for images without annotations
4. Does not copy image binaries (images must be placed manually)

Coordinate Precision

Normalized floats written with 6 decimal places:

0 0.500000 0.750000 0.300000 0.200000

Subdirectories

Preserves image subdirectory structure:

• Image: train/img1.jpg → Label: labels/train/img1.txt

Lossiness

YOLO format is lossy. Not preserved:

• Dataset-level metadata/licenses
• Image-level license/date metadata
• Annotation confidence/attributes
• Category supercategory
• Custom attributes

Only preserved:

• Image filenames and dimensions
• Category names (via data.yaml)
• Bounding box coordinates

YOLO does not store image binaries during conversion. You must manually copy images to the images/ directory after writing.

Usage

Read YOLO

panlabel convert dataset/ output.json --input-format yolo --output-format ir-json

or from labels/ directly:

panlabel convert dataset/labels/ output.json --input-format yolo --output-format ir-json

Write YOLO

panlabel convert input.json yolo-output/ --input-format ir-json --output-format yolo

Then manually copy images:

cp -r original/images/* yolo-output/images/

Limitations

• Segmentation/pose annotations not supported (lines with >5 tokens rejected)
• Image binaries not copied during conversion
• No dataset-level metadata
• No annotation confidence/attributes

See Also

Pascal VOC

Another directory-based format

Format Overview

Compare all supported formats