Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

release: 2.41.0 candidate — regions read on the cut follow the aligned loop; an opt-in stretch floor; bend and seam readouts

Soohong Kim7570840a26fa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aff5ece..05bd2a1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## v2.41.0 - Regions read on the cut follow the loop aligned from it, cell for cell; a floor on the stretch, by direction and never above the fold rule; the bend and the seam written down
+
+- **New `video-follow --read-on <sha256>`: the strip the regions were read on, and the reading carried from it.** The regions of a follow-through are where somebody looked, in the first cell of the strip they were read on. `video-cycle-align` turns a loop to start on a foot strike, so its first cell is another, and `video-follow` given the same regions read the motion again from that cell 0: the regions landed on another place of the body, and a stretched loop moved them by a motion read anew. `--read-on` names the strip they were read on by its file's sha256 (as cut, before any follow-through). This loop's own strip as cut is `same`: the follow-through is the one without the flag, byte for byte. The cut this loop was aligned from is `transported`: each cell is carried by the cut's reading of the cut's cell it is, the regions stay on the cut's cell 0, and the damped mass is solved on the loop's own order, length and frame time — a turned loop gives the cut's follow-through cell for cell, a loop stretched by the nearer frame the new cycle's offsets on the cut's motion. A cell made between two frames of the cut, or one that is not the cut's cell pixel for pixel (a crop or a scale changed and nothing records how, or a cell drawn again), is refused `uncertain`: a made cell has no reading of its own, and none is taken from the nearer frame by rounding. Any other strip is refused `no-match`. Without `--read-on` nothing of this is read or written and the record holds no new key; with it the record carries `read_on` (`sha256`, `relation`, and for `transported` its `policy` and `cut_cells`). `video-follow-inspect` takes it too. [docs/video-pipeline.md](docs/video-pipeline.md#regions-read-on-the-cut-followed-on-the-aligned-loop----read-on).
+- **Output change: `video-cycle-align` records the cut it aligns from and where every cell is from.** `cycle_align.cells_from` holds, per cell of the rebuilt strip, `{"source": i}` (frame i of `cycle.source/`, as many times as it is taken) or `{"between": [i, j], "t": t}` (a frame made between two); the report's loop rows carry it too. The first alignment of a loop also records the strip as cut, read before anything is rewritten (`cycle_align.origin`: its file's sha256 — `follow.source.png`'s where a follow-through had moved it —, cell size, scale, crop origin, `sample_indices`, each cell's pixels by sha256, and the body's motion as `video-follow` reads it there), and every later alignment keeps it as it is. The strip, cycle frames, GIF and WebP are unchanged; the aligned meta gains these two keys. A loop aligned before this release has no origin and gets none: its cut is no longer there to read. [docs/loop-repair.md](docs/loop-repair.md).
+- **New `video-follow --stretch-floor D`: a least area every moved pixel keeps, read by the way the region moves.** The fold rule keeps a region from folding and so lets its steepest pixel take nearly nothing of the source. A move (ox, oy) of a cos² region leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of a pixel's area; each region takes the largest gain, in steps of 0.01, that keeps D in every cell, and never one above the fold rule's — where the direction would allow more (a region moving along its long axis) the fold rule's gain stands, so the floor only lowers. Under it the fold rule's handling stands: a region taken under 1 is held and named, every region held is refused, and `--on-fold refuse` refuses a move under the floor. It is opt-in with no default value: without it the fold rule alone decides, byte for byte, and a floor the move already keeps draws the same strip, GIF and WebP. The record carries `stretch` (`policy`, `floor`, per region `per_gain`, `least_cell`, `rule_gain`, `floor_gain`, `gain`, `held`, `least_area`, `under_measured`), and stderr names what lowered a region, the fold or the floor. On an aligned loop, with `--read-on`, the floor is read on the cut's motion, so a turned loop is lowered, held or refused as the cut is. [docs/video-pipeline.md](docs/video-pipeline.md#a-least-area-each-move-leaves----stretch-floor-d).
+- **Output change: `video-follow-inspect` writes schema 2 — the bend and the seams beside the least area.** A move stretches the picture (`jacobian_min`, D), tilts a line by its steepest slope, |offset|·π/(2·smaller radius) (`bend`, G, with `bend_deg` = atan G; the same number as `fold_ratio`, named for what it does — at 1 a line tilts 45°), and where two regions overlap bends it where the larger move changes hands. `cells[k].seams` and the record's `seams` give, per pair of moving regions that meet, the largest jump of the move's gradient on that curve and its angle (`jump`, `deg`, the point `at`, the `cell`); a held region has none. `regions[i]` adds the largest `bend` and `bend_deg`. `inputs.settings` adds `read_on` and `stretch_floor`, `inputs.policy` the names of the ways a reading is carried and a floor kept, both in `input_id`; and `carry_basis` says what carries a region (`outline-lay`) and that whose pixels it holds is `unverified`. `video-follow`'s own record changes only where a new flag is given, and then also carries `carry_basis`. [docs/video-pipeline.md](docs/video-pipeline.md#inspecting-a-follow-through--video-follow-inspect).
+- **`tests/video/test_follow_read_on.py` and `tests/video/test_follow_stretch_floor.py`** use synthetic strips. A runner turned by `video-cycle-align` and followed with `--read-on` is the cut's follow-through cell for cell, and the same turned loop followed as before moves other pixels; a loop stretched by the nearer frame is carried cell for cell, duplicates and all; made cells, a crop that narrowed when a frame was dropped and a cell drawn again are refused `uncertain` with the loop left as it was; another clip and an unknown or malformed `read_on` are refused; a floor on a turned loop decides as on the cut. Every cell keeps the floor; where the fold rule is stricter its gain stands, where the floor is it lowers; a floor already kept draws the same bytes, and a floor of 0 is the fold rule, not the direction alone. A lowered round region bends a line just under 45°; two overlapping regions record a seam at the point where their weights are equal, its jump the norm of the gradients' difference there. Two strips alike in alpha whose chest patch moves differently are carried alike and say the region is unverified, and an arm added to the outline carries nothing.
+
## v2.40.0 - A restored cell that brings back the jump the repair took out is not an improvement
- **Output change: source restoration's comparison reads the jump around the restored cell (`axes.jump`).** A cell the restoration rebuilds is one the jump repair replaced, because a step into or out of its source frame jumped. The source frame's pixels clear the in-between's melt and can bring that jump back, and the comparison read only the melt. `video-loop-compare` (and the preview in `video-loop-repair`) now scores the final cells of both loops with the jump repair's own step score (`repair.jump_scores`: per step, the change of coverage over the whole body and over the hair behind it, each over its median in the loop, the larger of the two), on the source cells' union box and with the `facing` the loop report's `jump_repair` recorded. A changed cell reads the larger score of the step into it and the step out of it; more than the baseline's is `regressed`, reason `jump:regressed`, as on every other axis. No bound is read (`JUMP_RATIO` included) and no constant is added: the baseline is the measure. A cell the jump repair made is now restored only where its in-between jumped more than the source frame does, as when it lost coverage; where the in-between was the smoother step and only its drawing melted, the delivered in-between stays. The guard reads coverage, not colour. `axes.jump` carries both loops' step scores and their whole-body and hair parts, the facing, the hair box, the box and, per changed cell, its two steps and both readings. A loop report whose jump repair names replaced cells but no facing (`right` or `left`) is shared `unknown`, `jump-repair-facing-unverified`; a loop whose repair replaced nothing needs none and stays a no-op. [docs/loop-comparison.md](docs/loop-comparison.md#the-jump-guard).
diff --git a/SKILL.md b/SKILL.md
index 88bd274..4c3de07 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
---
name: sprite-gen
-version: 2.40.0
+version: 2.41.0
description: "Generates images and game sprites through GPT or Grok with guided provider choices, separate saved defaults, automatic cleanup and optional curation. Handles sprite requests, ordinary image generation/editing, standalone image-to-video clips (i2v, animate this still, 그록 영상, 이매진 비디오, 스틸 움직여줘, first/last frame, reference-to-video, 영상 이어붙이기, 영상 편집, extend/edit a clip), clips from a video MCP on the agent (ZCRE, 지크 MCP), chroma removal, animation atlases, video loops, 큐레이션뷰, image candidates, 팔레트 스왑, palette swap, recolor, rig layers, engine exports, repeating backgrounds, projected shadows, motion/contact inspection and optional scene composition from existing assets."
license: Apache-2.0
depends_on:
diff --git a/pyproject.toml b/pyproject.toml
index d778050..febff0c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
name = "sprite-gen"
# Release discipline: keep this package metadata version synchronized with
# SKILL.md's `version:` field in the same release commit.
-version = "2.40.0"
+version = "2.41.0"
description = "Component-row pipeline for clean 2D game sprites and animation atlases"
readme = "README.md"
license = "Apache-2.0"