Files
DumasNodes/dumas_clothing_layout_planner.py

517 lines
22 KiB
Python

"""Deterministic, object-agnostic inventory layout planning for ComfyUI."""
from __future__ import annotations
import json
import math
import re
from typing import Any
SIZE_WEIGHTS = {"small": 1.0, "medium": 2.0, "large": 3.0}
ASPECT_RATIOS = {"portrait": 0.7, "landscape": 1.5, "square": 1.0}
DEFAULT_BACKGROUND = "#EEE8DC"
VALID_UNITS = {"item", "pair"}
VALID_SIZES = set(SIZE_WEIGHTS)
VALID_ASPECTS = set(ASPECT_RATIOS)
def _bounded_number(value: Any, name: str, minimum: float, maximum: float) -> float:
try:
number = float(value)
except (TypeError, ValueError) as exc:
raise ValueError(f"{name} must be a number between {minimum} and {maximum}") from exc
if not minimum <= number <= maximum:
raise ValueError(f"{name} must be between {minimum} and {maximum}")
return number
def _positive_integer(value: Any, name: str) -> int:
try:
number = int(value)
except (TypeError, ValueError) as exc:
raise ValueError(f"{name} must be a positive integer") from exc
if number < 1:
raise ValueError(f"{name} must be a positive integer")
return number
def _parse_json(inventory_json: str) -> dict[str, Any]:
text = str(inventory_json or "").strip()
fenced = re.fullmatch(r"```(?:json)?\s*(.*?)\s*```", text, re.IGNORECASE | re.DOTALL)
if fenced:
text = fenced.group(1).strip()
if not text:
raise ValueError("inventory_json is empty; provide a JSON object containing an items list")
try:
value = json.loads(text)
except json.JSONDecodeError as exc:
repaired = _repair_vlm_json(text)
if repaired is None:
salvaged = _salvage_inventory(text)
if salvaged is not None:
return {"items": salvaged}
raise ValueError(
f"inventory_json is invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}. "
"Check that the VLM returned a complete JSON object with quoted strings."
) from exc
try:
value = json.loads(repaired)
except json.JSONDecodeError as repaired_exc:
salvaged = _salvage_inventory(text)
if salvaged is not None:
return {"items": salvaged}
raise ValueError(
f"inventory_json is invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}. "
f"Automatic VLM repair also failed at line {repaired_exc.lineno}, column {repaired_exc.colno}."
) from exc
if not isinstance(value, dict):
raise ValueError("inventory_json must be a JSON object with an 'items' list")
items = value.get("items", [])
if not isinstance(items, list):
raise ValueError("inventory_json.items must be a list")
return value
def _salvage_inventory(text: str) -> list[dict[str, Any]] | None:
"""Extract schema fields from item objects when one VLM string is broken."""
starts = [match.start() for match in re.finditer(r'\{\s*"id"\s*:', text)]
if not starts:
return None
items: list[dict[str, Any]] = []
fields = ("id", "name", "quantity", "unit", "size", "aspect_ratio", "description")
for index, start in enumerate(starts):
chunk = text[start:starts[index + 1] if index + 1 < len(starts) else len(text)]
item: dict[str, Any] = {}
for field in fields[:-1]:
match = re.search(rf'"{field}"\s*:\s*(?:"([^"\\]*(?:\\.[^"\\]*)*)"|(-?\d+))', chunk, re.DOTALL)
if not match:
continue
raw = match.group(1) if match.group(1) is not None else match.group(2)
if field == "quantity":
item[field] = int(raw)
else:
try:
item[field] = json.loads(f'"{raw}"')
except json.JSONDecodeError:
item[field] = raw
description_marker = re.search(r'"description"\s*:\s*"', chunk, re.DOTALL)
if description_marker:
tail = chunk[description_marker.end():]
next_field = re.search(r',\s*"(?:id|name|quantity|unit|size|aspect_ratio)"\s*:', tail, re.DOTALL)
if next_field:
tail = tail[:next_field.start()]
tail = tail.strip()
# Description is the final accepted field. Remove only structural
# suffixes; leave an incomplete final sentence intact.
tail = re.sub(r'\s*[,}\]]+\s*$', "", tail)
if tail.endswith('"'):
tail = tail[:-1]
item["description"] = tail.replace('\\n', '\n').replace('\\"', '"').strip()
if item.get("id") and item.get("name"):
items.append(item)
return items or None
def _repair_vlm_json(text: str) -> str | None:
"""Repair only safe, common VLM JSON damage.
VLMs frequently emit literal newlines in descriptions, leave a quote
unescaped inside prose, or stop before writing the final closing braces.
This scanner repairs those cases without changing field names or values.
It deliberately does not guess missing commas, keys, or inventory items.
"""
start = text.find("{")
if start < 0:
return None
source = text[start:]
output: list[str] = []
stack: list[str] = []
in_string = False
escaped = False
root_closed = False
index = 0
while index < len(source):
char = source[index]
if root_closed:
index += 1
continue
if in_string:
if escaped:
output.append(char)
escaped = False
elif char == "\\":
output.append(char)
escaped = True
elif char == '"':
lookahead = index + 1
while lookahead < len(source) and source[lookahead].isspace():
lookahead += 1
# A quote followed by normal prose is part of a VLM string;
# JSON string terminators are followed by structure.
if lookahead == len(source) or source[lookahead] in ",]}:":
output.append(char)
in_string = False
else:
output.append('\\"')
elif char in "\r\n":
output.append("\\n")
elif ord(char) < 32:
output.append(f"\\u{ord(char):04x}")
else:
output.append(char)
else:
if char == '"':
in_string = True
output.append(char)
elif char in "[{":
stack.append(char)
output.append(char)
elif char in "]}":
if stack and ((char == "]" and stack[-1] == "[") or (char == "}" and stack[-1] == "{")):
stack.pop()
output.append(char)
if not stack:
root_closed = True
else:
# Ignore trailing prose or an unmatched closing token.
pass
else:
output.append(char)
index += 1
if in_string:
output.append('"')
while stack:
output.append("]" if stack.pop() == "[" else "}")
repaired = re.sub(r",\s*([}\]])", r"\1", "".join(output)).strip()
return repaired if repaired.startswith("{") else None
def normalize_inventory(inventory_json: str) -> list[dict[str, Any]]:
"""Parse and validate inventory entries without inventing entries."""
raw_items = _parse_json(inventory_json).get("items", [])
normalized = []
seen_ids: set[str] = set()
for index, raw in enumerate(raw_items, 1):
if not isinstance(raw, dict):
raise ValueError(f"items[{index - 1}] must be an object")
item_id = str(raw.get("id", "")).strip()
name = str(raw.get("name", "")).strip()
if not item_id:
raise ValueError(f"items[{index - 1}] is missing a non-empty id")
if item_id in seen_ids:
raise ValueError(f"items[{index - 1}] duplicates inventory id '{item_id}'")
if not name:
raise ValueError(f"items[{index - 1}] is missing a non-empty name")
seen_ids.add(item_id)
unit = str(raw.get("unit", "item")).strip().lower() or "item"
size = str(raw.get("size", "medium")).strip().lower() or "medium"
aspect = str(raw.get("aspect_ratio", "square")).strip().lower() or "square"
if unit not in VALID_UNITS:
raise ValueError(f"item '{item_id}' has invalid unit '{unit}'; use item or pair")
if size not in VALID_SIZES:
raise ValueError(f"item '{item_id}' has invalid size '{size}'; use small, medium, or large")
if aspect not in VALID_ASPECTS:
raise ValueError(f"item '{item_id}' has invalid aspect_ratio '{aspect}'; use portrait, landscape, or square")
normalized.append({
"id": item_id,
"name": name,
"quantity": _positive_integer(raw.get("quantity", 1), f"item '{item_id}' quantity"),
"unit": unit,
"size": size,
"aspect_ratio": aspect,
"description": str(raw.get("description", "")).strip(),
})
return normalized
def _instances(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
result = []
for item in items:
quantity = item["quantity"]
for index in range(1, quantity + 1):
instance = dict(item)
instance["original_id"] = item["id"]
instance["instance"] = index
instance["id"] = item["id"] if quantity == 1 else f"{item['id']}_{index:03d}"
result.append(instance)
return result
def _grid_shape(count: int, canvas_width: int, canvas_height: int) -> tuple[int, int]:
columns = max(1, min(count, math.ceil(math.sqrt(count * canvas_width / canvas_height))))
return math.ceil(count / columns), columns
def _position_name(cx: float, cy: float) -> str:
vertical = "upper" if cy < 1 / 3 else "lower" if cy > 2 / 3 else "centre"
horizontal = "left" if cx < 1 / 3 else "right" if cx > 2 / 3 else "centre"
if vertical == "centre" and horizontal == "centre":
return "centre"
if vertical == "centre":
return f"centre-{horizontal}"
if horizontal == "centre":
return f"{vertical}-centre"
return f"{vertical}-{horizontal}"
def plan_layout(
inventory_json: str,
canvas_width: int = 1536,
canvas_height: int = 1024,
layout_mode: str = "balanced",
margin_percent: float = 5.0,
spacing_percent: float = 3.0,
) -> dict[str, Any]:
"""Return a deterministic, non-overlapping normalized rectangle plan."""
width = int(_bounded_number(canvas_width, "canvas_width", 64, 8192))
height = int(_bounded_number(canvas_height, "canvas_height", 64, 8192))
margin = _bounded_number(margin_percent, "margin_percent", 0, 40) / 100
spacing = _bounded_number(spacing_percent, "spacing_percent", 0, 20) / 100
mode = str(layout_mode or "balanced").lower()
if mode not in {"balanced", "grid"}:
raise ValueError("layout_mode must be balanced or grid")
items = normalize_inventory(inventory_json)
instances = _instances(items)
if not instances:
return {"canvas": {"width": width, "height": height}, "regions": [], "warnings": []}
rows, columns = _grid_shape(len(instances), width, height)
usable_x, usable_y = margin, margin
usable_w, usable_h = 1 - 2 * margin, 1 - 2 * margin
gap_x = spacing * height / width
gap_y = spacing * width / height
cell_w = (usable_w - gap_x * (columns - 1)) / columns
cell_h = (usable_h - gap_y * (rows - 1)) / rows
if cell_w <= 0 or cell_h <= 0:
raise ValueError("margin and spacing leave no usable canvas area")
regions = []
for index, item in enumerate(instances):
row, column = divmod(index, columns)
x = usable_x + column * (cell_w + gap_x)
y = usable_y + row * (cell_h + gap_y)
cell_ratio = cell_w / cell_h
target_ratio = ASPECT_RATIOS[item["aspect_ratio"]]
if mode == "grid":
region_w, region_h = cell_w, cell_h
else:
# Fit the requested aspect ratio in the cell. Weight changes the
# footprint within the cell while never crossing cell boundaries.
if target_ratio >= cell_ratio:
region_w, region_h = cell_w, cell_w / target_ratio
else:
region_w, region_h = cell_h * target_ratio, cell_h
weight = SIZE_WEIGHTS[item["size"]]
scale = min(1.0, math.sqrt(weight / SIZE_WEIGHTS["large"]))
region_w *= scale
region_h *= scale
offset_x, offset_y = (cell_w - region_w) / 2, (cell_h - region_h) / 2
rx, ry = x + offset_x, y + offset_y
regions.append({
"id": item["id"],
"original_id": item["original_id"],
"name": item["name"],
"quantity": item["quantity"],
"unit": item["unit"],
"description": item["description"],
"size": item["size"],
"aspect_ratio": item["aspect_ratio"],
"instance": item["instance"],
"x": round(rx, 8), "y": round(ry, 8),
"width": round(region_w, 8), "height": round(region_h, 8),
"position": _position_name(rx + region_w / 2, ry + region_h / 2),
})
warnings = []
if len(instances) > 25:
warnings.append("Large inventory: regions were scaled to fit the requested canvas.")
return {"canvas": {"width": width, "height": height}, "regions": regions, "warnings": warnings}
def build_layout_prompt(plan: dict[str, Any]) -> str:
regions = plan["regions"]
if not regions:
return ""
lines = [
f"Arrange exactly {len(regions)} unique inventory region(s) on the {plan['canvas']['width']}x{plan['canvas']['height']} canvas.",
"Each allocated region represents one unique inventory entry; do not invent, merge, delete, or duplicate objects.",
]
for region in regions:
right = region["x"] + region["width"]
bottom = region["y"] + region["height"]
description = region["description"] or "No additional description provided."
lines.append(
f"{region['id']} ({region['name']}, quantity {region['quantity']}, {region['unit']}): "
f"place only this object in the {region['position']} region, approximately "
f"from {region['x']:.0%},{region['y']:.0%} to {right:.0%},{bottom:.0%}. "
f"Visual description: {description}"
)
return "\n".join(lines)
def _flux3_bbox(region: dict[str, Any], padding_percent: float = 0.0) -> list[int]:
"""Convert a normalized region to FLUX.3's 0-1000 box format."""
padding = _bounded_number(padding_percent, "flux3_box_padding", 0, 40) / 100
x, y = float(region["x"]), float(region["y"])
width, height = float(region["width"]), float(region["height"])
# Padding is internal: shrink the target box symmetrically without moving
# it outside the layout or changing the original legacy plan.
x += width * padding
y += height * padding
width *= max(0.0, 1 - 2 * padding)
height *= max(0.0, 1 - 2 * padding)
top = max(0, min(1000, round(y * 1000)))
left = max(0, min(1000, round(x * 1000)))
bottom = max(0, min(1000, round((y + height) * 1000)))
right = max(0, min(1000, round((x + width) * 1000)))
if top >= 1000:
top = 999
if left >= 1000:
left = 999
if bottom <= top:
bottom = min(1000, top + 1)
if right <= left:
right = min(1000, left + 1)
return [top, left, bottom, right]
def build_flux3_boxes(
plan: dict[str, Any],
padding_percent: float = 0.0,
include_descriptions: bool = True,
) -> list[dict[str, Any]]:
"""Build FLUX.3 generation-style layout rows from an existing plan."""
rows = []
for region in plan["regions"]:
description = region["description"] if include_descriptions else ""
if not description:
description = region["name"]
rows.append({
"id": region["id"],
"bbox": _flux3_bbox(region, padding_percent),
"desc": description,
})
return rows
def build_flux3_prompt(
plan: dict[str, Any],
padding_percent: float = 0.0,
include_descriptions: bool = True,
) -> tuple[str, str]:
"""Return a FLUX.3 caption and its trailing JSON box array."""
boxes = build_flux3_boxes(plan, padding_percent, include_descriptions)
if not boxes:
return "", "[]"
references = []
for region in plan["regions"]:
references.append(f"{region['name']} <{region['id']}>")
caption = (
"A photorealistic 90-degree overhead flat-lay product photograph of "
"the exact physical objects identified in the supplied reference image, "
"arranged individually on a clean neutral surface with realistic materials, "
"natural fabric drape, soft studio lighting, and subtle contact shadows. "
f"The scene contains exactly these unique inventory entries: {', '.join(references)}. "
"Reproduce each item's original colours, materials, construction, prints, "
"graphics, and visible details faithfully. Display each object only once "
"inside its allocated region. Do not include the original person, mannequin, "
"duplicate garments, invented accessories, or unrelated props."
)
boxes_json = json.dumps(boxes, ensure_ascii=False, separators=(",", ":"))
return f"{caption} {boxes_json}", boxes_json
def _background(value: str) -> tuple[int, int, int]:
text = str(value or DEFAULT_BACKGROUND).strip().lstrip("#")
if len(text) == 3:
text = "".join(char * 2 for char in text)
if len(text) != 6 or any(char not in "0123456789abcdefABCDEF" for char in text):
raise ValueError("background_color must be a hex colour such as #EEE8DC")
return tuple(int(text[index:index + 2], 16) for index in (0, 2, 4))
def render_preview(plan: dict[str, Any], background_color: str, show_labels: bool = True):
try:
from PIL import Image, ImageDraw, ImageFont
except ImportError as exc:
raise RuntimeError("DUMAS Clothing Layout Planner requires Pillow for layout_preview") from exc
image = Image.new("RGB", (plan["canvas"]["width"], plan["canvas"]["height"]), _background(background_color))
if not plan["regions"]:
return image
draw = ImageDraw.Draw(image)
font = ImageFont.load_default()
colours = [(91, 126, 157), (115, 151, 112), (181, 135, 78), (139, 112, 156), (166, 104, 104)]
width, height = image.size
for index, region in enumerate(plan["regions"]):
left = round(region["x"] * width)
top = round(region["y"] * height)
right = round((region["x"] + region["width"]) * width) - 1
bottom = round((region["y"] + region["height"]) * height) - 1
colour = colours[index % len(colours)]
draw.rectangle((left, top, right, bottom), outline=colour, width=max(2, min(width, height) // 300))
if show_labels:
label = f"{region['id']} — {region['name']}"
label_width = draw.textbbox((0, 0), label, font=font)[2]
if label_width > right - left - 8:
label = region["id"]
label_y = min(bottom - 14, top + 4)
draw.rectangle((left + 2, label_y - 1, min(right - 2, left + 6 + draw.textbbox((0, 0), label, font=font)[2]), label_y + 12), fill=(245, 240, 229))
draw.text((left + 4, label_y), label, fill=(35, 35, 35), font=font)
return image
class DumasClothingLayoutPlanner:
CATEGORY = "Dumas/Image/Layout"
DESCRIPTION = "Create a deterministic object layout from VLM inventory JSON."
RETURN_TYPES = ("STRING", "STRING", "IMAGE", "STRING", "STRING")
RETURN_NAMES = ("layout_prompt", "layout_json", "layout_preview", "flux3_prompt", "flux3_boxes_json")
FUNCTION = "plan"
@classmethod
def INPUT_TYPES(cls):
return {"required": {
"inventory_json": ("STRING", {"multiline": True, "default": "{\"items\": []}"}),
"canvas_width": ("INT", {"default": 1536, "min": 64, "max": 8192, "step": 1}),
"canvas_height": ("INT", {"default": 1024, "min": 64, "max": 8192, "step": 1}),
"layout_mode": (["balanced", "grid"], {"default": "balanced"}),
"margin_percent": ("FLOAT", {"default": 5.0, "min": 0.0, "max": 40.0, "step": 0.5}),
"spacing_percent": ("FLOAT", {"default": 3.0, "min": 0.0, "max": 20.0, "step": 0.5}),
"background_color": ("STRING", {"default": DEFAULT_BACKGROUND}),
"show_labels": ("BOOLEAN", {"default": True}),
"output_format": (["legacy", "flux3", "both"], {"default": "both"}),
"flux3_box_padding": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 40.0, "step": 0.5}),
"flux3_include_descriptions": ("BOOLEAN", {"default": True}),
"flux3_reference_mode": (["generation", "editing"], {"default": "generation"}),
}}
def plan(self, inventory_json, canvas_width, canvas_height, layout_mode, margin_percent, spacing_percent, background_color, show_labels, output_format, flux3_box_padding, flux3_include_descriptions, flux3_reference_mode):
plan = plan_layout(inventory_json, canvas_width, canvas_height, layout_mode, margin_percent, spacing_percent)
if output_format in {"flux3", "both"} and flux3_reference_mode == "editing":
raise ValueError(
"flux3_reference_mode='editing' requires source bounding boxes and reference-image identifiers; "
"the current inventory schema only supports generation mode"
)
preview = render_preview(plan, background_color, show_labels)
try:
import numpy as np
import torch
tensor = torch.from_numpy(np.asarray(preview).astype("float32") / 255.0)[None, ...]
except ImportError as exc:
raise RuntimeError("DUMAS Clothing Layout Planner requires ComfyUI's torch and numpy runtime") from exc
flux3_prompt, flux3_boxes_json = "", "[]"
if output_format in {"flux3", "both"}:
flux3_prompt, flux3_boxes_json = build_flux3_prompt(
plan, flux3_box_padding, flux3_include_descriptions
)
return build_layout_prompt(plan), json.dumps(plan, ensure_ascii=False, indent=2), tensor, flux3_prompt, flux3_boxes_json
NODE_CLASS_MAPPINGS = {"DumasClothingLayoutPlanner": DumasClothingLayoutPlanner}
NODE_DISPLAY_NAME_MAPPINGS = {"DumasClothingLayoutPlanner": "DUMAS Clothing Layout Planner"}