Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(video-loop): the side a refused frame is made again on in loop-repair section 7, pinned runs of the binary in release.md, and the CHANGELOG's Unreleased (v3.10.1) on 3.10.0
Soohong Kim33cff1a2c504
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 807d90c..3b685a0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,12 +4,12 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased (v3.10.1)-**Upgrading from 3.9.0: A cut with no held cell is unchanged (six synthetic cuts pinned to their decoded pictures still match). A cut whose frames between are real new pictures is unchanged (the synthetic stalled walk filled by a true in-between gives the same cells, 27/27). `--fill-held off` is unchanged. A run that 3.8.0 and 3.9.0 reported as filled although its frame between repeated a picture beside it is now made at another fraction where one passes, or kept as filmed with a warning; its `faults` in `held_fill.before.held_runs` list `held`. At `--out-fps`, such cells are now listed in `out_fps.shown_again` with a warning instead of being counted as made.**+**Upgrading from 3.10.0: Every cut with no held cell, every cut whose frames between are real new pictures, and every `--fill-held off` run give the same cells as 3.10.0.** A run that 3.8.0 to 3.10.0 reported as filled although its frame between repeated a picture beside it is now made at another fraction where one passes, or kept as filmed with a warning. Its `faults` in `held_fill.before.held_runs` list `held`. At `--out-fps` and in an air retimed with `--air-retime`, such cells are now listed in `out_fps.shown_again` or `air_retime.shown_again` with a warning instead of being counted as made. On twelve tests of the suite that run the binary, 3.10.0 runs the binary 146 times and 3.10.1 runs it 188 times because 3.10.0 took frames between that showed a picture beside them again, while 3.10.1 refuses them and makes them again at other fractions. So a cut whose frames between show a picture beside them again asks the binary for more runs, and takes longer, than in 3.10.0.-- **Fix: A frame made that shows the same picture as a frame beside it or the cell delivered before it is no longer accepted.** In 3.8.0 and 3.9.0, an interpolator returning one of the two frames it was handed (or the same picture for two different times) made no frame between at all, but the run was recorded `filled: true`, its cells listed in `made`, with no retry and no warning, while poses over cells remained unchanged (for example 24/27 before and after). At `--out-fps`, such cells were counted as made and omitted from `out_fps.shown_again`. A frame made must now read as a distinct picture from both frames beside it and from the cell delivered before it; otherwise it receives the fault `held` and is refused. Refused frames are retried at the nearest other fractions of `RETIME_T` within half a cell. If none passes, the run is kept as filmed with a `warning:` line naming its cells and faults. At `--out-fps`, a cell refused this way is the nearer frame, listed in `out_fps.shown_again` and named in a `warning:` line.-- Python callers: New function `held_fill.same_picture` (`held_fill.same_picture(frame, others)`); `held_fill.judge(..., before=)` takes `before=` (the cell delivered before the frame).-- **Docs**: [loop-repair.md](docs/loop-repair.md) section 7: the rule and its measurements, the `--out-fps` cells; [video-pipeline.md](docs/video-pipeline.md); `SKILL.md`.-- **Tests**: `tests/video/test_held_fill.py` (stalled walk with held runs of two cells at cell 5 and three cells at cell 14 kept as filmed when an interpolator gives back the frame before or after, 24/27 poses/cells, each run's first cell tried at its own time and at every other fraction within half a cell, pictures delivered equal to `--fill-held off`, and warnings naming cells 5-6 and 14-16; an interpolator always drawing the half way time makes the run of two and keeps the run of three as filmed; `--out-fps` 60 from 24 with an interpolator returning the frame before lists all eight cells between in `out_fps.shown_again`, while drawing the half way time makes the cell at 0.4 and lists the cell at 0.8 as the nearer frame; synthetic fall sinking less than a pixel in half a frame refused as `held` at 0.5, 0.45, 0.55 and 0.4, then made at 0.6 where the body has moved; mutation check: eight tests fail with the new reading switched off, two fail without the comparison to the cell before, and two fail without the comparison to the frame after).+- **Fix: A frame made that shows the same picture as a frame beside it is refused as `held`, made again only on the side away from that picture, or its run kept as filmed.** In 3.8.0 to 3.10.0, an interpolator that gave back one of the two frames it was handed, or the same picture for two different times, made no frame between at all. The run was recorded `filled: true`, its cells listed in `made`, with no retry and no warning, while poses over cells remained unchanged. A frame made must not read as the same picture as either frame it is made between, nor as the cell delivered just before it; otherwise it receives the fault `held` and is refused. A refused frame is made again at the nearest other fractions of `RETIME_T` within half a cell, but only on the side away from the picture it showed: later where it showed the frame before or the cell before it, earlier where it showed the frame after, and not again where it showed both. Because frames between run from one pose to the next, a fraction nearer a picture it showed shows that picture too. If none passes, the run is kept as filmed with a `warning:` line naming its cells. At `--out-fps` and in an air retimed with `--air-retime`, a cell refused this way is the nearer frame, listed in `shown_again` and named in a `warning:` line. On the synthetic cuts of eight tests that reach the binary through the default fill, 3.10.0 took all 44 frames between it asked for, and 19 showed a picture beside them again. Version 3.10.1 makes 26 cells. Poses over cells are 324/383 as filmed, 341/383 in 3.10.0, and 348/383 in 3.10.1. Runs of the binary on them are 90 in 3.10.0, 124 in 3.10.1, and 214 in a first version that retried a refused frame at every fraction within half a cell on both sides. On a Linux runner with a CPU Vulkan driver, that first version made each of those eight tests run longer than its 120 s limit, so each of them timed out and failed.+- Python callers: New function `held_fill.same_picture(frame, others)`. `held_fill.judge(..., before=)` takes the cell delivered before the frame, and its reading names `shows` (which of `a`, `b` and `before` the frame shows again). Each try the loop report records (`tries`) names `shows` where it showed one.+- **Docs**: [loop-repair.md](docs/loop-repair.md) section 7 documents the rule, the side a refused frame is made again on, their measurements, and the `--out-fps` cells. [video-pipeline.md](docs/video-pipeline.md) and `SKILL.md` are updated. [release.md](docs/release.md) notes that a test that reaches the binary through a cut's default fill and runs it often enough to pass the default 120 s limit on a CPU's Vulkan driver carries the 900 s limit and pins its runs of RIFE with `rife_runs`.+- **Tests**: `tests/video/test_held_fill.py` (stalled walk with runs of two and three held cells kept as filmed when returning the frame before or after, 24/27 poses/cells, nine frames asked for, pictures matching `--fill-held off`, warnings naming cells 5-6 and 14-16; frame showing both poses refused with no retry; interpolator drawing the half way time making the run of two and trying the second cell of the run of three only later at 0.6667 to 0.8; `--out-fps` 60 from 24 with eight cells listed in `out_fps.shown_again`; synthetic fall refused as `held` at 0.5 and 0.55 and made at 0.6 in changed test `test_a_once_cut_and_a_one_shot_have_their_held_cells_made_too`); `tests/video/test_root_motion.py` (synthetic jump air retimed twice as long with ten cells listed in `air_retime.shown_again` and named in a warning, each tried at 0.5 and then only later). Twelve tests that run the RIFE binary on a synthetic cut (the eight that timed out in the first version: three rows of `tests/video/test_explicit_window.py`, two tests of `tests/video/test_gait_fallback.py`, `tests/video/test_ghost_given_way.py`, one test of `tests/video/test_one_step_cut.py`, `tests/video/test_play.py`; and four more: the step screen test of `tests/video/test_one_step_cut.py`, the checkpoints test of `tests/video/test_wrap_blend.py`, a test of `tests/video/test_once.py`, and a test of `tests/video/test_ghost_screen.py` marked `real_rife` that hands frames to `rife.Rife` itself; the other eleven reach the binary through a cut's default fill) carry `@pytest.mark.timeout(900)` with a comment naming their calls of the binary, and each pins its runs of RIFE (between 6 and 36): eleven through `rife_runs` in `tests/conftest.py` (0 where `rife_located()` finds no binary), the `tests/video/test_ghost_screen.py` test through `Rife.calls`. With no binary found, every count is 0 and the two tests marked `real_rife` skip. On the first version, nine of the twelve fail on the count, with run counts of 18 to 38: the eight, and the checkpoints test of `tests/video/test_wrap_blend.py` (20 against 16). The other three ask for the same runs in both versions. Red first for two test files, `tests/video/test_held_fill.py` and `tests/video/test_root_motion.py`: 10 failed and 46 passed on 3.10.0; 56 passed on 3.10.1. Mutation check over those two files: with the new reading switched off, ten tests fail; without comparison to the cell before, two; without comparison to the frame after, three; without "only later" after the frame before or cell before, eight; without "only earlier" after the frame after, three; with the cell before not counted for the side, two.## v3.10.0 - Root motion on single-play cuts, their air retimed on a given gravity, length and speed (--air-retime), and a caller-named single play (--cycle once --start --length)diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex ba792b3..0551223 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -2788,8 +2788,8 @@ plays the clip's filmed frames, none made between two others, and names a run it| Kept: a loop's last cells | A run that ends on a loop's last cell | Its next pose is across the wrap: made, the last cell would change and with it the wrap. A run that opens a loop is made (its first cell stays). A periodic cut chooses its wrap where the steps either side read alike, so a held run seldom closes it; a fixed cut whose last cells are held keeps them, and its wrap then steps from a held picture (cut it elsewhere, or `--fill-held off` to keep the whole cut as filmed). || A frame made, judged | `align.measure_made` and `interpolation_quality.faults` (smear, outline, ghost, hole, doubled), the alignment's own | One acceptance policy for every frame RIFE makes (section 4). || A part standing still, kept still (`still_kept`) | The outline pixels both frames draw in one place in one colour (solid at alpha 128, within 24 levels) must be drawn there in the frame made, within a pixel, for at least `STILL_KEPT_MIN` 0.8 of them in every window a tenth of the body high that holds 12 or more; else the fault `contact` | A foot planted or a hand on a ledge stays where it stood. A synthetic in-between that drags a planted foot 3 px along the floor keeps 0.50 of its window; one off by a pixel, 1.00. |-| A picture of its own (`same_picture`) | The frame made must not read as the same picture (the reading above) as either frame it is made between or as the cell delivered before it (in a run of three, or at `--out-fps`, that can be a frame made too); else the fault `held` | An interpolator that gives back a frame it was handed, or one picture at two times, makes no frame between. Taken, the cell would be counted as made and still show the picture beside it. On a synthetic stalled walk (runs of two and three cells) whose interpolator gives back the frame before, both runs are kept as filmed (24/27 poses/cells), each first cell tried at its own time and at every other fraction within half a cell, and `warning:` lines name cells 5-6 and 14-16. A synthetic fall that sinks less than a pixel in half a frame shows the frame before it again at 0.4, 0.45, 0.5 and 0.55, and is made at 0.6. |-| A frame refused | Made again at the fraction of `RETIME_T` nearest its own within half a cell of it, its ghost band under `RETIME_WINDOW_MAX` (section 4's bar for a frame made off its time); else the run is kept as filmed, with a warning naming the cells and the faults | A frame half way that RIFE cannot draw is often clean nearer one side. |+| A picture of its own (`same_picture`) | The frame made must not read as the same picture (the reading above) as either frame it is made between or as the cell delivered before it (in a run of three, at `--out-fps` or in an air retimed with `--air-retime`, that can be a frame made too); else the fault `held` | An interpolator that gives back a frame it was handed, or one picture at two times, makes no frame between. Taken, the cell would be counted as made and still show the picture beside it. On a synthetic stalled walk (runs of two and three cells) whose interpolator gives back the frame before, both runs are kept as filmed (24/27 poses/cells). Each first cell is tried at its own time and then only later within half a cell (0.5 to 0.7, and 0.3333 to 0.45). `warning:` lines name cells 5-6 and 14-16. A synthetic fall that sinks less than a pixel in half a frame shows the frame before it again at 0.5 and 0.55, and is made at 0.6. |+| A frame refused | Made again at the fraction of `RETIME_T` nearest its own within half a cell of it, its ghost band under `RETIME_WINDOW_MAX` (section 4's bar for a frame made off its time). One refused as `held` is made again only on the side away from the picture it showed (later where it showed the frame before or the cell before it, earlier where it showed the frame after), and not again where it showed both. Else the run is kept as filmed, with a warning naming the cells and the faults | A frame half way that RIFE cannot draw is often clean nearer one side. The frames between run from one pose to the next, so a fraction nearer a picture a frame showed again shows it too. On the cuts of eight tests that reach the binary through the default fill, trying every fraction within half a cell ran the binary 214 times. The side rule runs it 124 times and makes the same cells (3.10.0, which took such frames, ran it 90 times). || Whole or not at all | A run is made whole or kept whole | Half made, it would step back to the held picture and on again. || Order | After the anchor and `source_projection`, before the ghost screen, the wrap blend, the part pop and the jump repair | Everything that reads the flow and the wrap reads the cut as it will play. || No RIFE | The held cells are delivered as filmed, the cut passes, and a `warning:` line names the motion, the cells and `sprite-gen rife install`; `held_fill.unmade` records them | Never a failure, never silent. |diff --git a/docs/release.md b/docs/release.mdindex c60adbf..99c1be2 100644--- a/docs/release.md+++ b/docs/release.md@@ -32,6 +32,8 @@ RIFE 가 닿는 곳이 하나도 없는 상태로 스위트 전체를 돌려 그시험(`pytest --full -m "real_rife and not torch_rife"`, 아래 torch 단계가 나머지)을 돌린다 — 하나라도 건너뛰거나, 표시된 시험이 없으면 실패다. 그래서 새실제-RIFE 시험은 표시만 붙이면 `--rife-only` 가 저절로 걷는다.+컷의 기본 채움(`--fill-held auto`)으로 바이너리에 닿고 CPU 의 Vulkan 드라이버에서 기본 120 s 제한을 넘길 만큼 자주 실행하는 시험은 `real_rife` 표시 여부와 관계없이 긴 바이너리 시험처럼 `@pytest.mark.timeout(900)` 과 바이너리 호출 수 주석을 달고 `tests/conftest.py` 의 `rife_runs` 로 요청하는 RIFE 실행 수를 고정한다(`rife_located()` 가 바이너리를 못 찾으면 0). 바이너리를 몇 번만 실행하고 기본 제한 안에서 여유 있게 끝나는 시험은 둘 다 두지 않는다. CPU 의 Vulkan 드라이버에서는 실행 하나에 몇 초씩 걸리므로, 실행을 더 요구하는 변경이 시간 초과가 아니라 호출 수에서 걸린다.+RIFE 의 torch 백엔드(`SPRITE_GEN_RIFE_BACKEND=torch`, docs/loop-repair.md 1절)를 돌리는 시험은`torch_rife` 표시를 단다(`pyproject.toml` 이 등록한다). `tests/conftest.py` 는 PyTorch 가 import 되지않거나, `rife.locate_model()` 이 모델을 못 찾거나, `SPRITE_GEN_RIFE_DEVICE` 가 이름 댄 장치가