custom_nodes/ComfyUI-BFSNodes/multiref_sheet_node.py

"""Multi-Ref Sheet Builder — combine 1-5 reference images into the single

composite reference sheet used by the multi-ref LTX-2 LoRA (source_id=2,

layout=overlap). Same grid convention as the training pipeline's

build_multiref_sheet.py: fixed 512x512 panels, deterministic grid by count

(1x1, 2x1, 3x1, 2x2, 3-top+2-bottom), centered with padding onto a fixed

1536x1024 canvas so every sheet is the same resolution regardless of how

many refs are plugged in.



Panel order = image index order (ref_image_1 -> image0, ref_image_2 ->

image1, ...), matching the training data's image0/image1/... convention.

"""
import torch
from PIL import Image

from .util import tensor_to_pil, pil_to_tensor

CATEGORY = "BFS/multiref"

PANEL_SIZE = 512
CANVAS_W, CANVAS_H = 1536, 1024
BG_COLOR = (255, 255, 255)

# row layout per ref count: list of ints = panels per row, top to bottom.
LAYOUTS = {
    1: [1],
    2: [2],
    3: [3],
    4: [2, 2],
    5: [3, 2],
}


def _cover_resize_crop(img: Image.Image, size: int) -> Image.Image:
    """Resize+center-crop to exactly fill a size x size square (no stretch, crops excess)."""
    img = img.convert("RGB")
    w, h = img.size
    scale = max(size / w, size / h)
    nw, nh = round(w * scale), round(h * scale)
    img = img.resize((nw, nh), Image.LANCZOS)
    x0, y0 = (nw - size) // 2, (nh - size) // 2
    return img.crop((x0, y0, x0 + size, y0 + size))


def _justified_compose(imgs, rows_counts, canvas_w, canvas_h, bg):
    """Row-justified layout (no cropping, no distortion) -- identical algorithm to

    build_multiref_sheet.py's _justified_compose, kept in sync so inference-time

    sheets match training-time sheets exactly. Each row is split into

    `rows_counts[i]` images; every image in a row shares that row's height, and

    its width = row_height * (image's own aspect ratio) -- one uniform scale

    factor per image, so nothing is stretched.



    Each row's natural height fills canvas_w at scale=1. If all rows fit within

    canvas_h, they're drawn at natural size (leftover vertical space -> a single

    top+bottom bar, whole block centered) -- never blown up past canvas_w. Only

    if rows would collectively overflow canvas_h do all rows shrink by one

    shared factor < 1, giving a single shared pair of side bars instead of

    per-panel scattered padding.

    """
    it = iter(imgs)
    rows = []
    for count in rows_counts:
        row_imgs = [next(it) for _ in range(count)]
        aspects = [im.width / im.height for im in row_imgs]
        rows.append((row_imgs, aspects))

    natural_heights = [canvas_w / sum(aspects) for _, aspects in rows]
    scale = min(1.0, canvas_h / sum(natural_heights))

    row_heights = [round(nat_h * scale) for nat_h in natural_heights]
    drift_h = round(sum(natural_heights) * scale) - sum(row_heights)
    if row_heights:
        row_heights[-1] += drift_h

    sheet = Image.new("RGB", (canvas_w, canvas_h), bg)
    y = (canvas_h - sum(row_heights)) // 2
    for (row_imgs, aspects), row_h in zip(rows, row_heights):
        widths = [max(1, round(row_h * a)) for a in aspects]
        row_w = sum(widths)
        x = (canvas_w - row_w) // 2
        for im, w_i in zip(row_imgs, widths):
            resized = im.convert("RGB").resize((max(1, w_i), max(1, row_h)), Image.LANCZOS)
            sheet.paste(resized, (x, y))
            x += w_i
        y += row_h
    return sheet


