diff --git a/README.md b/README.md index 931c170..8dddcdf 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/__init__.py b/__init__.py index ec0219f..9bda6f3 100644 --- a/__init__.py +++ b/__init__.py @@ -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) diff --git a/dumas_clothing_layout_planner.py b/dumas_clothing_layout_planner.py new file mode 100644 index 0000000..51adbef --- /dev/null +++ b/dumas_clothing_layout_planner.py @@ -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"} diff --git a/tests/test_dumas_clothing_layout_planner.py b/tests/test_dumas_clothing_layout_planner.py new file mode 100644 index 0000000..4cb06ca --- /dev/null +++ b/tests/test_dumas_clothing_layout_planner.py @@ -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()