pylabelconv

pylabelconv is a lightweight, production‑ready Python utility for converting YOLO‑format object‑detection datasets into COCO JSON format. It uses Pydantic for strict data validation, Pathlib for clean filesystem handling, and includes optional visualization tools for rapid inspection of converted annotations.

The tool is designed for real‑world dataset pipelines and provides:

• Flexible split handling — supports standard YOLO splits (train, val, test) and automatically discovers images when split files are missing.
• Robust conversion logic — clips out‑of‑bounds bounding boxes, drops zero‑area artifacts, and skips invalid or unmappable class IDs.
• Safe JSON output — writes annotations atomically to prevent partial or corrupted files.
• Optional visual debugging — renders bounding boxes and class labels onto sample images for quick verification.

---

Installation

git clone https://github.com/yourusername/pylabelconv.git
cd pylabelconv
pip install -e ".[test]"

---

Usage

Ensure your dataset directory contains:

• YOLO split files (train.txt, val.txt, test.txt)
• A data.names file listing class names

Basic Conversion

pylabelconv /path/to/data /path/to/output

Visual Verification

Render bounding boxes and class labels onto sample images:

pylabelconv /path/to/data /path/to/output --visualize

Images will be saved under debug_vis/.

---

Project Structure

pylabelconv/
├── pyproject.toml
├── README.md
├── src/
│   └── pylabelconv/
│       ├── __init__.py
│       ├── cli.py
│       ├── structs.py
│       ├── transform.py
│       └── visualizer.py
└── tests/
    ├── test_cli.py
    ├── test_structs.py
    └── test_transform.py

---

Running Tests

pytest --cov=pylabelconv