From c9eb575e2fd25f74b15f1d7336af4932c7fe6338 Mon Sep 17 00:00:00 2001 From: Chris Dumas Date: Tue, 20 Oct 2026 13:43:48 +0000 Subject: [PATCH] Squashed 'vendor/dumas_h3_refmod_picker/' content from commit c732f8b git-subtree-dir: vendor/dumas_h3_refmod_picker git-subtree-split: c732f8b8893bf4f00c6974c9b9941c763496fe48 --- .gitignore | 22 + LICENSE | 21 + README.md | 89 ++ __init__.py | 36 + docs/examples/browser_example.png | Bin 0 -> 1725430 bytes docs/examples/create_from_folder_example.png | Bin 0 -> 77034 bytes docs/examples/workflow_example.png | Bin 0 -> 1347514 bytes example_workflows/create_refmod_example.jpg | Bin 0 -> 44169 bytes example_workflows/create_refmod_example.json | 1 + example_workflows/refmod_example.jpg | Bin 0 -> 114856 bytes example_workflows/refmod_example.json | 1 + example_workflows/refmod_to_video_example.jpg | Bin 0 -> 1074193 bytes .../refmod_to_video_example.json | 1 + image.png | Bin 0 -> 77034 bytes js/placeholder.png | Bin 0 -> 30069 bytes js/refmod_create.js | 392 ++++++ js/refmod_loader.js | 116 ++ js/visual_refmod_picker.js | 1230 +++++++++++++++++ nodes/refmod_apply.py | 183 +++ nodes/refmod_axis.py | 186 +++ nodes/refmod_create.py | 1143 +++++++++++++++ nodes/refmod_decode.py | 116 ++ nodes/refmod_loader.py | 283 ++++ nodes/refmod_visual_picker.py | 165 +++ nodes/refmods_to_video.py | 293 ++++ py/refmod_browser.py | 253 ++++ py/refmod_common.py | 96 ++ py/refmod_core.py | 958 +++++++++++++ py/refmod_vae_loader.py | 60 + tools/generate_video_thumbnails.py | 138 ++ 30 files changed, 5783 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 __init__.py create mode 100644 docs/examples/browser_example.png create mode 100644 docs/examples/create_from_folder_example.png create mode 100644 docs/examples/workflow_example.png create mode 100644 example_workflows/create_refmod_example.jpg create mode 100644 example_workflows/create_refmod_example.json create mode 100644 example_workflows/refmod_example.jpg create mode 100644 example_workflows/refmod_example.json create mode 100644 example_workflows/refmod_to_video_example.jpg create mode 100644 example_workflows/refmod_to_video_example.json create mode 100644 image.png create mode 100755 js/placeholder.png create mode 100644 js/refmod_create.js create mode 100644 js/refmod_loader.js create mode 100644 js/visual_refmod_picker.js create mode 100644 nodes/refmod_apply.py create mode 100644 nodes/refmod_axis.py create mode 100644 nodes/refmod_create.py create mode 100644 nodes/refmod_decode.py create mode 100644 nodes/refmod_loader.py create mode 100644 nodes/refmod_visual_picker.py create mode 100644 nodes/refmods_to_video.py create mode 100644 py/refmod_browser.py create mode 100644 py/refmod_common.py create mode 100644 py/refmod_core.py create mode 100644 py/refmod_vae_loader.py create mode 100644 tools/generate_video_thumbnails.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0448413 --- /dev/null +++ b/.gitignore @@ -0,0 +1,22 @@ +# Python bytecode / caches +__pycache__/ +*.py[cod] +*$py.class + +# Virtual environments +.venv/ +venv/ +env/ + +# Editor / OS clutter +*.swp +*.swo +*~ +.DS_Store +.directory +Thumbs.db + +# Tooling +.history/ +*.code-workspace +test/ \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f4729f6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Luisa (luisacaotica) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..0b37f0c --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# ComfyUI-H3RefModPicker + +Companion add-on for [ComfyUI-MiniMaxH3Mod](https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod) + +This add-on is meant to work alongside **MiniMaxH3Mod**. It provides a small, focused subset of RefMod features: a Visual Picker, a simple loader, an apply axis, a batch Create From Folder node, and grounded RefMods-to-Video generation with an optional reference collector. It keeps compatibility with both the original RefMod format and the newer bundle format. + +If you want the fuller MiniMax H3 RefMod toolset and more creation/apply options, the recommended install is [ComfyUI-MiniMaxH3Mod](https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod). + +Please note, the `Create from Input` node was removed from this add-on. The same functionality is available in the official MiniMaxH3Mod add-on, using the `Create H3 RefMod Master` node. + +## Latest Updates + +Video-file support has been removed from `Create H3 RefMod From Folder`. Video clips are not ideal for the simple, lightweight RefMods this add-on aims to create: around **six to ten well-chosen reference images** are usually sufficient. Keep their aspect ratios consistent within each dataset folder. This is a recommendation, not an image limit; optional audio remains supported, and video files in the folder are ignored. + +## Preview image naming + +To have the Visual Picker pick up a preview image, place the image beside the RefMod using the same base name as the RefMod file. + +- For the newer bundle format, the image and the RefMod just need to share the exact same name. Example: `character_refMod.safetensors` with `character_refMod.png`. +- For older split RefMods, do not name the preview image `_audio` or `_visual`. Use only the shared base name. Example: `character_refMod_visual.safetensors` and `character_refMod_audio.safetensors` should use `character_refMod.png`. +- When a matching `_visual` and `_audio` pair exists, plus that shared preview image, the picker sees them as one logical item. + + +

