From 7f0e8d8fe465f5bb353e8a0ca8beaf36ced43e2d Mon Sep 17 00:00:00 2001 From: Chris Dumas Date: Tue, 20 Oct 2026 13:13:50 +0000 Subject: [PATCH] Add DUMAS H3 RefMod picker --- README.md | 19 +- __init__.py | 6 + dumas_h3_refmod_nodes.py | 10 + dumas_h3_refmod_picker.py | 267 +++++++++++++++++++++++++++ js/dumas_h3_refmod_picker.js | 77 ++++++++ tests/test_dumas_h3_refmod_picker.py | 71 +++++++ 6 files changed, 448 insertions(+), 2 deletions(-) create mode 100644 dumas_h3_refmod_picker.py create mode 100644 js/dumas_h3_refmod_picker.js create mode 100644 tests/test_dumas_h3_refmod_picker.py diff --git a/README.md b/README.md index 5bff9f7..e98d716 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,23 @@ MiniMax H3 RefMod nodes and adds explicit DUMAS-owned storage policy: All writes use the RefMod object's atomic save operation. The node reports the resolved `.safetensors` paths through `saved_paths`. External folders are not -automatically added to the RefMod dropdown; register them as a ComfyUI -`refmods` root or load them through the upstream folder/library tooling. +automatically persistent across restarts, but they are registered as RefMod +roots for the current ComfyUI process so the DUMAS picker can discover them. +For persistence across restarts, add the folder to ComfyUI's `refmods` mapping +in `extra_model_paths.yaml`. + +### DUMAS H3 RefMod Visual Picker + +`DUMAS H3 RefMod Visual Picker` provides a small browser button for selecting +registered RefMod `.safetensors` files. It supports the maintained upstream +loader's standalone and bundle formats, including embedded visual/audio +members, and appends the selected rows to an optional existing `H3_REF_MODS` +bundle. Video and audio weights are independent, and values above 1 repeat a +reference as additional weighted rows, matching the companion add-on's +behaviour. The picker shows matching preview images when present. + +The maintained MiniMax H3 RefMod reader must be installed alongside DUMAS; +DUMAS does not duplicate that reader or override its node IDs. ### DUMAS H3 Continuum Tiled Latent Upscale (Per Clip) diff --git a/__init__.py b/__init__.py index b895706..24f11f5 100644 --- a/__init__.py +++ b/__init__.py @@ -31,6 +31,10 @@ from .dumas_h3_refmod_nodes import ( NODE_CLASS_MAPPINGS as H3_REFMOD_NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS as H3_REFMOD_NODE_DISPLAY_NAME_MAPPINGS, ) +from .dumas_h3_refmod_picker import ( + NODE_CLASS_MAPPINGS as H3_REFMOD_PICKER_NODE_CLASS_MAPPINGS, + NODE_DISPLAY_NAME_MAPPINGS as H3_REFMOD_PICKER_NODE_DISPLAY_NAME_MAPPINGS, +) NODE_CLASS_MAPPINGS = {} NODE_CLASS_MAPPINGS.update(JSON_NODE_CLASS_MAPPINGS) @@ -40,6 +44,7 @@ NODE_CLASS_MAPPINGS.update(MINIMAX_NODE_CLASS_MAPPINGS) NODE_CLASS_MAPPINGS.update(H3_PROMPT_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) NODE_DISPLAY_NAME_MAPPINGS = {} NODE_DISPLAY_NAME_MAPPINGS.update(JSON_NODE_DISPLAY_NAME_MAPPINGS) @@ -49,6 +54,7 @@ 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(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) WEB_DIRECTORY = "./js" diff --git a/dumas_h3_refmod_nodes.py b/dumas_h3_refmod_nodes.py index 7ac2051..72fed2e 100644 --- a/dumas_h3_refmod_nodes.py +++ b/dumas_h3_refmod_nodes.py @@ -108,11 +108,21 @@ class DumasH3RefModSave: if not raw_folder: raise ValueError("Input folder mode requires a connected input_folder path.") root = os.path.realpath(raw_folder) + try: + from .dumas_h3_refmod_picker import register_refmod_root + except ImportError: + register_refmod_root = lambda _path: None + register_refmod_root(root) elif save_location == "Custom folder": raw_folder = str(custom_output_folder or "").strip() if not raw_folder: raise ValueError("Custom folder mode requires a connected custom_output_folder path.") root = os.path.realpath(raw_folder) + try: + from .dumas_h3_refmod_picker import register_refmod_root + except ImportError: + register_refmod_root = lambda _path: None + register_refmod_root(root) else: raise ValueError(f"Unknown RefMod save location: {save_location!r}") diff --git a/dumas_h3_refmod_picker.py b/dumas_h3_refmod_picker.py new file mode 100644 index 0000000..6361bb0 --- /dev/null +++ b/dumas_h3_refmod_picker.py @@ -0,0 +1,267 @@ +"""DUMAS H3 RefMod browser and picker. + +The picker consumes the ``H3_REF_MODS`` type from the maintained MiniMax H3 +RefMod implementation. It intentionally does not duplicate the upstream +extract/apply implementation; it only discovers files, presents them safely, +and loads the selected RefMod into a compatible bundle. +""" + +from __future__ import annotations + +import json +import os +import sys +from typing import Dict, List + +import folder_paths + + +_SKIP_DIRS = {".git", "__pycache__", "graph_presets"} +_MAX_WEIGHT = 10.0 +_CACHE = {} + + +def _roots() -> List[str]: + roots = [] + try: + roots.extend(folder_paths.get_folder_paths("refmods")) + except Exception: + pass + fallback = os.path.join(folder_paths.models_dir, "refmods") + roots.append(fallback) + result = [] + seen = set() + for root in roots: + root = os.path.realpath(os.path.abspath(root)) + if root not in seen and os.path.isdir(root): + seen.add(root) + result.append(root) + return result + + +def register_refmod_root(path: str) -> str: + """Register an explicitly selected external folder for this process.""" + root = os.path.realpath(os.path.abspath(str(path or "").strip())) + if not os.path.isdir(root): + raise ValueError(f"RefMod folder does not exist: {root}") + try: + folder_paths.add_model_folder_path("refmods", root) + except Exception: + pass + return root + + +def _inside(path: str, root: str) -> bool: + try: + return os.path.commonpath((os.path.realpath(path), os.path.realpath(root))) == os.path.realpath(root) + except ValueError: + return False + + +def _safe_file(path: str) -> str: + raw = os.path.abspath(os.path.expanduser(str(path or "").strip())) + for root in _roots(): + if _inside(raw, root) and os.path.isfile(raw): + return os.path.realpath(raw) + raise ValueError("RefMod path is not inside a registered refmods folder.") + + +def _read_meta(path_no_ext: str): + try: + from safetensors import safe_open + with safe_open(path_no_ext + ".safetensors", framework="pt") as handle: + metadata = handle.metadata() or {} + for key in ("refmod_meta", "audio_refmod_meta"): + if key in metadata: + return json.loads(metadata[key]) + except Exception: + return None + return None + + +def _capabilities(meta): + if not isinstance(meta, dict): + return {"kind": "unknown", "has_visual": False, "has_audio": False} + kind = str(meta.get("kind", "unknown")) + if kind == "bundle": + members = meta.get("members") or [] + return {"kind": kind, + "has_visual": any(x.get("kind") in ("image", "video") for x in members if isinstance(x, dict)), + "has_audio": any(x.get("kind") == "audio" for x in members if isinstance(x, dict))} + if kind in ("image", "video"): + return {"kind": kind, "has_visual": True, + "has_audio": int(meta.get("ref_audio_t", 0) or 0) > 0} + return {"kind": kind, "has_visual": False, "has_audio": kind == "audio"} + + +def _preview(path_no_ext): + stem = os.path.basename(path_no_ext) + for suffix in ("_visual", "_Visual", "_video", "_Video", "_audio", "_Audio"): + if stem.endswith(suffix): + stem = stem[:-len(suffix)] + break + directory = os.path.dirname(path_no_ext) + for ext in (".png", ".jpg", ".jpeg", ".webp"): + candidate = os.path.join(directory, stem + ext) + if os.path.isfile(candidate): + return candidate + return None + + +def _list_entries(current): + dirs, mods = [], [] + for entry in sorted(os.scandir(current), key=lambda item: item.name.lower()): + if entry.name.startswith(".") or entry.name in _SKIP_DIRS: + continue + try: + if entry.is_dir(follow_symlinks=False): + dirs.append({"name": entry.name, "path": os.path.realpath(entry.path)}) + elif entry.is_file(follow_symlinks=False) and entry.name.lower().endswith(".safetensors"): + stem = entry.path[:-len(".safetensors")] + meta = _read_meta(stem) + caps = _capabilities(meta) + if caps["kind"] not in ("image", "video", "audio", "bundle"): + continue + mods.append({ + "name": entry.name, + "path": os.path.realpath(entry.path), + "preview_path": _preview(stem), + **caps, + "description": str((meta or {}).get("description", "") or ""), + "concept_type": str((meta or {}).get("concept_type", "generic") or "generic"), + }) + except OSError: + continue + return dirs, mods + + +def browser_root(): + roots = _roots() + if not roots: + root = os.path.realpath(os.path.join(folder_paths.models_dir, "refmods")) + os.makedirs(root, exist_ok=True) + return root + return roots[0] + + +def list_browser_dir(path=""): + roots = _roots() + if not roots: + root = browser_root() + roots = [root] + current = browser_root() if not path else _safe_directory(path) + if os.path.realpath(current) in {os.path.realpath(x) for x in roots}: + dirs, mods = [], [] + for root in roots: + d, m = _list_entries(root) + dirs.extend(d) + mods.extend(m) + parent = None + current = browser_root() + else: + dirs, mods = _list_entries(current) + parent_candidate = os.path.dirname(current.rstrip(os.sep)) + parent = parent_candidate if any(_inside(parent_candidate, root) for root in roots) else None + return {"root": browser_root(), "current_path": current, "parent_path": parent, + "dirs": dirs, "mods": mods} + + +def _safe_directory(path): + raw = os.path.realpath(os.path.abspath(os.path.expanduser(str(path or "")))) + if any(_inside(raw, root) for root in _roots()) and os.path.isdir(raw): + return raw + raise ValueError("RefMod folder is not inside a registered refmods root.") + + +def _find_loader_api(): + """Find the maintained RefMod reader already loaded by ComfyUI.""" + for module in list(sys.modules.values()): + if module is None: + continue + loader = getattr(module, "load_refmods_from_file", None) + if callable(loader): + return loader + raise RuntimeError( + "No MiniMax H3 RefMod reader is loaded. Install/load the maintained " + "MiniMax H3 RefMod node pack alongside DumasNodes." + ) + + +def _expand_weight(weight): + value = min(_MAX_WEIGHT, max(0.0, float(weight))) + whole = int(value) + remainder = round(value - whole, 6) + result = [1.0] * whole + if remainder > 1e-6: + result.append(remainder) + return result + + +def _hint(rows): + return "; ".join( + f"{getattr(mod, 'concept_type', 'generic')}: {getattr(mod, 'description', '')}" + for mod, strength in rows if strength > 0 and getattr(mod, "description", "") + ) + + +class DumasH3RefModPicker: + @classmethod + def INPUT_TYPES(cls): + return { + "required": { + "mod_path": ("STRING", {"default": "", "tooltip": "Choose a RefMod from the DUMAS browser."}), + "video_weight": ("FLOAT", {"default": 1.0, "min": 0.0, "max": _MAX_WEIGHT, "step": 0.01}), + "audio_weight": ("FLOAT", {"default": 1.0, "min": 0.0, "max": _MAX_WEIGHT, "step": 0.01}), + }, + "optional": {"mods": ("H3_REF_MODS",)}, + } + + RETURN_TYPES = ("H3_REF_MODS", "STRING") + RETURN_NAMES = ("mods", "prompt_hint") + FUNCTION = "pick" + CATEGORY = "Dumas/MiniMax H3/RefMod" + + def pick(self, mod_path="", video_weight=1.0, audio_weight=1.0, mods=None): + rows = list(mods or []) + selected = str(mod_path or "").strip() + if not selected or selected.lower() == "(none)": + return rows, _hint(rows) + path = _safe_file(selected) + loader = _find_loader_api() + loaded = loader(path[:-len(".safetensors")], device="cpu") + for mod in loaded: + weight = audio_weight if getattr(mod, "kind", "") == "audio" else video_weight + for strength in _expand_weight(weight): + rows.append((mod, strength)) + return rows, _hint(rows) + + +NODE_CLASS_MAPPINGS = {"DumasH3RefModPicker": DumasH3RefModPicker} +NODE_DISPLAY_NAME_MAPPINGS = {"DumasH3RefModPicker": "DUMAS H3 RefMod Visual Picker"} + + +try: + from server import PromptServer, web + + @PromptServer.instance.routes.get("/dumas/h3-refmod-browser/root") + async def dumas_refmod_root(request): + return web.json_response({"ok": True, "root": browser_root()}) + + @PromptServer.instance.routes.get("/dumas/h3-refmod-browser/list") + async def dumas_refmod_list(request): + try: + return web.json_response({"ok": True, **list_browser_dir(request.query.get("path", ""))}) + except ValueError as exc: + return web.json_response({"ok": False, "error": str(exc)}, status=404) + + @PromptServer.instance.routes.get("/dumas/h3-refmod-browser/file") + async def dumas_refmod_file(request): + try: + path = _safe_file(request.query.get("path", "")) + if os.path.splitext(path)[1].lower() not in (".png", ".jpg", ".jpeg", ".webp"): + raise ValueError("Unsupported preview type") + return web.FileResponse(path, headers={"Cache-Control": "no-cache"}) + except ValueError as exc: + return web.json_response({"ok": False, "error": str(exc)}, status=404) +except Exception: + pass diff --git a/js/dumas_h3_refmod_picker.js b/js/dumas_h3_refmod_picker.js new file mode 100644 index 0000000..a353a64 --- /dev/null +++ b/js/dumas_h3_refmod_picker.js @@ -0,0 +1,77 @@ +import { app } from "../../scripts/app.js"; +import { api } from "../../scripts/api.js"; + +function openBrowser(node, widget) { + const overlay = document.createElement("div"); + overlay.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,.72);z-index:10000;display:flex;align-items:center;justify-content:center;font:13px sans-serif;color:#eee"; + const panel = document.createElement("div"); + panel.style.cssText = "width:min(760px,92vw);max-height:80vh;background:#20242b;border:1px solid #596474;border-radius:10px;padding:12px;display:flex;flex-direction:column;gap:8px;box-shadow:0 12px 40px #000"; + const header = document.createElement("div"); + header.style.cssText = "display:flex;justify-content:space-between;align-items:center;font-weight:bold"; + header.append("DUMAS H3 RefMod Browser"); + const close = document.createElement("button"); + close.textContent = "Close"; + close.onclick = () => overlay.remove(); + header.append(close); + panel.append(header); + const status = document.createElement("div"); + status.textContent = "Loading registered RefMods…"; + panel.append(status); + const body = document.createElement("div"); + body.style.cssText = "overflow:auto;display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:8px"; + panel.append(body); + overlay.append(panel); + document.body.append(overlay); + + const previewUrl = (path) => api.apiURL(`/dumas/h3-refmod-browser/file?path=${encodeURIComponent(path)}`); + void (async () => { + try { + const rootResponse = await api.fetchApi("/dumas/h3-refmod-browser/root"); + const root = await rootResponse.json(); + const listResponse = await api.fetchApi(`/dumas/h3-refmod-browser/list?path=${encodeURIComponent(root.root || "")}`); + const data = await listResponse.json(); + if (!data.ok) throw new Error(data.error || "Could not list RefMods"); + body.innerHTML = ""; + status.textContent = `${data.mods.length} RefMod(s) found`; + for (const item of data.mods || []) { + const card = document.createElement("button"); + card.style.cssText = "text-align:left;background:#303844;border:1px solid #566274;border-radius:7px;color:#eee;padding:6px;cursor:pointer;min-height:90px"; + if (item.preview_path) { + const image = document.createElement("img"); + image.src = previewUrl(item.preview_path); + image.style.cssText = "width:100%;height:58px;object-fit:cover;border-radius:4px"; + card.append(image); + } + const label = document.createElement("div"); + label.textContent = item.name; + label.style.marginTop = "5px"; + card.append(label); + card.onclick = () => { + widget.value = item.path; + widget.callback?.(item.path); + node.setDirtyCanvas(true, true); + overlay.remove(); + }; + body.append(card); + } + if (!body.childElementCount) status.textContent = "No RefMods found in registered roots."; + } catch (error) { + status.textContent = error?.message || "Could not load RefMods."; + } + })(); +} + +app.registerExtension({ + name: "DumasNodes.H3RefModPicker", + async beforeRegisterNodeDef(nodeType, nodeData) { + if (nodeData?.name !== "DumasH3RefModPicker") return; + const original = nodeType.prototype.onNodeCreated; + nodeType.prototype.onNodeCreated = function () { + original?.apply(this, arguments); + const widget = this.widgets?.find((item) => item.name === "mod_path"); + if (!widget || this._dumasRefModButton) return; + this._dumasRefModButton = this.addWidget("button", "Browse RefMods", null, () => openBrowser(this, widget)); + this.setSize([300, 180]); + }; + }, +}); diff --git a/tests/test_dumas_h3_refmod_picker.py b/tests/test_dumas_h3_refmod_picker.py new file mode 100644 index 0000000..d2da8e1 --- /dev/null +++ b/tests/test_dumas_h3_refmod_picker.py @@ -0,0 +1,71 @@ +import importlib.util +import os +import sys +import tempfile +import types +import unittest + + +class FakeMod: + def __init__(self, kind="video", description="hero"): + self.kind = kind + self.description = description + self.concept_type = "identity" + + +class DumasRefModPickerTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + folder_paths = types.ModuleType("folder_paths") + folder_paths.models_dir = tempfile.gettempdir() + folder_paths.get_folder_paths = lambda _name: [] + folder_paths.add_model_folder_path = lambda *_args: None + sys.modules.setdefault("folder_paths", folder_paths) + spec = importlib.util.spec_from_file_location( + "dumas_h3_refmod_picker", "dumas_h3_refmod_picker.py") + cls.module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(cls.module) + + def test_weight_expands_into_full_and_fractional_rows(self): + self.assertEqual(self.module._expand_weight(2.4), [1.0, 1.0, 0.4]) + self.assertEqual(self.module._expand_weight(0.0), []) + + def test_browser_lists_only_refmod_metadata_files(self): + with tempfile.TemporaryDirectory() as folder: + old_roots = self.module._roots + self.module._roots = lambda: [folder] + try: + with open(os.path.join(folder, "not_a_refmod.safetensors"), "wb") as handle: + handle.write(b"not a safetensors file") + original_meta = self.module._read_meta + self.module._read_meta = lambda path: {"kind": "video", "description": "test"} + try: + result = self.module.list_browser_dir(folder) + finally: + self.module._read_meta = original_meta + self.assertEqual(len(result["mods"]), 1) + self.assertEqual(result["mods"][0]["kind"], "video") + finally: + self.module._roots = old_roots + + def test_picker_loads_legacy_loader_api_and_appends_existing_rows(self): + loaded = [FakeMod("video"), FakeMod("audio", "voice")] + loader_module = types.SimpleNamespace( + load_refmods_from_file=lambda _path, device="cpu": loaded) + old_modules = dict(sys.modules) + sys.modules["fake_refmod_core"] = loader_module + old_safe = self.module._safe_file + self.module._safe_file = lambda _path: "/tmp/hero.safetensors" + try: + result = self.module.DumasH3RefModPicker().pick( + "/tmp/hero.safetensors", video_weight=1.0, audio_weight=0.5, + mods=[(FakeMod(), 1.0)]) + self.assertEqual(len(result[0]), 3) + finally: + self.module._safe_file = old_safe + sys.modules.clear() + sys.modules.update(old_modules) + + +if __name__ == "__main__": + unittest.main()