Skip to main content

LabelCraft - Intelligent Image Annotation Tool

Version 2.1.0 - A modern image annotation tool with project management, developed based on labelImg

License Python Version PySide6 Version Downloads

中文文档 | English

LabelCraft is a professional graphical image annotation tool with advanced project management capabilities. It's designed for efficient data preparation in deep learning tasks such as object detection and image classification.

This project is a major evolution of the open-source project labelImg, adding project-based workflow, multi-format support, and intelligent annotation features. Special thanks to the original author TzuTa Lin for his pioneering work.

✨ Key Features

🎯 Core Annotation

  • Rectangle bounding box annotation
  • Polygon annotation (coming soon)
  • Real-time preview and editing
  • Undo/Redo support

📁 Project Management (v2.0 New!)

  • Create and manage annotation projects
  • Project configuration persistence (.labelcraft files)
  • Recent projects quick access
  • Automatic annotation directory management
  • Project metadata tracking

🔄 Multi-Format Support

Support 5 major annotation formats with seamless conversion:

  • PASCAL VOC (XML) - Traditional format for Faster R-CNN, SSD, etc.
  • YOLO (TXT) - For YOLO series models (v5, v8, v10)
  • CreateML (JSON) - For Apple CreateML framework
  • COCO (JSON) - Microsoft COCO dataset standard
  • CSV (CSV) - Universal format for data analysis

🌐 Advanced Internationalization

Dynamic language switching without restart:

  • English
  • 简体中文 (Simplified Chinese)
  • 繁體中文 (Traditional Chinese)
  • 日本語 (Japanese)
  • Deutsch (German)
  • Français (French)

⚡ Smart Workflow

  • Pending annotation queue management
  • Completed annotations list
  • Auto-save mode
  • Default label for batch annotation
  • Verification mode for quality control
  • Copy previous frame annotations
  • Import external annotations (v2.0.4+) - Import from YOLO, VOC, COCO, CreateML datasets
  • Smart label mapping - Automatically maps imported labels to project definitions

🛠️ Developer Tools

  • Built-in format converter (all 5 formats)
  • Command-line interface
  • Python API for integration
  • Customizable shortcuts
  • Brightness adjustment
  • Cross-Platform Dark Mode (v2.1.1+)
    • Windows 11/10: Automatic registry detection
    • Linux (GNOME/KDE/Ubuntu): dconf/gsettings support
    • macOS: System appearance detection
    • See Windows 11 Dark Mode Guide for setup

📸 Screenshot

LabelCraft Interface

🚀 Quick Start

pip install labelcraft

Launch from command line:

labelcraft

Or specify an image directory:

labelcraft /path/to/images

One-Click Launch (From Source)

Linux/macOS:

chmod +x start.sh
./start.sh

Windows:

start.bat

The script will automatically:

  1. Check Python environment
  2. Create virtual environment
  3. Install dependencies
  4. Compile resources
  5. Launch application

Manual Installation

# Clone repository
git clone https://github.com/syd168/LabelCraft.git
cd LabelCraft

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Compile resources (Linux/macOS)
make pyside6
# or Windows
pyside6-rcc -o libs/resources.py resources.qrc

# Run
python main.py

📖 Usage Guide

Standard Workflow (Project-Based)

Step 1: Create a New Project

  1. Menu: File → New Project or press Ctrl+N
  2. Fill in project information:
    • Project Name: Your project name
    • Project Location: Directory to store project files
    • Output Format: Choose annotation format (VOC/YOLO/CreateML/COCO/CSV)
    • Labels: Add your object categories
  3. Click "Create Project"

The system will automatically create:

  • Project file: {project_name}.labelcraft
  • Annotations directory: {project_dir}/annotations/

Step 2: Add Images to Project

  1. Menu: File → Open Dir or press Ctrl+U
  2. Select the directory containing your images
  3. Images will be loaded into the pending queue

You can also:

  • Drag and drop images directly
  • Use File → Add Images to add specific files

