spritegen-cli 0.1.0__py3-none-any.whl

spritegen/stages/anchor.py

@@ -0,0 +1,215 @@
+"""One generated image: an anchor, box art, or an icon.
+
+`--kind` says which, and that is the directory it goes in — all three come out of this
+stage and none of them is the others. The **anchor** is the neutral sprite every later
+stage animates, and it is the one call that decides everything after it: a wrong anchor
+wastes every paid call downstream, which is why `--dry-run` prints the payload and why
+the report names what it found. **Box art** settles the look before a sprite exists and
+then becomes the anchor's identity reference. An **icon** is one object and stops here.
+
+Absorbed from the `gen_image.py` this grew out of. What changed is where things live, not what
+they do — the transforms are in `imaging` and pinned by `tests/parity`, and the paths
+come from the asset directory instead of the command line.
+
+Two endpoints, chosen by whether references were given. `openai/gpt-image-2` is
+text-to-image and takes no image at all; `openai/gpt-image-2/edit` takes a list, and
+**the order matters** — the prompt has to say what each reference is for.
+
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import fal, imaging, prompts, workspace
+
+MODEL = "openai/gpt-image-2"
+MODEL_EDIT = "openai/gpt-image-2/edit"
+
+PRESETS = (
+    "square_hd",
+    "square",
+    "portrait_4_3",
+    "portrait_16_9",
+    "landscape_4_3",
+    "landscape_16_9",
+    "auto",
+)
+
+#: The endpoint refuses an area below this and rounds each side to a multiple of 16.
+MIN_PIXELS = 655_360
+EDGE_MULTIPLE = 16
+MAX_EDGE = 3840
+
+#: Chroma green. Far from skin, steel, fire and stone, which is what this game draws.
+DEFAULT_CHROMA = "00b140"
+
+CHROMA_INSTRUCTION = (
+    "The background is a single solid flat #{hex} chroma-green field, edge to edge, "
+    "with nothing else in it: no scenery, no ground plane, no shadow cast onto it, "
+    "no gradient, no vignette, no border, no text and no watermark. The subject does "
+    "not touch or overlap the edges of the image, and nothing in the subject itself "
+    "uses that chroma green."
+)
+
+
+def parse_size(text: str) -> str | dict:
+    """A fal preset, or WIDTHxHEIGHT in pixels."""
+    if text in PRESETS:
+        return text
+    if "x" not in text.lower():
+        raise ValueError(f"a size is WIDTHxHEIGHT or one of: {', '.join(PRESETS)}")
+    width_text, _, height_text = text.lower().partition("x")
+    try:
+        width, height = int(width_text), int(height_text)
+    except ValueError:
+        raise ValueError(f"size {text!r} is not WIDTHxHEIGHT") from None
+    if width <= 0 or height <= 0:
+        raise ValueError("a size needs positive sides")
+    if max(width, height) > MAX_EDGE:
+        raise ValueError(f"size {text!r} has a side longer than {MAX_EDGE}")
+    return {"width": width, "height": height}
+
+
+def check_size(size: str | dict) -> str | None:
+    """The warning this size deserves, or None.
+
+    A warning rather than a refusal: the endpoint rounds a side up and takes it, so the
+    run still works. What it must not do is round silently — the anchor decides
+    everything after it, and a size that came back different from the one asked for is
+    exactly the kind of surprise worth seeing before the next call is built on it.
+    """
+    if not isinstance(size, dict):
+        return None
+    width, height = size["width"], size["height"]
+    problems = []
+    if width * height < MIN_PIXELS:
+        problems.append(
+            f"{width}x{height} = {width * height:,} px, under the {MIN_PIXELS:,} minimum "
+            f"the endpoint accepts"
+        )
+    off = [str(value) for value in (width, height) if value % EDGE_MULTIPLE]
+    if off:
+        problems.append(
+            f"side {' and '.join(off)} is not a multiple of {EDGE_MULTIPLE}; fal rounds it"
+        )
+    return " ; ".join(problems) if problems else None
+
+
+def build_prompt(args: argparse.Namespace, prompt: str) -> str:
+    """The prompt as sent.
+
+    With `--transparent`, the chroma instruction is appended. Without it the flag would
+    cut a background nobody asked the model to paint: the cut only works because the
+    prompt demanded a flat key field in the first place.
+    """
+    if not args.transparent:
+        return prompt
+    red, green, blue = imaging.parse_chroma(args.chroma)
+    key = f"{red:02x}{green:02x}{blue:02x}"
+    return f"{prompt.rstrip()}\n\n{CHROMA_INSTRUCTION.format(hex=key)}"
+
+
+def read_prompt(args: argparse.Namespace) -> str:
+    """The prompt, from `--prompt` or `--prompt-file`, and never from both."""
+    return prompts.resolve(args.prompt, args.prompt_file, "the anchor")
+
+
+def build_payload(args: argparse.Namespace, prompt: str, refs: list[str]) -> dict:
+    """The payload as the endpoint takes it.
+
+    Built before anything is uploaded or spent, so `--dry-run` shows the real thing.
+    """
+    payload: dict = {
+        "prompt": build_prompt(args, prompt),
+        "image_size": parse_size(args.size),
+        "quality": args.quality,
+        "num_images": args.count,
+        "output_format": "png",
+    }
+    if refs:
+        payload["image_urls"] = refs
+    return payload
+
+
+def post_process(path: Path, args: argparse.Namespace) -> dict:
+    """The unpaid transforms, in the order that makes each one cheaper than the next.
+
+    Chroma first, because the grid detector should see alpha where the background was
+    rather than a flat colour competing for a palette slot.
+    """
+    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,
+        )
+    if args.pixelart:
+        report["pixelart"] = imaging.to_pixelart(path, args.colors, args.scale)
+    return report
+
+
+def run(args: argparse.Namespace) -> int:
+    context = workspace.context_from_args(args)
+    prompt = read_prompt(args)
+
+    refs = [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}")
+
+    endpoint = MODEL_EDIT if refs else MODEL
+
+    warning = check_size(parse_size(args.size))
+    if warning:
+        print(f"warning: {warning}")
+
+    if context.dry_run:
+        # Uploading a reference costs nothing but is still a request; a dry run names
+        # the files it would send instead of sending them.
+        payload = build_payload(args, prompt, [str(one) for one in refs])
+        fal.show(endpoint, payload)
+        return 0
+
+    fal.require_key()
+    # Before the upload and before the call: the text has to survive a run that fails
+    # halfway, and a --prompt-file can be edited the moment this returns — R2.4.
+    context.keep_prompt(prompt)
+    uploaded = [fal.upload(one) for one in refs]
+    payload = build_payload(args, prompt, uploaded)
+    result = fal.call(endpoint, payload)
+
+    urls = fal.urls_in(result)
+    if not urls:
+        raise ValueError(f"{endpoint} returned no image; nothing to write")
+
+    out = context.ensure_out()
+    written = [
+        fal.download(url, out / _name(context.kind or "anchor", index, len(urls)))
+        for index, url in enumerate(urls)
+    ]
+    context.paid_call(endpoint=endpoint, payload=payload, urls=urls, files=written)
+
+    reports = [post_process(path, args) for path in written]
+    context.record(endpoint=endpoint, images=[path.name for path in written], reports=reports)
+
+    for path, report in zip(written, reports, strict=True):
+        grid = report.get("pixelart")
+        found = f"  grid {grid['cols']}x{grid['rows']}  {grid['colours']} colours" if grid else ""
+        print(f"{path}{found}")
+    return 0
+
+
+def _name(kind: str, index: int, total: int) -> str:
+    """The file, named after what it is rather than after the stage that made it.
+
+    `--count 4` gives four candidates for one prompt, and they are numbered from one
+    rather than from zero: the number is what somebody says out loud when picking.
+    """
+    return f"{kind}.png" if total == 1 else f"{kind}-{index + 1}.png"

spritegen/stages/board.py

@@ -0,0 +1,68 @@
+"""Close every matted board into a row of a sprite sheet.
+
+The only free stage. Everything it does is local, which is why it is worth re-running:
+a row that came out wrong costs nothing to rebuild from a board that was paid for once.
+
+The work itself is in `sheet`, pinned byte for byte by `tests/parity`. This is the part
+that knows about assets — which boards to read, where the rows go, and what to record.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import sheet, workspace
+
+
+def run(args: argparse.Namespace) -> int:
+    context = workspace.context_from_args(args)
+    sources = context.source_files("*.png")
+    # A mask sits beside its cut and is not a board; matting one would double every row.
+    sources = [path for path in sources if not path.name.endswith(".mask.png")]
+    if not sources:
+        raise workspace.StageRefused(f"{context.asset}: no board to close in {context.source}")
+
+    grid = sheet.parse_grid(args.grid)
+    out = context.ensure_out()
+    reports: dict[str, dict] = {}
+
+    for source in sources:
+        row = out / f"{source.stem}.row.png"
+        gif = None if args.no_gif else out / f"{source.stem}.row.gif"
+        # Keyed by what was written, not by what was read. The two live in different
+        # directories, and reporting the source's name under the output's directory
+        # names a path that does not exist.
+        reports[row.name] = sheet.board_to_row(
+            source,
+            row,
+            grid=grid,
+            frames=args.frames or None,
+            cell=args.cell,
+            scale=args.scale or None,
+            fit=args.fit,
+            art=args.art,
+            colors=args.colors,
+            alpha_floor=args.alpha_floor,
+            alpha_ceil=args.alpha_ceil,
+            chroma=args.chroma,
+            tol=args.tol,
+            feather=args.feather,
+            chroma_mode=args.chroma_mode,
+            gif=gif,
+            fps=args.fps,
+        )
+
+    context.record(grid=args.grid, cell=args.cell, art=args.art, rows=reports)
+
+    for name, report in reports.items():
+        native = f"  native {report['native']}" if report["native"] else ""
+        print(
+            f"{out / name}{native}  union {report['union']}, scale {report['scale']}x, "
+            f"placed {report['placed']} at {report['offset']}"
+        )
+        if report["overflow"]:
+            print(
+                f"warning: {name} does not fit the cell; give a smaller --scale, "
+                f"or --fit to bring it down"
+            )
+    return 0

