magiclabel 0.2.0

AI-assisted image annotation CLI for computer vision datasets

MagicLabel

AI‑assisted image labeling CLI — go from raw images to your own trained model, end to end.

Good models start with good data, and labeling that data by hand is the slowest part of any computer‑vision project. MagicLabel runs the whole loop from one command line:

1. Auto‑detect objects in a folder of images — including custom objects you describe in plain words (no training needed).
2. Review & fix the labels in a browser — draw, move, resize, relabel, delete.
3. Train a custom YOLO model on your labeled data.
4. Reuse your named model (rohan.pt, findelon.pt, …) to auto‑label the next batch — the loop closes.

Everything runs locally and free — no account, no cloud upload, no Docker.

---

Features

• 🔍 Auto‑detect — label an image folder with a YOLO model (the 80 COCO classes out of the box).
• 🗣️ Open‑vocabulary detect — --prompt "missile,launcher" detects anything you name, with no training (YOLO‑World).
• 🖊️ Visual review — a Gradio web app to draw / move / resize / relabel / delete boxes and save back to YOLO format. Type any class name you want.
• 🎓 Train — fine‑tune a custom model on your labeled data and save it as a named .pt.
• 🔄 Export — convert YOLO labels to COCO JSON.
• 🏷️ Inspect — print the class names a YOLO model knows.

---

Who is this for?

Anyone who needs a labeled image dataset and a model to train on it:

• ML engineers & researchers bootstrapping a dataset from raw images.
• Hobbyists & students learning the full CV pipeline without paying for a labeling service.
• Privacy‑sensitive / air‑gapped users (medical, defense, proprietary data) who can't upload images to a cloud tool.

---

Requirements

• Python 3.8+
• Disk space for model weights (downloaded automatically on first use)
• Works on CPU; a CUDA or Apple‑Silicon (MPS) GPU is used automatically when available and is much faster for training

Heads‑up: MagicLabel depends on torch and ultralytics, so installation pulls ~1 GB of packages. That's normal for a computer‑vision tool.

---

Installation

From PyPI

pip install magiclabel

From source

git clone https://github.com/your-username/magiclabel.git
cd magiclabel
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

Verify:

magiclabel --help

---

Quick start — the full loop

# 1. Auto-label a folder of images (closed-set, 80 COCO classes)
magiclabel detect ./images --output ./labels

#    …or detect a CUSTOM object by describing it (no training):
magiclabel detect ./images --prompt "missile, launcher" --output ./labels

# 2. Review and fix the labels in your browser
magiclabel review ./images ./labels

# 3. Train your own model on the corrected dataset
magiclabel train ./images ./labels --name rohan.pt --epochs 50

# 4. Reuse your model to auto-label the next batch
magiclabel detect ./new_images --model rohan.pt --output ./labels2

---

Commands

Run magiclabel <command> --help at any time for the full option list.

detect — auto‑annotate with bounding boxes

Runs a model over every image in a directory and writes one YOLO‑format .txt per image, plus a classes.txt (the class list).

magiclabel detect SOURCE [OPTIONS]

Option	Default	Description
SOURCE	(required)	Directory of images (.jpg, .jpeg, .png, .bmp, .tif)
--prompt	(none)	Comma‑separated object names for open‑vocabulary detection, e.g. "missile,launcher". No training needed.
--model	yolov8n.pt / yolov8s-world.pt	Model file. Defaults to yolov8n.pt (closed‑set), or yolov8s-world.pt when --prompt is given. Pass your own .pt to use a trained model.
--output	./labels_detect	Output directory for labels + classes.txt
--conf	0.25	Confidence threshold (0–1); higher = fewer, surer boxes

Examples

# Closed-set: the 80 COCO classes
magiclabel detect ./images --conf 0.3 --output ./labels

# Open-vocabulary: detect objects YOLO has never been trained on
magiclabel detect ./images --prompt "drone, fixed-wing aircraft" --conf 0.1

# Use your own trained model
magiclabel detect ./images --model rohan.pt --output ./labels

Open‑vocabulary is great for common/clear objects and hit‑or‑miss on unusual ones (it does the easy 70–80%). For hard objects (e.g. missiles), hand‑label a first batch in review, train a model, then detect --model your.pt to auto‑label the rest.

---

review — fix annotations in your browser

