diff --git a/README.md b/README.md index b6627e9..931c170 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,26 @@ from the installed upstream H3 Continuum pack. Install that pack alongside DumasNodes; DumasNodes does not copy or replace the upstream reference-image implementation. +### DUMAS Reference Image Preprocessor + +`DumasReferenceImagePreprocessor` keeps a reference `IMAGE` unchanged and +creates an editable `STRING` prompt for a reusable `@R1`–`@R9` reference. +Choose a type (`Character`, `Object`, `Scene`, `Creature`, or `Vehicle`), a +reference ID, and optional additional information. The generated prompt is +shown in a multiline editor and is also emitted as the `reference_prompt` +output. Type and reference-ID changes regenerate the editor; description +changes can be applied with **Regenerate prompt**, preserving manual edits +until regeneration is requested. + +The node outputs: + +- `image`: the original image tensor, unchanged +- `reference_prompt`: the editable prompt text containing the selected `@R#` + +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 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 19e99e1..ec0219f 100644 --- a/__init__.py +++ b/__init__.py @@ -23,6 +23,10 @@ from .dumas_h3_prompt_nodes import ( NODE_CLASS_MAPPINGS as H3_PROMPT_NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS as H3_PROMPT_NODE_DISPLAY_NAME_MAPPINGS, ) +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_h3_upscale_nodes import ( NODE_CLASS_MAPPINGS as H3_UPSCALE_NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS as H3_UPSCALE_NODE_DISPLAY_NAME_MAPPINGS, @@ -50,6 +54,7 @@ NODE_CLASS_MAPPINGS.update(IMAGE_NODE_CLASS_MAPPINGS) 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(H3_UPSCALE_NODE_CLASS_MAPPINGS) NODE_CLASS_MAPPINGS.update(H3_REFMOD_NODE_CLASS_MAPPINGS) NODE_CLASS_MAPPINGS.update(H3_REFMOD_PICKER_NODE_CLASS_MAPPINGS) @@ -62,6 +67,7 @@ NODE_DISPLAY_NAME_MAPPINGS.update(IMAGE_NODE_DISPLAY_NAME_MAPPINGS) 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(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_reference_image_preprocessor.py b/dumas_reference_image_preprocessor.py new file mode 100644 index 0000000..2d218dd --- /dev/null +++ b/dumas_reference_image_preprocessor.py @@ -0,0 +1,114 @@ +"""Reference-image prompt helper for reusable image references.""" + +from __future__ import annotations + + +REFERENCE_TYPES = ("Character", "Object", "Scene", "Creature", "Vehicle") +REFERENCE_IDS = tuple(str(index) for index in range(1, 10)) + + +def reference_token(reference_id: str | int) -> str: + """Return the Continuum reference token for a user-facing ID.""" + + try: + index = int(reference_id) + except (TypeError, ValueError) as exc: + raise ValueError("reference_id must be an integer from 1 to 9") from exc + if index < 1 or index > 9: + raise ValueError("reference_id must be an integer from 1 to 9") + return f"@R{index}" + + +_TEMPLATES = { + "Character": ( + "Describe the character in the image in exquisite detail. Include " + "clothing, accessories, body type, proportions, and size. The character " + "will be referred to as {token} and should be treated as a photographic " + "representation of a real person, so start the description with \"{token}\". " + "Do not refer to individual shots; treat this as a visual description of " + "the character." + ), + "Object": ( + "Describe the object in the image in exquisite detail. Include its shape, " + "size, materials, colours, construction, surface detail, condition, and " + "distinctive features. The object will be referred to as {token}. Do not " + "refer to individual shots; treat this as a visual description of the object." + ), + "Scene": ( + "Describe the scene in the image in exquisite detail. Include the " + "environment, architecture, spatial layout, lighting, atmosphere, colours, " + "perspective, and important background elements. The scene will be referred " + "to as {token}. Do not refer to individual shots; treat this as a visual " + "description of the scene." + ), + "Creature": ( + "Describe the creature in the image in exquisite detail. Include its anatomy, " + "body structure, size, proportions, skin, fur, scales, colouring, distinctive " + "features, expression, and physical condition. The creature will be referred " + "to as {token}. Do not refer to individual shots; treat this as a visual " + "description of the creature." + ), + "Vehicle": ( + "Describe the vehicle in the image in exquisite detail. Include its type, " + "dimensions, shape, materials, colours, design, mechanical features, " + "condition, markings, and distinctive details. The vehicle will be referred " + "to as {token}. Do not refer to individual shots; treat this as a visual " + "description of the vehicle." + ), +} + + +def build_reference_prompt(reference_type: str, reference_id: str | int, description: str = "") -> str: + """Build the editable prompt shown by the node.""" + + if reference_type not in _TEMPLATES: + raise ValueError(f"reference_type must be one of: {', '.join(REFERENCE_TYPES)}") + token = reference_token(reference_id) + prompt = _TEMPLATES[reference_type].format(token=token) + extra = str(description or "").strip() + if extra: + prompt += f'\n\nAdditional information about the {reference_type.lower()}: "{extra}"' + return prompt + + +class DumasReferenceImagePreprocessor: + """Keep an image unchanged and generate an editable reference prompt.""" + + CATEGORY = "Dumas/Reference" + DESCRIPTION = ( + "Pass through a reference image and create an editable @R1–@R9 prompt " + "for a Character, Object, Scene, Creature, or Vehicle." + ) + RETURN_TYPES = ("IMAGE", "STRING") + RETURN_NAMES = ("image", "reference_prompt") + FUNCTION = "process" + + @classmethod + def INPUT_TYPES(cls): + return { + "required": { + "image": ("IMAGE",), + "reference_type": (list(REFERENCE_TYPES), {"default": "Character"}), + "reference_id": (list(REFERENCE_IDS), {"default": "1"}), + "description": ("STRING", {"default": "", "multiline": True}), + "generated_prompt": ( + "STRING", + { + "default": build_reference_prompt("Character", "1"), + "multiline": True, + }, + ), + } + } + + def process(self, image, reference_type, reference_id, description, generated_prompt): + prompt = str(generated_prompt or "").strip() + if not prompt: + prompt = build_reference_prompt(reference_type, reference_id, description) + return (image, prompt) + + +NODE_CLASS_MAPPINGS = {"DumasReferenceImagePreprocessor": DumasReferenceImagePreprocessor} +NODE_DISPLAY_NAME_MAPPINGS = { + "DumasReferenceImagePreprocessor": "DUMAS Reference Image Preprocessor", +} diff --git a/js/reference_image_preprocessor.js b/js/reference_image_preprocessor.js new file mode 100644 index 0000000..cdb0149 --- /dev/null +++ b/js/reference_image_preprocessor.js @@ -0,0 +1,59 @@ +import { app } from "../../scripts/app.js"; + +const CLASS = "DumasReferenceImagePreprocessor"; +const get = (node, name) => node.widgets?.find((widget) => widget.name === name); + +const promptFor = (node) => { + const type = String(get(node, "reference_type")?.value || "Character"); + const id = String(get(node, "reference_id")?.value || "1"); + const description = String(get(node, "description")?.value || "").trim(); + const token = `@R${id}`; + const opening = { + Character: `Describe the character in the image in exquisite detail. Include clothing, accessories, body type, proportions, and size. The character will be referred to as ${token} and should be treated as a photographic representation of a real person, so start the description with "${token}". Do not refer to individual shots; treat this as a visual description of the character.`, + Object: `Describe the object in the image in exquisite detail. Include its shape, size, materials, colours, construction, surface detail, condition, and distinctive features. The object will be referred to as ${token}. Do not refer to individual shots; treat this as a visual description of the object.`, + Scene: `Describe the scene in the image in exquisite detail. Include the environment, architecture, spatial layout, lighting, atmosphere, colours, perspective, and important background elements. The scene will be referred to as ${token}. Do not refer to individual shots; treat this as a visual description of the scene.`, + Creature: `Describe the creature in the image in exquisite detail. Include its anatomy, body structure, size, proportions, skin, fur, scales, colouring, distinctive features, expression, and physical condition. The creature will be referred to as ${token}. Do not refer to individual shots; treat this as a visual description of the creature.`, + Vehicle: `Describe the vehicle in the image in exquisite detail. Include its type, dimensions, shape, materials, colours, design, mechanical features, condition, markings, and distinctive details. The vehicle will be referred to as ${token}. Do not refer to individual shots; treat this as a visual description of the vehicle.`, + }[type] || ""; + return `${opening}${description ? `\n\nAdditional information about the ${type.toLowerCase()}: "${description}"` : ""}`; +}; + +function setPrompt(node) { + const widget = get(node, "generated_prompt"); + if (!widget) return; + widget.value = promptFor(node); + widget.callback?.(widget.value); + node.setDirtyCanvas?.(true, true); +} + +function configure(node) { + if (node?.comfyClass !== CLASS || node.__dumasReferencePreprocessor) return; + node.__dumasReferencePreprocessor = true; + const type = get(node, "reference_type"); + const id = get(node, "reference_id"); + const prompt = get(node, "generated_prompt"); + const wrap = (widget) => { + if (!widget) return; + const callback = widget.callback; + widget.callback = function (value) { + const result = callback?.call(this, value); + setPrompt(node); + return result; + }; + }; + wrap(type); + wrap(id); + if (prompt) { + prompt.options ||= {}; + prompt.options.multiline = true; + prompt.computeSize = (width) => [Math.max(320, Number(width) || 420), 150]; + } + const button = node.addWidget?.("button", "regenerate_prompt", "Regenerate prompt", () => setPrompt(node)); + if (button) button.serialize = false; + setPrompt(node); +} + +app.registerExtension({ + name: "Dumas.ReferenceImagePreprocessor", + nodeCreated(node) { configure(node); }, +}); diff --git a/tests/test_reference_image_preprocessor.py b/tests/test_reference_image_preprocessor.py new file mode 100644 index 0000000..4399be2 --- /dev/null +++ b/tests/test_reference_image_preprocessor.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +import importlib.util +import pathlib +import unittest + + +ROOT = pathlib.Path(__file__).parents[1] +spec = importlib.util.spec_from_file_location( + "dumas_reference_image_preprocessor_test", + ROOT / "dumas_reference_image_preprocessor.py", +) +MODULE = importlib.util.module_from_spec(spec) +assert spec.loader is not None +spec.loader.exec_module(MODULE) + + +class ReferenceImagePreprocessorTests(unittest.TestCase): + def test_all_reference_types_use_the_selected_token(self): + for reference_type in MODULE.REFERENCE_TYPES: + prompt = MODULE.build_reference_prompt(reference_type, "3", "blue details") + self.assertIn("@R3", prompt) + self.assertIn("Additional information about the", prompt) + self.assertIn('"blue details"', prompt) + + def test_invalid_reference_id_is_rejected(self): + with self.assertRaises(ValueError): + MODULE.build_reference_prompt("Character", "10") + + def test_empty_description_is_not_appended(self): + prompt = MODULE.build_reference_prompt("Scene", 1) + self.assertNotIn("Additional information", prompt) + + def test_node_preserves_image_and_allows_manual_prompt(self): + image = object() + node = MODULE.DumasReferenceImagePreprocessor() + result = node.process(image, "Vehicle", "9", "red van", "my edited prompt") + self.assertIs(result[0], image) + self.assertEqual(result[1], "my edited prompt") + + def test_node_generates_prompt_when_widget_is_empty(self): + node = MODULE.DumasReferenceImagePreprocessor() + result = node.process(object(), "Object", "2", "wooden handle", "") + self.assertIn("@R2", result[1]) + self.assertIn("wooden handle", result[1]) + + +if __name__ == "__main__": + unittest.main()