Metadata-Version: 2.4
Name: ultimate_ai_labeller
Version: 0.1.13
Summary: AI Labelling tool for computer vision
Author-email: James Chang <james2738999@gmail.com>
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: ultralytics
Dynamic: license-file

# Ultimate AI Labeller

Desktop image annotation tool for object detection datasets (Tkinter + Ultralytics), with a separate web project.

## Features

- Bounding-box annotation with drag, move, and resize handles
- Rotated bounding boxes:
  - Drag rotate knob on selected box
  - 8 resize handles follow box rotation
  - Keyboard rotate (`Q/E`, `Shift+Q/E`)
- Multi-select boxes (`Shift/Ctrl + Click`) for batch class reassignment and delete
- Select all boxes in current image (`Ctrl+A`)
- Nested/overlapping box picking prefers inner (smaller) box for easier adjustment
- Undo/redo history (`Ctrl+Z`, `Ctrl+Y`)
- Image navigation (`F` next/save, `D` previous)
- Auto red-region proposal (`A`)
- YOLO detection from UI (`Run Detection`)
- Startup source selection:
  - Open Images Folder
  - Open YOLO Dataset
  - Open RF-DETR Dataset
- Detection model management:
  - Official model mode (`yolo26m.pt` path by default)
  - Import custom models (`.pt`, `.onnx`) via `Browse Model`
  - Select model from dropdown library
- Train from existing labels:
  - Choose training range by index
  - Choose weight source before training:
    - Official `yolo26m.pt`
    - Custom weight file (`.pt` / `.onnx`)
    - From scratch (`pretrained=False`)
  - Save training artifacts to selected output folder
  - Non-blocking background training (continue labeling while training)
  - Built-in training monitor (command/log/progress/ETA)
- Class management:
  - Add / rename / delete class in class table
  - Deleting a class reindexes following class IDs automatically
- Auto-detect and propagate options (3 propagate modes: no-label-only / always / selected labels only)
- Scrollable right settings panel
- Remove/restore bad frames from split
- Image dropdown jump
- Session resume (last project/split/image/model settings)
- English/Chinese UI switch and light/dark theme
- Export all annotations by format:
  - `YOLO (.txt)` export to `images/train` + `labels/train` structure
  - `JSON` full dataset export (per-image annotation json)

## Repositories

- Desktop app (this repo): `https://github.com/JamesChang666/ultimate_ai_labeller`
- Web app (separate repo): `https://github.com/JamesChang666/labeller_web`

## Dataset Structure

```text
your_project/
  images/
    train/
    val/
    test/
  labels/
    train/
    val/
    test/
```

- Image extensions: `.png`, `.jpg`, `.jpeg`
- Label format: YOLO txt (`class cx cy w h`, normalized)
- Rotated-box metadata (when used): sidecar `*.txt.rot.json` with `angles_deg`
- Full guide (ZH): `docs/dataset-structure-guide.md`

Removed frames are moved to:

```text
your_project/
  removed/
    train|val|test/
      images/
      labels/
```

## Install

From PyPI:

```bash
pip install ultimate_ai_labeller
```

From local wheel:

```bash
pip install dist/ultimate_ai_labeller-*.whl
```

From source:

```bash
pip install .
```

For development:

```bash
pip install -e .
```

## Run

```bash
ai-labeller
```

Or:

```bash
python src/ai_labeller/main.py
```

## Web Version

This desktop repository includes local development files under `web_labeller/`, but the maintained web repository is:

- `https://github.com/JamesChang666/labeller_web`

Run locally:

```bash
cd web_labeller
pip install -r requirements.txt
uvicorn app:app --host 127.0.0.1 --port 8000 --reload
```

## Shortcuts

- `F`: save and next image
- `D`: previous image
- `A`: auto red detection
- `Q/E`: rotate selected box (-5 deg / +5 deg)
- `Shift+Q/E`: rotate selected box faster (-15 deg / +15 deg)
- `Ctrl+Z`: undo
- `Ctrl+Y`: redo
- `Ctrl+A`: select all boxes in current image
- `Ctrl+Left Drag`: marquee multi-select boxes
- `Delete`: delete selected box

## Notes

- Default detection model mode is `Official YOLO26m.pt (Bundled)`.
- If the official model file is unavailable locally, import a custom `.pt/.onnx` model from the UI.
- If CUDA/GPU runtime is incompatible, detection/training automatically falls back to CPU.
- To use your own Tk app icon, put `app_icon.png` in `src/ai_labeller/assets/`.
- Session file: `~/.ai_labeller_session.json`.
- Project progress YAML: `<project_root>/.ai_labeller_progress.yaml` (resume split/image and class names after reopen).
