Metadata-Version: 2.5
Name: cv-benchkit
Version: 0.2.0
Summary: Computer-vision benchmark toolkit: bbox format converters, dataset translators, and evaluation metrics.
Project-URL: Homepage, https://github.com/udayraj1238/cv-benchkit
Project-URL: Repository, https://github.com/udayraj1238/cv-benchkit
Project-URL: Issues, https://github.com/udayraj1238/cv-benchkit/issues
Author-email: Uday Raj <rajuday6002@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: bbox,coco,computer-vision,iou,metrics,voc,yolo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# cv-benchkit

[![CI](https://github.com/udayraj1238/cv-benchkit/actions/workflows/ci.yml/badge.svg)](https://github.com/udayraj1238/cv-benchkit/actions)
[![PyPI](https://img.shields.io/pypi/v/cv-benchkit.svg)](https://pypi.org/project/cv-benchkit/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Good First Issues](https://img.shields.io/github/issues/udayraj1238/cv-benchkit/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/udayraj1238/cv-benchkit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)

> **Contributing:** Looking to contribute? Check out our [good first issues](https://github.com/udayraj1238/cv-benchkit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)!
> To claim an issue, post a short comment on the issue before or when opening your PR, and include `Closes #<issue-number>` in your PR description.
> First-time contributors (0 prior merged PRs) are prioritized for `good first issue` tickets to give newcomers a fair start.

Unified computer vision annotation converter and model benchmarking toolkit for PyTorch and NumPy.

---

## Quickstart & Installation

Install `cv-benchkit` via `pip`:
```bash
pip install cv-benchkit
```

Or using `uv`:
```bash
uv add cv-benchkit
```

Or run directly without installation via `uvx`:
```bash
uvx --from cv-benchkit cv-benchkit --help
```

---

## Features

- **Format Converters**: Seamless, vectorized conversions between `xyxy`, `xywh` (COCO), `cxcywh`, and normalized (YOLO) bounding-box representations.
- **Dataset Translators**: Two-way translations between **COCO JSON**, **YOLO txt**, and **Pascal VOC XML**.
- **Vectorized Evaluation Metrics**: Fast NumPy implementations of pairwise **IoU**, **GIoU**, and multiclass **confusion matrix** calculations with background handling.
- **CLI Utility**: Command-line interface for fast dataset conversion and validation.
- **Strictly Typed & Tested**: 100% typed with PEP 561 marker, passing `mypy --strict`, with 95%+ unit test coverage.

---

## Python API Usage

```python
import numpy as np
from cv_benchkit import compute_iou, xyxy_to_normalized, validate_coco_file

# Compute pairwise IoU
boxes_a = np.array([[0, 0, 100, 100], [50, 50, 150, 150]])
boxes_b = np.array([[20, 20, 120, 120]])
iou_matrix = compute_iou(boxes_a, boxes_b)
print(iou_matrix)

# Validate and parse COCO annotations
dataset = validate_coco_file("path/to/annotations.json")
```

---

## CLI Usage

```bash
# Validate COCO dataset
cv-benchkit validate annotations.json

# Summarize a COCO dataset (add --json for machine-readable output)
cv-benchkit stats annotations.json

# Convert COCO to YOLO format
cv-benchkit convert --from coco --to yolo --input annotations.json --output ./yolo_labels

# Convert YOLO to COCO format
cv-benchkit convert --from yolo --to coco --input ./yolo_labels --output ./coco_out --image-width 640 --image-height 480 --categories person car bicycle
```

---

## Contributing & Good First Issues

We welcome first-time open-source contributors! 🚀

We have curated and actively maintain **modular, beginner-friendly issues** with clear acceptance criteria and verification commands:

👉 **[Browse All Open Good First Issues (15+ Available)](https://github.com/udayraj1238/cv-benchkit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)**

### How to Claim an Issue:
1. Find an issue labeled [`good first issue`](https://github.com/udayraj1238/cv-benchkit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that is not yet assigned.
2. Comment on the issue: `I'd like to work on this! Plan: [one sentence approach]`.
3. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for local setup, community standards, and pull request guidelines.
4. Also see our [Good First Issues Catalog](docs/GOOD_FIRST_ISSUES_CATALOG.md) for a comprehensive catalog of upcoming tasks across documentation, converters, and metrics.

### Local Development Setup:
```bash
git clone https://github.com/udayraj1238/cv-benchkit.git
cd cv-benchkit
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy src/
```

---

## Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting and responsible disclosure.

---

## License

Apache-2.0. See [LICENSE](LICENSE) for details.
