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

📸 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.1

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.1
File Size Uploaded Provenance Actions
labelcraft-2.1.1.tar.gz 1.7 MB Without provenance Details for labelcraft-2.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 2.4 MB

Release files / labelcraft-2.1.1.tar.gz

Download URL labelcraft-2.1.1.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
22dcf0585ab1517ba342377ec2d79c0ac41e7ce5836c6baf6b0ed60974a67ddd
BLAKE2b-256 checksum
How to use checksums
b95d41fe0740c8460f7929b712637677b087183ef911bbdd6d1086ec9b96bf32
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.20

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

Download URL labelcraft-2.1.1-py2.py3-none-any.whl
Size 790.6 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
e1cfe82e3a61d27746ca7844bb18341cee7441f546c50845255d9abd5f50b4dd
BLAKE2b-256 checksum
How to use checksums
6a81b615600b9d91b40d335020317e840bad758730bef89f318a640e20f4f3c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.20

Security for LabelCraft 2.1.1

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