comicforge 0.0.1__py3-none-any.whl

comicforge/inspire.py

@@ -0,0 +1,246 @@
+"""Generate reference images from a project theme + per-item descriptions.
+
+These images are **inspiration** for hand/LLM-authored SVG art — they are *not*
+shipped assets. The idea: describe a character or scene in words, blend it with a
+project-wide theme (style, color scale, mood), and let an image model paint a
+reference to author crisp SVG from. Do not auto-vectorize the output; it breaks
+overlay registration and the editable slot structure.
+
+    comicforge inspire examples/pes/references.yaml
+
+Requires the optional `inspire` extra::
+
+    pip install "comicforge[inspire]"
+
+and a ``REPLICATE_API_TOKEN`` (read from the environment, or a ``.env`` file next
+to the references spec / in the cwd). Use ``--dry-run`` to preview the composed
+prompts without calling the API (and without needing a token).
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+DEFAULT_MODEL = "google/imagen-3"
+DEFAULT_ASPECT = "1:1"
+# Imagen on Replicate caps at ~6 req/min; pause between live calls.
+RATE_LIMIT_SECONDS = 11
+
+
+@dataclass
+class Theme:
+    """Project-wide style applied to every generated reference image."""
+
+    style: str = ""
+    palette: list[str] = field(default_factory=list)
+    mood: str = ""
+    negative: str = "No text, no letters, no words, no watermark, no signature."
+    aspect_ratio: str = DEFAULT_ASPECT
+    model: str = DEFAULT_MODEL
+
+
+@dataclass
+class Item:
+    """One thing to depict: an id (→ filename) and a free-text description."""
+
+    id: str
+    prompt: str
+
+
+def load_theme(path: Path) -> Theme:
+    """Load ``theme.yaml``. A missing file yields an empty (defaults) theme."""
+    if not path.exists():
+        return Theme()
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    palette = data.get("palette") or []
+    if isinstance(palette, str):
+        palette = [palette]
+    return Theme(
+        style=str(data.get("style", "")).strip(),
+        palette=[str(c) for c in palette],
+        mood=str(data.get("mood", "")).strip(),
+        negative=str(data.get("negative", Theme.negative)).strip(),
+        aspect_ratio=str(data.get("aspect_ratio", DEFAULT_ASPECT)),
+        model=str(data.get("model", DEFAULT_MODEL)),
+    )
+
+
+def load_items(path: Path) -> list[Item]:
+    """Load the references spec — a bare list, or a mapping with ``items:``.
+
+    Each entry needs an id (``id`` / ``name``) and a description
+    (``prompt`` / ``description`` / ``desc``).
+    """
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    raw = data.get("items", []) if isinstance(data, dict) else data
+    if not isinstance(raw, list):
+        # malformed config, not a type bug -> ValueError is the right contract
+        raise ValueError(  # noqa: TRY004
+            f"{path}: expected a list of items (or an 'items:' key)"
+        )
+    items: list[Item] = []
+    for i, entry in enumerate(raw):
+        if not isinstance(entry, dict):
+            raise ValueError(f"{path}: item {i} is not a mapping")  # noqa: TRY004
+        ident = entry.get("id") or entry.get("name")
+        prompt = entry.get("prompt") or entry.get("description") or entry.get("desc")
+        if not ident or not prompt:
+            raise ValueError(f"{path}: item {i} needs both an id and a prompt")
+        items.append(Item(id=str(ident), prompt=str(prompt).strip()))
+    return items
+
+
+def build_prompt(theme: Theme, item: Item) -> str:
+    """Compose the final image prompt: theme style + subject + palette + mood."""
+    parts: list[str] = []
+    if theme.style:
+        parts.append(theme.style)
+    parts.append(f"Subject: {item.prompt}")
+    if theme.palette:
+        parts.append("Use this color palette: " + ", ".join(theme.palette) + ".")
+    if theme.mood:
+        parts.append(f"Mood: {theme.mood}.")
+    if theme.negative:
+        parts.append(theme.negative)
+    return "\n\n".join(parts)
+
+
+def _load_dotenv(*dirs: Path) -> None:
+    """Best-effort: load a ``.env`` from the given dirs if python-dotenv is present."""
+    try:
+        from dotenv import (  # noqa: PLC0415  # ty: ignore[unresolved-import]
+            load_dotenv,
+        )
+    except ImportError:
+        return
+    for d in dirs:
+        env = d / ".env"
+        if env.exists():
+            load_dotenv(env)
+
+
+def _generate_one(model: str, prompt: str, aspect_ratio: str) -> bytes:
+    """Call Replicate and return the raw image bytes."""
+    # lazy: only needed for live generation, keeps Replicate an optional dep
+    import replicate  # noqa: PLC0415  # ty: ignore[unresolved-import]
+
+    output = replicate.run(
+        model,
+        input={
+            "prompt": prompt,
+            "aspect_ratio": aspect_ratio,
+            "output_format": "png",
+        },
+    )
+    # Imagen returns a single FileOutput; some models return a list.
+    if isinstance(output, list):
+        output = output[0]
+    if hasattr(output, "read"):
+        return output.read()
+    raise RuntimeError(f"unexpected Replicate output: {type(output).__name__}")
+
+
+def generate(
+    refs_path: Path,
+    out_dir: Path | None = None,
+    *,
+    theme_path: Path | None = None,
+    only: set[str] | None = None,
+    force: bool = False,
+    review: bool = False,
+    dry_run: bool = False,
+) -> list[Path]:
+    """Generate reference images for every item in ``refs_path``.
+
+    Paths in the spec resolve against the spec's own directory. ``theme.yaml`` and
+    the output ``references/`` dir default to siblings of the spec. Each item
+    writes ``<id>.png`` plus an ``<id>.prompt.txt`` sidecar; ``--dry-run`` writes
+    only the sidecars. Returns the list of files written.
+    """
+    refs_path = refs_path.resolve()
+    base = refs_path.parent
+    theme = load_theme(theme_path.resolve() if theme_path else base / "theme.yaml")
+    items = load_items(refs_path)
+    out_dir = (out_dir or base / "references").resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if not dry_run:
+        _load_dotenv(base, Path.cwd())
+
+    written: list[Path] = []
+    targets = [it for it in items if only is None or it.id in only]
+    print(f"[inspire] {len(targets)} item(s) → {out_dir}  (model: {theme.model})")  # noqa: T201
+
+    for item in targets:
+        prompt = build_prompt(theme, item)
+        prompt_path = out_dir / f"{item.id}.prompt.txt"
+        prompt_path.write_text(prompt, encoding="utf-8")
+        written.append(prompt_path)
+
+        img_path = out_dir / f"{item.id}.png"
+        if dry_run:
+            print(f"  {item.id}: prompt written (dry-run)")  # noqa: T201
+            continue
+        if img_path.exists() and not force and only is None:
+            print(f"  {item.id}: cached, skipping")  # noqa: T201
+            continue
+
+        print(f"  {item.id}: generating…")  # noqa: T201
+        try:
+            data = _generate_one(theme.model, prompt, theme.aspect_ratio)
+        except Exception as e:  # surface and keep going on the rest
+            print(f"  {item.id}: FAILED — {e}")  # noqa: T201
+            continue
+        img_path.write_bytes(data)
+        written.append(img_path)
+        print(f"  {item.id}: wrote {img_path.name} ({len(data) // 1024} KB)")  # noqa: T201
+        time.sleep(RATE_LIMIT_SECONDS)
+
+    if review:
+        written.append(_write_review(out_dir, targets))
+
+    return written
+
+
+def _write_review(out_dir: Path, items: list[Item]) -> Path:
+    """Write a self-contained HTML grid of the generated images + prompts."""
+    cards: list[str] = []
+    for item in items:
+        img_path = out_dir / f"{item.id}.png"
+        if img_path.exists():
+            b64 = base64.b64encode(img_path.read_bytes()).decode("ascii")
+            src = f"data:image/png;base64,{b64}"
+        else:
+            src = ""
+        prompt_path = out_dir / f"{item.id}.prompt.txt"
+        prompt = prompt_path.read_text(encoding="utf-8") if prompt_path.exists() else ""
+        cards.append(
+            f'<div class="card">'
+            f'<img src="{src}" alt="{item.id}" loading="lazy">'
+            f"<div class=label>{item.id}</div>"
+            f"<details><summary>prompt</summary><pre>{prompt}</pre></details>"
+            f"</div>"
+        )
+    html = (
+        "<!doctype html><meta charset=utf-8><title>inspire review</title>"
+        "<style>body{font-family:sans-serif;padding:2rem;background:#fafafa}"
+        ".grid{display:grid;gap:1.5rem;"
+        "grid-template-columns:repeat(auto-fill,minmax(260px,1fr))}"
+        ".card{background:#fff;border-radius:12px;padding:1rem;text-align:center;"
+        "box-shadow:0 2px 8px rgba(0,0,0,.08)}"
+        ".card img{width:100%;border-radius:8px;background:#f0f0f0}"
+        ".label{margin-top:.5rem;font-weight:600}"
+        "details{margin-top:.5rem;text-align:left}"
+        "pre{font-size:.75rem;white-space:pre-wrap;background:#f5f5f5;"
+        "padding:.5rem;border-radius:4px}</style>"
+        f"<h1>inspire review · {len(items)} item(s)</h1>"
+        f"<div class=grid>{''.join(cards)}</div>"
+    )
+    path = out_dir / "review.html"
+    path.write_text(html, encoding="utf-8")
+    return path

comicforge/library.py

@@ -0,0 +1,235 @@
+"""Load the character library and compose a posed character.
+
+A character is an **identity** (name, label, …) that owns one or more **poses**.
+A pose is a body drawn in its own local viewBox; expressions ("face", …) are
+*shared* overlays authored once and re-registered onto each pose.
+
+Two on-disk shapes, both loaded here:
+
+*Flat (single pose):* the classic layout — everything in one viewBox::
+
+    <name>/
+      base.svg                 the body
+      <slot>-<variant>.svg     stackable overlays in the SAME viewBox
+      character.yaml           name, label, viewbox, slots, default
+
+*Posed (multiple poses):* the body changes between poses (sit vs walk), so each
+pose gets its own ``base.svg``; the shared overlays live at the character root
+and are translated onto each pose by an *anchor* (a reference point — e.g. the
+head centre — that the overlays are drawn around)::
+
+    <name>/
+      character.yaml           name, label, anchor, slots (SHARED), default, poses
+      <slot>-<variant>.svg     SHARED overlays, drawn around the canonical anchor
+      poses/
+        <pose>/
+          pose.yaml            viewbox, anchor, slots (pose-specific), default
+          base.svg             this pose's body
+          <slot>-<variant>.svg pose-specific overlays (optional)
+
+Composition = pose base + pose-specific overlays + shared overlays (each shifted
+by ``pose.anchor - character.anchor``), stacked in the pose's local viewBox, then
+wrapped in a ``<g transform>`` that places and scales it inside a panel.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+_SVG_INNER = re.compile(r"<svg[^>]*>(.*)</svg>", re.DOTALL)
+
+
+def _inner(svg_path: Path) -> str:
+    text = svg_path.read_text(encoding="utf-8")
+    m = _SVG_INNER.search(text)
+    if not m:
+        raise ValueError(f"{svg_path} is not a well-formed <svg>…</svg> file")
+    return m.group(1).strip()
+
+
+def _load_variants(dir_: Path, slots: dict[str, list[str]]) -> dict[str, str]:
+    """Read every ``<slot>-<variant>.svg`` overlay in *dir_* into inner markup."""
+    out: dict[str, str] = {}
+    for slot, names in slots.items():
+        for v in names:
+            out[f"{slot}-{v}"] = _inner(dir_ / f"{slot}-{v}.svg")
+    return out
+
+
+@dataclass
+class Pose:
+    """One body of a character, drawn in its own local viewBox."""
+
+    name: str
+    w: float
+    h: float
+    anchor: tuple[float, float]  # where shared overlays land in this pose
+    base: str  # inner svg markup
+    slots: dict[str, list[str]] = field(default_factory=dict)  # pose-specific
+    defaults: dict[str, str] = field(default_factory=dict)
+    variants: dict[str, str] = field(default_factory=dict)  # "slot-variant"
+
+
+@dataclass
+class Character:
+    name: str
+    label: str
+    anchor: tuple[float, float]  # canonical point shared overlays draw around
+    slots: dict[str, list[str]]  # SHARED slots (re-anchored onto each pose)
+    defaults: dict[str, str]  # shared defaults (may include "pose")
+    variants: dict[str, str]  # shared "slot-variant" -> inner
+    poses: dict[str, Pose]
+    default_pose: str
+
+    def resolve_pose(self, pose: str | None) -> Pose:
+        name = pose or self.default_pose
+        if name not in self.poses:
+            raise ValueError(
+                f"{self.name}: no pose '{name}'. Available: {list(self.poses)}"
+            )
+        return self.poses[name]
+
+    def slots_for(self, pose: str | None = None) -> dict[str, list[str]]:
+        """Every selectable slot for a pose: shared slots + that pose's own slots."""
+        return {**self.slots, **self.resolve_pose(pose).slots}
+
+    def compose_inner(self, selection: dict[str, str], pose: str | None = None) -> str:
+        """Inner SVG for this character in the chosen pose with the chosen variants."""
+        p = self.resolve_pose(pose)
+        parts = [p.base]
+
+        # pose-specific overlays: drawn directly in the pose's own coordinates
+        for slot in p.slots:  # manifest order = draw order
+            variant = selection.get(slot, p.defaults.get(slot))
+            if variant is None:
+                continue
+            if variant not in p.slots[slot]:
+                raise ValueError(
+                    f"{self.name}/{p.name}: slot '{slot}' has no variant "
+                    f"'{variant}'. Available: {p.slots[slot]}"
+                )
+            parts.append(p.variants[f"{slot}-{variant}"])
+
+        # shared overlays: authored around the canonical anchor, shifted onto this pose
+        dx, dy = p.anchor[0] - self.anchor[0], p.anchor[1] - self.anchor[1]
+        for slot in self.slots:
+            variant = selection.get(
+                slot, p.defaults.get(slot) or self.defaults.get(slot)
+            )
+            if variant is None:
+                continue
+            if variant not in self.slots[slot]:
+                raise ValueError(
+                    f"{self.name}: shared slot '{slot}' has no variant '{variant}'. "
+                    f"Available: {self.slots[slot]}"
+                )
+            inner = self.variants[f"{slot}-{variant}"]
+            if dx or dy:
+                inner = f'<g transform="translate({dx:.2f},{dy:.2f})">\n{inner}\n</g>'
+            parts.append(inner)
+        return "\n".join(parts)
+
+    def place(self, selection, cx, cy, height, flip=False, pose=None) -> str:
+        """Place the character centred at (cx, cy) scaled so it is `height` tall."""
+        p = self.resolve_pose(pose)
+        s = height / p.h
+        w, h = p.w * s, p.h * s
+        tx, ty = cx - w / 2, cy - h / 2
+        if flip:
+            transform = f"translate({tx + w:.2f},{ty:.2f}) scale({-s:.4f},{s:.4f})"
+        else:
+            transform = f"translate({tx:.2f},{ty:.2f}) scale({s:.4f})"
+        inner = self.compose_inner(selection, pose)
+        return f'<g transform="{transform}">\n{inner}\n</g>'
+
+
+def _load_character(cdir: Path) -> Character:
+    man = yaml.safe_load((cdir / "character.yaml").read_text(encoding="utf-8"))
+    name = man["name"]
+    label = man.get("label", name)
+    anchor = tuple(man.get("anchor", (0.0, 0.0)))
+    shared_slots = man.get("slots", {})
+    shared_defaults = man.get("default", {})
+    shared_variants = _load_variants(cdir, shared_slots)
+
+    poses: dict[str, Pose] = {}
+    if "poses" in man:
+        for pname in man["poses"]:
+            pdir = cdir / "poses" / pname
+            pman = yaml.safe_load((pdir / "pose.yaml").read_text(encoding="utf-8"))
+            pw, ph = pman["viewbox"]
+            pslots = pman.get("slots", {})
+            poses[pname] = Pose(
+                name=pname,
+                w=pw,
+                h=ph,
+                anchor=tuple(pman.get("anchor", anchor)),
+                base=_inner(pdir / "base.svg"),
+                slots=pslots,
+                defaults=pman.get("default", {}),
+                variants=_load_variants(pdir, pslots),
+            )
+        default_pose = shared_defaults.get("pose") or man["poses"][0]
+    else:
+        # flat single-pose character: the body + overlays live at the root, in one
+        # viewBox. The shared overlays sit at the canonical anchor (translate 0).
+        w, h = man["viewbox"]
+        poses["default"] = Pose(
+            name="default", w=w, h=h, anchor=anchor, base=_inner(cdir / "base.svg")
+        )
+        default_pose = "default"
+
+    return Character(
+        name=name,
+        label=label,
+        anchor=anchor,
+        slots=shared_slots,
+        defaults=shared_defaults,
+        variants=shared_variants,
+        poses=poses,
+        default_pose=default_pose,
+    )
+
+
+class Library:
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self._cache: dict[str, Character] = {}
+
+    def get(self, name: str) -> Character:
+        if name in self._cache:
+            return self._cache[name]
+        cdir = self.root / name
+        if not cdir.is_dir():
+            avail = [p.name for p in self.root.iterdir() if p.is_dir()]
+            raise KeyError(
+                f"character '{name}' not found in {self.root}. Have: {avail}"
+            )
+        char = _load_character(cdir)
+        self._cache[name] = char
+        return char
+
+    def manifest(self) -> dict:
+        """Machine-readable contract: every character, its poses, slots and variants."""
+        out = {}
+        for p in sorted(self.root.iterdir()):
+            if p.is_dir() and (p / "character.yaml").exists():
+                c = self.get(p.name)
+                entry: dict[str, object] = {
+                    "label": c.label,
+                    "slots": c.slots,  # shared across poses
+                    "default": c.defaults,
+                }
+                # only advertise poses for genuinely multi-pose characters
+                if list(c.poses) != ["default"]:
+                    entry["default_pose"] = c.default_pose
+                    entry["poses"] = {
+                        name: {"slots": pose.slots, "default": pose.defaults}
+                        for name, pose in c.poses.items()
+                    }
+                out[c.name] = entry
+        return out

