bbannotate 1.1.0

A lightweight bounding box annotation tool for image datasets. Built with React/TypeScript frontend and FastAPI backend. Export to YOLO, COCO, Pascal VOC, and more.

Features

• 🖼️ Multi-format support — PNG, JPEG, WebP, BMP
• 📁 Project management — Organize annotations by project
• 🏷️ Custom labels — Define your own class labels
• 🎨 Adaptive box colors — Auto contrast, label-based, or custom color modes
• ⌨️ Keyboard shortcuts — Fast annotation workflow
• 📤 Multiple export formats — YOLO, COCO, Pascal VOC, CreateML, CSV
• 🔄 Train/Val/Test split — Automatic dataset splitting for YOLO export

Installation

pip install bbannotate

Requirements

• Python 3.12+
• Node.js (only for frontend development)

Quick Start

# Start the annotation server
bbannotate start

# Opens http://127.0.0.1:8000 in your browser.
# By default the server runs detached, so you can close the terminal.
# Closing that browser session stops the detached server automatically.

Runtime Modes

• Default (bbannotate start): Starts server in detached mode and links lifecycle to the opened browser session.
• Development (bbannotate start --reload): Runs in foreground with auto-reload.
• No Browser (bbannotate start --no-browser): Starts server without opening browser automatically.

CLI Options

bbannotate start [OPTIONS]

Options:
  -h, --host TEXT        Host to bind the server to [default: 127.0.0.1]
  -p, --port INTEGER     Port to bind the server to [default: 8000]
  --no-browser           Don't open browser automatically
  -r, --reload           Enable auto-reload for development
  -d, --data-dir PATH    Directory for storing data [default: ./data]
  --projects-dir PATH    Directory for storing projects [default: ./projects]
  --help                 Show help and exit

Other Commands

bbannotate info             # Show installation info
bbannotate status           # Show runtime status (backend/frontend processes + ports)
bbannotate build-frontend   # Build frontend assets (development)

Keyboard Shortcuts

Export Formats

Configuration

Environment Variables

Development

Setup

git clone https://github.com/sebastianydemadsen/bbannotate.git
cd bbannotate
make install        # Install with dev dependencies
make frontend-install  # Install frontend dependencies

Development Commands

Project Structure

src/               # Python package (FastAPI backend)
  api/             # API routes
  models/          # Pydantic models
  services/        # Business logic
  cli.py           # CLI entry point
frontend/          # React/TypeScript frontend
  src/
    components/    # UI components
    hooks/         # React hooks
tests/             # Python test suite

License

MIT