yolo-datasets git:20260811.47343d9A

Immutable. This exact content is served forever at /api/v1/blob/b30e833a52f1153b.

---
name: yolo-datasets
description: >
  Use when building, converting, analyzing, or debugging datasets for Ultralytics YOLO —
  writing data.yaml, YOLO label .txt formats, converting from COCO/DOTA/masks,
  auto-labeling raw images, train/val splitting, dataset validation, or errors like
  "no labels found", "dataset not found", or mAP near 0 after training. Covers detect,
  segment, semantic, depth, classify, pose, and OBB dataset formats.
---

# Ultralytics YOLO datasets

The #1 cause of silent training failure is a malformed dataset — validate before training.

## The `images` → `labels` mirror rule

Ultralytics finds a label file by replacing the **last** `/images/` path segment with
`/labels/` and the image extension with `.txt`:

```
dataset/
├── data.yaml
├── images/train/  img001.jpg ...     ├── images/val/  ...
└── labels/train/  img001.txt ...     └── labels/val/  ...
```

- Labels next to images, or in a dir not named `labels`, are **not found** → silent
  all-background training.
- Filenames must match stems exactly (case-sensitive on Linux).
- An image with no/empty label file trains as a **background image**. A few percent of
  true backgrounds reduce false positives; accidentally missing labels destroy recall.

## data.yaml anatomy

```yaml
path: /abs/dataset/root # relative paths resolve against `yolo settings` datasets_dir — prefer absolute
train: images/train # dir, .txt file of image paths, or list of dirs
val: images/val
test: images/test # optional
names: # 0-based, contiguous indices
  0: person
  1: helmet
# pose only:
kpt_shape: [17, 3] # [num_keypoints, dims]; dims 2 (x,y) or 3 (x,y,visibility)
flip_idx: [0, 2, 1, ...] # L/R keypoint swap map — without it, flip augs are auto-disabled
# semantic only (optional — polygon labels/ also work):
masks_dir: masks # per-pixel PNG mask images
# depth only: paired depth/{train,val}/*.npy float32 depth maps, nc: 1
```

- Classification datasets use **no yaml**: folder structure is the label
  (`dataset/train/<class>/*.jpg`, `dataset/val/<class>/*.jpg`); train with
  `data=path/to/dataset`.
- Per-task label line formats and their gotchas: read `label-formats.md` (this folder)
  whenever writing or debugging label files.

## Converting from other formats — use built-ins first

```python
from ultralytics.data.converter import convert_coco

convert_coco(labels_dir="coco/annotations/", use_segments=True)  # COCO → detect/segment
convert_coco(labels_dir="coco/annotations/", use_keypoints=True)  # COCO → pose
```

Also in `ultralytics.data.converter`: `convert_dota_to_yolo_obb(root)` (DOTA → OBB),
`convert_segment_masks_to_yolo_seg(masks_dir, output_dir, classes)` (index PNGs →
polygons), `yolo_bbox2segment(im_dir)` (upgrade detect labels to segment via SAM),
`convert_to_multispectral(path, n_channels)`.

Auto-label a raw image folder (detector proposes boxes, SAM refines masks):

```python
from ultralytics.data.annotator import auto_annotate

auto_annotate(data="path/to/images", det_model="yolo26x.pt", sam_model="sam_b.pt")
```

For VOC XML/CSV there is no converter — write a small script emitting the per-task line
format (normalize coords, center-based boxes).

## Splitting

```python
from ultralytics.data.split import autosplit

autosplit(path="dataset/images", weights=(0.9, 0.1, 0.0))  # writes autosplit_*.txt lists
```

Point `train:`/`val:` at the generated `.txt` files. Keep frames from the same
video/scene in ONE split — per-image random splits of video frames leak near-duplicates
into val and inflate mAP. For classify: `split_classify_dataset(source_dir, 0.8)`.

## Validate before training (do this, in order)

1. **Structural check** — loads, resolves paths, counts images/labels, auto-downloads
   known datasets:

   ```python
   from ultralytics.data.utils import check_det_dataset

   check_det_dataset("data.yaml")  # detect/segment/pose/obb/semantic/depth
   ```

2. **Visual check of one image** — labels drawn on the image; wrong normalization or
   swapped x/y is instantly visible:

   ```python
   from ultralytics.data.utils import visualize_image_annotations

   visualize_image_annotations("images/train/img001.jpg", "labels/train/img001.txt", label_map={0: "person", 1: "helmet"})
   ```

3. **1-epoch smoke test**, then eyeball the mosaic:
   ```bash
   yolo detect train data=data.yaml model=yolo26n.pt epochs=1 fraction=0.1
   # inspect runs/detect/train/train_batch0.jpg — boxes/masks must sit on objects
   ```
4. **Distribution sanity** (quick script over label files): instances per class
   (heavy imbalance → collect more or weigh expectations), boxes < ~8 px at train
   `imgsz` (undetectable — raise imgsz or tile), % background images, duplicate
   stems across splits (leakage).

Known-good tiny datasets for pipeline smoke tests (auto-download): `coco8.yaml`,
`coco8-seg.yaml`, `coco8-pose.yaml`, `dota8.yaml`, `cityscapes8.yaml`, `depth8.yaml`,
`imagenet10`.

## Related pages

- `label-formats.md` — exact per-task label line formats + symptom→cause table. Read
  when writing labels, converting formats, or any label-related error.

If the installed version rejects an argument or format here, trust its error message and
`yolo checks` over this file.