comicforge/pixelart.py

@@ -0,0 +1,80 @@
+"""Tiny pixel-art helper.
+
+A sprite is a list of equal-length strings + a palette {char: color}.
+'.' (or space) = transparent. Returns inner SVG in local coords (cols x rows),
+placed into a panel the same way characters are.
+
+Sprites are loaded from a directory of YAML files via :class:`PixelLibrary`.
+Each ``<name>.yaml`` contains ``grid`` (list of strings) and ``palette``
+(dict of char -> color).  Inline ``{grid, palette}`` specs also work with no
+library.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+class PixelLibrary:
+    """Loads pixel-art sprites from ``<root>/<name>.yaml`` lazily, caching."""
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self._cache: dict[str, dict] = {}
+
+    def get(self, name: str) -> dict:
+        if name in self._cache:
+            return self._cache[name]
+        path = self.root / f"{name}.yaml"
+        if not path.exists():
+            avail = sorted(p.stem for p in self.root.glob("*.yaml"))
+            raise KeyError(
+                f"pixel art '{name}' not found in {self.root}. Available: {avail}"
+            )
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        self._cache[name] = data
+        return data
+
+
+def sprite_svg(grid: list[str], palette: dict[str, str], cell: float = 1.0) -> str:
+    rects = []
+    for r, row in enumerate(grid):
+        for c, ch in enumerate(row):
+            if ch in (".", " "):
+                continue
+            color = palette.get(ch, "#000000")
+            rects.append(
+                f'<rect x="{c * cell:.2f}" y="{r * cell:.2f}" '
+                f'width="{cell:.2f}" height="{cell:.2f}" fill="{color}"/>'
+            )
+    return f'<g shape-rendering="crispEdges">{"".join(rects)}</g>'
+
+
+def dims(grid: list[str]) -> tuple[int, int]:
+    return (max(len(r) for r in grid), len(grid))
+
+
+def resolve(
+    spec: dict,
+    pixel_library: PixelLibrary | None = None,
+) -> tuple[str, int, int]:
+    """spec: {art: <library name>} OR {grid: [...], palette: {...}}.
+
+    When ``spec`` has ``"art"``, a ``pixel_library`` must be provided.
+    Inline ``{grid, palette}`` works with no library.
+    Returns (inner_svg, cols, rows).
+    """
+    if "art" in spec:
+        if pixel_library is None:
+            raise ValueError(
+                f"pixel art '{spec['art']}' requires a pixel library "
+                "(pass pixel_library= or set pixel_dir: in the spec)"
+            )
+        b = pixel_library.get(spec["art"])
+        grid, palette = b["grid"], b["palette"]
+    else:
+        grid, palette = spec["grid"], spec.get("palette", {})
+    cols, rows = dims(grid)
+    return sprite_svg(grid, palette), cols, rows