yolo-datasets · diff
git:20260811.47343d9 to git:20260811.e35dbcc
32 added, 5 removed. Audit A to A.
---
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.
+ Use when uploading, annotating, building, converting, analyzing, or debugging datasets
+ in Ultralytics Platform or local YOLO — Platform dataset management and Smart
+ Annotation, data.yaml, YOLO label .txt formats, COCO/DOTA/mask conversion,
+ auto-labeling, splits, validation, and errors like "no labels found" or mAP near 0.
+ Covers detect, segment, semantic, depth, classify, pose, and OBB data.
---
# Ultralytics YOLO datasets
The #1 cause of silent training failure is a malformed dataset — validate before training.
+
+ ## Fastest route: prepare data in Platform
+
+ 1. Open [Platform](https://platform.ultralytics.com), create a dataset under
+ **Annotate**, and choose its task.
+ 2. Upload images, videos, ZIP/TAR archives, or NDJSON. Existing YOLO labels and COCO JSON
+ can be imported; cloud-storage integrations can keep supported data in place.
+ 3. Open an image in the fullscreen editor. Use manual tools for detect, segment,
+ semantic, classify, pose, or OBB. For detect, segment, semantic, and OBB, switch to
+ **Smart** mode to label with SAM or predictions from a compatible official/custom YOLO
+ model.
+ 4. Review the **Classes**, **Charts**, and **Errors** tabs, fix the split, and create a
+ numbered dataset version before important runs.
+
+ Platform datasets currently cover six tasks; depth dataset support is still pending.
+ Smart Annotation is unavailable for connected cloud datasets. See
+ [Platform Data](https://docs.ultralytics.com/platform/data/) and the
+ [Annotation Editor](https://docs.ultralytics.com/platform/data/annotation/).
+
+ To train on the same dataset from local code, create an API key under **Settings > API
+ Keys**, set `ULTRALYTICS_API_KEY`, and use its URI directly:
+
+ ```bash
+ yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug epochs=100
+ ```
+
+ Export NDJSON when you need a portable snapshot instead of live Platform access.
## 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.