"""Generation backend interface. A backend turns a *conditioning render* (the current state of the model seen from one camera: textured where projections exist, plain clay elsewhere) plus a prompt and optional reference images into an image aligned with that render. """ from __future__ import annotations import io import base64 from dataclasses import dataclass, field from typing import Any import numpy as np from PIL import Image class PendingGeneration(Exception): """Raised by asynchronous/external backends when the image is not available yet.""" @dataclass class GenRequest: image: Image.Image | None # conditioning render, RGB (None: text-to-image, see Backend.text_to_image) prompt: str # fully composed instruction prompt width: int = 1024 height: int = 1024 seed: int = 0 task: str = "view" # view | repair | replace | upscale mask: Image.Image | None = None # L, white = region to (re)paint references: list[tuple[Image.Image, str]] = field(default_factory=list) # (image, role) negative_prompt: str = "" name: str = "" # view / layer name (used by file backends and logs) context: dict[str, Any] = field(default_factory=dict) # camera, gl, mesh ... for synthetic backends class Backend: name = "base" #: whether the backend reads ``GenRequest.mask`` natively (otherwise the mask is drawn into the image) native_mask = False #: maximum number of extra reference images understood max_references = 0 #: whether ``GenRequest.image`` may be None (generate from the prompt alone) text_to_image = False def generate(self, req: GenRequest) -> Image.Image: # pragma: no cover - interface raise NotImplementedError def describe(self) -> dict: return {"name": self.name, "native_mask": self.native_mask, "max_references": self.max_references, "text_to_image": self.text_to_image} def close(self) -> None: pass def to_data_url(img: Image.Image, fmt: str = "PNG") -> str: buf = io.BytesIO() img.save(buf, format=fmt) mime = "image/png" if fmt.upper() == "PNG" else "image/jpeg" return f"data:{mime};base64," + base64.b64encode(buf.getvalue()).decode() def from_data_url(url: str) -> Image.Image: b64 = url.split(",", 1)[1] if url.startswith("data:") else url return Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGB") def fit_output(img: Image.Image, width: int, height: int) -> Image.Image: """Bring a generated image back to the request size (center-crop to aspect, then resize). Within 5 % of the aspect it only resizes: Spaces that follow the input's framing round its size to multiples of 32 (1024 x 384 came back 1664 x 640), and cropping that would shift the picture against its input.""" img = img.convert("RGB") if img.size == (width, height): return img w, h = img.size target = width / height if abs(np.log((w / h) / target)) > 0.05: if w / h > target: nw = int(round(h * target)) img = img.crop(((w - nw) // 2, 0, (w - nw) // 2 + nw, h)) else: nh = int(round(w / target)) img = img.crop((0, (h - nh) // 2, w, (h - nh) // 2 + nh)) return img.resize((width, height), Image.LANCZOS)