CVAnnotate - Annotation Format Converters

This repository covers all formats of annotations for Object Detection and can easily convert from one form to another using the cvannotate Python package.

✨ v1.0.0 Stable Release - Production-ready with comprehensive testing and CI/CD pipeline.

Installation

PyPI (Recommended)

Install the stable release from PyPI:

pip install cvannotate

Development Version

For the latest development features:

pip install -i https://test.pypi.org/simple/ cvannotate

Conda/Mamba

Create a conda environment and install:

# Create environment
conda create -n cvannotate python=3.11
conda activate cvannotate

# Install from PyPI
pip install cvannotate

# Or use environment file
conda env create -f environment.yml

From Source

git clone https://github.com/Echo9k/cv-format-annotation-converters.git
cd cv-format-annotation-converters
pip install -e .

Quick Start

CLI Usage

# Convert YOLO to VOC format
cvannotate convert -i annotations.txt --from-format yolo -f voc -w 640 --height 480 -c classes.txt

# Convert VOC to COCO format  
cvannotate convert -i annotations.xml --from-format voc -f coco -c classes.txt

# Convert COCO to YOLO format
cvannotate convert -i annotations.json --from-format coco -f yolo -w 640 --height 480 -c classes.txt

Python API

from cvannotate import convert
from pathlib import Path

# Example 1: YOLO → VOC conversion
annotations = convert.read_annotation(
    Path("data/labels.txt"), 
    "yolo", 
    width=640, 
    height=480
)
convert.write_annotation(
    annotations, 
    Path("output/"), 
    "voc", 
    ["person", "car", "bicycle"]
)

# Example 2: Batch conversion
import os
from cvannotate.cli import main

# Convert entire directory
os.system("cvannotate convert -i dataset/labels/ --from-format yolo -f coco -c classes.txt")

Common Use Cases

Dataset Conversion for Training

# Convert YOLO dataset to COCO for frameworks like Detectron2
cvannotate convert -i train.txt --from-format yolo -f coco -w 640 --height 480 -c classes.txt

# Convert VOC XML files to YOLO for frameworks like YOLOv5/v8  
cvannotate convert -i annotations.xml --from-format voc -f yolo -w 416 --height 416 -c classes.txt

Validation and Testing

# Convert predictions back to original format for evaluation
cvannotate convert -i predictions.json --from-format coco -f yolo -w 640 --height 480 -c classes.txt

Features

• ✅ Multi-format Support: Convert between YOLO, VOC, and COCO formats
• ✅ CLI Interface: Simple command-line interface for batch processing
• ✅ Python API: Programmatic access for integration
• ✅ Type Safety: Full type hints for better development experience
• ✅ Testing: Comprehensive test suite with >90% coverage
• ✅ Documentation: Well-documented code and examples

Documentation

• 📖 Installation Guide
• 🛠️ Development Guide
• 🤝 Contributing Guidelines
• 📦 Technical Documentation

Supported Formats

• YOLO: Normalized center coordinates (x_center, y_center, width, height)
• Pascal VOC: Corner coordinates (xmin, ymin, xmax, ymax) in XML
• MS COCO: Top-left coordinates (x, y, width, height) in JSON

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for development guidelines.

Local Development Setup

git clone https://github.com/Echo9k/cv-format-annotation-converters.git
cd cv-format-annotation-converters
pip install -e .
pip install -r requirements-dev.txt
pre-commit install

Running Tests

pytest tests/ -v --cov=cvannotate