Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Sheet Slicing — multi-figure grid sheets to per-cell standing cuts (tachi-e)
Owns: Multi-figure grid sheets to per-cell standing cuts; the
cutoutroutes · Index: docs/README.md
slice_sheet_cells.py (= sprite_gen.cli slice-sheet) turns ONE generated
image containing a COLSxROWS grid of the same character (expressions, poses,
outfits) into per-cell RGBA cuts on a fixed canvas with a shared feet
baseline and a normalized subject height. Built for dialogue cut-in
portraits (立ち絵); works for any "same subject, N variants in one sheet"
generation. For a sheet of different props or icons, --scale sheet keeps
the sizes they were drawn at and --fit contain keeps every cut whole
(Props and icons).
This is NOT the component-row animation pipeline. Rows animate one state
over time; a sheet enumerates variants of one standing subject. Use
prepare/extract/compose-atlas for animation, slice-sheet for
variant sheets.
Alpha ownership
Alpha truth is sprite_gen.frames.extract.remove_chroma_background — the same
v1.13 4-pass chain the row pipeline uses (hard key cut → key-depth in-band
unmix → soft-alpha unmix → trapped-spill despill). slice-sheet owns only
cell geometry. Generate sheets on a chroma background chosen by the
subject-color gate in image-gen's SKILL.md (pink/purple material → green
key, green material → magenta key). Never generate variant sheets on a
cream/white background and flood-fill them — background pockets trapped
between props and legs survive as opaque bands, and light clothing is one
tolerance away from being punched full of holes (2026-07-09 field
accident, twice).
Usage
$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/slice_sheet_cells.py \
--sheet raw/hero_expressions.png \
--out-dir portraits/hero \
--chroma-key green \
--grid 3x2 \
--names default,smile,sad,annoyed,angry,pleased \
--prefix hero_ \
--cell-width 512 --cell-height 768 \
--baseline-y 725 --target-height 645
--namescount must equal the grid cell count (reading order, left-to-right then top-to-bottom). Omit forcell-Nnames.--target-heightis the character's canonical body height on the output canvas. Keep one value per character across every sheet so a cast keeps its height hierarchy.- Extraction tunables (
--key-threshold,--fringe-*,--spill-max-fraction) pass through toremove_chroma_backgroundwith the same defaults asextract. The key distance is measured from the pure key and from the background colour detected on the sheet's borders, so a sheet the generator painted a darker green/magenta than asked still keys cleanly (chroma-alpha.md).
Transparent sheets
A sheet a provider returned with real alpha (gen --transparent on a native-alpha route)
has no key to remove: pass --chroma-key none and the sheet keeps its own alpha.
Transparent sheets often carry a faint alpha haze around and between the drawn objects. It
joins neighbouring parts and enlarges a figure's measured height. --alpha-floor N (1..255;
64 suits most generated sheets) clears it before parts are measured, with the shared
alpha cleanup: pixels at or above the floor and the faint pixels
within --alpha-edge pixels (default 2) of them are kept as they are, every other faint pixel
becomes fully transparent. The run writes the cleanup's report to
<out-dir>/<prefix>alpha-cleanup.json (haze share before and after, pixels cleared, and the
count of solid and edge pixels that changed, which is 0). Without the flag nothing changes:
the default 0 leaves the alpha exactly as extraction made it.
sprite-gen slice-sheet --sheet props.png --out-dir props/ --chroma-key none --alpha-floor 64 \
--grid 3x2 --names pillar,statue,shrub,lantern,gravestone,fountain --prefix prop_
Alpha cleanup
Transparent sheets from image models often carry a faint alpha haze: barely visible pixels around and between the drawn objects. --alpha-floor clears it with sprite_gen.frames.alpha_floor.clear_haze.
- A pixel at or above the floor (
--alpha-floor) is solid. A pixel above zero and below the floor is faint. - A faint pixel within
--alpha-edgepixels (8-connected, so diagonals count) of a solid pixel is part of an object's anti-aliased edge and is kept unchanged. - Every other faint pixel is haze and becomes fully transparent (
0, 0, 0, 0). A pixel that was already fully transparent is left as it was.
Solid pixels and edge pixels are never changed, so a stroke stays whole as long as some of its pixels reach the floor. A stroke drawn entirely below the floor is indistinguishable from haze and is removed: lower the floor for very faint art. The report measures instead of asserting: it counts what actually changed.
| Field | Meaning |
|---|---|
floor, edge_px |
the settings |
pixels |
pixels in the image |
faint_fraction_before, faint_fraction_after |
share of all pixels with alpha from 1 to floor - 1, before and after |
haze_fraction_before, haze_fraction_after |
share of all pixels that are faint and farther than edge_px from a solid pixel |
cleared_pixels |
pixels made transparent |
changed_solid_pixels, changed_edge_pixels |
solid and kept-edge pixels whose value changed; 0 unless the cleanup is wrong |
Props and icons: sheet scale and contain fit
The default suits a character's variants: each cell's main subject is scaled to --target-height on its own,
and the canvas cuts whatever that scale puts past its edge. A sheet of different things needs two other rules,
each a flag:
--scale sheettakes one factor for the whole sheet: the tallest main subject reaches--target-heightand every other cell is scaled by the same factor. A prop drawn twice as tall as another stays twice as tall, within a pixel. The default--scale cellgives every cell its own factor.--fit containlowers the factor until the whole cut, every part the cell kept, fits the canvas: the main subject stays centred with its base on--baseline-y, and nothing past an edge is cut. A wide icon on a square canvas is scaled down to the canvas width instead of losing its sides. With--scale sheetthe sheet takes the smallest factor any of its cells fits at, so the relative sizes stay. The default--fit nonekeeps the factor and lets the canvas cut.containneeds--baseline-yinside the canvas, and a part drawn below the main subject's base needs room under the baseline; a cell that cannot fit is refused by name.
# props: drawn sizes kept, nothing cut, feet on the canvas floor
sprite-gen slice-sheet --sheet props.png --out-dir props/ --chroma-key none --alpha-floor 64 \
--grid 3x2 --names pillar,statue,shrub,lantern,gravestone,fountain --prefix prop_ \
--cell-width 512 --cell-height 256 --baseline-y 256 --target-height 240 --scale sheet --fit contain
# icons: each icon as tall as the target unless it is wide, then as wide as the canvas
sprite-gen slice-sheet --sheet icons.png --out-dir icons/ --chroma-key none --alpha-floor 64 \
--grid 4x3 --cell-width 256 --cell-height 256 --baseline-y 236 --target-height 216 --fit contain
Every cell of a sheet is cut on the same canvas, so a consumer that draws each cell at the same height scales them
all by the same amount and the sizes stay relative there too. The alpha
cleanup (--alpha-floor) runs before anything is measured, so the factor is taken on the cleaned sheet and applies to
every cell alike.
Report
Every run writes <out-dir>/<prefix>slice-sheet.json:
{
"kind": "sprite-gen-slice-sheet",
"version": 1,
"sheet": "props.png",
"grid": [3, 2],
"canvas": {"w": 512, "h": 256},
"baseline_y": 256.0,
"target_height": 240.0,
"scale": "sheet",
"fit": "contain",
"factor": 0.8,
"factor_from": {"rule": "target_height", "cell": "fountain"},
"alpha_cleanup": "prop_alpha-cleanup.json",
"cells": [
{"name": "pillar", "file": "prop_pillar.png", "factor": 0.8, "factor_from": "target_height",
"subject": {"sheet": {"w": 120, "h": 260}, "canvas": {"w": 96, "h": 208}},
"box": {"x": 208, "y": 48, "w": 96, "h": 208}, "anchor": [256.0, 256.0],
"clipped_px": 0, "parts": 1}
]
}
scaleandfitname the rules the run used.factoris the one factor of asheetrun andfactor_fromsays where it came from:target_heightof the tallest cell, orfitof the cell that needed the smallest factor. Both arenullfor acellrun, where each cell has its own.- Per cell, in reading order:
fileis the PNG beside the report;factorandfactor_from(target_heightorfit) are that cell's;subjectis the main subject's size on the sheet and scaled onto the canvas;boxis where the whole cut (every part kept) lies on the canvas;anchoris[x, y]on the canvas, the centre of the main subject's base, the point it stands on;clipped_pxcounts the cut's pixels with any alpha that fell past the canvas edge (always0withcontain; the run also prints a line for each cell the canvas cut);partsis how many parts the cell kept. anchoris in the PNG's own pixels, so an engine can take it as the image's origin as it is.
The PNGs of a default run (--scale cell --fit none) are byte for byte those of the version before these flags.
Geometry rules (and the field failures they encode)
Each rule below exists because the naive version shipped a visible defect during the a cut-in overhaul (2026-07-09):
- Component-to-cell assignment by centroid, not grid cropping. Grid cropping slices a figure's own cape/broom at the cell border and imports the neighbour's overflow. Whole-sheet connected components go to the cell containing their centroid, so a figure keeps everything attached to it.
- Merged-figure split + in-cell re-label. Adjacent figures fused through a touching prop (kunai tip into the next figure's hair) form one sheet-wide component spanning cells. Pixels split at cell borders, then connectivity is re-run inside each cell — without the re-label, the neighbour's hair stays fused to the cell's own figure and ships as a floating clothes/hair fragment.
- Neighbour-debris rule. After splitting, fragments that touch the
cell border and are far smaller than the cell's main figure
(
--debris-fraction, default 0.30) are neighbour overhang — dropped. Detached effects (hearts, sparkles, ZZZ) sit inside the cell and survive. - Per-cell height normalization. Generators routinely draw grid rows
at different sizes (one sheet shipped a top row ~40% taller than the
bottom row). Sheet-wide max-height scaling preserves that jitter; each
cell's main figure is scaled independently so every variant's body
height equals
--target-height. Trade-off: a bowed pose (sleep) gets a slightly larger body — runtime cut-in renderers assume one scale, so asset-side height consistency wins. The figure is scaled with its coverage and its colour taken apart (resize_cell, video-pipeline.md "Cells"), so the scaled figure has no rim or key tint at its edge that the sliced figure did not have. - Feet on the baseline. The main figure's lowest pixel lands on
--baseline-y; effects above the head never shift the feet. Under the default--fit nonea cut that crosses the canvas's top or left edge is moved back inside and the canvas cuts it on the other side; the report'sanchor,boxandclipped_pxsay where it landed and what was cut.--fit containscales it until it fits instead. - Fail loud on empty cells. A cell with no subject after extraction raises instead of writing a blank — a cropped or mis-gridded sheet must be regenerated, not silently absorbed. Every cell is measured before any is written, so a failing sheet writes no cells.
Prompting the sheet
Ask for: exactly COLSxROWS figures, one full body per cell with head and feet fully inside the sheet (generators love cropping the top row's feet at the row boundary — say "shoe soles fully visible"), identical body size and feet line across cells, the flat chroma background, and no grid lines, labels, or numbers. Two-arm/anatomy constraints belong in the prompt too: the slicer cannot repair a three-armed generation, only regeneration fixes bad drawing (same doctrine as the row pipeline).
Related
- docs/README.md — documentation index