Metadata-Version: 2.4
Name: yolo-dataset-doctor
Version: 0.1.0
Summary: Catch YOLO dataset problems (broken labels, duplicates, class imbalance) before training does.
Author-email: Kethan H S <kethanshetty05@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Kethan-hs/yolo-dataset-doctor
Project-URL: Repository, https://github.com/Kethan-hs/yolo-dataset-doctor
Keywords: yolo,computer-vision,dataset,machine-learning,data-validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Requires-Dist: ImageHash>=4.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# yolo-dataset-doctor

Catch YOLO dataset problems before a training run does, not after.

Built out of a specific, recurring problem: merging several heterogeneous
image sources into one YOLO dataset produces broken labels, duplicate
images, and class imbalance that don't show up as an error — they show up
three hours later as an unexplained drop in precision/recall.

## Install

```bash
pip install yolo-dataset-doctor
```

Requires Python 3.9+. Depends on `Pillow` and `ImageHash`.

## Commands

### `validate` — structural and range checks

```bash
yolodoc validate --images data/images --labels data/labels --num-classes 4 --verbose
```

Catches, per label file and line number:
- class ids outside `[0, num_classes)`
- coordinates outside the normalized `[0, 1]` range
- zero-area (degenerate) bounding boxes
- malformed lines (wrong field count, non-numeric values)
- images that fail to open (truncated/corrupt files)
- labels with no matching image, and images with no matching label
  (reported as a warning — a background image with no label is often
  intentional)

Exits with a non-zero status if any errors were found, so it's usable as a
CI gate before a training job kicks off.

### `dedupe` — duplicate / near-duplicate detection

```bash
yolodoc dedupe --images data/images --max-distance 4
```

Perceptual-hash (`phash`) based. `--max-distance 0` finds only near-exact
duplicates; a small positive value (2-6) also catches re-compressed or
lightly cropped copies of the same source frame — the common case when
combining scraped or multi-vendor datasets.

**Run this before `split`, not after.** A duplicate that lands in `train`
and its twin that lands in `test` is silent train/test leakage — your
validation metrics will look better than the model actually is.

### `stats` — class balance and box-size report

```bash
yolodoc stats --labels data/labels --classes classes.txt
```

Reports box count, image count, and average box width/height per class,
plus a largest/smallest class ratio. Flags a warning at 3x imbalance or
greater — the kind of thing worth knowing *before* you spend a training run
finding out the hard way.

### `split` — reproducible train/val/test split

```bash
yolodoc split --images data/images --labels data/labels \
  --output data/split --train 0.8 --val 0.1 --test 0.1 --seed 42
```

Splits at the image level (an image's boxes never get split across sets),
is fully reproducible given the same seed, and copies (or `--move`s) the
resulting files into `output/{train,val,test}/{images,labels}/`.

## Recommended workflow

```bash
yolodoc validate --images data/images --labels data/labels --num-classes N
yolodoc dedupe   --images data/images
# fix/remove whatever the above two turned up, then:
yolodoc stats    --labels data/labels
yolodoc split    --images data/images --labels data/labels --output data/split
```

## Why this exists

Most YOLO tutorials assume a clean, single-source dataset. Real datasets —
especially ones assembled from multiple vendors or scraped sources — are
not that. This tool exists to make the invisible failure modes (silent
label corruption, cross-source duplicates, class imbalance) visible before
they cost you a training run.

## Development

```bash
git clone https://github.com/Kethan-hs/yolo-dataset-doctor
cd yolo-dataset-doctor
pip install -e ".[dev]"
pytest
```

## License

MIT
