BoxLab

A comprehensive Python toolkit for managing, converting, and annotating object detection datasets with support for COCO and YOLO formats.

Features

• Dataset Management - Load, merge, split, and analyze datasets with multi-source support
• Format Conversion - Seamlessly convert between COCO and YOLO formats
• GUI Annotator - Interactive desktop application for viewing and editing annotations
• CLI Tools - Powerful command-line interface for batch operations
• PyTorch Integration - Direct integration with PyTorch training pipelines
• Plugin System - Extensible architecture for custom format support

Installation

From PyPI (Recommended)

pip install boxlab

From Source

# Clone repository
git clone https://github.com/6ixGODD/boxlab.git
cd boxlab

# Install with Poetry (recommended)
poetry install

# Or install with pip
pip install -e .

Optional Dependencies

For PyTorch integration:

pip install torch torchvision

Quick Start

View Dataset Information

boxlab dataset info data/coco/annotations.json --format coco

Convert Between Formats

# COCO to YOLO
boxlab dataset convert input.json -if coco output -of yolo

# YOLO to COCO
boxlab dataset convert data/yolo -if yolo output -of coco

Merge Multiple Datasets

boxlab dataset merge \
  -i dataset1/ann.json coco source1 \
  -i dataset2/ann.json coco source2 \
  -o merged_dataset

Launch GUI Annotator

boxlab annotator

Python API

from boxlab.dataset.io import load_dataset, export_dataset

# Load dataset
dataset = load_dataset("annotations.json", format="coco")

# Get statistics
stats = dataset.get_statistics()
print(f"Images: {stats['num_images']}")
print(f"Annotations: {stats['num_annotations']}")

# Export to different format
export_dataset(dataset, "output/yolo", format="yolo")

CLI Commands

Dataset Operations

# View information
boxlab dataset info <path> --format <coco|yolo>

# Convert formats
boxlab dataset convert <input> -if <format> <output> -of <format>

# Merge datasets
boxlab dataset merge -i <path> <format> [name] -o <output>

# Visualize dataset
boxlab dataset visualize <path> --format <format> -o <output>

Annotator

# Launch GUI application
boxlab annotator

PyTorch Integration

from boxlab.dataset.io import load_dataset
from boxlab.dataset.torchadapter import build_torchdataset
from torch.utils.data import DataLoader

# Load and prepare dataset
dataset = load_dataset("train.json", format="coco")

# Create PyTorch dataset with augmentation
torch_dataset = build_torchdataset(
    dataset,
    image_size=640,
    augment=True,
    normalize=True,
    return_format="xyxy"
)

# Create DataLoader
train_loader = DataLoader(
    torch_dataset,
    batch_size=16,
    shuffle=True,
    collate_fn=torch_dataset.collate
)

# Training loop
for images, targets in train_loader:
    # Your training code here
    pass

Custom Plugin Development

Custom Loader

from boxlab.dataset.plugins import LoaderPlugin
from boxlab.dataset import Dataset

class CustomLoader(LoaderPlugin):
    @property
    def name(self) -> str:
        return "custom_format"

    @property
    def description(self) -> str:
        return "Custom format loader"

    def load(self, path, **kwargs):
        dataset = Dataset(name="custom")
        # Your loading logic here
        return dataset

# Register and use
from boxlab.dataset.plugins.registry import register_loader
register_loader("custom_format", CustomLoader)

Documentation

Full documentation is available at: https://6ixgodd.github.io/boxlab

• Installation Guide
• Quick Start Tutorial
• CLI Reference
• API Reference
• Advanced Usage

Examples

Convert with Custom Split Ratio

boxlab dataset convert annotations.json \
  -if coco \
  output/yolo \
  -of yolo \
  --train-ratio 0.7 \
  --val-ratio 0.2 \
  --test-ratio 0.1 \
  --seed 42

Merge with Source Tracking

boxlab dataset merge \
  -i manual_annotations.json coco manual \
  -i automatic_annotations.json coco automatic \
  -o combined_dataset \
  --preserve-sources

Visualize with Heatmap

boxlab dataset visualize data/yolo \
  --format yolo \
  -o visualizations \
  --samples 10 \
  --show-heatmap \
  --show-source-dist

Requirements

• Python 3.10 or higher
• NumPy
• Pillow
• Matplotlib
• PyYAML
• Pandas

Optional

• PyTorch (for training integration)
• torchvision (for training integration)

Project Structure

boxlab/
├── boxlab/
│   ├── dataset/            # Core dataset management
│   │   ├── plugins/        # Format plugins (COCO, YOLO)
│   │   ├── io.py           # I/O operations
│   │   ├── types.py        # Data structures
│   │   └── torchadapter.py # PyTorch integration
│   ├── annotator/          # GUI application
│   ├── cli/                # Command-line interface
│   └── exceptions.py       # Error handling
├── docs/                   # Documentation
├── tests/                  # Test suite
└── pyproject.toml          # Project configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone repository
git clone https://github.com/6ixGODD/boxlab.git
cd boxlab

# Install with development and test dependencies
poetry install --all-extras

# Run tests
poetry run pytest

# Run linting
poetry run ruff check .

# Build documentation
poetry run mkdocs serve

Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Support

• Documentation: https://6ixgodd.github.io/boxlab
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history and release notes.