init

README.md

@@ -0,0 +1,66 @@
+# sprite_gen
+
+Procedural 96x96 creature sprites for businesses. You give it a business name and logo. It picks a type, builds a creature from parts and recolors it with the logo's brand colors.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+You only need an [OpenRouter](https://openrouter.ai) API key if you want the type picked automatically. Skip the key by passing `--type`.
+
+## Generate a sprite
+
+```bash
+# Type picked from the business name
+OPENROUTER_API_KEY=<API_KEY> python generate_sprite.py "Rosas Landscaping" logos/rosas.png
+
+# Add a description to help pick the type
+OPENROUTER_API_KEY=<API_KEY> python generate_sprite.py "Rosas Landscaping" logos/rosas.png --desc "Lawn care and garden design"
+
+# Set the type yourself (no API key needed)
+python generate_sprite.py "Rosas Landscaping" logos/rosas.png --type grass
+
+# Set the colors yourself instead of using a logo (main color first)
+python generate_sprite.py "Rosas Landscaping" --type grass --colors "#2E7D32,#FBC02D"
+
+# A different creature for the same business
+python generate_sprite.py "Rosas Landscaping" logos/rosas.png --type grass --reroll 1
+```
+
+Each run writes `sprites/<slug>.png` (96x96), `sprites/<slug>@4x.png` and `sprites/<slug>.json` (type, parts, colors). With `--reroll N`, the file names end in `-rN`.
+
+| Option | Meaning |
+|---|---|
+| `--type T` | Skip the classifier. One of: normal fire water grass electric ice fighting poison ground flying psychic bug rock ghost dragon |
+| `--desc TEXT` | Description sent to the classifier (default: the name) |
+| `--colors "#main,#accent"` | Manual colors; overrides the logo |
+| `--reroll N` | Alternate creature; the name alone always gives the same sprite |
+| `--out DIR` | Output folder (default `sprites`) |
+| `--scale N` | Size of the upscaled copy (default 4, `1` disables it) |
+
+Logo colors: transparent pixels, soft edge pixels and a solid white/black/gray background are ignored, and colored brand colors are used before white, black or gray. A logo with only white, black or gray in it still uses those colors.
+
+## Batch
+
+Use a CSV with the columns `name,logo,type,description`. Only `name` is required, and rows with no `type` use the classifier.
+
+```bash
+OPENROUTER_API_KEY=<API_KEY> python generate_sprite.py --batch businesses.csv --out sprites
+```
+
+## Editing the art
+
+The parts are text grids in `parts_src/<slot>/<name>.txt`, compiled to `parts/<slot>/<name>.png`. Weights, compatibility and deny lists live in `sprite_parts.py`. See `AI_PIXEL_ART_GUIDE.md` for the palette and anchor rules.
+
+```bash
+python build_parts.py                     # compile all grids (or pass part names)
+python validate_parts.py --sample 3000    # check colors, anchors, canvas fit on random composites
+python preview.py bases                   # contact sheets in preview/
+python preview.py part back plant_bulb    # one part on every base it fits
+python preview.py zoom body=base_fox tail=tail_leaf
+python generate_sprite.py --sprite-list SPRITES.md   # regenerate the part list and weight report
+```
+
+Do not run `--make-placeholders --overwrite`, because it replaces the real art with test placeholders.