Step 3: Annotate Images

  1. Click "Create RectBox" button or press W
  2. Draw bounding box on the object
  3. Enter label name (or use default label)
  4. Press Enter to confirm
  5. Save with Ctrl+S or enable auto-save

Tips:

  • Use arrow keys to fine-tune box position
  • Hold Ctrl while drawing for perfect squares
  • Right-click box to edit properties
  • Use verification mode (Space) to mark completed images

Step 4: Manage Annotations

View Status:

  • Left panel: Pending images queue
  • Right panel: Current image annotations
  • Window title shows progress: (5/100)

Navigation:

  • Next image: D or →
  • Previous image: A or ←
  • Jump to specific image from file list

Step 5: Export & Convert

Export Annotations:

  • Menu: File → Export Annotations
  • Choose export location and format

Convert Formats: Use the built-in converter programmatically:

from libs.annotation_converter import AnnotationConverter

converter = AnnotationConverter()

# Convert entire project from VOC to YOLO
converter.convert(
    input_dir='path/to/voc_annotations',
    input_format='voc',
    output_format='yolo',
    output_dir='path/to/yolo_output'
)

Or via command line:

python -m libs.annotation_converter \
    --input /path/to/input \
    --input_format voc \
    --output_format yolo \
    --output /path/to/output

Legacy Mode (Quick Annotation)

For simple tasks without project management:

# Open single image
python main.py image.jpg

# Open directory directly
python main.py /path/to/images

# With predefined labels
python main.py /path/to/images data/predefined_classes.txt

⌨️ Keyboard Shortcuts

File Operations

Shortcut Action
Ctrl+N New Project
Ctrl+O Open Project
Ctrl+U Open Directory
Ctrl+S Save Annotation
Ctrl+E Edit Project
Ctrl+Shift+C Close Project

Annotation

Shortcut Action
W Create RectBox
Ctrl+J Edit Mode
Delete Delete Selected Box
Ctrl+D Duplicate Box
Ctrl+V Copy Previous Frame
Space Verify Image

Navigation

Shortcut Action
D / → Next Image
A / ← Previous Image
Ctrl++ Zoom In
Ctrl+- Zoom Out
Ctrl+F Fit Window
Ctrl+Shift+F Fit Width

View

Shortcut Action
Ctrl+T Toggle Toolbar
Ctrl+H Hide All Boxes
Ctrl+A Show All Boxes
Ctrl+Shift++ Increase Brightness
Ctrl+Shift+- Decrease Brightness
Ctrl+Shift+= Reset Brightness

🔧 Advanced Configuration

Predefined Labels

Create a text file with one label per line:

person
car
dog
cat
bicycle

Load at startup:

python main.py data/predefined_classes.txt

Or at runtime: File → Load Predefined Classes (Ctrl+Shift+L)

Custom Settings

Settings are automatically saved to system config:

  • Recently used directories
  • Window size and position
  • Default annotation format
  • Brush colors
  • Language preference

Command Line Arguments

python main.py [IMAGE_PATH] [PREDEFINED_CLASSES] [SAVE_DIR]

Examples:

# Open specific image
python main.py images/test.jpg

# With predefined classes
python main.py images/ data/classes.txt

# Specify save directory
python main.py images/ classes.txt annotations/

🏗️ Project Structure

LabelCraft/
├── main.py                 # Application entry point
├── labelcraft_ui.py        # Main UI implementation
├── libs/                   # Core libraries
│   ├── project.py          # Project management
│   ├── canvas.py           # Drawing canvas
│   ├── shape.py            # Shape classes
│   ├── annotation_converter.py  # Format converter
│   ├── i18n_engine.py      # Internationalization
│   ├── pascal_voc_io.py    # VOC format I/O
│   ├── yolo_io.py          # YOLO format I/O
│   ├── create_ml_io.py     # CreateML I/O
│   ├── coco_io.py          # COCO I/O
│   └── csv_io.py           # CSV I/O
├── locales/                # Translation files
│   ├── en.json
│   ├── zh-CN.json
│   ├── zh-TW.json
│   ├── ja-JP.json
│   ├── de-DE.json
│   └── fr-FR.json
├── resources/              # Icons and assets
├── doc/                    # Documentation
│   ├── tutorial.md
│   ├── tutorial_zh-CN.md
│   └── TRANSLATION_GUIDE.md
└── build-tools/            # Build scripts

