Simplify to one generate->playable flow: Citrus theme, parallel H3 calls, un-mixing despill, 3s default

app.py

@@ -3,11 +3,13 @@
 An implementation of the workflow Victor Mustar described: design one character on a flat magenta backdrop, generate
 one short H3 clip per move, cut each clip down to its pose extremes, key out the magenta, and pack the result.
 
-Two things are specific to doing it here rather than by hand:
+Three things are specific to doing it here rather than by hand:
 
-* **Every clip loops.** Each move is generated with the character still passed as *both* the first and the last
-  keyframe, so H3's `fl2va` branch has to leave the rest pose and arrive back at it. A sprite that does not return
-  to its start pose visibly pops every time the animation repeats.
+* **Every clip loops.** Each move is generated with the character passed as *both* the first and the last keyframe,
+  so H3's `fl2va` branch has to leave the rest pose and arrive back at it. A sprite that does not return to its start
+  pose visibly pops every time the animation repeats.
+* **The moves are generated concurrently.** They are independent conditioning-identical requests, so the wall clock
+  is one clip rather than the sum of them.
 * **This Space owns no GPU.** It runs on `cpu-basic` and calls other Spaces for both models. See `backends.py`.
 """
 
@@ -17,6 +19,7 @@ import os
 import tempfile
 import time
 import traceback
+from concurrent.futures import ThreadPoolExecutor
 
 import gradio as gr
 
@@ -29,6 +32,23 @@ OUTPUT_DIR = os.path.join(tempfile.gettempdir(), "sprite-forge")
 os.makedirs(OUTPUT_DIR, exist_ok=True)
 
 DEFAULT_SUBJECT = "a scrappy alley cat in a bomber jacket"
+EXAMPLES = [
+    "a scrappy alley cat in a bomber jacket",
+    "a round little wizard with an oversized pointed hat",
+    "a rusty barrel-chested robot with one glowing eye",
+    "a punk frog in a leather vest",
+    "a knight in dented armor holding a short sword",
+]
+
+PENDING = (
+    "<div style='display:flex;align-items:center;justify-content:center;height:560px;opacity:.55;"
+    "border:1px dashed var(--border-color-primary);border-radius:8px'>Building your character…</div>"
+)
+IDLE_PANEL = (
+    "<div style='display:flex;align-items:center;justify-content:center;height:560px;opacity:.55;"
+    "border:1px dashed var(--border-color-primary);border-radius:8px'>"
+    "Your playable character will appear here.</div>"
+)
 
 
 def _out(name: str) -> str:
@@ -36,109 +56,91 @@ def _out(name: str) -> str:
 
 
 # ---------------------------------------------------------------------------
-# step 1 — the character design still
+# the one flow
 # ---------------------------------------------------------------------------
 
 
-def design_character(subject, style, backend_label, canvas_label, seed, request: gr.Request):
-    if not (subject or "").strip():
-        raise gr.Error("Describe a character first.")
-
-    backend = backends.BY_LABEL[backend_label]
-    _, width, height = backends.CANVASES[canvas_label]
-    prompt = move_defs.character_prompt(subject, style)
-
-    try:
-        path = backend.generate(prompt, width, height, int(seed), backends.ip_token_of(request))
-    except Exception as error:
-        traceback.print_exc()
-        raise gr.Error(f"{backend.space} failed: {type(error).__name__}: {error}") from error
-
-    return path, gr.update(value=f"Designed with `{backend.space}`. Regenerate until the pose reads clearly — "
-                                 f"every move starts and ends here.")
-
-
-# ---------------------------------------------------------------------------
-# step 2 — one clip per move
-# ---------------------------------------------------------------------------
-
-
-def animate_moves(subject, character, selected, canvas_label, duration, steps, seed, clips, request: gr.Request):
-    """Generate the selected moves one at a time, streaming each clip back as it lands.
-
-    Sequential rather than parallel on purpose: every call books a ZeroGPU slot on the visitor's own quota, and
-    firing five at once mostly earns five places in the same queue.
+def forge(
+    subject,
+    uploaded,
+    style,
+    backend_label,
+    canvas_label,
+    selected,
+    duration,
+    steps,
+    seed,
+    tolerance,
+    softness,
+    despill,
+    despeckle,
+    playback_fps,
+    sprite_height,
+    request: gr.Request,
+):
+    """Character -> one clip per move -> keyed extremes -> packed sheet -> playable demo, as one generator.
+
+    Yields on every step so the demo panel holds Gradio's pending state from the moment the button is pressed rather
+    than only lighting up at the end of a multi-minute run.
     """
