image-sprite-sheet-split

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.py through the python manifest entry (.dependency/python/). Never use host python, py, or python3.
• 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 COLSxROWS before running (e.g. 4x4, 6x3).
• populated: false is not a reason to skip. Install first, set populated: 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)

1. Ensure python and ffmpeg are populated in .dependency/manifest.json (see skill-dependency-manager).

2. FFmpeg must include ffprobe beside ffmpeg in the same bin/ 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

1. **Confirm grid size** �?ask or infer from context (`4x4`, `3x6`, etc.).
2. **Trial first** �?split one sheet, inspect `image-sprite-sheet-split/<stem>/001.png` and the last frame.
3. **Check warnings** �?if image size is not evenly divisible, verify cell crops still look correct.
4. **More sheets** �?run once per file with the same grid settings.
5. **Revert** �?delete the output folder; sources are never modified.

## Examples

4×4 explosion sheet (2048×2048 �?16 × 512×512):

```bash
.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

1. Use the bundled script, not hand-written FFmpeg crop commands.
2. Missing Python/FFmpeg �?populate .dependency/ per skill-dependency-manager, retry same command.
3. Do not copy, move, or replace the source with frame outputs �?tell the user where the output folder is.