# 🎮 Sprite Tagger

[![WARN-LLM GENERATED](https://img.shields.io/badge/WARN-LLM%20GENERATED-FF6347)](https://github.com/40ants/ai-badges)

A fast, keyboard-driven tool for sorting sprite animation frames into labeled directories. Load a folder of frames, tag them as `idle`, `walk`, `run`, whatever — then export them into organized subfolders in one shot.

![Python](https://img.shields.io/badge/Python-3.9+-blue?style=flat-square&logo=python)
![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey?style=flat-square)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)

![Sprite Tagger screenshot](screenshot.png)

---

## ✨ Features

- 🖼️ **Pixel-perfect display** — small sprites zoom in with nearest-neighbor scaling; transparency shows on a checkerboard background
- ⌨️ **Fully keyboard-driven** — tag and advance without touching the mouse
- ▶️ **Live animation preview** — `Space` plays through all frames; `P` plays back *only the current frame's label* on a loop, so you can confirm a walk cycle or attack animation reads right
- 🏷️ **Label up to 9 categories** — one keypress per tag, auto-advances to the next frame; add new labels on the fly with `N`
- 📁 **Non-destructive** — copies originals into labeled subdirectories, leaves your source untouched
- 💾 **Autosave & resume** — every label is written to a `.sprite_tags.json` sidecar as you go, so you can quit mid-batch and pick up exactly where you left off
- 🎨 **Dark theme UI** — easy on the eyes during long tagging sessions

---

## 🚀 Quick Start

### Prerequisites

```bash
pip install Pillow
```

> tkinter is included with most Python installs. On macOS with Homebrew: `brew install python-tk`

### Run it

```bash
python sprite_tagger.py /path/to/frames idle walk run jump attack
```

With a custom output directory:

```bash
python sprite_tagger.py ./sprites idle walk run --out ./sorted_frames
```

---

## ⌨️ Controls

| Key | Action |
|-----|--------|
| `←` `→` | Previous / next frame |
| `1` – `9` | Assign label and advance to next frame |
| `Space` | Play / pause all frames |
| `P` | Play / pause only the current frame's label, looping |
| `[` `]` | Decrease / increase playback speed (1–30 fps) |
| `X` | Clear label on current frame |
| `N` | Add a new label on the fly |
| `Enter` | Export all labeled frames |

---

## 📂 Output Structure

After exporting, your labeled frames are copied into subdirectories named after each label:

```
output/
├── idle/
│   ├── frame_000.png
│   ├── frame_001.png
│   └── frame_002.png
├── walk/
│   ├── frame_003.png
│   └── frame_004.png
└── run/
    ├── frame_005.png
    └── frame_006.png
```

If no `--out` path is specified, output goes to `<frames_dir>/labeled/`.

---

## 🎯 Workflow

1. Point it at a directory of exported sprite frames
2. Use `←` `→` to step through frames, or hit `Space` to play them back and get a feel for the animation
3. When you land on a frame you want to tag, press the number key for that label — it tags and jumps to the next frame automatically
4. Made a mistake? Navigate back and press the same or different number to reassign, or `X` to clear
5. Hit `Enter` when done — a summary dialog confirms what was copied where

---

## 🛠️ Supported Formats

`.png` · `.jpg` · `.jpeg` · `.gif` · `.bmp` · `.webp` · `.tga`

---

## 📋 Requirements

- Python 3.9+
- [Pillow](https://python-pillow.org/)
- tkinter (standard library, included with most Python distributions)