initial commit

README.md

@@ -0,0 +1,108 @@
+# 🎮 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)