spritegen/stages/matte.py

@@ -0,0 +1,209 @@
+"""Cut the board's background by segmentation rather than by colour.
+
+Absorbed from the `bg_remove.py` this grew out of. It sits next to `anchor`'s `--transparent`
+because the two fail differently: a chroma key decides by distance to one colour, so
+wherever the subject is near that colour it eats art, and wherever the key painted over
+a thin contour it leaves halo. Hair is the worst of it — a strand is thinner than the
+tolerance band.
+
+Segmentation decides by asking what the subject is, so it has neither problem. Two
+options carry the result: `Matting` returns continuous alpha instead of a hard cut, and
+`refine_foreground` pulls the background back out of the RGB of edge pixels. The second
+is what kills the halo, not the alpha.
+
+**Two backends, and `local` is the default.** `--backend local` runs BiRefNet through
+`rembg` on this machine — the same family of model, no invoice, and on a GPU no slower.
+`--backend fal` is the paid endpoint, for a machine with neither the extra installed nor
+a GPU worth using. Everything downstream is identical: the same files land in the same
+directory with the same names, and `board` cannot tell which one ran.
+
+**Several images go up as one, on the paid backend.** Sent separately they are several
+charges and several 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. Joined, the endpoint answers
+once, for all of them. What it costs is resolution: the endpoint operates at a fixed
+size, so four 1024 images join into exactly the default 2048 and lose nothing, while
+four 1400 boards do not fit and the stage says so before spending. `--no-join` goes back
+to one call each.
+
+The local backend does not join, and does not need to. Joining bought two things: one
+charge instead of six, and one decision instead of six. Locally the first is worth
+nothing, and the second comes free from reusing one session across every frame — while
+joining would still cost the resolution. So each frame is cut at its own full size.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import atlas, fal, imaging, matting, workspace
+
+MODEL = "fal-ai/birefnet/v2"
+
+
+def build_payload(args: argparse.Namespace) -> dict:
+    """The payload, without the image, which is added once the upload has a URL."""
+    return {
+        "model": args.variant,
+        "operating_resolution": args.resolution,
+        "refine_foreground": not args.no_refine,
+        "output_format": "png",
+        "output_mask": bool(args.mask),
+    }
+
+
+def _cut_one(context, payload: dict, source: Path, dest: Path, want_mask: bool) -> list[Path]:
+    """One paid call: upload, cut, download, record. Returns what it wrote."""
+    sent = {**payload, "image_url": fal.upload(source)}
+    result = fal.call(MODEL, sent)
+
+    url = (result.get("image") or {}).get("url")
+    if not url:
+        raise ValueError(f"{MODEL} returned no image for {source.name}")
+
+    written = [fal.download(url, dest)]
+    fetched = [url]
+    if want_mask:
+        mask_url = (result.get("mask_image") or {}).get("url")
+        if mask_url:
+            written.append(fal.download(mask_url, dest.with_name(f"{dest.stem}.mask.png")))
+            fetched.append(mask_url)
+        else:
+            print(f"warning: no mask came back for {source.name}")
+
+    # The uploaded URL is kept out of the record by `ledger.redact`, for every stage
+    # at once rather than by each one remembering to strip it. Only the URLs actually
+    # fetched are recorded: `urls_in` finds every `url` in the response, and a mask
+    # nobody asked for has no local copy behind it — recording it would persist a live
+    # link to something this asset does not hold.
+    context.paid_call(endpoint=MODEL, payload=sent, urls=fetched, files=written)
+    return written
+
+
+def run_local(args: argparse.Namespace, context, sources: list[Path]) -> int:
+    """Cut every frame here, with one session, and spend nothing.
+
+    No `paid_call`, because there was none. `--dry-run` still exists and still prints
+    what would happen: the point of it on this backend is not the money but seeing what
+    would be written before it is.
+    """
+    if context.dry_run:
+        where = "GPU" if matting.on_gpu() else "CPU"
+        model = args.model or "the configured model"
+        print(f"dry run: {model} locally on the {where}, one session for all of them")
+        for source in sources:
+            print(f"  {source}")
+        return 0
+
+    matting.require_rembg()
+    if not matting.on_gpu():
+        print("warning: onnxruntime reports no GPU; this runs on the CPU and is slow")
+
+    out = context.ensure_out()
+    current = matting.session(args.model)
+    alpha = {}
+    for source in sources:
+        alpha[source.name] = matting.cut_file(
+            source, out / source.name, current=current, refine=not args.no_refine
+        )
+
+    context.record(
+        endpoint=None,
+        backend="local",
+        model=args.model or matting.DEFAULT_MODEL,
+        images=list(alpha),
+        alpha=alpha,
+        joined=None,
+    )
+    for name, stats in alpha.items():
+        print(
+            f"{out / name}  {stats['size']}  "
+            f"{stats['transparent_px']:,} transparent, {stats['partial_px']:,} at the edge"
+        )
+    return 0
+
+
+def run(args: argparse.Namespace) -> int:
+    context = workspace.context_from_args(args)
+    sources = context.source_files("*.png")
+    if not sources:
+        raise workspace.StageRefused(f"{context.asset}: nothing to matte in {context.source}")
+
+    from .. import settings
+
+    backend = args.backend or settings.load().matte_backend
+    if backend == "local":
+        return run_local(args, context, sources)
+
+    payload = build_payload(args)
+    joining = len(sources) > 1 and not args.no_join
+
+    if context.dry_run:
+        fal.show(MODEL, {**payload, "image_url": "<upload>"})
+        if joining:
+            print(f"would join {len(sources)} images and cut them in 1 paid call")
+        else:
+            count = len(sources)
+            print(f"would cut {count} image{'' if count == 1 else 's'}, one call each")
+        return 0
+
+    fal.require_key()
+    out = context.ensure_out()
+    written: list[Path] = []
+    layout = None
+
+    if joining:
+        # Under a subdirectory: the joined image and its cut are what was paid for and
+        # worth keeping, but `board` globs *.png here and must not mistake them for
+        # boards of their own.
+        scratch = out / "_join"
+        layout = atlas.pack(sources, scratch / "joined.png")
+        if not atlas.fits(layout, args.resolution):
+            # Said before spending, not after: the loss is in the upload, and by the
+            # time the cut comes back there is nothing to decide.
+            print(
+                f"warning: the joined image is {layout['size']} against an operating "
+                f"resolution of {args.resolution}; detail is lost on the way in. "
+                f"--no-join sends them one at a time at full size."
+            )
+        cut_atlas = scratch / "joined.cut.png"
+        _cut_one(context, payload, scratch / "joined.png", cut_atlas, args.mask)
+        written = atlas.unpack(cut_atlas, layout, out)
+        if args.mask:
+            mask = cut_atlas.with_name(f"{cut_atlas.stem}.mask.png")
+            if mask.is_file():
+                written += atlas.unpack(mask, _mask_layout(layout), out)
+    else:
+        for source in sources:
+            written += _cut_one(context, payload, source, out / source.name, args.mask)
+
+    alpha = {
+        path.name: imaging.measure_alpha(path)
+        for path in written
+        if not path.name.endswith(".mask.png")
+    }
+    context.record(
+        endpoint=MODEL,
+        images=[path.name for path in written],
+        alpha=alpha,
+        joined=layout,
+    )
+
+    for name, stats in alpha.items():
+        print(
+            f"{out / name}  {stats['size']}  "
+            f"{stats['transparent_px']:,} transparent, {stats['partial_px']:,} at the edge"
+        )
+    return 0
+
+
+def _mask_layout(layout: dict) -> dict:
+    """The same boxes, named for the masks they cut out of the joined mask."""
+    return {
+        **layout,
+        "placed": [
+            {**entry, "name": f"{Path(entry['name']).stem}.mask.png"}
+            for entry in layout["placed"]
+        ],
+    }

spritegen/stages/motion.py

@@ -0,0 +1,164 @@
+"""Transfer movement from a driving clip onto the anchor, or onto a pose.
+
+The alternative to `video`, and the difference is where the movement comes from. `video`
+asks a model to invent a walk and hopes the result is a cycle. This hands the model a
+clip built from a reference sheet the game already ships, and the model's job is only to
+put the new character through that movement — identity from the anchor, motion from the
+clip.
+
+That is the answer to what `plans/character-forge.md` measured: generating frame by
+frame moved the head-and-torso region 0.25 between steps against the reference's 0.11,
+because the model redrew the character in every cell instead of moving it. A pose-driven
+endpoint cannot redraw it, because the anchor is what pins the appearance.
+
+The reference sheet is named on the command line, and that is deliberate rather than an
+exception to R3.2: it is a shared game asset, like a prompt file, not something the asset
+directory holds. Everything written still goes to the asset.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import clip, drive, endpoints, fal, workspace
+
+
+def parse_set(pairs: list[str] | None, endpoint: endpoints.Endpoint) -> dict:
+    """`NAME=VALUE` pairs, checked against the endpoint before anything is spent — R4.4.
+
+    Values are read as JSON when they parse as JSON, so `true`, `7` and `"regular"` all
+    arrive as the type the endpoint's schema expects rather than as strings.
+    """
+    import json
+
+    settings: dict = {}
+    for pair in pairs or []:
+        name, sep, raw = pair.partition("=")
+        if not sep:
+            raise ValueError(f"an endpoint option is NAME=VALUE; got {pair!r}")
+        try:
+            value = json.loads(raw)
+        except json.JSONDecodeError:
+            value = raw
+        endpoint.check(name, value)
+        settings[name] = value
+    return settings
+
+
+def build_payload(
+    endpoint: endpoints.Endpoint,
+    image_url: str,
+    video_url: str,
+    prompt: str,
+    settings: dict,
+) -> dict:
+    """The payload as this endpoint takes it."""
+    return {
+        "image_url": image_url,
+        "video_url": video_url,
+        # Defaults first, so a prompt given here wins over an endpoint that carries an
+        # empty one only to satisfy its schema. `run` has already refused a prompt for
+        # an endpoint that does not declare one.
+        **endpoint.defaults,
+        **({"prompt": prompt} if prompt else {}),
+        **settings,
+    }
+
+
+def driving_clip(args: argparse.Namespace, out: Path) -> tuple[Path, dict]:
+    """The clip that carries the movement, built or handed over.
+
+    `--clip` exists for a clip that already is what it should be — a previous run's, or
+    footage. Everything else comes from a sheet, because that is the movement this
+    project has already measured.
+    """
+    if args.clip:
+        given = Path(args.clip)
+        if not given.is_file():
+            raise FileNotFoundError(f"no driving clip at {given}")
+        return given, {"source": str(given)}
+
+    if not args.sheet:
+        raise ValueError("the motion stage needs --sheet, or --clip")
+    sheet = Path(args.sheet)
+    if not sheet.is_file():
+        raise FileNotFoundError(f"no reference sheet at {sheet}")
+
+    built = out / "driving.mp4"
+    report = drive.build(
+        sheet,
+        built,
+        row=args.row,
+        frames=args.sheet_frames or None,
+        target=args.target,
+        fps=args.drive_fps,
+        seconds=args.seconds,
+    )
+    return built, {"source": str(sheet), **report}
+
+
+def run(args: argparse.Namespace) -> int:
+    context = workspace.context_from_args(args)
+    endpoint = endpoints.get(args.endpoint)
+    settings = parse_set(args.set, endpoint)
+    if args.prompt:
+        # `--prompt` is one of this stage's own flags, but it is still an endpoint
+        # option: only one of the three declares it, and the other two would be paid to
+        # ignore it.
+        endpoint.check("prompt", args.prompt)
+    pick = clip.parse_pick(args.pick)
+
+    # A pose-driven endpoint takes one image and deforms it, so there is no last frame
+    # here — only which image the movement is applied to.
+    from .video import first_and_last
+
+    anchor, _ = first_and_last(context, args)
+
+    if context.dry_run:
+        # The driving clip is built even for a dry run: it costs nothing, it is the part
+        # most likely to be wrong, and a payload naming a clip nobody looked at is not
+        # what a dry run is for. It goes beside the stage's output rather than into it,
+        # because a dry run that filled `board/` would make the real run look already
+        # done and be refused.
+        built, report = driving_clip(args, context.directory / "_dry")
+        fal.show(
+            endpoint.id,
+            build_payload(endpoint, str(anchor), str(built), args.prompt, settings),
+        )
+        print(f"driving clip: {built}  {report.get('frames', '?')} frames")
+        return 0
+
+    fal.require_key()
+    out = context.ensure_out()
+    built, report = driving_clip(args, out)
+
+    payload = build_payload(endpoint, fal.upload(anchor), fal.upload(built), args.prompt, settings)
+    result = fal.call(endpoint.id, payload)
+
+    found = fal.urls_in(result)
+    if not found:
+        raise ValueError(f"{endpoint.id} returned no clip")
+
+    animated = fal.download(found[0], out / "clip.mp4")
+    frames = clip.decode_frames(animated)
+    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.id, payload=payload, urls=found, files=[animated, board])
+    context.record(
+        endpoint=endpoint.id,
+        driving=report,
+        clip="clip.mp4",
+        board="board.png",
+        decoded=len(frames),
+        indices=indices,
+        grid=f"{cols}x{rows}",
+        settings=settings,
+    )
+
+    print(f"{built}  driving, {report.get('frames', '?')} frames")
+    print(f"{animated}  {len(frames)} frames decoded")
+    print(f"{board}  {len(chosen)} frames at {indices}, packed {cols}x{rows}")
+    return 0