spritegen-cli 0.1.0__py3-none-any.whl

spritegen/__init__.py

@@ -0,0 +1,3 @@
+"""Turn a handful of images into a game-ready character sheet, one stage at a time."""
+
+__version__ = "0.1.0"

spritegen/atlas.py

@@ -0,0 +1,99 @@
+"""Join several images into one, and cut the result back apart.
+
+Why it exists: a segmentation endpoint charges per call and decides per image. Sending
+six frames separately is six charges *and* six independent decisions about where the
+edge is, so the contour alpha varies between frames and the silhouette flickers — the
+same failure `sheet` avoids by recovering one grid and one palette across a whole board.
+Joining first makes the endpoint answer once, for all of them.
+
+What it costs: the endpoint operates at a fixed resolution. Four 1024 images join into
+a 2048 atlas, which is exactly the default operating resolution and loses nothing; four
+1400 boards join into 2800 and lose about a quarter of their detail on the way in.
+`fits` is how a caller finds that out before spending.
+
+Cells are uniform — the largest source, in both directions — so a mixed set still cuts
+back apart exactly. Each image keeps its own size in the record, and `unpack` crops to
+it rather than to the cell.
+"""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+
+def grid_for(count: int) -> tuple[int, int]:
+    """The squarest grid holding `count` cells.
+
+    Squarest rather than one row: a long strip wastes the endpoint's resolution on empty
+    width, and some segmenters treat an extreme aspect ratio as a reason to letterbox.
+    """
+    if count < 1:
+        raise ValueError("an atlas needs at least one image")
+    cols = math.ceil(math.sqrt(count))
+    rows = math.ceil(count / cols)
+    return cols, rows
+
+
+def pack(paths: list[Path], out: Path) -> dict:
+    """Write one atlas holding every image, and return where each of them went."""
+    from PIL import Image
+
+    if not paths:
+        raise ValueError("nothing to pack")
+
+    images = [Image.open(path).convert("RGBA") for path in paths]
+    cell_w = max(image.width for image in images)
+    cell_h = max(image.height for image in images)
+    cols, rows = grid_for(len(images))
+
+    atlas = Image.new("RGBA", (cell_w * cols, cell_h * rows), (0, 0, 0, 0))
+    placed = []
+    for index, (path, image) in enumerate(zip(paths, images, strict=True)):
+        left, top = (index % cols) * cell_w, (index // cols) * cell_h
+        atlas.paste(image, (left, top))
+        placed.append(
+            {"name": path.name, "box": [left, top, left + image.width, top + image.height]}
+        )
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    atlas.save(out)
+    return {
+        "atlas": out.name,
+        "size": f"{atlas.width}x{atlas.height}",
+        "cell": f"{cell_w}x{cell_h}",
+        "grid": f"{cols}x{rows}",
+        "placed": placed,
+    }
+
+
+def unpack(atlas: Path, layout: dict, out_dir: Path) -> list[Path]:
+    """Cut the matted atlas back into the images it was packed from.
+
+    Each one is cropped to the box it occupied, not to the cell, so an image smaller
+    than the cell does not come back with a transparent margin it never had.
+    """
+    from PIL import Image
+
+    image = Image.open(atlas).convert("RGBA")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written = []
+    for entry in layout["placed"]:
+        left, top, right, bottom = entry["box"]
+        if right > image.width or bottom > image.height:
+            raise ValueError(
+                f"{entry['name']} sat at {entry['box']} but the matted atlas is "
+                f"{image.width}x{image.height}; the endpoint resized it"
+            )
+        path = out_dir / entry["name"]
+        image.crop((left, top, right, bottom)).save(path)
+        written.append(path)
+    return written
+
+
+def fits(layout: dict, resolution: str) -> bool:
+    """Whether the atlas is within the endpoint's operating resolution — R2.6."""
+    atlas_w, atlas_h = (int(part) for part in layout["size"].split("x"))
+    limit_w, limit_h = (int(part) for part in resolution.split("x"))
+    return atlas_w <= limit_w and atlas_h <= limit_h

spritegen/cli.py

@@ -0,0 +1,178 @@
+"""The sub-command table, and nothing else.
+
+Two kinds of sub-command, and the difference matters: `new`, `status` and `cost` talk
+about the workspace and are free; the names in `stages.STAGES` run a stage and most of
+them spend money. The table is built from the registry, so a new stage shows up in the
+help without touching this file.
+
+No stage is imported at start-up. `stages.implementation` resolves the module only once
+the command has been chosen — a stage that does not exist yet takes down that command,
+not the whole CLI.
+
+Nothing here reads configuration. `settings.load()` does, wherever it is needed, and it
+finds a `.env` at or above the working directory on its own — so `FAL_KEY` can live in a
+file beside the assets instead of in every shell that runs a stage, without the CLI
+having to push it into the process first.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import __version__, stages
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The full parser, with one sub-command per registered stage."""
+    parser = argparse.ArgumentParser(
+        prog="spritegen",
+        description="Turn a handful of images into a character sheet, one stage at a time.",
+    )
+    parser.add_argument("--version", action="version", version=f"spritegen {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    new = sub.add_parser("new", help="open a new asset")
+    new.add_argument("name", help="the character's name, and the asset directory's")
+
+    status = sub.add_parser("status", help="where each asset stopped, and what comes next")
+    status.add_argument("--json", action="store_true", help="for another program to read")
+
+    show = sub.add_parser("show", help="what one asset holds, and what comes next")
+    show.add_argument("name", help="the asset")
+    show.add_argument("--json", action="store_true", help="for another program to read")
+
+    cost = sub.add_parser("cost", help="the paid calls per asset, read from the ledger")
+    cost.add_argument("name", nargs="?", help="one asset; without it, all of them")
+
+    upscale = sub.add_parser("upscale", help="enlarge an artifact locally, for nothing")
+    upscale.add_argument("name", help="the asset")
+    upscale.add_argument(
+        "--artifact", help="which one; without it, whatever the asset produced last"
+    )
+    upscale.add_argument("--scale", type=int, default=2, help="the factor, 2 or more")
+    upscale.add_argument(
+        "--model", choices=("anime", "general"), help="which weights; default from settings"
+    )
+    upscale.add_argument(
+        "--device", choices=("auto", "cuda", "cpu"), default="auto", help="where it runs"
+    )
+    upscale.add_argument("--dry-run", action="store_true", help="print the files and touch none")
+
+    migrate = sub.add_parser("migrate", help="move an asset to the current on-disk layout")
+    migrate.add_argument("name", nargs="?", help="one asset; without it, every outdated one")
+    migrate.add_argument(
+        "--dry-run", action="store_true", help="print the moves and touch nothing"
+    )
+
+    init = sub.add_parser("init", help="write the Claude skill describing this pipeline")
+    init.add_argument(
+        "--dir",
+        dest="directory",
+        help="where the skill goes; without it, the first .claude at or above the "
+        "working directory",
+    )
+    init.add_argument("--force", action="store_true", help="rewrite a skill already there")
+    init.add_argument(
+        "--yes",
+        action="store_true",
+        help="answer yes to what init would otherwise ask, for a run with nobody at it",
+    )
+
+    for stage in stages.STAGES:
+        run = sub.add_parser(stage.name, help=stage.summary)
+        run.add_argument("name", help="the asset")
+        run.add_argument(
+            "--force",
+            action="store_true",
+            help=f"rewrite {stage.produces!r} even though it already exists",
+        )
+        if stage.paid:
+            run.add_argument(
+                "--dry-run",
+                action="store_true",
+                help="print the payload and spend nothing",
+            )
+        for option in stage.options:
+            run.add_argument(*option.flags, **_option_kwargs(option))
+
+    return parser
+
+
+_KINDS = {"str": str, "int": int, "float": float}
+
+
+def _option_kwargs(option: stages.Option) -> dict:
+    """One declared option, as argparse takes it."""
+    kwargs: dict = {"help": option.help, "default": option.default}
+    if option.action:
+        kwargs["action"] = option.action
+        if option.action == "store_true":
+            kwargs["default"] = bool(option.default)
+            return kwargs
+    else:
+        kwargs["type"] = _KINDS[option.kind]
+    if option.choices:
+        kwargs["choices"] = list(option.choices)
+    return kwargs
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    """Run the parsed command.
+
+    Returns the exit code rather than exiting: `main` is what talks to the process, and
+    a test calls this directly.
+    """
+    if args.command in stages.BY_NAME:
+        module = stages.implementation(args.command)
+        return int(module.run(args))
+
+    handlers = _free_commands()
+    if args.command not in handlers:
+        raise NotImplementedError(f"command {args.command!r} has no implementation yet")
+    return int(handlers[args.command](args))
+
+
+def _free_commands() -> dict:
+    """The commands that are not stages, imported late for the same reason the stages are.
+
+    `new`, `status` and `cost` are about one asset; `migrate` is about the shape of the
+    directory it lives in; `init` is about the tool itself and lives with the skill it
+    writes. All three modules are cheap to import, which is what makes a free command
+    answer without loading Pillow, numpy or fal_client.
+    """
+    from . import migrate, skill, upscale, workspace
+
+    handlers = {}
+    for module, commands in (
+        (workspace, ("new", "status", "show", "cost")),
+        (skill, ("init",)),
+        (migrate, ("migrate",)),
+        (upscale, ("upscale",)),
+    ):
+        for command in commands:
+            handler = getattr(module, f"cmd_{command}", None)
+            if handler is not None:
+                handlers[command] = handler
+    return handlers
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    try:
+        return dispatch(args)
+    except NotImplementedError as exc:
+        print(f"spritegen: {exc}", file=sys.stderr)
+        return 3
+    except (KeyError, FileNotFoundError, FileExistsError, ValueError) as exc:
+        print(f"spritegen: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spritegen/clip.py

@@ -0,0 +1,81 @@
+"""Turn a generated clip into a board of animation frames.
+
+Absorbed from the `gen_video.py` this grew out of, minus the paid call. What a video
+model gives that a grid of images does not is real movement, with contrast between contact and
+passing. What it takes away is that the output is not pixel art: the codec interpolates,
+the scale drifts across the clip, and the model invents background and moves the camera.
+That is why the prompt pins the camera, and why the board exists at all — `sheet`
+recovers one grid over every frame at once, which per-frame extraction could not do.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def decode_frames(video: Path) -> list:
+    """Every frame of the clip, in order."""
+    import av
+
+    with av.open(str(video)) as container:
+        stream = container.streams.video[0]
+        stream.thread_type = "AUTO"
+        images = [frame.to_image() for frame in container.decode(stream)]
+    if not images:
+        raise ValueError(f"{video} has no frames in it")
+    return images
+
+
+def parse_pick(text: str | None) -> list[int] | None:
+    """`12,17,22` to `[12, 17, 22]`."""
+    if not text:
+        return None
+    try:
+        return [int(part) for part in text.split(",")]
+    except ValueError:
+        raise ValueError(f"frame indices are comma-separated whole numbers; got {text!r}") from None
+
+
+def choose_frames(
+    images: list, count: int, start: float, end: float, pick: list[int] | None
+) -> tuple[list, list[int]]:
+    """Pick the frames of the cycle. Returns the images and the indices chosen.
+
+    The start of the clip is not the start of the cycle. In an image-to-video model the
+    first frame *is* the input image, standing still, and the movement only engages
+    after it — so extracting from zero spends one of six frames on a pose that does not
+    belong to the cycle. `start` cuts that entry off.
+    """
+    total = len(images)
+    if pick:
+        bad = [index for index in pick if not 0 <= index < total]
+        if bad:
+            raise ValueError(f"frame indices outside the clip (0..{total - 1}): {bad}")
+        return [images[index] for index in pick], list(pick)
+
+    low, high = round(start * (total - 1)), round(end * (total - 1))
+    if high - low < 1:
+        raise ValueError(f"start and end left fewer than 2 frames of {total}")
+    window = list(range(low, high + 1))
+    if count >= len(window):
+        return [images[index] for index in window], window
+    # The window's last frame repeats its first when the cycle closes, so it is left
+    # out: taking both would put a standing step at the seam.
+    span = len(window) - 1
+    indices = [window[round(index * span / count)] for index in range(count)]
+    return [images[index] for index in indices], indices
+
+
+def pack_board(frames: list, cols: int, out: Path) -> tuple[int, int]:
+    """Lay the chosen frames out in a grid, so `sheet` can read one grid over them all."""
+    from PIL import Image
+
+    rows = (len(frames) + cols - 1) // cols
+    width = max(frame.size[0] for frame in frames)
+    height = max(frame.size[1] for frame in frames)
+    board = Image.new("RGBA", (width * cols, height * rows), (0, 0, 0, 0))
+    for index, frame in enumerate(frames):
+        board.paste(frame.convert("RGBA"), ((index % cols) * width, (index // cols) * height))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    board.save(out)
+    return cols, rows

spritegen/drive.py

@@ -0,0 +1,163 @@
+"""Build the clip that drives a motion-transfer endpoint, out of a reference sheet.
+
+A pose-driven model takes two things: one image of the character, and a clip whose
+movement it copies. This builds the second from a reference sheet the project already
+has, so the
+movement a new character inherits is movement that was measured rather than movement the
+model invented. That is the whole difference from the `video` stage, which asks a model
+to make up a walk and then hopes the result is a cycle.
+
+Three things this has to get right, and each is a way the endpoint fails otherwise:
+
+1. **Nearest neighbour, at an integer factor.** The endpoint works at its own resolution,
+   far above a 166 px cell. On a sheet that really is pixel art, smooth resampling turns
+   flat blocks into gradients and a pose extractor reading a blurred silhouette finds a
+   different skeleton every frame. Note that not every reference sheet is pixel art:
+   measured on the one this was built against, a single 166 px cell held 1290 distinct
+   colours and changed colour 128 times across a scanline, which is an antialiased render
+   rather than flat blocks. Nearest neighbour costs nothing there and is what a pixel-art
+   sheet needs, so it stays either way.
+2. **A flat opaque backdrop.** Video has no alpha, so a transparent cell encodes as
+   black — or as whatever the codec decides — and the figure's own dark outline stops
+   being separable from it.
+3. **Long enough to be a clip.** Six frames at 7 fps is under a second; the endpoints
+   want seconds. The cycle repeats to fill the duration, which is safe precisely because
+   it *is* a cycle: the sheet's last frame already meets its first.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+#: The reference sheet's cell, matching `sheet.CELL`.
+CELL = 166
+
+#: Mid grey. Far from skin, from the outline black these sheets use, and from the chroma
+#: green the anchor stage asks for, so nothing in the figure disappears into it.
+BACKDROP = (110, 110, 110)
+
+
+def cells_from_sheet(path: Path, cell: int = CELL) -> list:
+    """Every cell of the sheet, left to right then top to bottom."""
+    from PIL import Image
+
+    sheet = Image.open(path).convert("RGBA")
+    cols, rows = sheet.width // cell, sheet.height // cell
+    if cols < 1 or rows < 1:
+        raise ValueError(f"{path} is {sheet.width}x{sheet.height}, smaller than one {cell} cell")
+    return [
+        sheet.crop((col * cell, row * cell, (col + 1) * cell, (row + 1) * cell))
+        for row in range(rows)
+        for col in range(cols)
+    ]
+
+
+def sheet_grid(path: Path, cell: int = CELL) -> tuple[int, int]:
+    """The sheet's grid in cells."""
+    from PIL import Image
+
+    sheet = Image.open(path)
+    return sheet.width // cell, sheet.height // cell
+
+
+def pick_row(cells: list, cols: int, row: int, frames: int | None = None) -> list:
+    """One row of the sheet — one animation, in order.
+
+    A sheet row is an animation; which row is which is the sheet's business, not this
+    module's, so the row comes in as a number.
+    """
+    total_rows = len(cells) // cols
+    if not 0 <= row < total_rows:
+        raise ValueError(f"row {row} is outside a sheet of {total_rows} rows")
+    taken = cells[row * cols : (row + 1) * cols]
+    return taken[:frames] if frames else taken
+
+
+def scale_cells(cells: list, target: int, backdrop: tuple[int, int, int] = BACKDROP) -> list:
+    """Blow each cell up to `target`, nearest neighbour, on a flat opaque field.
+
+    The factor is a whole number so every source pixel becomes an exact square. Scaling
+    to fill `target` precisely would need a fractional factor, which is the thing being
+    avoided, so the enlarged cell is centred on a `target` canvas instead.
+    """
+    from PIL import Image
+
+    if not cells:
+        raise ValueError("no cells to scale")
+
+    cell = cells[0].width
+    factor = max(1, target // cell)
+    size = cell * factor
+
+    scaled = []
+    for source in cells:
+        big = source.resize((size, size), Image.NEAREST)
+        canvas = Image.new("RGB", (target, target), backdrop)
+        offset = (target - size) // 2
+        canvas.paste(big, (offset, offset), big)
+        scaled.append(canvas)
+    return scaled
+
+
+def repeat_to(frames: list, fps: int, seconds: float) -> list:
+    """The cycle, repeated until it is `seconds` long.
+
+    Safe because it is a cycle: the sheet's last frame already meets its first, so the
+    seam is the same seam the animation has in the game.
+    """
+    if not frames:
+        raise ValueError("no frames to repeat")
+    wanted = max(len(frames), round(fps * seconds))
+    return [frames[index % len(frames)] for index in range(wanted)]
+
+
+def write_clip(frames: list, out: Path, fps: int = 12) -> Path:
+    """Encode the frames as an mp4 the endpoint will take."""
+    import av
+
+    if not frames:
+        raise ValueError("no frames to encode")
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    width, height = frames[0].size
+    with av.open(str(out), mode="w") as container:
+        stream = container.add_stream("libx264", rate=fps)
+        stream.width, stream.height = width, height
+        stream.pix_fmt = "yuv420p"
+        # A high bitrate keeps the block edges the pose extractor reads. Measured against
+        # the frames going in, this loses a mean of 0.75 of 255 per channel, so what
+        # reaches the endpoint is the scaled cell and not the codec's idea of it.
+        stream.options = {"crf": "16", "preset": "veryslow", "tune": "stillimage"}
+        for frame in frames:
+            container.mux(stream.encode(av.VideoFrame.from_image(frame.convert("RGB"))))
+        container.mux(stream.encode())
+    return out
+
+
+def build(
+    sheet: Path,
+    out: Path,
+    *,
+    row: int = 0,
+    frames: int | None = None,
+    cell: int = CELL,
+    target: int = 720,
+    fps: int = 12,
+    seconds: float = 4.0,
+) -> dict:
+    """A reference sheet through to a driving clip. Returns what it measured."""
+    cols, rows = sheet_grid(sheet, cell)
+    cells = pick_row(cells_from_sheet(sheet, cell), cols, row, frames)
+    scaled = scale_cells(cells, target)
+    filled = repeat_to(scaled, fps, seconds)
+    write_clip(filled, out, fps)
+    return {
+        "sheet": f"{cols}x{rows}",
+        "row": row,
+        "cycle": len(cells),
+        "frames": len(filled),
+        "size": f"{target}x{target}",
+        "factor": max(1, target // cell),
+        "fps": fps,
+        "seconds": round(len(filled) / fps, 2),
+    }

spritegen/endpoints.py

@@ -0,0 +1,113 @@
+"""The motion-transfer endpoints, and what each one takes.
+
+Three of them do the same job — a character image plus a driving clip, out comes the
+character doing that movement — and each names its knobs differently. The table is here
+rather than inside the stage so the CLI can check an option against the chosen endpoint
+*before* spending, and so adding a fourth is one entry rather than a branch.
+
+Every one takes `image_url` and `video_url`; `options` is only what is particular to it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    """One motion-transfer endpoint.
+
+    `options` maps an option name to the values it accepts: `None` means anything of the
+    right type, a tuple means exactly those. `defaults` is what goes in the payload when
+    the caller said nothing, so a dry run shows the real request rather than a sketch.
+    """
+
+    id: str
+    summary: str
+    options: dict[str, tuple | None] = field(default_factory=dict)
+    defaults: dict = field(default_factory=dict)
+
+    def accepts(self, name: str) -> bool:
+        return name in self.options
+
+    def check(self, name: str, value) -> None:
+        """Raise if this endpoint would not take `name=value` — R4.4.
+
+        Every option goes through here, including the ones the stage declares as flags
+        of its own. An option is an option whether it arrived as `--set name=value` or
+        as `--prompt`, and sending one the endpoint never declared is a paid call that
+        should not have been made.
+        """
+        if not self.accepts(name):
+            known = ", ".join(sorted(self.options)) or "no options of its own"
+            raise ValueError(f"{self.id} has no option {name!r}; it takes: {known}")
+        allowed = self.options[name]
+        if allowed is not None and value not in allowed:
+            raise ValueError(
+                f"{self.id} takes {name}={' or '.join(map(str, allowed))}, not {value!r}"
+            )
+
+
+MOTION: dict[str, Endpoint] = {
+    "wan-motion": Endpoint(
+        id="fal-ai/wan-motion",
+        summary="720p, retargets the driving skeleton to the character's proportions",
+        options={
+            "adapt_motion": (True, False),
+            "enhance_identity": (True, False),
+            "acceleration": ("none", "regular"),
+            "seed": None,
+            "enable_safety_checker": (True, False),
+        },
+        defaults={"adapt_motion": True, "acceleration": "regular"},
+    ),
+    "wan-animate": Endpoint(
+        id="fal-ai/wan/v2.2-14b/animate/move",
+        summary="Wan 2.2 Animate, the full model wan-motion is a streamlined form of",
+        options={
+            "seed": None,
+            "resolution": ("480p", "580p", "720p"),
+            "num_inference_steps": None,
+            "enable_safety_checker": (True, False),
+        },
+        defaults={"resolution": "720p"},
+    ),
+    "one-to-all": Endpoint(
+        id="fal-ai/one-to-all-animation/14b",
+        summary="pose-driven, with identity and pose weighted against each other",
+        options={
+            "prompt": None,
+            "negative_prompt": None,
+            "resolution": ("480p", "580p", "720p"),
+            "num_inference_steps": None,
+            "image_guidance_scale": None,
+            "pose_guidance_scale": None,
+        },
+        # prompt and negative_prompt are required by this one's schema, so they are
+        # here as empty strings rather than left out: absent, the call comes back 422
+        # and the driving clip was uploaded for nothing.
+        defaults={
+            "prompt": "",
+            "negative_prompt": "",
+            "resolution": "720p",
+            "num_inference_steps": 30,
+            "image_guidance_scale": 2,
+            "pose_guidance_scale": 1.5,
+        },
+    ),
+}
+
+#: The default. Fewest knobs, and the one whose pose retargeting is the point: the
+#: driving sheet and the generated character rarely have the same proportions. The other
+#: two are here because they fail differently — `one-to-all` is the one to reach for when
+#: identity and pose need weighing against each other, which is a dial the other two do
+#: not expose.
+DEFAULT = "wan-motion"
+
+
+def get(name: str) -> Endpoint:
+    try:
+        return MOTION[name]
+    except KeyError:
+        known = ", ".join(sorted(MOTION))
+        raise KeyError(f"unknown motion endpoint {name!r}; there are: {known}") from None