LabelEZ - YOLO Polygon Labeling Tool

A web-based polygon labeling tool for creating YOLO format annotations with an intuitive interface.

⚠️ DISCLAIMER

This code was generated by AI and is provided "as is" without any warranties or guarantees.

• 🚨 Use at your own risk - This is experimental software
• 🤖 AI-generated code - May contain bugs, inefficiencies, or unexpected behavior
• 🔧 No support guaranteed - You're on your own if things break
• 💾 Backup your data - Don't blame us if you lose your precious annotations
• 🧪 Test thoroughly - This isn't production-ready enterprise software
• 🎯 Works for us - But your mileage may vary

Proceed with caution and don't say we didn't warn you! ⚡

Features

• Polygon Drawing: Click to add points, click first point to close polygon
• Multi-Input Support: Works with mouse, touch, and pen/stylus input (Pointer Events API)
• Class Selection: Configurable classes with color-coded buttons (supports up to 20 classes)
• Visual Status System:
  • 🟢 Green dots: Complete - All classes present
  • 🟡 Yellow dots: Partial - Many polygons but missing some classes
  • 🟠 Orange dots: Incomplete - Few polygons or missing classes
  • ⚪ Gray circles: Empty - No labels
• Zoom & Pan:
  • Mouse wheel to zoom, Space+move to pan
  • Touch pinch zoom on mobile/tablets
  • Dedicated zoom buttons and keyboard shortcuts
  • Space key disabled in image list scroll (prevents conflicts)
• Smart Navigation:
  • Image list with live status indicators
  • Click any image to navigate instantly
  • Auto-refresh status when saving changes
• Keyboard Shortcuts:
  • S - Save
  • Z - Undo last point
  • X - Delete current polygon
  • B - Back to previous image
  • N - Next image
  • - - Zoom out
  • = - Zoom in
  • R - Reset zoom
  • 1-9 - Select classes 0-8
  • 0 - Select class 9 (10th class)
  • Q-P - Select classes 10-19 (Q=class 10, W=class 11, etc.)
• Auto-save: Automatically saves when polygons are completed
• Label Loading: Loads existing labels when switching images
• Real-time Status Bar: Shows current image filename, zoom level, polygon count, and completion status
• Enhanced UX Features:
  • Class name labels on polygon first points (accessibility for color-blind users)
  • Click inside polygons to select them for editing/deletion
  • Extended status message visibility (3+ seconds)
• Docker Support: Ready-to-deploy container with health checks

Setup

1. Install Python 3.8+
2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install flask flask-cors

4. Create required directories:

   mkdir images labels

5. Add your images to the images/ directory
6. Update classes.txt with your class names (one per line, supports up to 20 classes)
7. Run the application:

   python app.py

8. Open http://localhost:5000 in your browser

Docker Deployment (Recommended)

Quick Start with Docker Compose

# Pull and run the pre-built image
docker-compose up -d

# Or use the deployment script
./deploy.sh

Manual Docker Setup

# Pull the image
docker pull rantyawset/labelez:latest

# Run the container
docker run -d -p 5000:5000 \
  -v $(pwd)/images:/app/images \
  -v $(pwd)/labels:/app/labels \
  -v $(pwd)/classes.txt:/app/classes.txt \
  --name labelez-app \
  rantyawset/labelez:latest

Docker Features

• Health checks - automatic container monitoring
• Non-root user - security best practices
• Volume mounting - persistent data storage
• Pre-built image - rantyawset/labelez:latest on Docker Hub

File Structure

labelEZ/
├── app.py              # Flask backend with CORS support
├── classes.txt         # Class definitions
├── requirements.txt    # Python dependencies
├── Dockerfile          # Container configuration
├── docker-compose.yml  # Docker deployment
├── deploy.sh           # Deployment script
├── templates/
│   └── index.html      # Frontend interface with pen support
├── images/             # Your images (not included in repo)
├── labels/             # Generated label files (not included in repo)
└── venv/               # Virtual environment

Usage

1. Select Class: Click class buttons (right panel) or use keyboard shortcuts (1-9, 0, Q-P)
2. Draw Polygon: Click to add points, click first point to close polygon
3. Zoom & Pan:
   • Hold Space + drag to pan around
   • Mouse wheel to zoom
   • -/= keys or zoom buttons for precise control
4. Navigate Images:
   • Use left panel image list (click any image to jump to it)
   • B/N keys or Previous/Next buttons
   • Status dots show completion status
5. Edit Polygons:
   • Click inside polygon to select it
   • Drag existing points to adjust
   • Z key to undo last point
   • X key to delete current polygon
   • Class names shown on first points for accessibility
6. Save: Automatic when polygon is closed, or press S manually
7. Monitor Progress:
   • Bottom status bar shows current filename, zoom, polygon count
   • Image list shows color-coded completion status
   • Extended status messages (3+ seconds visibility)

Input Methods

• Mouse: Standard clicking and dragging
• Touch: Tap to add points, pinch to zoom
• Pen/Stylus: Full support via Pointer Events API (Windows pen devices)

Label Format

Labels are saved in YOLO polygon format:

class_id x1 y1 x2 y2 x3 y3 ...

Where coordinates are normalized (0-1) relative to image dimensions.

Recent Improvements

v2.1 - Interface Enhancements

• Visual Status System: Color-coded dots show completion status at a glance
• Smart Status Bar: Compact status display with image filename, zoom, and polygon count
• Enhanced Image Navigation: Clickable image list with live status updates
• Space Key Fix: Prevents image list scroll conflicts during panning
• Improved Rendering: Better image display on page load with multiple draw passes
• Status Legend: Clear indicators for Complete, Partial, Incomplete, and Empty states

v2.2 - UX Improvements

• Class Name Labels: Text labels on polygon first points for accessibility
• Click-to-Select Polygons: Click inside polygons to select them for editing/deletion
• Extended Status Visibility: Status messages now display for 3+ seconds
• Enhanced Accessibility: Color-blind friendly with text labels alongside colors
• Improved Selection: Better polygon selection workflow for large annotation projects

Security Note

The images/ and labels/ directories are excluded from version control to protect sensitive data. Add your own images and the tool will generate labels locally.

License

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

Final Warning

Remember: This is AI slop code! 🎭 It works, but it's not perfect. Use it, break it, fix it, or throw it away - it's all up to you. Just don't come crying to us when your polygons look like abstract art! 🎨