-    if not character:
-        raise gr.Error("Design or upload a character first.")
+    if not uploaded and not (subject or "").strip():
+        raise gr.Error("Describe a character, or upload one.")
     if not selected:
-        raise gr.Error("Pick at least one move.")
+        raise gr.Error("Pick at least one move under Advanced.")
 
     ip_token = backends.ip_token_of(request)
-    clips = list(clips or [])
-    existing = {clip["label"] for clip in clips}
-    todo = [move_defs.BY_LABEL[label] for label in selected if label not in existing]
-    skipped = len(selected) - len(todo)
-
-    if not todo:
-        yield clips, _clip_gallery(clips), "Every selected move is already generated. Clear them to redo."
-        return
-
-    log = []
-    if skipped:
-        log.append(f"Skipped {skipped} already-generated move(s).")
-
-    for i, preset in enumerate(todo, 1):
-        note = f"Generating **{preset.label}** ({i}/{len(todo)}) — about a minute per move."
-        yield clips, _clip_gallery(clips), "\n\n".join(log + [note])
+    presets = [move_defs.BY_LABEL[label] for label in selected]
+
+    # ---- 1. the character design still ----
+    if uploaded:
+        character = uploaded
+        yield PENDING, character, [], None, [], None, "Using your uploaded character."
+    else:
+        yield PENDING, None, [], None, [], None, "Designing the character…"
+        backend = backends.BY_LABEL[backend_label]
+        _, width, height = backends.CANVASES[canvas_label]
         try:
-            video, report = backends.animate(
-                prompt=preset.prompt(subject),
-                image_path=character,
-                canvas_label=canvas_label,
-                duration=float(duration),
-                steps=int(steps),
-                # Vary the seed per move so two moves never collapse onto the same motion.
-                seed=int(seed) + i,
-                ip_token=ip_token,
+            character = backend.generate(
+                move_defs.character_prompt(subject, style), width, height, int(seed), ip_token
             )
         except Exception as error:
             traceback.print_exc()
-            log.append(f"**{preset.label}** failed: `{type(error).__name__}: {error}`")
-            yield clips, _clip_gallery(clips), "\n\n".join(log)
-            continue
-
-        clips.append({"key": preset.key, "label": preset.label, "video": video, "frames": preset.frames})
-        log.append(f"**{preset.label}** — {report}")
-        yield clips, _clip_gallery(clips), "\n\n".join(log)
-
-    yield clips, _clip_gallery(clips), "\n\n".join(log + ["Done. Build the sheet below."])
-
-
-def _clip_gallery(clips):
-    return [(clip["video"], clip["label"]) for clip in clips]
-
-
-def clear_clips():
-    return [], [], "Cleared."
-
-
-# ---------------------------------------------------------------------------
-# step 3 — key, cut to extremes, pack
-# ---------------------------------------------------------------------------
+            raise gr.Error(f"{backend.space} failed: {type(error).__name__}: {error}") from error
+        yield PENDING, character, [], None, [], None, f"Character designed. Animating {len(presets)} moves…"
+
+    # ---- 2. one clip per move, concurrently ----
+    # These requests are fully independent, so they are fired together: the wall clock becomes the slowest single
+    # clip instead of the sum. Each gets its own seed so two moves never collapse onto the same motion.
+    def one(index_preset):
+        index, preset = index_preset
+        return preset, backends.animate(
+            prompt=preset.prompt(subject if not uploaded else "the character"),
+            image_path=character,
+            canvas_label=canvas_label,
+            duration=float(duration),
+            steps=int(steps),
+            seed=int(seed) + index + 1,
+            ip_token=ip_token,
+        )
 
+    clips, failures = [], []
+    with ThreadPoolExecutor(max_workers=max(1, len(presets))) as pool:
+        for preset, result in zip(presets, pool.map(_safe(one), enumerate(presets))):
+            if isinstance(result, Exception):
+                failures.append(f"**{preset.label}**: `{type(result).__name__}: {result}`")
+                continue
+            _preset, (video, report) = result
+            clips.append({"key": preset.key, "label": preset.label, "video": video, "frames": preset.frames})
 
-def build_sprites(clips, tolerance, softness, despill, despeckle, playback_fps, sprite_height,
-                  progress=gr.Progress()):
     if not clips:
-        raise gr.Error("Generate at least one move first.")
+        raise gr.Error("Every move failed. " + (failures[0] if failures else ""))
 
-    packed: list[sk.Move] = []
-    previews: list[tuple[str, str]] = []
-    key_hex = None
+    gallery = [(clip["video"], clip["label"]) for clip in clips]
+    yield PENDING, character, gallery, None, [], None, f"{len(clips)} clips generated. Cutting to pose extremes…"
 
-    for i, clip in enumerate(clips):
-        progress((i) / max(len(clips), 1), desc=f"Keying {clip['label']}")
+    # ---- 3. key, cut to extremes, pack ----
+    packed, previews, key_hex = [], [], None
+    for clip in clips:
         frames, _fps = sk.read_video(clip["video"])
         keyed, key_rgb = sk.key_clip(
             frames,
@@ -149,18 +151,15 @@ def build_sprites(clips, tolerance, softness, despill, despeckle, playback_fps,
         )
         key_hex = "#%02X%02X%02X" % tuple((key_rgb * 255).astype(int))
 
-        indices = sk.pose_extremes(keyed, int(clip.get("frames", 6)))
+        indices = sk.pose_extremes(keyed, int(clip["frames"]))
         box = sk.content_bbox(keyed)
         sprites = sk.fit_height([sk.to_pil(keyed[j]).crop(box) for j in indices], int(sprite_height))
 
-        move = sk.Move(name=clip["key"], frames=sprites, fps=float(playback_fps))
-        packed.append(move)
-
+        packed.append(sk.Move(name=clip["key"], frames=sprites, fps=float(playback_fps)))
         preview = _out(f"{clip['key']}.webp")
         sk.save_animation(sprites, preview, fps=float(playback_fps))
         previews.append((preview, f"{clip['label']} · {len(sprites)} extremes"))
 
-    progress(0.9, desc="Packing sheet")
     sheet, atlas = sk.pack_sheet(packed)
     atlas["source"] = {"model": "MiniMaxAI/MiniMax-H3", "lora": "larryvrh/MiniMax-H3-Turbo-Lora", "keyed": key_hex}
 
@@ -174,129 +173,130 @@ def build_sprites(clips, tolerance, softness, despill, despeckle, playback_fps,
         handle.write(demo_html)
 
     total = sum(len(m.frames) for m in packed)
-    summary = (
-        f"**{len(packed)} moves · {total} frames** · cell {atlas['cell']['width']}x{atlas['cell']['height']} · "
-        f"sheet {atlas['sheet']['width']}x{atlas['sheet']['height']} · keyed `{key_hex}`"
+    status = (
+        f"**{len(packed)} moves · {total} frames** · cell {atlas['cell']['width']}×{atlas['cell']['height']} · "
+        f"sheet {atlas['sheet']['width']}×{atlas['sheet']['height']} · keyed `{key_hex}` · "
+        f"click the demo, then use the keys."
     )
-    return (
+    if failures:
+        status += "\n\nFailed: " + "; ".join(failures)
+
+    yield (
+        player.as_iframe(demo_html),
+        character,
+        gallery,
         sheet_path,
         previews,
-        player.as_iframe(demo_html),
         [sheet_path, atlas_path, demo_path],
-        summary,
+        status,
     )
 
 
+def _safe(fn):
+    """Let one failed move return its exception instead of cancelling the others."""
+
+    def wrapped(item):
+        try:
+            return fn(item)
+        except Exception as error:  # noqa: BLE001 — surfaced per move in the status line
+            traceback.print_exc()
+            return error
+
+    return wrapped
+
+
 # ---------------------------------------------------------------------------
 # ui
 # ---------------------------------------------------------------------------
 
 CSS = """
-.step h3 { margin-top: 0; }
-footer { display: none !important; }
+#col-container { max-width: 1300px; margin: 0 auto; }
+.dark .gradio-container { color: var(--body-text-color); }
 """
 
-with gr.Blocks(title="Sprite Forge", css=CSS, fill_width=True) as demo:
-    clips_state = gr.State([])
-
-    gr.Markdown(
-        """
-        # 🕹️ Sprite Forge
-        Game sprite sheets from a single character design, using **MiniMax-H3** with the 6-step
-        [Turbo LoRA](https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora).
-
-        One character still on a flat magenta backdrop → one short clip per move → cut to pose extremes →
-        key out the magenta → packed sheet + a playable demo. Every clip is generated with the character as **both
-        the first and last frame**, so every animation loops seamlessly.
-
-        *This Space has no GPU of its own — it calls other Spaces, and the bookings run on your own ZeroGPU quota.*
-        """
-    )
+with gr.Blocks(theme=gr.themes.Citrus(), css=CSS, title="Sprite Forge") as demo:
+    with gr.Column(elem_id="col-container"):
+        gr.Markdown(
+            """
+            # 🕹️ Sprite Forge
+            Describe a character, get a **playable** one. Powered by
+            [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) with the 6-step
+            [Turbo LoRA](https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora), after
+            [@victormustar's workflow](https://x.com/victormustar/status/2089310616854892818).
+
+            One clip per move, each generated with the same first *and* last frame so it loops — then keyed, cut to
+            its pose extremes and packed into a sprite sheet. Runs on your own ZeroGPU quota.
+            """
+        )
 
-    with gr.Row():
-        # ---------------- step 1 ----------------
-        with gr.Column(scale=4, elem_classes="step"):
-            gr.Markdown("### 1 · Character")
+        with gr.Row():
             subject = gr.Textbox(
                 label="Character",
                 value=DEFAULT_SUBJECT,
-                lines=2,
                 placeholder="a scrappy alley cat in a bomber jacket",
+                scale=5,
+                container=True,
             )
+            run = gr.Button("Generate", variant="primary", scale=1)
+
+        with gr.Accordion("Advanced", open=False):
             with gr.Row():
-                style = gr.Dropdown(
-                    list(move_defs.STYLES), value=move_defs.DEFAULT_STYLE, label="Style", scale=1
-                )
-                canvas = gr.Dropdown(
-                    list(backends.CANVASES), value=backends.DEFAULT_CANVAS, label="Canvas", scale=1
+                uploaded = gr.Image(
+                    label="Or start from your own character",
+                    type="filepath",
+                    height=220,
+                    scale=1,
                 )
-            image_backend = gr.Dropdown(
-                backends.BACKEND_LABELS, value=backends.BACKEND_LABELS[0], label="Image model"
-            )
-            seed = gr.Number(value=1234, label="Seed", precision=0)
-            design_btn = gr.Button("Design character", variant="primary")
-            character = gr.Image(
-                label="Character (upload your own to skip this step)",
-                type="filepath",
-                height=340,
-            )
-            character_note = gr.Markdown()
-
-        # ---------------- step 2 ----------------
-        with gr.Column(scale=4, elem_classes="step"):
-            gr.Markdown("### 2 · Moves")
-            selected_moves = gr.CheckboxGroup(
-                move_defs.LABELS, value=move_defs.DEFAULT_MOVES, label="Moves to generate"
-            )
+                with gr.Column(scale=2):
+                    selected_moves = gr.CheckboxGroup(
+                        move_defs.LABELS, value=move_defs.DEFAULT_MOVES, label="Moves"
+                    )
+                    with gr.Row():
+                        style = gr.Dropdown(
+                            list(move_defs.STYLES), value=move_defs.DEFAULT_STYLE, label="Style"
+                        )
+                        image_backend = gr.Dropdown(
+                            backends.BACKEND_LABELS, value=backends.BACKEND_LABELS[0], label="Image model"
+                        )
+                    with gr.Row():
+                        canvas = gr.Dropdown(
+                            list(backends.CANVASES), value=backends.DEFAULT_CANVAS, label="Canvas"
+                        )
+                        seed = gr.Number(value=1234, label="Seed", precision=0)
             with gr.Row():
-                duration = gr.Slider(2, 5, value=2, step=0.5, label="Clip seconds")
+                duration = gr.Slider(
+                    2, 5, value=3, step=0.5, label="Clip seconds",
+                    info="H3 generates a 5s clip per move; 3s keeps each move punchy.",
+                )
                 steps = gr.Slider(4, 8, value=6, step=1, label="H3 steps")
+                playback_fps = gr.Slider(4, 24, value=12, step=1, label="Playback fps")
+                sprite_height = gr.Slider(64, 512, value=256, step=32, label="Max sprite height")
             with gr.Row():
-                animate_btn = gr.Button("Generate moves", variant="primary", scale=3)
-                clear_btn = gr.Button("Clear", scale=1)
-            clip_gallery = gr.Gallery(label="Clips", columns=3, height=260, object_fit="contain")
-            move_log = gr.Markdown()
-
-        # ---------------- step 3 ----------------
-        with gr.Column(scale=5, elem_classes="step"):
-            gr.Markdown("### 3 · Sprites")
-            with gr.Accordion("Keying", open=False):
                 tolerance = gr.Slider(0.02, 0.30, value=0.10, step=0.01, label="Key tolerance")
                 softness = gr.Slider(0.01, 0.25, value=0.09, step=0.01, label="Edge softness")
                 despill = gr.Slider(0, 1, value=1.0, step=0.05, label="Despill")
                 despeckle = gr.Slider(0, 4, value=2, step=1, label="Despeckle")
-                playback_fps = gr.Slider(4, 24, value=12, step=1, label="Playback fps")
-                sprite_height = gr.Slider(
-                    64, 512, value=256, step=32, label="Max sprite height (px)",
-                    info="Caps the cell size. The clip resolves at 544px, so 256 is a downscale, never an upscale.",
-                )
-            build_btn = gr.Button("Build sprite sheet", variant="primary")
-            summary = gr.Markdown()
-            sheet_image = gr.Image(label="Sprite sheet (transparent PNG)", height=260)
-            sprite_previews = gr.Gallery(label="Looping moves", columns=4, height=210, object_fit="contain")
-            downloads = gr.Files(label="Download")
-
-    gr.Markdown("### Playable demo")
-    demo_frame = gr.HTML(
-        "<p style='opacity:.6'>Build a sheet to get a playable demo — arrow keys walk and jump, "
-        "J/K/L punch, kick and block.</p>"
-    )
 
-    design_btn.click(
-        design_character,
-        [subject, style, image_backend, canvas, seed],
-        [character, character_note],
-    )
-    animate_btn.click(
-        animate_moves,
-        [subject, character, selected_moves, canvas, duration, steps, seed, clips_state],
-        [clips_state, clip_gallery, move_log],
-    )
-    clear_btn.click(clear_clips, None, [clips_state, clip_gallery, move_log])
-    build_btn.click(
-        build_sprites,
-        [clips_state, tolerance, softness, despill, despeckle, playback_fps, sprite_height],
-        [sheet_image, sprite_previews, demo_frame, downloads, summary],
+        demo_frame = gr.HTML(IDLE_PANEL, label="Playable")
+        status = gr.Markdown()
+
+        gr.Examples(EXAMPLES, inputs=subject, label="Try a character")
+
+        with gr.Accordion("Sprite sheet, clips and downloads", open=False):
+            with gr.Row():
+                character_preview = gr.Image(label="Character still", height=250)
+                clip_gallery = gr.Gallery(label="H3 clips", columns=3, height=250, object_fit="contain")
+            sheet_image = gr.Image(label="Sprite sheet (transparent PNG)", height=250)
+            sprite_previews = gr.Gallery(label="Looping moves", columns=5, height=210, object_fit="contain")
+            downloads = gr.Files(label="Download — sheet, atlas.json, standalone demo.html")
+
+    run.click(
+        forge,
+        [
+            subject, uploaded, style, image_backend, canvas, selected_moves, duration, steps, seed,
+            tolerance, softness, despill, despeckle, playback_fps, sprite_height,
+        ],
+        [demo_frame, character_preview, clip_gallery, sheet_image, sprite_previews, downloads, status],
     )
 
 if __name__ == "__main__":

spritekit.py

@@ -114,19 +114,23 @@ def key_out(
 
     out = frame
     if despill > 0:
-        # Spill is backdrop light bounced onto the subject: chroma displaced along the backdrop's own direction.
-        # Remove the component parallel to it, keeping the perpendicular part that is the subject's real color.
+        # Un-mix the backdrop out of the edge instead of merely desaturating it.
         #
-        # Weighted by `1 - alpha`, and that weight is load-bearing rather than a refinement. A magenta backdrop keys
-        # to a chroma direction that is almost pure +Cr, and *every warm color shares it* — subtracting the full
-        # projection everywhere turns an orange cat green, which is exactly what an unweighted version of this line
-        # did. Real spill only lands where the backdrop shows through, so confining the correction to the matte's
-        # transition band both fixes the hue and still cleans the fringe, which is all this needs to do on flat art.
-        proj = np.einsum("...c,c->...", ycc[..., 1:], key_dir)
-        excess = np.maximum(proj, 0.0) * despill * (1.0 - alpha)
-        cleaned = ycc.copy()
-        cleaned[..., 1:] -= excess[..., None] * key_dir
-        out = to_rgb(cleaned)
+        # An edge pixel is a real alpha composite of the character over the backdrop,
+        # ``observed = a*F + (1-a)*key``, so the character's own color is recoverable exactly:
+        # ``F = (observed - (1-a)*key) / a``. Solving it removes the fringe rather than trading it for a grey rim,
+        # and it is an identity at ``a == 1``, so opaque interior pixels are provably untouched.
+        #
+        # That last property is why this replaced a chroma-projection despill. Projection subtracts the backdrop's
+        # chroma direction from *every* pixel, and a magenta key points almost exactly along +Cr, which every warm
+        # color shares — the first version of this turned an orange cat green. Scaling it by `1 - alpha` fixed the
+        # hue but then only removed a fraction of the spill on the edge, leaving the 1px magenta halo this does not.
+        safe = np.maximum(alpha, 1e-3)[..., None]
+        unmixed = np.clip((frame - (1.0 - alpha)[..., None] * key_rgb) / safe, 0.0, 1.0)
+        # Below a few percent coverage the division is mostly amplifying noise, and those pixels are invisible
+        # anyway — fade the correction out rather than letting it produce confetti.
+        trust = np.clip(alpha / 0.15, 0.0, 1.0)[..., None] * despill
+        out = frame * (1.0 - trust) + unmixed * trust
 
     return np.concatenate([out, alpha[..., None]], axis=-1).astype(np.float32)