🌍 Adding New Language

  1. Create new file in locales/ (e.g., es-ES.json)
  2. Copy existing JSON as template
  3. Translate all values (keep keys unchanged)
  4. Restart application - new language auto-detected

See TRANSLATION_GUIDE.md for details.

❓ FAQ

Q: What's the difference between v1.x and v2.0?

A: Version 2.0 introduces:

  • ✅ Project-based workflow (vs. file-based in v1.x)
  • ✅ Support for COCO and CSV formats
  • ✅ Built-in format converter
  • ✅ Dynamic language switching
  • ✅ Enhanced UI with better organization
  • ✅ Improved annotation management

Q: Can I still use it without creating a project?

A: Yes! You can use legacy mode by opening directories directly. However, projects provide better organization and persistence.

Q: How do I convert my existing annotations?

A: Use the built-in converter:

from libs.annotation_converter import AnnotationConverter

converter = AnnotationConverter()
converter.convert('old_annotations/', 'voc', 'yolo', 'new_annotations/')

Q: Where are my annotations saved?

A:

  • With Project: In {project_dir}/annotations/
  • Without Project: Same directory as images
  • Filename matches image with appropriate extension (.xml, .txt, .json, .csv)

Q: Can I change the output format mid-project?

A: Yes! Edit project (Ctrl+E) and change the format. Existing annotations will be migrated if needed.

Q: How do I backup my project?

A: Simply copy the entire project directory including:

  • .labelcraft project file
  • annotations/ directory
  • Your images (if stored in project)

Q: Is there an API for programmatic use?

A: Yes! You can integrate LabelCraft into your Python code:

from libs.project import Project
from libs.annotation_converter import AnnotationConverter

# Create project
project = Project(name="MyProject", project_dir="/path/to/project")
project.save("/path/to/project/myproject.labelcraft")

# Convert formats
converter = AnnotationConverter()
converter.convert("input/", "voc", "yolo", "output/")

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Development Setup

# Clone and setup
git clone https://github.com/syd168/LabelCraft.git
cd LabelCraft
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run tests
python -m pytest tests/

# Compile resources after UI changes
pyside6-rcc -o libs/resources.py resources.qrc

📄 License

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

🙏 Acknowledgments

  • labelImg - Original project by TzuTa Lin
  • All contributors who improved LabelCraft
  • The open-source community for inspiration and support

📮 Contact & Support


Happy Annotating! 🎉

Made with ❤️ for the computer vision community

Metadata

Release files for LabelCraft 2.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for LabelCraft 2.1.2
File Size Uploaded Provenance Actions
labelcraft-2.1.2.tar.gz 1.7 MB Without provenance Details for labelcraft-2.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for LabelCraft 2.1.2
File Interpreter ABI Platform Actions
labelcraft-2.1.2-py2.py3-none-any.whl Python 3, Python 2 none any Details for labelcraft-2.1.2-py2.py3-none-any.whl

Total release size: 2.5 MB

Release files / labelcraft-2.1.2.tar.gz

Download URL labelcraft-2.1.2.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
7398c0aeb770428ef18e49afbb15cd90324a11e241250831b86dcfc8dc9d86ef
BLAKE2b-256 checksum
How to use checksums
e0faab9024c9a23435a2796d3db5a6d9850406b5d89c3d368689877fdc9d39f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.9

Release files / labelcraft-2.1.2-py2.py3-none-any.whl

Download URL labelcraft-2.1.2-py2.py3-none-any.whl
Size 794.5 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
716fcca6fea1141597b2b77df09990081821f233c271c480f4254fd285fab690
BLAKE2b-256 checksum
How to use checksums
f5a2ffb9d4693398cf2b5c97311a9b760eb13201705e952e1be1bd1f7a7220d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.9

Security for LabelCraft 2.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page