Skip to content

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

fix: encode opaque GIF previews without transparent disposal

Soohong Kima7a71227cd5d
diff --git a/sprite_gen/util/gif_utils.py b/sprite_gen/util/gif_utils.py
index 0725b99..b937bc4 100644
--- a/sprite_gen/util/gif_utils.py
+++ b/sprite_gen/util/gif_utils.py
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: Apache-2.0
"""Shared GIF helpers for sprite-gen.
-GIF previews must not leak the previous frame through transparent pixels. Use a
-fresh transparent palette index per frame and GIF disposal method 2, so each
-frame clears before the next one is drawn.
+Transparent previews clear each frame with GIF disposal method 2. Opaque
+previews retain their canvas with disposal method 1 and no transparency.
"""
from __future__ import annotations
@@ -51,14 +50,25 @@ def save_clean_gif(
duration_ms: int,
loop: int | None = 0,
alpha_threshold: int = 8,
+ opaque: bool = False,
) -> None:
- """Save RGBA frames as a clean transparent GIF.
+ """Save frames as a transparent GIF, or an explicitly opaque preview.
`loop=0` means infinite loop in GIF/Pillow terminology.
+ `opaque=True` expects frames already composited onto their preview background.
"""
if duration_ms <= 0:
raise ValueError("duration_ms must be positive")
- prepared = [_prepare_transparent_frame(frame, alpha_threshold) for frame in frames]
+ if opaque:
+ prepared = [frame.convert("RGB").convert("P", palette=Image.ADAPTIVE) for frame in frames]
+ for frame in prepared:
+ frame.info.pop("transparency", None)
+ # Restore-to-background depends on palette indices that can change per
+ # frame. Keep the opaque canvas and encode every changed pixel instead.
+ options = {"disposal": 1, "optimize": False}
+ else:
+ prepared = [_prepare_transparent_frame(frame, alpha_threshold) for frame in frames]
+ options = {"disposal": 2, "transparency": 255}
if not prepared:
raise ValueError("at least one frame is required")
output_path.parent.mkdir(parents=True, exist_ok=True)
@@ -68,8 +78,7 @@ def save_clean_gif(
append_images=prepared[1:],
duration=duration_ms,
**({"loop": loop} if loop is not None else {}),
- disposal=2,
- transparency=255,
+ **options,
)
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index eae882c..3003cbf 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -1610,7 +1610,8 @@ def run_loop(
# background instead of turning its faint partial-alpha glow into opaque dark pixels.
gif_background = "#000000" if cycle["kind"] == "lifetime" else None
gif_pick = [effect.on_black(im) for im in pick] if gif_background is not None else pick
- save_clean_gif(gif_pick, gif_path, duration_ms=delay_ms, loop=None if single_play else 0, alpha_threshold=128)
+ save_clean_gif(gif_pick, gif_path, duration_ms=delay_ms, loop=None if single_play else 0,
+ alpha_threshold=128, opaque=gif_background is not None)
write_webp(pick, webp_path, delay_ms=delay_ms, workdir=out_dir / ".webp-frames", **({"loop": 1} if single_play else {}))
shutil.rmtree(out_dir / ".webp-frames", ignore_errors=True)
# A filmed ghost given way to the frame beside it is that frame shown twice in a row: one frame of the GIF or WebP
diff --git a/tests/util/test_gif_utils.py b/tests/util/test_gif_utils.py
index 731de24..3e10121 100644
--- a/tests/util/test_gif_utils.py
+++ b/tests/util/test_gif_utils.py
@@ -18,7 +18,10 @@ def test_opaque_sequence_keeps_black_canvas_and_empty_endpoint(tmp_path, loop, s
(12 - radius, 12 - radius, 12 + radius, 12 + radius))
frames.append(frame)
path = tmp_path / "opaque.gif"
- save_clean_gif(frames, path, duration_ms=60, loop=loop)
+ sources = [frame.convert("RGB") for frame in frames]
+ for frame in sources:
+ frame.info["transparency"] = (0, 0, 0)
+ save_clean_gif(sources, path, duration_ms=60, loop=loop, opaque=True)
data = path.read_bytes()
assert data.count(b"GIF89a") + data.count(b"GIF87a") == 1