Pixel Print Kit
Image in, printable kit out. The script finds the pixel grid (or pixelates a normal image), cleans the palette, builds watertight per-colour geometry with manifold3d, and checks the result the way a slicer reads it.
Quick start
SKILL_DIR = the folder containing this file (${CLAUDE_SKILL_DIR} when available). Quote paths.
python "$SKILL_DIR/scripts/pixelkit.py" sprite.png # 45 mm keychain, one part per colour
python "$SKILL_DIR/scripts/pixelkit.py" sprite.png --product magnet --style swap # single-nozzle printer
python "$SKILL_DIR/scripts/pixelkit.py" logo.png --pixels 32 --max-colors 4 --render # pixelate a logo, add renders
First time only: python -m pip install manifold3d numpy pillow (the script prints this if anything is missing).
Output in pixelkit-out/<name>/: stl/ (one file per colour), <name>.3mf (one object, one part per colour, named
01_black, 02_... in slot order), guide.md (filaments, settings, colour-change heights), kit.json,
preview.png (flat colour check), and with --render: hero.jpg, top.jpg, turntable.mp4.
Pick product and style
| the user wants | flags |
|---|---|
| keychain (default) | --product keychain (45 mm, 2.2 mm outline, Ø4.2 mm ring hole) |
| fridge magnet | --product magnet (adds a pocket for a 10x2 mm magnet; --magnet 8x3 to change) |
| coaster | --product coaster (95 mm round) |
| wall plaque / sign | --product plaque (120 mm rounded rectangle) |
| just the art | --product tile (no outline) |
| has an AMS / multi-material | --style ams (default): flush colours, changes only in the top layers |
| single nozzle, no AMS | --style swap: one body, each colour one height step; guide lists the layer for each filament change |
Useful: --size 60 (finished outer size, mm) · --grid-gap 0.3 (grooves between pixels, very "pixel") ·
--raise 0.6 (ams: colours stand proud) · --shape silhouette|rect|round · --border 0 · --hole 0 ·
--hole-pos left|center|right · --base-color "#hex" (outline colour) · --order "#a,#b,..." (swap: bottom to top) ·
--max-colors 4 (match the user's AMS slots) · --keep-bg (opaque background is part of the art).
Workflow
- [ ] run pixelkit.py; read the console: grid size, colours -> filaments, checks OK
- [ ] look at preview.png: is the palette right? (stray anti-aliasing colours -> raise --merge or lower --max-colors)
- [ ] pixel size >= 0.8 mm (a warning appears otherwise -> bigger --size or fewer --pixels)
- [ ] --render and Read hero.jpg / top.jpg before delivering
- [ ] tell the user: dimensions, filament slots, and for swap the colour-change heights from guide.md
The checks (open edges 0, overlap 0) must pass; the script exits with code 2 if not. Never hand over a failing kit.
Rules of thumb
- Real pixel art beats pixelated photos. For a logo, 24-40 pixels wide and 3-5 colours read best.
- Colours = filaments. Keep
--max-colorsat or below the user's AMS slots; suggested PLA names are nearest matches, so ask the user to compare with their spools. - Swap order: darkest at the bottom works for most art (outline first). Light details on top stay crisp.
- Small pixels: keychains under 40 mm with 32+ px get fragile features; grow the size or simplify the art.
- Pixel art from games/brands is someone else's IP: fine for personal prints, not for selling.
When to read what
references/print-notes.md- slicer steps (Bambu/Orca/Prusa), tolerances, magnets, troubleshooting.