+ Extract H3 RefMod in use +
+ Example using refMods from Malcolm Reynolds. +

+ +

+ Workflow example +
+ Use Left and Right arrows when over Picker to switch quickly. +

+ +

+ Create from folder example +
+ Create refMods from Folder example. +

+ +## Main additions + +- `Visual RefMod Picker` lets you browse using a **RefMods** browser. It supports legacy split RefMods and the newer single-file bundle format. +- For legacy split RefMods, found pairs are grouped as one item in the picker. They are shown as one entry and loaded together, with separate video/audio weight controls. This uses a weight behavior: `0..1` is regular strength, values above 1 expand into repeated copies. For example, a weight of 2.7 would be the same as strength: 1.0, copies: 2.7. +- `Create H3 RefMod From Folder` scans a folder of reference images and optional audio, and saves in the bundle format by default. Around six to ten images can be sufficient. It can also batch-create RefMods for all subfolders found. The optional `include_images` switch adds reconstructed encoder pictures to visual RefMods while keeping the existing latent format compatible; it is off by default. +- `Load RefMod Simple` is a singular loader. It supports standalone visual/audio RefMods and the new bundle format, while still using the same weight behavior as the Picker. +- `MiniMax H3 RefMods to Video` grounds prompt labels with RefMod pictures and applies their visual/audio latents, returning positive conditioning, an empty AV latent, and a reference map. Optional ordinary media can be added through `Collect H3 References`. It replaced minimax's Reference to Video node. It takes in mods as an input, bypassing the need to apply the RefMods using an apply node. +- `Apply H3 RefMod Simple` is a streamlined version of the Apply H3 RefMod, without the extra controls. + +## RefMods to Video Node + +The grounded RefMods-to-Video node builds on work by [Adudeguyman's ComfyUI-Fantastic-MiniMaxH3-PromptBuilder](https://github.com/Adudeguyman/ComfyUI-Fantastic-MiniMaxH3-PromptBuilder). This also revisits earlier visual-grounding experiments this add-on had initially, which were perhaps set aside a little too quickly :) + +Unlike plain prompt encoding followed by RefMod Apply, this node gives the text encoder visual content behind labels such as `` and `