spritegen-cli 0.1.0__py3-none-any.whl

spritegen/stages/pose.py

@@ -0,0 +1,172 @@
+"""The frame an animation starts from, and the one it ends on.
+
+The anchor is neutral on purpose — facing south, weight even, hands empty. That is the
+rest state a pose-driven endpoint deforms from, and an anchor caught mid-swing puts that
+swing into every frame of the walk.
+
+Which leaves a gap. A sword attack begins with the sword already in hand and already
+drawn back, in a pose the anchor does not have. Asking a video model to introduce the
+weapon *and* the movement in one call is asking for two things, and identity is the one
+that gets dropped — the character comes back holding a different sword, or a different
+character comes back holding the right one.
+
+So the first frame is generated as an image: cheap, reviewable, and quoting the anchor for
+identity, which separates the two questions. **The last frame closes the cycle**, and by
+default it *is* the first — copied, not generated, because a cycle that ends where it
+began is the ordinary case and paying twice for one image would be absurd. `seedance` and
+`kling` take that as `end_image_url` and `tail_image_url`; `video --loop` was already
+sending the anchor to both ends for want of anything better.
+
+One pose per animation, under its own name: `pose/attack/start.png`. That is the same
+shape `sheet/<direction>/` has, and for the same reason — one sprite has several, and
+none of them is *the* pose.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import fal, imaging, prompts, workspace
+
+MODEL = "openai/gpt-image-2/edit"
+
+#: What each file is called inside the pose's directory. `video` looks for these names.
+START = "start.png"
+END = "end.png"
+
+
+def build_payload(args: argparse.Namespace, prompt: str, refs: list[str]) -> dict:
+    """The payload as the endpoint takes it.
+
+    Always the edit endpoint, never the text-to-image one: a pose that does not quote the
+    anchor is a different character in the first frame, which is the whole failure this
+    stage exists to avoid.
+    """
+    from .anchor import build_prompt, parse_size
+
+    return {
+        "prompt": build_prompt(args, prompt),
+        "image_urls": refs,
+        "image_size": parse_size(args.size),
+        "quality": args.quality,
+        "num_images": 1,
+        "output_format": "png",
+    }
+
+
+def read_prompts(args: argparse.Namespace) -> tuple[str, str | None]:
+    """The start prompt, and the end prompt if one was given."""
+    start = prompts.resolve(args.prompt, args.prompt_file, "the pose")
+    if args.no_end:
+        if args.end_prompt or args.end_prompt_file:
+            raise ValueError("--no-end and an end prompt ask for opposite things")
+        return start, None
+    if not (args.end_prompt or args.end_prompt_file):
+        return start, None
+    return start, prompts.resolve(args.end_prompt, args.end_prompt_file, "the pose's end")
+
+
+def check_name(name: str) -> str:
+    """The animation's name, if it can be a directory.
+
+    Checked here rather than left to the filesystem, and by the same rule an asset name
+    is: it becomes a path segment under `pose/`, so a separator in it would write outside
+    the sprite. `workspace.check_name` is that rule, and there is no second one.
+    """
+    if not name:
+        raise ValueError(
+            "a pose is for an animation; name it with --animation, e.g. --animation attack"
+        )
+    return workspace.check_name(name)
+
+
+def run(args: argparse.Namespace) -> int:
+    check_name(args.animation)
+    context = workspace.context_from_args(args)
+    start_prompt, end_prompt = read_prompts(args)
+
+    anchor = context.source_files("*.png")
+    anchor = [path for path in anchor if not path.stem.endswith(".raw")]
+    if not anchor:
+        raise workspace.StageRefused(f"{context.asset}: no anchor in {context.source}")
+
+    refs = [anchor[0], *(Path(one) for one in (args.ref or []))]
+    for one in refs:
+        if not one.is_file():
+            raise FileNotFoundError(f"no reference image at {one}")
+
+    calls = 1 if end_prompt is None else 2
+
+    if context.dry_run:
+        fal.show(MODEL, build_payload(args, start_prompt, [str(one) for one in refs]))
+        if end_prompt is not None:
+            fal.show(MODEL, build_payload(args, end_prompt, [str(one) for one in refs]))
+        closing = "copied from the start frame" if not args.no_end else "not written"
+        print(f"would spend {calls} call(s); the end frame would be {closing}")
+        return 0
+
+    fal.require_key()
+    context.keep_prompt(start_prompt)
+    uploaded = [fal.upload(one) for one in refs]
+    out = context.ensure_out()
+
+    written = [_one(context, args, start_prompt, uploaded, out / START)]
+    report = {"start": _finish(args, out / START)}
+
+    if args.no_end:
+        pass
+    elif end_prompt is None:
+        # Copied, not generated. A cycle that ends where it began is the ordinary case,
+        # and a second paid call for the same image would buy nothing but drift.
+        (out / END).write_bytes((out / START).read_bytes())
+        written.append(out / END)
+        report["end"] = "copied from the start frame"
+    else:
+        # Before its call, like the start's: a second paid call whose text nobody kept is
+        # an image nobody can regenerate or amend, which is the failure `prompts` exists
+        # to prevent — and it is worse here, because the artifact would then cite the
+        # start's text for both.
+        context.keep_prompt(end_prompt, part="end")
+        written.append(_one(context, args, end_prompt, uploaded, out / END))
+        report["end"] = _finish(args, out / END)
+
+    context.record(
+        endpoint=MODEL,
+        animation=args.animation,
+        images=[path.name for path in written],
+        reports=report,
+    )
+    for path in written:
+        print(path)
+    return 0
+
+
+def _one(context, args: argparse.Namespace, prompt: str, refs: list[str], dest: Path) -> Path:
+    """One paid call, downloaded to `dest` and recorded against the asset."""
+    payload = build_payload(args, prompt, refs)
+    result = fal.call(MODEL, payload)
+
+    urls = fal.urls_in(result)
+    if not urls:
+        raise ValueError(f"{MODEL} returned no image; nothing to write")
+
+    written = fal.download(urls[0], dest)
+    context.paid_call(endpoint=MODEL, payload=payload, urls=urls[:1], files=[written])
+    return written
+
+
+def _finish(args: argparse.Namespace, path: Path) -> dict:
+    """The unpaid transforms, the same ones and in the same order the anchor applies."""
+    report: dict = {}
+    if args.transparent:
+        report["chroma"] = imaging.cut_chroma(
+            path,
+            imaging.parse_chroma(args.chroma),
+            args.tol,
+            args.feather,
+            args.despill,
+            args.despill_radius,
+            args.chroma_mode,
+        )
+    return report

spritegen/stages/video.py

@@ -0,0 +1,196 @@
+"""Animate the anchor directly and pull a board of frames out of the clip.
+
+Absorbed from the `gen_video.py` this grew out of. Four endpoints in two shapes:
+
+- **grok**, reference-to-video, takes a **list** of references and the prompt addresses
+  each by `<IMAGE_0>`, `<IMAGE_1>` in the order given. The only one here that takes more
+  than one image, so the only one where the character and a pose sheet go up together.
+- **grok-i2v**, **seedance**, **kling**, image-to-video, take one first frame. The last
+  two also take a last frame, and sending the anchor as both is what closes the cycle:
+  the final frame meets the first, which is the condition for a walk that loops. Without
+  it the clip ends wherever it likes and the seam jumps.
+
+The anchor is not an argument. It is the asset's own anchor, which is what stops a clip
+from being generated against an image nobody can find again.
+
+**Video is billed per second of output.** `--duration` and `--resolution` are the two
+options that move the bill, and this is the most expensive call in the tool.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import clip, fal, prompts, workspace
+
+MODELS = {
+    "grok": "xai/grok-imagine-video/v1.5/reference-to-video",
+    "grok-i2v": "xai/grok-imagine-video/image-to-video",
+    "seedance": "bytedance/seedance-2.5/image-to-video",
+    "kling": "fal-ai/kling-video/v2.5-turbo/pro/image-to-video",
+}
+
+#: The one endpoint that takes a list of references rather than a single first frame.
+REFERENCE_LIST = {"grok"}
+
+#: What each endpoint calls its last frame. None means it does not take one.
+TAIL_FIELD = {
+    "seedance": "end_image_url",
+    "kling": "tail_image_url",
+    "grok-i2v": None,
+    "grok": None,
+}
+
+
+def read_prompt(args: argparse.Namespace) -> str:
+    return prompts.resolve(args.prompt, args.prompt_file, "the video stage")
+
+
+def first_and_last(context, args: argparse.Namespace) -> tuple[Path, Path | None]:
+    """What the clip starts from, and what it ends on.
+
+    Without `--pose` this is the anchor, and `--loop` sends it to both ends — which is
+    what there was before a pose existed, and the reason `--loop` reads oddly: the clip
+    was told to return to a rest state it never left.
+
+    With `--pose` the clip starts from that animation's first frame and ends on its last,
+    which is the first frame again unless somebody generated a different one.
+
+    `--loop` on top of a pose usually has nothing left to say, since the pose already
+    closes. It has one thing to say on a pose made with `--no-end` — a death, a movement
+    that does not return — where asking for a loop and silently getting no last frame
+    would be a trap. There, `--loop` means what it always meant: end where you began.
+    """
+    if not args.pose:
+        # `.raw` is the copy `upscale` keeps of what the paid call returned, and it is
+        # not the anchor: animating it would throw away the enlargement. Sorting hid
+        # this — `anchor.raw.png` follows `anchor.png` for the same stem — but a
+        # directory holding only the backup would have animated it.
+        anchors = [
+            path for path in context.source_files("*.png") if not path.stem.endswith(".raw")
+        ]
+        if not anchors:
+            raise workspace.StageRefused(f"{context.asset}: no anchor in {context.source}")
+        # `--loop` is this stage's option; `motion` shares the lookup and not the flag.
+        return anchors[0], (anchors[0] if getattr(args, "loop", False) else None)
+
+    from . import pose as pose_stage
+
+    key = f"pose:{pose_stage.check_name(args.pose)}"
+    entry = context.state.artifacts.get(key)
+    if entry is None:
+        made = ", ".join(sorted(k for k in context.state.artifacts if k.startswith("pose:")))
+        raise workspace.StageRefused(
+            f"{context.asset}: no pose {args.pose!r}; it has: {made or 'none'}"
+        )
+
+    directory = workspace.inside(context.asset, entry["dir"])
+    start = directory / pose_stage.START
+    if not start.is_file():
+        raise workspace.StageRefused(f"{context.asset}: {start} is not there")
+    end = directory / pose_stage.END
+    if end.is_file():
+        return start, end
+    return start, (start if getattr(args, "loop", False) else None)
+
+
+def build_payload(args: argparse.Namespace, prompt: str, urls: dict) -> dict:
+    """The payload each endpoint takes, from the URLs already uploaded."""
+    if args.model in REFERENCE_LIST:
+        return {
+            "prompt": prompt,
+            "reference_image_urls": urls["refs"],
+            "duration": args.duration,
+            "resolution": args.resolution,
+            "aspect_ratio": args.aspect,
+        }
+
+    payload: dict = {"prompt": prompt, "image_url": urls["image"]}
+
+    if "end" in urls:
+        tail = TAIL_FIELD[args.model]
+        if tail is None:
+            asked = "--pose" if args.pose else "--loop"
+            raise ValueError(f"{args.model} does not take a last frame, so {asked} cannot use one")
+        payload[tail] = urls["end"]
+
+    if args.model == "seedance":
+        payload["duration"] = str(args.duration)
+        payload["resolution"] = args.resolution
+        payload["generate_audio"] = False
+    elif args.model == "kling":
+        # Kling only takes 5 or 10 seconds.
+        payload["duration"] = "10" if args.duration > 5 else "5"
+        payload["negative_prompt"] = args.negative
+    else:
+        payload["duration"] = args.duration
+        payload["resolution"] = args.resolution
+    return payload
+
+
+def run(args: argparse.Namespace) -> int:
+    context = workspace.context_from_args(args)
+    prompt = read_prompt(args)
+    pick = clip.parse_pick(args.pick)
+
+    first, last = first_and_last(context, args)
+
+    extra = [Path(one) for one in (args.ref or [])]
+    for one in extra:
+        if not one.is_file():
+            raise FileNotFoundError(f"no reference image at {one}")
+    if extra and args.model not in REFERENCE_LIST:
+        raise ValueError(f"{args.model} takes one first frame, not a reference list")
+
+    endpoint = MODELS[args.model]
+
+    if context.dry_run:
+        placeholder = (
+            {"refs": [str(path) for path in [first, *extra]]}
+            if args.model in REFERENCE_LIST
+            else {"image": str(first), **({"end": str(last)} if last else {})}
+        )
+        fal.show(endpoint, build_payload(args, prompt, placeholder))
+        return 0
+
+    fal.require_key()
+    context.keep_prompt(prompt)
+    out = context.ensure_out()
+
+    if args.model in REFERENCE_LIST:
+        urls = {"refs": [fal.upload(path) for path in [first, *extra]]}
+    else:
+        uploaded = fal.upload(first)
+        # The same file uploads once: `--loop` on an anchor sends one URL to both ends,
+        # and a pose whose end frame is a copy of its start does the same.
+        tail = uploaded if last == first else fal.upload(last) if last else None
+        urls = {"image": uploaded, **({"end": tail} if tail else {})}
+
+    payload = build_payload(args, prompt, urls)
+    result = fal.call(endpoint, payload)
+
+    found = fal.urls_in(result)
+    if not found:
+        raise ValueError(f"{endpoint} returned no clip")
+
+    video = fal.download(found[0], out / "clip.mp4")
+    frames = clip.decode_frames(video)
+    chosen, indices = clip.choose_frames(frames, args.frames, args.start, args.end, pick)
+    board = out / "board.png"
+    cols, rows = clip.pack_board(chosen, args.cols, board)
+
+    context.paid_call(endpoint=endpoint, payload=payload, urls=found, files=[video, board])
+    context.record(
+        endpoint=endpoint,
+        model=args.model,
+        clip="clip.mp4",
+        board="board.png",
+        decoded=len(frames),
+        indices=indices,
+        grid=f"{cols}x{rows}",
+    )
+
+    print(f"{video}  {len(frames)} frames decoded")
+    print(f"{board}  {len(chosen)} frames at {indices}, packed {cols}x{rows}")
+    return 0