def _cover_justified_compose(imgs, rows_counts, canvas_w, canvas_h, bg):
    """Row-justified layout, but COVER the canvas instead of contain -- fills both

    width and height completely, cropping the minimum necessary (like

    _cover_resize_crop, applied to the whole grid block instead of per-panel).

    Identical algorithm to build_multiref_sheet.py's _cover_justified_compose,

    kept in sync so inference-time sheets match training-time sheets exactly."""
    it = iter(imgs)
    rows = []
    for count in rows_counts:
        row_imgs = [next(it) for _ in range(count)]
        aspects = [im.width / im.height for im in row_imgs]
        rows.append((row_imgs, aspects))

    natural_heights = [canvas_w / sum(aspects) for _, aspects in rows]
    h1 = sum(natural_heights)

    if h1 >= canvas_h:
        # overfill: each row already fills canvas_w exactly at scale=1 (by construction
        # of natural_heights) -- keep that, crop the excess height after assembly.
        row_heights = [round(nh) for nh in natural_heights]
        block_w = canvas_w
    else:
        # underfill: scale UP so total height == canvas_h; every row becomes wider
        # than canvas_w by that same factor -- crop the excess width after assembly.
        scale = canvas_h / h1
        row_heights = [round(nh * scale) for nh in natural_heights]
        block_w = max(canvas_w, round(canvas_w * scale))

    block = Image.new("RGB", (block_w, sum(row_heights)), bg)
    y = 0
    for (row_imgs, aspects), row_h in zip(rows, row_heights):
        widths = [max(1, round(row_h * a)) for a in aspects]
        row_w = sum(widths)
        x = (block_w - row_w) // 2
        for im, w_i in zip(row_imgs, widths):
            resized = im.convert("RGB").resize((max(1, w_i), max(1, row_h)), Image.LANCZOS)
            block.paste(resized, (x, y))
            x += w_i
        y += row_h

    bw, bh = block.size
    x0 = max(0, (bw - canvas_w) // 2)
    y0 = max(0, (bh - canvas_h) // 2)
    return block.crop((x0, y0, x0 + canvas_w, y0 + canvas_h))


def compose_sheet(imgs, panel_size=PANEL_SIZE, canvas_w=CANVAS_W, canvas_h=CANVAS_H, bg=BG_COLOR, fit_mode="crop"):
    """fit_mode: 'crop' fills each fixed-size panel completely (crops excess, current

    default, matches the training data); 'fit' uses a row-justified layout that keeps

    every pixel of every reference (no cropping, no distortion) while maximizing

    canvas coverage (can underfill on one axis); 'cover' row-justifies AND fills the

    entire canvas on both axes, cropping the minimum shared/symmetric amount needed

    -- no background bars."""
    n = len(imgs)
    if not 1 <= n <= 5:
        raise ValueError(f"expected 1-5 reference images, got {n}")
    rows = LAYOUTS[n]

    if fit_mode == "cover":
        return _cover_justified_compose(imgs, rows, canvas_w, canvas_h, bg)

    if fit_mode == "fit":
        return _justified_compose(imgs, rows, canvas_w, canvas_h, bg)

    native_w = max(rows) * panel_size
    native_h = len(rows) * panel_size
    native = Image.new("RGB", (native_w, native_h), bg)

    it = iter(imgs)
    for row_idx, count in enumerate(rows):
        row_w = count * panel_size
        x_offset = (native_w - row_w) // 2  # center short rows (e.g. bottom row of a 5-ref sheet)
        y = row_idx * panel_size
        for col in range(count):
            panel = _cover_resize_crop(next(it), panel_size)
            x = x_offset + col * panel_size
            native.paste(panel, (x, y))

    sheet = Image.new("RGB", (canvas_w, canvas_h), bg)
    px = (canvas_w - native_w) // 2
    py = (canvas_h - native_h) // 2
    sheet.paste(native, (px, py))
    return sheet


class MultiRefSheetBuilder:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "fit_mode": (["crop", "fit", "cover"], {
                    "default": "crop",
                    "tooltip": "crop: zoom+center-crop to fill each panel completely (matches training data, "
                               "may cut off edges). fit: scale each reference down to fit entirely inside its "
                               "panel with no cropping (preserves every pixel, aspect ratio never distorted -- "
                               "one uniform scale factor for both axes -- leftover space padded with background). "
                               "cover: row-justified like fit, but fills the WHOLE 1536x1024 canvas on both axes "
                               "(no background bars) by cropping the minimum shared amount needed.",
                }),
            },
            "optional": {
                "ref_image_1": ("IMAGE", {"tooltip": "image0 in the compositional prompt (anchor)."}),
                "ref_image_2": ("IMAGE", {"tooltip": "image1."}),
                "ref_image_3": ("IMAGE", {"tooltip": "image2."}),
                "ref_image_4": ("IMAGE", {"tooltip": "image3."}),
                "ref_image_5": ("IMAGE", {"tooltip": "image4."}),
            },
        }

    RETURN_TYPES = ("IMAGE", "INT", "STRING")
    RETURN_NAMES = ("sheet", "n_refs", "debug")
    FUNCTION = "build"
    CATEGORY = CATEGORY
    DESCRIPTION = ("Combines 1-5 plugged-in reference images into the fixed 1536x1024 composite "
                   "sheet the multi-ref LoRA was trained on. Leave slots empty for fewer refs; "
                   "an empty slot is simply skipped, not padded with blank content.")

    def build(self, fit_mode="crop", ref_image_1=None, ref_image_2=None, ref_image_3=None,

              ref_image_4=None, ref_image_5=None):
        slots = [ref_image_1, ref_image_2, ref_image_3, ref_image_4, ref_image_5]
        provided = [s for s in slots if s is not None]
        if not provided:
            raise ValueError("MultiRefSheetBuilder needs at least one ref_image_N input.")

        pil_imgs = [tensor_to_pil(t[0] if t.dim() == 4 else t) for t in provided]
        sheet = compose_sheet(pil_imgs, fit_mode=fit_mode)
        sheet_t = pil_to_tensor(sheet).unsqueeze(0)  # [1,H,W,C]

        dbg = (f"MultiRefSheet | {len(provided)} refs -> {CANVAS_W}x{CANVAS_H} "
               f"({'+'.join(str(r) for r in LAYOUTS[len(provided)])} grid, fit_mode={fit_mode})")
        return (sheet_t, len(provided), dbg)


NODE_CLASS_MAPPINGS = {"BFSMultiRefSheetBuilder": MultiRefSheetBuilder}
NODE_DISPLAY_NAME_MAPPINGS = {"BFSMultiRefSheetBuilder": "Multi-Ref Sheet Builder"}