Metadata-Version: 2.4
Name: magiclabel
Version: 0.1.0
Summary: AI-assisted image annotation CLI for computer vision datasets
Author: Rohan Rustagi
License: MIT
Keywords: annotation,labeling,computer-vision,yolo,dataset,object-detection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich
Requires-Dist: opencv-python
Requires-Dist: gradio
Requires-Dist: gradio_image_annotation
Requires-Dist: torch
Requires-Dist: torchvision
Dynamic: license-file

# 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.

![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

---

## 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

```bash
pip install magiclabel
```

### From source

```bash
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:

```bash
magiclabel --help
```

---

## Quick start — the full loop

```bash
# 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).

```bash
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**

```bash
# 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.

```bash
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 <kbd>Delete</kbd> 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`.

```bash
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**

```bash
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:

```bash
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

```bash
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  |

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

---

### `export-classes` — list a model's class names

```bash
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:

```text
<class_id> <x_center> <y_center> <width> <height>
```

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

```text
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:
  ```bash
  kill $(lsof -nP -tiTCP:7860 -sTCP:LISTEN)
  ```
- **Restart after changes:** the review server does not hot‑reload — stop it (<kbd>Ctrl</kbd>+<kbd>C</kbd>) and run `magiclabel review …` again.

---

## Project structure

```text
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](LICENSE).