Launches a local web app (default: http://127.0.0.1:7860) to inspect and correct labels.

magiclabel review IMAGES_DIR LABELS_DIR [--model yolov8n.pt]

Argument / Option	Description
IMAGES_DIR	Directory of images
LABELS_DIR	Directory of YOLO .txt labels (and classes.txt)
--model	Model whose class names label the boxes (default yolov8n.pt). Use --model none to start a clean custom dataset with no preset names.

In the UI you can:

• Draw a new box — click and drag on the image.
• Move / resize — click a box and drag it or its corner handles.
• Set the class — double‑click a box and type any class name (missile, crack, logo), then click the editor's apply/✓ to commit. New names are added automatically.
• Delete — the box's remove button, the Delete key, or Clear All Boxes.
• Switch images — the dropdown at the top (it opens on the first image that already has boxes).
• Save Changes — writes boxes back to the .txt; the view then reloads from disk so you can confirm exactly what was saved.

Custom classes & classes.txt: YOLO label files store integer class ids, so MagicLabel keeps a classes.txt (one name per line, id = line number) in your labels folder. Whatever name you type is mapped to a stable id behind the scenes, and new names are appended automatically. That classes.txt is the class list you train on.

Edits live only in the browser until you click Save Changes. Saving an image with no boxes writes an empty label file (a valid "no objects" annotation).

---

train — train your own model

Fine‑tunes a YOLO model on your labeled dataset and saves it as a named .pt.

magiclabel train IMAGES_DIR LABELS_DIR [OPTIONS]

Option	Default	Description
IMAGES_DIR	(required)	Directory of images
LABELS_DIR	(required)	Directory of YOLO labels + classes.txt
--name	custom.pt	Output model name, e.g. rohan.pt
--base	yolov8n.pt	Base model to fine‑tune
--epochs	50	Training epochs
--imgsz	640	Training image size
--val-split	0.2	Fraction of images held out for validation

Example

magiclabel train ./images ./labels --name rohan.pt --epochs 100
# → rohan.pt  (and a rohan_dataset/ folder with the train/val split + data.yaml)

The command builds a proper YOLO dataset (train/val split + data.yaml) from your labels, trains, and copies the best weights to your named file. Use it anywhere a model is accepted:

magiclabel detect ./new_images --model rohan.pt

A useful model needs dozens‑to‑hundreds of labeled images and enough epochs. On CPU this can be slow — a GPU is much faster. Start small to validate the pipeline, then scale your data.

---

yolo2coco — convert labels to COCO JSON

magiclabel yolo2coco IMAGES_DIR LABELS_DIR OUTPUT_JSON --class NAME [--class NAME ...]

Argument / Option	Description
IMAGES_DIR	Directory of images
LABELS_DIR	Directory of YOLO detection labels
OUTPUT_JSON	Path to write the COCO JSON file
--class	Class names in class‑id order (0, 1, 2, …), repeated

magiclabel yolo2coco ./images ./labels annotations.json \
  --class person --class bicycle --class car

---

export-classes — list a model's class names

magiclabel export-classes yolov8n.pt
# 0: person
# 1: bicycle
# 2: car
# ...

---

Label format

MagicLabel reads and writes the YOLO detection format: one .txt per image, sharing the image's base name (dog.jpg → dog.txt). Each line is one box:

<class_id> <x_center> <y_center> <width> <height>

All four coordinates are normalized to 0–1 relative to the image size. Example:

16 0.593846 0.400000 0.250769 0.258462

A classes.txt alongside the labels maps each id to a name (id = line number).

---

Tips & troubleshooting

• Model downloads: the first run of a new model downloads its weights into the current directory and reuses them after.
• Speed: detection is fast on CPU; training is much faster on a GPU (PyTorch uses CUDA/MPS automatically).
• "No images found": the source must be a directory containing images with a supported extension (.jpg, .jpeg, .png, .bmp, .tif, .tiff).
• Port 7860 already in use: an old review server is still running. Stop it with:

  kill $(lsof -nP -tiTCP:7860 -sTCP:LISTEN)
  

• Restart after changes: the review server does not hot‑reload — stop it (Ctrl+C) and run magiclabel review … again.

---

Project structure

magiclabel/
├── cli.py          # Typer CLI entry point (detect, review, train, yolo2coco, export-classes)
├── annotator.py    # YOLO / YOLO-World detection → label files + classes.txt
├── review_app.py   # Gradio review/annotation web app
├── trainer.py      # builds the dataset and trains a custom model
├── convertor.py    # YOLO → COCO conversion
└── utils.py        # image discovery + helpers

---

License

Released under the MIT License.