Add DUMAS H3 RefMod picker

This commit is contained in:
2026-10-20 13:13:50 +00:00
parent 37abd6e86e
commit 7f0e8d8fe4
6 changed files with 448 additions and 2 deletions
+17 -2
View File
@@ -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 All writes use the RefMod object's atomic save operation. The node reports the
resolved `.safetensors` paths through `saved_paths`. External folders are not resolved `.safetensors` paths through `saved_paths`. External folders are not
automatically added to the RefMod dropdown; register them as a ComfyUI automatically persistent across restarts, but they are registered as RefMod
`refmods` root or load them through the upstream folder/library tooling. 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) ### DUMAS H3 Continuum Tiled Latent Upscale (Per Clip)
+6
View File
@@ -31,6 +31,10 @@ from .dumas_h3_refmod_nodes import (
NODE_CLASS_MAPPINGS as H3_REFMOD_NODE_CLASS_MAPPINGS, NODE_CLASS_MAPPINGS as H3_REFMOD_NODE_CLASS_MAPPINGS,
NODE_DISPLAY_NAME_MAPPINGS as H3_REFMOD_NODE_DISPLAY_NAME_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 = {}
NODE_CLASS_MAPPINGS.update(JSON_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_PROMPT_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(H3_UPSCALE_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_NODE_CLASS_MAPPINGS)
NODE_CLASS_MAPPINGS.update(H3_REFMOD_PICKER_NODE_CLASS_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS = {} NODE_DISPLAY_NAME_MAPPINGS = {}
NODE_DISPLAY_NAME_MAPPINGS.update(JSON_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_PROMPT_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(H3_UPSCALE_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_NODE_DISPLAY_NAME_MAPPINGS)
NODE_DISPLAY_NAME_MAPPINGS.update(H3_REFMOD_PICKER_NODE_DISPLAY_NAME_MAPPINGS)
WEB_DIRECTORY = "./js" WEB_DIRECTORY = "./js"
+10
View File
@@ -108,11 +108,21 @@ class DumasH3RefModSave:
if not raw_folder: if not raw_folder:
raise ValueError("Input folder mode requires a connected input_folder path.") raise ValueError("Input folder mode requires a connected input_folder path.")
root = os.path.realpath(raw_folder) 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": elif save_location == "Custom folder":
raw_folder = str(custom_output_folder or "").strip() raw_folder = str(custom_output_folder or "").strip()
if not raw_folder: if not raw_folder:
raise ValueError("Custom folder mode requires a connected custom_output_folder path.") raise ValueError("Custom folder mode requires a connected custom_output_folder path.")
root = os.path.realpath(raw_folder) 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: else:
raise ValueError(f"Unknown RefMod save location: {save_location!r}") raise ValueError(f"Unknown RefMod save location: {save_location!r}")
+267
View File
@@ -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
+77
View File
@@ -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]);
};
},
});
+71
View File
@@ -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()