Metadata-Version: 2.4
Name: pyqt-image-annotation-tool
Version: 0.1.0
Summary: Desktop tool for whole-image classification and bounding-box image annotation
Project-URL: Homepage, https://github.com/nikuznetsov/PyQt-image-annotation-tool
Project-URL: Issues, https://github.com/nikuznetsov/PyQt-image-annotation-tool/issues
License-Expression: MIT
License-File: LICENSE
Keywords: PySide6,Qt,bounding box,computer vision,dataset,image annotation,labeling
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Requires-Dist: pyside6<7,>=6.7
Requires-Dist: xlsxwriter>=3.2
Provides-Extra: dev
Requires-Dist: openpyxl; extra == 'dev'
Requires-Dist: pyinstaller; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-qt; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# PyQt Image Annotation Tool

[![CI](https://github.com/nikuznetsov/PyQt-image-annotation-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/nikuznetsov/PyQt-image-annotation-tool/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pyqt-image-annotation-tool.svg)](https://pypi.org/project/pyqt-image-annotation-tool/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)

A desktop app for labeling images in a folder — either assigning whole-image classes, or
drawing bounding boxes. Built with [PySide6](https://doc.qt.io/qtforpython/).

|                  Whole-image classification                   |                    Bounding boxes                     |
|:----------------------------------------------------------------:|:------------------------------------------------------:|
| ![Classification mode](docs/screenshots/classification.png) | ![Bounding box mode](docs/screenshots/bbox.png) |

## Features

**Whole-image classification**
- Assign one or more labels to each image
- Move or copy labeled images into per-label sub-folders, or leave files untouched
- Export to CSV and/or XLSX

**Bounding boxes**
- Draw, move, resize, and delete rectangular regions per image, each with its own label
- Export to COCO JSON and/or YOLO txt (with `classes.txt`)

**Both modes**
- Zoom & pan on the image (mouse wheel to zoom, drag to pan)
- Thumbnail filmstrip showing every image's labeling status
- Undo (Ctrl+Z)
- Dark theme
- Drag & drop a folder onto the app to open it
- Autosave: progress is saved continuously and offered back to you if you reopen the
  same folder, so a crash or an accidental close doesn't lose your work

![Setup screen](docs/screenshots/setup.png)

## Installation

**From PyPI:**
```bash
pip install pyqt-image-annotation-tool
annotator
```

**Standalone build (no Python required):** download the archive for your OS from the
[latest release](https://github.com/nikuznetsov/PyQt-image-annotation-tool/releases) and
run the `annotator` executable inside it.

**From source:**
```bash
git clone https://github.com/nikuznetsov/PyQt-image-annotation-tool.git
cd PyQt-image-annotation-tool
pip install -e .
annotator            # or: python -m annotator
```

## Usage

1. Pick the folder containing your images (or drag & drop it onto the window).
2. Choose an annotation type — whole-image classification or bounding boxes.
3. For classification, also choose a mode:
   - **csv** — labels are tracked and exported to CSV/XLSX; files aren't moved.
   - **copy** / **move** — a folder is created per label and labeled images are copied/moved into it.
4. Enter your label names (or load them from a text file, one label per line).
5. Click **Next** and start labeling.

### Keyboard shortcuts

| Key | Action |
|---|---|
| → / ← | Next / previous image |
| 1–9, 0 | Select label (wraps after the 9th) |
| Ctrl+Z | Undo |
| Mouse wheel | Zoom |
| Middle-drag (bbox mode) / drag (classification mode) | Pan |
| Delete (bbox mode) | Remove selected box |

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for more.

## Contributing

Pull requests are welcome.

## License

[MIT](LICENSE)
