Skip to content

About

Lightweight Python desktop annotation tool for bounding box labeling. Supports YOLO, Pascal VOC, and COCO export formats.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

AlchemyAnnotate - Lightweight Image Annotation Tool for Object Detection

AlchemyAnnotate is a free, open-source, desktop image annotation tool built with Python and PySide6. It provides a fast and intuitive interface for creating bounding box annotations used in training object detection models such as YOLO, Faster R-CNN, and SSD.

Export your annotations in YOLO, Pascal VOC, and COCO formats with a single click.

AlchemyAnnotate Screenshot


Features

  • Bounding Box Annotation - Draw, select, edit, and delete bounding boxes directly on images
  • Multi-Format Export - Save annotations in YOLO, Pascal VOC (XML), and COCO (JSON) formats
  • Separate Annotation Folders - Each format is stored in its own folder (annotations_yolo/, annotations_voc/, annotations_coco/) to prevent overwrites
  • Class Management - Create, delete, and assign annotation classes through the UI with automatic color coding
  • Autosave - Annotations are saved automatically after every change
  • Format Switching - Switch between YOLO, VOC, and COCO at any time with automatic conversion of existing annotations
  • Existing Annotation Detection - Automatically detects and loads previously saved annotations when opening a folder
  • Project Session File - Remembers your last opened image, selected format, class list, and preferences across sessions
  • Image Navigation - Browse images using sidebar, keyboard shortcuts, or arrow keys
  • Zoom and Pan - Zoom with Ctrl+Scroll and pan with middle-click for precise annotation on large images
  • Sidebar Status - Visual indicators show which images are labeled and which are still pending

Supported Annotation Formats

Format Output Folder File Type Used By
YOLO annotations_yolo/ .txt per image + classes.txt YOLOv5, YOLOv8, Ultralytics
Pascal VOC annotations_voc/ .xml per image Faster R-CNN, SSD, Detectron
COCO annotations_coco/ Single annotations.json COCO API, Detectron2, MMDetection

Supported Image Formats

JPG, JPEG, PNG, BMP, TIFF, WEBP


Installation

Install from PyPI (recommended)

pip install alchemyannotate

Install from source

git clone https://github.com/kouya-marino/AlchemyAnnotate.git
cd AlchemyAnnotate
pip install .

Development install

git clone https://github.com/kouya-marino/AlchemyAnnotate.git
cd AlchemyAnnotate
pip install -e ".[dev]"

Requirements

  • Python 3.10 or higher
  • PySide6 (installed automatically)

How to Use

Launch the Application

python run.py

Or run as a Python module:

python -m alchemyannotate

Or if installed as a package:

alchemyannotate

Annotation Workflow

  1. Open a Folder - Click File > Open Folder or press Ctrl+O to select a folder containing your images
  2. Create Classes - In the right panel, type a class name (e.g., "car", "person") and click Add
  3. Select a Class - Click on a class in the class list to make it active
  4. Draw Bounding Boxes - Left-click and drag on the image to draw a box around an object
  5. Navigate Images - Use the sidebar, or press A / D to go to the previous / next image
  6. Edit Boxes - Click a box to select it, then change its class from the dropdown or press Delete to remove it
  7. Save - Annotations autosave after every change. Press Ctrl+S to force a manual save
  8. Switch Format - Use the format selector in the status bar to switch between YOLO, VOC, and COCO

Keyboard Shortcuts

Shortcut Action
Ctrl+O Open image folder
Ctrl+S Save annotations
Ctrl+Q Quit application
Delete Delete selected bounding box
A or Left Arrow Previous image
D or Right Arrow Next image
Ctrl+0 Fit image to window
Ctrl+Scroll Zoom in / out
Middle-click drag Pan the image

Project File

When you open a folder, AlchemyAnnotate creates an alchemyannotate_project.json file inside it. This file stores:

  • Selected annotation format
  • Class list
  • Last opened image
  • Autosave preferences
  • Recently used class

This allows you to resume your annotation session exactly where you left off.


Project Structure

AlchemyAnnotate/
├── alchemyannotate/
│   ├── models/          # Data models (BoundingBox, ImageAnnotation, ProjectConfig)
│   ├── views/           # UI components (Canvas, Sidebar, Panels, Dialogs)
│   ├── controllers/     # Application logic (App, Canvas, Navigation controllers)
│   ├── services/        # IO, autosave, format conversion, image loading
│   └── utils/           # Constants, geometry helpers
├── tests/               # Unit tests for models, IO formats, and store
├── run.py               # Quick launcher
├── pyproject.toml       # Build configuration
└── requirements.txt     # Dependencies

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Dependencies

Package Version Purpose
PySide6 >= 6.6 Qt6 GUI framework

No other external dependencies. XML and JSON handling use Python standard library modules.


Frequently Asked Questions

What annotation format should I use?

  • Use YOLO if you are training with Ultralytics YOLOv5, YOLOv8, or similar YOLO-based models
  • Use Pascal VOC if you are training with Faster R-CNN, SSD, or frameworks that expect XML annotations
  • Use COCO if you are using Detectron2, MMDetection, or the COCO evaluation API

Can I switch formats after annotating?

Yes. AlchemyAnnotate will prompt you to export existing annotations to the new format when you switch.

Where are my annotations saved?

Inside your image folder, in a subfolder named after the format:

  • annotations_yolo/ for YOLO format
  • annotations_voc/ for Pascal VOC format
  • annotations_coco/ for COCO format

Does it support polygons or segmentation masks?

Yes. AlchemyAnnotate supports both bounding box and polygon annotations. Polygons export as COCO segmentation fields and YOLOv8-seg format. Note: Pascal VOC does not support polygons — a warning is shown when switching to VOC if polygon data exists.


License

This project is open source. See the LICENSE file for details.


Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.

About

Lightweight Python desktop annotation tool for bounding box labeling. Supports YOLO, Pascal VOC, and COCO export formats.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages