Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video-sway): under --region-over what a lift uncovers reads the figure under the lower edge from its first row up, never from the region's last row, so it stays as opaque as that figure; the figure there is the cell as cut, a piece --hold-mask leaves out too
Soohong Kime3dc2e82d791
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3d43129..153766e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -85,9 +85,10 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- laid over the figure under it, the lower edge moves as much as the part above it does (at gain 2.5 and 1.25), while without `--region-over` the crease pins it;- the layer draws the band and the air where it lands, no read of the move taken there, and they keep their bytes elsewhere; nothing outside the region, its soft edge, the air and the band changes; the layer covers no deeper than the band; nothing folds;- where the part lifts it shows the figure under it, with no hole;- - where the part lifts, the torso's soft side under it keeps its alpha in the rows the part leaves (no notch), and what the lift uncovers is read in its own column;+ - where the part lifts, the torso's soft side under it keeps its alpha in the rows the part leaves (no notch), and what the lift uncovers is read in its own column, with the read never reaching above the torso's first row under the part's lower edge (it is clamped to that row), so the torso is drawn up from its own first row and never from the part's last row, and what the lift uncovers over an opaque torso stays opaque, with no part-transparent line along the lower edge;- its outline against the air goes with it and leaves the air behind, and its outline against the figure (the crease) keeps its bytes;- `--hold-mask` leaves the arm out of the region and the band (one PNG carried, and a folder per cell), the arm keeping its bytes in every cell; without it the arm's rows the mask covers move;+ - on a synthetic figure with a piece in the arm's colour right under the part's lower edge, left out with `--hold-mask` (a folder per cell), in every cell where the part lifts, what the lift uncovers over that piece (pixels opaque in the source) stays fully opaque, and the piece keeps its bytes;- `--region-shear` 0.5 and 0.25 widen the rim to the least it asks, so the drawn move's step across the rim stays within the bound, and less than without it;- the still strip is read from the region to its side (beside the arm, the px the mask left short; over the air, 0);- the tip is read on the side over the air; a tip moved whole is 0 px off its own shape, its shift found;diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex c6a781c..c395877 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -783,7 +783,7 @@ The options (`--region-mask`, `--region-over` and `--region-shear`) work on `--lWith `--region-mask` alone, every visible pixel outside the region is held and is an anchor of the rim (the weight is 0 at held pixels and rises by `sin²(pi/2 x d)` over the rim). Where the region lies on more of the figure (a part resting on the body under it), the held pixels right under its lower edge pin that edge: the lower edge barely moves while the rest of the part does. `--region-over` lays the region over the figure under it instead. It is off by default; when it is not given, nothing of it is read or written, and strips, frames and records are byte for byte what they were.-Per cell (`layer_sets`, then `lay_over`), under the region's lower edge (per column: the rows from the first row under the region's lowest pixel in that column; for a column past the region's sides, under the lowest pixel of the region's nearest column, the leftmost on a tie; in the region's columns and `air` px past them on each side; `air` = `ceil(reach) + REGION_AIR`, the same reach as the air the region moves into), every held pixel, solid or not, is no anchor of the rim (none of the pixels `--hold-mask` leaves out). So the lower edge moves with the rest of the region. The band is those pixels (solid or not) within `air` 8-neighbour steps of the region and its soft edge. They move too, and the layer is drawn over them. The layer is the region's own pixels (the region, its soft edge, and its outline against the air, premultiplied) read at the move. Where the layer lands on a band pixel (alpha over 0), that pixel is the layer laid by its own alpha over the band pixel's own colour. Where it does not land, the band pixel keeps its bytes. The air the region moves into is drawn the same way: where the layer lands on an air pixel (a drawn alpha of 1 or more), that pixel is the layer alone; where it does not land, the air pixel keeps its bytes. So the air shows the region moved into it, never the figure beside it. Where the region lifts off the figure under it, the region's pixels (and its soft edge's) that the lift uncovers (`uncovered`: those whose own column, read as far under them as the move, reaches past the region's last row into the rows under its lower edge) show the layer laid over the figure under the region as it lies in the pixel's own column, read down as far as the move: the rows under the lower edge drawn up, never moved sideways. So the figure's side under the region stays where it is as the region lifts and moves sideways, with no notch. The band, the air and what a lift uncovers are drawn by the layer (`lay_over`); `draw_held` draws only the rest of the region and its soft edge, so its counts (`renormalised_px`, `walked_px`, `read_held_weight`) read only those. The ledger records `lifted_px`: region pixels the lift uncovers under which the figure shows half or more where the layer does not.+Per cell (`layer_sets`, then `lay_over`), under the region's lower edge (per column: the rows from the first row under the region's lowest pixel in that column; for a column past the region's sides, under the lowest pixel of the region's nearest column, the leftmost on a tie; in the region's columns and `air` px past them on each side; `air` = `ceil(reach) + REGION_AIR`, the same reach as the air the region moves into), every held pixel, solid or not, is no anchor of the rim (none of the pixels `--hold-mask` leaves out). So the lower edge moves with the rest of the region. The band is those pixels (solid or not) within `air` 8-neighbour steps of the region and its soft edge. They move too, and the layer is drawn over them. The layer is the region's own pixels (the region, its soft edge, and its outline against the air, premultiplied) read at the move. Where the layer lands on a band pixel (alpha over 0), that pixel is the layer laid by its own alpha over the band pixel's own colour. Where it does not land, the band pixel keeps its bytes. The air the region moves into is drawn the same way: where the layer lands on an air pixel (a drawn alpha of 1 or more), that pixel is the layer alone; where it does not land, the air pixel keeps its bytes. So the air shows the region moved into it, never the figure beside it. Where the region lifts off the figure under it, the region's pixels (and its soft edge's) that the lift uncovers (`uncovered`: those whose own column, read as far under them as the move, reaches past the region's last row into the rows under its lower edge) show the layer laid over the figure under the region as it lies in the pixel's own column, read down as far as the move: the rows under the lower edge drawn up, never moved sideways. The figure under the region that the lift's read draws up is the cell as cut under the region's lower edge, every pixel there that is not the region or its soft edge, a piece that `--hold-mask` leaves out (an arm) included, so where such a piece lies right under the lower edge, what the lift uncovers shows that piece drawn up, with no hole, and the piece itself keeps its bytes. The read never reaches above the figure's first row under the region's lower edge (it is clamped to that row), so the figure is drawn up from its own first row and never from the region's last row. So the figure's side under the region stays where it is as the region lifts and moves sideways, with no notch, and what the lift uncovers over an opaque figure stays opaque, with no part-transparent line along the lower edge. The band, the air and what a lift uncovers are drawn by the layer (`lay_over`); `draw_held` draws only the rest of the region and its soft edge, so its counts (`renormalised_px`, `walked_px`, `read_held_weight`) read only those. The ledger records `lifted_px`: region pixels the lift uncovers under which the figure shows half or more where the layer does not.Under `--region-over`, the region's soft edge is every pixel not opaque (alpha over 0, under 128) within `REGION_SOFT` (2) 4-neighbour steps of the region, beside another solid pixel or not, none left out; it moves with the region. (Without `--region-over`, a soft pixel beside another solid pixel outside the region is held.) Left beside the figure under it, it would stay behind as a ghost of the region's outline. Under the region's lower edge, only such a pixel that touches no solid pixel outside the region (8-neighbour) is the soft edge; one that does is the figure's own soft side, which stays where it is (it is in the band). A solid band pixel that is the region's own outline against the air (beside a pixel that is neither solid nor left out, within 2 px of the region and its soft edge, and touching no other solid pixel outside the region by 4-neighbour) goes with the layer and leaves the air behind it. An outline pixel that touches the figure under it or a pixel left out keeps its bytes as the band does.diff --git a/sprite_gen/video/sway.py b/sprite_gen/video/sway.pyindex 0bbb63e..d229d92 100644--- a/sprite_gen/video/sway.py+++ b/sprite_gen/video/sway.py@@ -2568,10 +2568,11 @@ def lay_over(cell: Image.Image, drawn: Image.Image, field: tuple[np.ndarray, np.where it does not, the band pixel keeps its bytes. Where it lands on the air (a drawn alpha of 1 or more), that pixelis the layer alone, and the air keeps its bytes where it does not: the air shows the region moved into it, never thefigure beside it. Where the region lifts off the figure under it (`uncovered`), the layer is laid over that figure read- in the pixel's own column as far under it as the move (its rows under the lower edge drawn up, never moved sideways:- the figure's side under the region stays where it is). Also the pixels of the band the layer lands on (`laid`), the- band's it covers half or more (`over`, its outline not counted) and the region's pixels under which the figure shows- half or more where its layer does not (`lifted`)."""+ in the pixel's own column as far under it as the move, never above its first row under the lower edge (the cell as cut+ under the lower edge, a piece `--hold-mask` leaves out too, drawn up, never moved sideways: the figure's side under the+ region stays where it is, and what the lift uncovers over it is as opaque as it is). Also the pixels of the band the+ layer lands on (`laid`), the band's it covers half or more (`over`, its outline not counted) and the region's pixels+ under which the figure shows half or more, by its alpha, where its layer does not (`lifted`)."""as_cut = np.asarray(cell.convert("RGBA"))src = as_cut.astype(np.float64)out = np.asarray(drawn.convert("RGBA")).astype(np.float64)@@ -2595,18 +2596,17 @@ def lay_over(cell: Image.Image, drawn: Image.Image, field: tuple[np.ndarray, np.shown = uncovered(sets, move_y)share = np.zeros((h, w))if shown.any():- under = sets["under"]ys, xs = np.nonzero(shown)- depth = ys - move_y[ys, xs].astype(np.float64)+ depth = np.maximum(ys - move_y[ys, xs].astype(np.float64), sets["floor"][xs]) # never above its first rowrow = np.clip(np.floor(depth).astype(int), 0, h - 2)fy = np.clip(depth - row, 0, 1)- figure = pm * under[..., None]+ figure = pm * (~(region | soft))[..., None] # the cell as cut under the lower edge, a piece left out toobelow = (1 - fy)[:, None] * figure[row, xs] + fy[:, None] * figure[row + 1, xs]on = read[ys, xs] + (1 - read[ys, xs, 3:4] / 255) * belowa = np.clip(on[:, 3:4], 0, 255)on[:, :3] = np.where(a > 0, on[:, :3] * 255 / np.maximum(a, 1e-3), 0)out[ys, xs] = on- share[ys, xs] = (1 - fy) * under[row, xs] + fy * under[row + 1, xs]+ share[ys, xs] = below[:, 3] / 255out = np.clip(np.round(out), 0, 255).astype(np.uint8)out[(laid | landed | shown) & (out[..., 3] == 0)] = 0 # clear, no colour: as `draw_held` writes a pixel it clearskept = (band & ~laid) | (air & ~landed)diff --git a/tests/video/test_sway_region_over.py b/tests/video/test_sway_region_over.pyindex 4db8488..fa589e0 100644--- a/tests/video/test_sway_region_over.py+++ b/tests/video/test_sway_region_over.py@@ -9,7 +9,7 @@ way rises across it the other way by at most S px a px. With either, the ledgerstrip a region drawn short of its side leaves standing, and its tip. `--region-crease` with `--region-shrink`: the wearleaves the lower edge on the crease. Synthetic figures only: the region test's body and its striped part over the torso'sright side and past it over the air, a dark crease under it on the torso; an arm block beside the part's lower left; a dark-outline under the part over the air.+outline under the part over the air; a piece of the arm's colour right under the part's lower edge.Each case first reads what a sway writes with the new keys (its cells, its record), so on a release without them thesame input fails on what comes out.@@ -60,14 +60,31 @@ def outlined_figure(k, n=N):return Image.fromarray(a, 'RGBA')-def arm_masks(path):- """The arm in every cell, a folder of one PNG per cell, held as given."""+def arm_masks(path, at=arm_at):+ """The arm (or `at`'s piece) in every cell, a folder of one PNG per cell, held as given."""path.mkdir()for k in range(N):- mask_png(path/f'cell-{k:03d}.png', arm_at(k))+ mask_png(path/f'cell-{k:03d}.png', at(k))return path+UNDER_BOX = (56, BOTTOM+1, 64, BOTTOM+10) # x0, y0, x1, y1 in cell 0, last included: right under the part's lower edge+++def under_at(k):+ """A piece of the arm's colour right under the part's lower edge in cell k, carried with the body."""+ sx, sy = body_sway(k)+ yy, xx = np.mgrid[0:H, 0:W]+ x0, y0, x1, y1 = UNDER_BOX+ return (xx >= x0+sx) & (xx <= x1+sx) & (yy >= y0+sy) & (yy <= y1+sy)+++def under_figure(k, n=N):+ a = np.asarray(part_figure(k, n)).copy()+ a[under_at(k)] = ARM+ return Image.fromarray(a, 'RGBA')++def lower_rows(region, solid, columns, rows=3):"""The region's lowest `rows` pixels in each of `columns` whose lowest one has a solid pixel under it (on the figure)."""out = np.zeros_like(region)@@ -208,7 +225,7 @@ def test_where_the_part_lifts_it_shows_the_figure_under_it(tmp_path):loop_dir = strip_dir(tmp_path/'loop', part_figure)record = sway.sway_loop(loop_dir, [PART], **kw)answer = answer_of(strip_dir(tmp_path/'again', part_figure), [PART], **kw)- moved = cells_of(loop_dir)+ source, moved = cells_of(strip_dir(tmp_path/'source', part_figure)), cells_of(loop_dir)cells = lifting(answer)assert cellsshown = 0@@ -218,6 +235,13 @@ def test_where_the_part_lifts_it_shows_the_figure_under_it(tmp_path):assert lifted.any(), ksx, sy = body_sway(k)side = np.mgrid[0:H, 0:W][1] == 86+sx # the torso's soft side+ # what the lift uncovers over an opaque figure stays opaque, the row read between the part's last row and the+ # figure's first too: the figure is drawn up from its first row under the lower edge, never from the part's+ floor = read['floor']+ under_opaque = source[k][np.minimum(floor, H-1), np.arange(W), 3] == 255+ opaque = sway.uncovered(read, read['field'][2]) & under_opaque[None, :] & (source[k][..., 3] == 255)+ assert opaque.any(), k+ assert (moved[k][opaque][:, 3] == 255).all(), (k, sorted(set(moved[k][opaque][:, 3].tolist())))# the torso and the crease read up into the part's lower rows, each in its own column: no hole (the torso's soft# side shows as soft as it is), the torso's and the crease's red, none of the stripes' (200 or more)assert (moved[k][lifted & ~side][:, 3] >= 128).all(), k@@ -231,6 +255,27 @@ def test_where_the_part_lifts_it_shows_the_figure_under_it(tmp_path):assert shown > 0 and record['region_mask']['ledger']['lifted_px_max'] > 0+def test_where_the_part_lifts_off_a_piece_left_out_it_shows_that_piece(tmp_path):+ mask = mask_png(tmp_path/'mask.png', part_at(0))+ kw = dict(region_mask=mask, region_shrink=0, region_over=True, hold_mask=arm_masks(tmp_path/'piece', under_at))+ loop_dir = strip_dir(tmp_path/'loop', under_figure)+ sway.sway_loop(loop_dir, [PART], **kw)+ answer = answer_of(strip_dir(tmp_path/'again', under_figure), [PART], **kw)+ source, moved = cells_of(strip_dir(tmp_path/'source', under_figure)), cells_of(loop_dir)+ cells = lifting(answer)+ assert cells+ for k in cells:+ _, read = answer.masked_cell(k)+ piece = under_at(k)+ # the piece left out under the lower edge is the figure under it there: what the lift uncovers over it stays+ # opaque, the piece drawn up, and the piece keeps its bytes+ over_piece = piece[np.minimum(read['floor'], H-1), np.arange(W)]+ opaque = sway.uncovered(read, read['field'][2]) & over_piece[None, :] & (source[k][..., 3] == 255)+ assert opaque.any(), k+ assert (moved[k][opaque][:, 3] == 255).all(), (k, sorted(set(moved[k][opaque][:, 3].tolist())))+ assert np.array_equal(moved[k][piece], source[k][piece]), k++def test_its_outline_against_the_air_goes_with_it_and_against_the_figure_stays(tmp_path):mask = mask_png(tmp_path/'mask.png', part_at(0))kw = dict(region_mask=mask, region_shrink=0, region_over=True, hold_mask=arm_masks(tmp_path/'arm'))