godot-fun Image Sprite Sheet Split
Split uniform grid sprite sheets into individual PNG frames via FFmpeg crop. Preserves per-cell dimensions and alpha. Does not remove backgrounds — run image-remove-background on frames afterward if needed.
Rules
When this skill applies, read and follow skill-dependency-manager — run scripts as documented, install missing tools into .dependency/.
- Run
split_frames.pythrough thepythonmanifest entry (.dependency/python/). Never use hostpython,py, orpython3. - Do not hand-write FFmpeg crop commands — use the bundled script.
- Single file only. Pass one sprite sheet with
--image; directories are not supported. - Grid size required. Supply
--grid COLSxROWSbefore running (e.g.4x4,6x3). populated: falseis not a reason to skip. Install first, setpopulated: true, retry the same command.- Never overwrite sources. Output goes into
<image-dir>/image-sprite-sheet-split/<sheet-stem>/by default (or under-o). - Never copy or move input images. Pass the user's actual file path.
Setup (first run)
Ensure
pythonandffmpegare populated in.dependency/manifest.json(see skill-dependency-manager).FFmpeg must include
ffprobebesideffmpegin the samebin/folder.
Quick Start
Default: <image-dir>/image-sprite-sheet-split/<sheet-stem>/ beside the input sheet:
# 4×4 sheet → image/effects/image-sprite-sheet-split/fire_sheet/fire_sheet_001.png … fire_sheet_016.png
.dependency/python/python .ai/image-sprite-sheet-split/split_frames.py --image image/effects/fire_sheet.png --grid 4x4
Custom output root:
.dependency/python/python .ai/image-sprite-sheet-split/split_frames.py --image image/effects/fire_sheet.png --grid 4x4 -o image/effects/frames/
# → image/effects/frames/fire_sheet/fire_sheet_001.png …
Defaults
| Option | Default | Notes |
|---|---|---|
--image |
Required | Single sprite sheet image file |
--grid |
Required | COLSxROWS (columns first), e.g. 4x4, 6x3 |
| Output | image-sprite-sheet-split/<stem>/ |
Use -o / --output for a custom root directory |
Frames are exported row-major (left→right, top→bottom): _001, _002, …
Supported inputs: .png, .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff, .avif, .ico.
When to use
| Good fit | Poor fit |
|---|---|
| Uniform N×M grid (4×4, 3×6, 8×1) | Irregular / free-form layouts |
| Gemini or Aseprite-style sheets | Packed texture atlases with variable frame sizes |
| Sheets without gutters or border padding | Sheets with grid lines, gutters, or outer padding |
| Preparing frames for per-frame background removal | Auto-detecting grid size (must be supplied) |
rembg on whole sheets removes animation content — split frames first, then remove backgrounds per frame if needed.
Agent Workflow
- Confirm grid size — ask or infer from context (
4x4,3x6, etc.). - Trial first — split one sheet, inspect
image-sprite-sheet-split/<stem>/001.pngand the last frame. - Check warnings — if image size is not evenly divisible, verify cell crops still look correct.
- More sheets — run once per file with the same grid settings.
- Revert — delete the output folder; sources are never modified.
Examples
4×4 explosion sheet (2048×2048 → 16 × 512×512):
.dependency/python/python .ai/image-sprite-sheet-split/split_frames.py --image sheet.png --grid 4x4
6×3 sheet:
.dependency/python/python .ai/image-sprite-sheet-split/split_frames.py --image sheet.png --grid 6x3
Agent Notes
- Use the bundled script, not hand-written FFmpeg crop commands.
- Missing Python/FFmpeg → populate
.dependency/per skill-dependency-manager, retry same command. - Do not copy, move, or replace the source with frame outputs — tell the user where the output folder is.
- Need transparent frames → split first, then image-remove-background on each frame.
Troubleshooting
| Issue | Fix |
|---|---|
FFmpeg not found |
Populate ffmpeg in .dependency/manifest.json |
Directory passed to --image |
Run once per sheet; this skill accepts image files only |
| Output already exists | Delete the existing frame folder or choose a different -o path |
| Wrong frame count | Verify --grid matches the sheet layout |
| Misaligned crops | Sheet may have gutters/padding — this skill expects a clean uniform grid |
| Unused pixels warning | Image size is not evenly divisible by the grid; inspect output frames |
| Need transparent frames | Split first, then image-remove-background on frames |
CLI
Copy-paste commands: cli/image-sprite-sheet-split.md
Related
- Transparent cutouts per frame: image-remove-background
- Trim frame borders: image-trim