Add deterministic clothing layout planner

This commit is contained in:
2026-11-03 11:04:17 +00:00
parent 6646ecdfd9
commit f770609af8
4 changed files with 424 additions and 0 deletions
+21
View File
@@ -124,6 +124,27 @@ The prompt editor is intended to sit before a normal prompt builder or
Continuum reference-image workflow. It does not encode, resize, crop, or
modify the image.
### DUMAS Clothing Layout Planner
`DumasClothingLayoutPlanner` converts object inventory JSON from a VLM into a
deterministic spatial plan for flat-lay or product-image generation. It accepts
raw JSON or a fenced JSON block, expands quantities into deterministic instance
IDs, treats `unit: "pair"` entries as one region per pair, and supports
`balanced` and `grid` layouts. It is object-agnostic and does not infer or
download anything.
Outputs:
- `layout_prompt`: natural-language region instructions preserving IDs and
original descriptions
- `layout_json`: reusable normalized coordinates and warnings
- `layout_preview`: a diagnostic IMAGE showing the regions and optional labels
The planner uses normalized top-left-origin coordinates, configurable margins
and spacing, and rejects malformed or invalid inventory fields with actionable
errors. The preview is diagnostic only; feeding it to an image model does not
guarantee spatial control.
### DUMAS H3 RefMod Save
`DUMAS H3 RefMod Save` accepts the `H3_REF_MODS` bundle produced by the
+6
View File
@@ -27,6 +27,10 @@ from .dumas_reference_image_preprocessor import (
NODE_CLASS_MAPPINGS as REFERENCE_PREPROCESSOR_NODE_CLASS_MAPPINGS,
NODE_DISPLAY_NAME_MAPPINGS as REFERENCE_PREPROCESSOR_DISPLAY_NAME_MAPPINGS,
)
from .dumas_clothing_layout_planner import (
NODE_CLASS_MAPPINGS as CLOTHING_LAYOUT_NODE_CLASS_MAPPINGS,
NODE_DISPLAY_NAME_MAPPINGS as CLOTHING_LAYOUT_DISPLAY_NAME_MAPPINGS,
)
from .dumas_h3_upscale_nodes import (
NODE_CLASS_MAPPINGS as H3_UPSCALE_NODE_CLASS_MAPPINGS,
NODE_DISPLAY_NAME_MAPPINGS as H3_UPSCALE_NODE_DISPLAY_NAME_MAPPINGS,
@@ -55,6 +59,7 @@ NODE_CLASS_MAPPINGS.update(VIDEO_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(MINIMAX_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(H3_PROMPT_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(REFERENCE_PREPROCESSOR_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(CLOTHING_LAYOUT_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(H3_UPSCALE_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(H3_REFMOD_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(H3_REFMOD_PICKER_NODE_CLASS_MAPPINGS)
@@ -68,6 +73,7 @@ NODE_DISPLAY_NAME_MAPPINGS.update(VIDEO_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(MINIMAX_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(H3_PROMPT_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(REFERENCE_PREPROCESSOR_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(CLOTHING_LAYOUT_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(H3_UPSCALE_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(H3_REFMOD_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(H3_REFMOD_PICKER_NODE_DISPLAY_NAME_MAPPINGS)
+293
View File
@@ -0,0 +1,293 @@
"""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:
raise ValueError(f"inventory_json is invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}") 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 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 _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")
RETURN_NAMES = ("layout_prompt", "layout_json", "layout_preview")
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}),
}}
def plan(self, inventory_json, canvas_width, canvas_height, layout_mode, margin_percent, spacing_percent, background_color, show_labels):
plan = plan_layout(inventory_json, canvas_width, canvas_height, layout_mode, margin_percent, spacing_percent)
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
return build_layout_prompt(plan), json.dumps(plan, ensure_ascii=False, indent=2), tensor
NODE_CLASS_MAPPINGS = {"DumasClothingLayoutPlanner": DumasClothingLayoutPlanner}
NODE_DISPLAY_NAME_MAPPINGS = {"DumasClothingLayoutPlanner": "DUMAS Clothing Layout Planner"}
+104
View File
@@ -0,0 +1,104 @@
from __future__ import annotations
import importlib.util
import json
import pathlib
import unittest
ROOT = pathlib.Path(__file__).parents[1]
spec = importlib.util.spec_from_file_location(
"dumas_clothing_layout_planner_test",
ROOT / "dumas_clothing_layout_planner.py",
)
PLANNER = importlib.util.module_from_spec(spec)
assert spec.loader is not None
spec.loader.exec_module(PLANNER)
def inventory(*items):
return json.dumps({"items": list(items)})
class ClothingLayoutPlannerTests(unittest.TestCase):
def test_accepts_markdown_fenced_json_and_preserves_description(self):
items = PLANNER.normalize_inventory("```json\n" + inventory({
"id": "shirt", "name": "shirt", "description": "blue linen",
}) + "\n```")
self.assertEqual(items[0]["description"], "blue linen")
def test_quantities_and_pairs_create_deterministic_instances(self):
plan = PLANNER.plan_layout(inventory(
{"id": "sock", "name": "sock", "quantity": 3},
{"id": "shoes", "name": "shoes", "quantity": 2, "unit": "pair"},
), 1200, 800)
self.assertEqual(len(plan["regions"]), 5)
self.assertEqual([region["id"] for region in plan["regions"]], [
"sock_001", "sock_002", "sock_003", "shoes_001", "shoes_002",
])
self.assertEqual(plan["regions"][3]["original_id"], "shoes")
self.assertEqual(plan["regions"][3]["unit"], "pair")
def test_regions_are_in_bounds_and_do_not_overlap(self):
plan = PLANNER.plan_layout(inventory(*[
{"id": f"item_{index}", "name": f"Object {index}", "size": "large" if index == 1 else "small"}
for index in range(1, 11)
]), 1536, 1024, "balanced")
regions = plan["regions"]
for region in regions:
self.assertGreaterEqual(region["x"], 0)
self.assertGreaterEqual(region["y"], 0)
self.assertLessEqual(region["x"] + region["width"], 1)
self.assertLessEqual(region["y"] + region["height"], 1)
for left_index, left in enumerate(regions):
for right in regions[left_index + 1:]:
overlap_x = min(left["x"] + left["width"], right["x"] + right["width"]) - max(left["x"], right["x"])
overlap_y = min(left["y"] + left["height"], right["y"] + right["height"]) - max(left["y"], right["y"])
self.assertFalse(overlap_x > 1e-7 and overlap_y > 1e-7)
def test_same_inputs_are_deterministic(self):
value = inventory({"id": "a", "name": "A", "aspect_ratio": "portrait"}, {"id": "b", "name": "B"})
self.assertEqual(PLANNER.plan_layout(value), PLANNER.plan_layout(value))
def test_balanced_mode_gives_large_items_more_area(self):
plan = PLANNER.plan_layout(inventory(
{"id": "large", "name": "Large", "size": "large"},
{"id": "small", "name": "Small", "size": "small"},
), 1200, 800)
areas = {region["id"]: region["width"] * region["height"] for region in plan["regions"]}
self.assertGreater(areas["large"], areas["small"])
@unittest.skipUnless(importlib.util.find_spec("PIL"), "Pillow is only available in the ComfyUI runtime")
def test_empty_inventory_has_empty_layout_and_preview(self):
plan = PLANNER.plan_layout('{"items": []}', 640, 480)
preview = PLANNER.render_preview(plan, "#EEE8DC")
self.assertEqual(plan["regions"], [])
self.assertEqual(preview.size, (640, 480))
self.assertEqual(PLANNER.build_layout_prompt(plan), "")
def test_layout_prompt_contains_ids_descriptions_and_positions(self):
plan = PLANNER.plan_layout(inventory({
"id": "item_001", "name": "blue shirt", "description": "cotton shirt",
}))
prompt = PLANNER.build_layout_prompt(plan)
self.assertIn("item_001", prompt)
self.assertIn("blue shirt", prompt)
self.assertIn("cotton shirt", prompt)
self.assertIn("region", prompt)
def test_invalid_fields_have_actionable_errors(self):
with self.assertRaisesRegex(ValueError, "invalid unit"):
PLANNER.normalize_inventory(inventory({"id": "x", "name": "X", "unit": "trio"}))
with self.assertRaisesRegex(ValueError, "invalid JSON"):
PLANNER.normalize_inventory("{not-json}")
@unittest.skipUnless(importlib.util.find_spec("PIL"), "Pillow is only available in the ComfyUI runtime")
def test_preview_matches_requested_dimensions_and_labels(self):
plan = PLANNER.plan_layout(inventory({"id": "hat", "name": "hat"}), 777, 333, "grid")
preview = PLANNER.render_preview(plan, "#123456", True)
self.assertEqual(preview.size, (777, 333))
self.assertEqual(preview.getpixel((0, 0)), (18, 52, 86))
if __name__ == "__main__":
unittest.main()