YOLO Format

​

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

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

• 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

0 0.500000 0.500000 0.300000 0.200000
1 0.250000 0.750000 0.150000 0.100000

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

​

Class Map

​

1. data.yaml (preferred)

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

names:
  - person
  - bicycle
  - car

​

2. classes.txt (fallback)

person
bicycle
car

​

3. Inferred from labels (last resort)

​

Bounding Box Format

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

​

Conversion Example

0 0.5 0.5 0.3 0.2

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

​

Reader Behavior

​

Input Path

• 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

​

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

0 0.500000 0.750000 0.300000 0.200000

​

Subdirectories

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

​

Lossiness

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

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

​

Usage

​

Read YOLO

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

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

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