310 lines
15 KiB
Markdown
310 lines
15 KiB
Markdown
# DumasNodes
|
||
|
||
## Vendored MiniMax H3 packs
|
||
|
||
DumasNodes contains complete, license-preserving source copies of the three
|
||
upstream packs used by the MiniMax H3 workflow:
|
||
|
||
- `vendor/dumas_h3_continuum/`
|
||
- `vendor/dumas_minimax_h3_refmod/`
|
||
- `vendor/dumas_h3_refmod_picker/`
|
||
|
||
Their registrations and browser extensions are loaded by DUMAS. Every vendored
|
||
node is registered with a stable DUMAS-prefixed ID and under a DUMAS category:
|
||
|
||
- `DumasH3Continuum_*` → `Dumas/MiniMax H3/Continuum`
|
||
- `DumasMiniMaxH3RefMod_*` → `Dumas/MiniMax H3/RefMod`
|
||
- `DumasH3RefModPicker_*` → `Dumas/MiniMax H3/RefMod Picker`
|
||
|
||
This prevents the vendored nodes from replacing or colliding with an upstream
|
||
node of the same name. Existing workflows that use the upstream IDs are not
|
||
silently rewritten; they must continue to use the upstream pack or be
|
||
reconnected to the DUMAS nodes. The original packs should still not be loaded
|
||
alongside this copy because their server routes can overlap even though the
|
||
node IDs are now isolated.
|
||
|
||
The upstream source is imported as git subtrees, making future reviews and
|
||
selective updates possible without losing provenance. DUMAS-specific changes
|
||
belong outside `vendor/` unless an upstream implementation is intentionally
|
||
being amended.
|
||
|
||
Generic ComfyUI utility nodes under the Dumas brand. MiniMax H3-specific
|
||
nodes are grouped under `Dumas/MiniMax H3/...` so they can be installed
|
||
as the self-contained H3 installation; do not install the separate upstream
|
||
packs alongside this vendored copy.
|
||
|
||
## Sequential video assembly
|
||
|
||
### Dumas Standalone Video
|
||
|
||
`DumasStandaloneVideo` saves both the complete generated clip and a full copy.
|
||
For a continuation clip, set `reference_frames` to the number of frames taken
|
||
from the previous clip for continuity. The value is returned as the final
|
||
`reference_frames` output so it can be wired directly into
|
||
`DumasJoinVideoClips`.
|
||
|
||
### Dumas Join Video Clips (No Re-encode)
|
||
|
||
`DumasJoinVideoClips` accepts one reference-frame input for each clip. It trims
|
||
that many frames from the beginning of any clip whose value is greater than
|
||
zero, then concatenates the resulting files with FFmpeg stream copy. This
|
||
avoids a full re-encode of the assembled video. Clip 1 normally remains at
|
||
zero; continuation clips receive the reference-frame output from their
|
||
standalone nodes.
|
||
|
||
Stream-copy trimming is codec/keyframe-aware: the requested boundary is
|
||
converted using the clip's frame rate, but a codec may choose the nearest safe
|
||
packet boundary. For exact frame cuts, use the existing `complete_clip` output
|
||
or accept a re-encoded workflow.
|
||
|
||
## Project rendering
|
||
|
||
## MiniMax H3 tiled latent upscale
|
||
|
||
`DumasMMH3TiledLatentUpscale` is a thin integration node for the native
|
||
`MMH3UltimateUpscale` node used by the MiniMax-H3 workflow. It accepts the
|
||
native H3 latent-upscale, temporal-split, and spatial-split parameter objects,
|
||
but creates a separate upscale sampler, scheduler, sigma schedule, noise seed,
|
||
denoise value, steps value, and CFG value. The base H3 sampling pass is not
|
||
changed.
|
||
|
||
Typical wiring:
|
||
|
||
```text
|
||
base H3 latent + model + conditioning
|
||
-> Dumas MiniMax-H3 Tiled Latent Upscale
|
||
H3 Latent Upscale Params --------------------^
|
||
H3 Temporal Split Params ---------------------^
|
||
H3 Spatial Split Params -----------------------^
|
||
```
|
||
|
||
The node requires the ComfyUI installation to provide `MMH3UltimateUpscale`,
|
||
`RandomNoise`, `KSamplerSelect`, and `BasicScheduler`. It does not copy or
|
||
redistribute the third-party H3 LongVideos implementation. The native node's
|
||
current socket types are `H3_UPSCALE_PARAM`, `H3_TEMPORAL_PARAM`, and
|
||
`H3_SPATIAL_PARAM`; these are deliberately used unchanged for workflow
|
||
compatibility.
|
||
|
||
### MiniMax H3 2D spatial latent upscale
|
||
|
||
`DumasMMH3LatentUpscale2D` supports the `minimax_h3_latent_upscaler_2d_conv_v1`
|
||
checkpoint from [LBH-123-AI](https://huggingface.co/LBH-123-AI/Minimax_h3_latent_Upscaler).
|
||
It uses the model's published loader and architecture, but keeps DUMAS ownership
|
||
of the node and adds X/Y tiling. The full temporal latent is passed through each
|
||
tile; temporal splitting is intentionally not used. Put the checkpoint in
|
||
`models/latent_upscale_models`, then set the target `width` and `height` in
|
||
pixels. The dimensions are converted to H3 latent dimensions internally. Set
|
||
`tile_size` and `tile_overlap` to fit available VRAM.
|
||
|
||
`DumasMMH3LatentUpscale2DModelParams` is the matching parameter node. Its output
|
||
is `latent_upscale_param` with type `H3_UPSCALE_PARAM`, so it connects to the
|
||
existing DUMAS Continuum tiled-upscale node in the same place as the native H3
|
||
model-parameter node.
|
||
|
||
### DUMAS H3 Sequence Prompt Builder
|
||
|
||
`DumasH3SequencePromptBuilder` provides the tabbed, timeline-oriented prompt
|
||
editor used for multi-chunk H3 jobs. It emits one absolute sequence prompt,
|
||
the chunk count, the shared chunk duration, and a per-chunk reference bundle.
|
||
Reference images are inserted as `@R1` through `@R9`; routing is based on the
|
||
shared directive, soundscape, music, and each chunk's full prompt text.
|
||
|
||
The builder exposes nine optional `IMAGE` sockets, labelled `Reference Image 1`
|
||
through `Reference Image 9`. Each connected socket occupies the matching `@R`
|
||
slot, and the generated Continuum reference bundle contains those images with
|
||
per-chunk routing. RefMod inputs and direct RefMod conditioning are deliberately
|
||
not part of this node.
|
||
|
||
The prompt builder intentionally uses the `ReferenceImagesV39Bundle` class
|
||
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 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
|
||
|
||
Optional FLUX.3 outputs:
|
||
|
||
- `flux3_prompt`: a complete FLUX.3 scene caption followed by the native
|
||
bounding-box JSON array. Connect this to the FLUX.3 Klein prompt input; keep
|
||
the workflow's official prompt upsampler in the normal position.
|
||
- `flux3_boxes_json`: the same bounding-box array separately for inspection or
|
||
downstream processing.
|
||
|
||
The `output_format` setting selects `legacy`, `flux3`, or `both` (default).
|
||
FLUX.3 boxes use `[top, left, bottom, right]` integer coordinates on a 0–1000
|
||
top-left-origin grid. Every generated ID is also emitted as `<id>` in the
|
||
caption. `flux3_reference_mode=editing` is intentionally rejected until source
|
||
coordinates and reference-image identifiers are available; the current VLM
|
||
inventory schema supports generation-style layouts only. Bounding boxes guide
|
||
placement and scale but are not hard pixel masks.
|
||
|
||
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
|
||
MiniMax H3 RefMod nodes and adds explicit DUMAS-owned storage policy:
|
||
|
||
- `Registered RefMods` is the default and saves to ComfyUI's first registered
|
||
`refmods` root, preserving normal loader discovery.
|
||
- `Input folder` saves beside a server-side source folder supplied through the
|
||
`input_folder` socket. Standard IMAGE/VIDEO tensors do not contain their
|
||
original filesystem path, so this path must be supplied explicitly.
|
||
- `Custom folder` saves to an explicitly supplied server-side folder.
|
||
- `Increment filename` is the default collision policy; `Replace` and `Fail`
|
||
are also available.
|
||
|
||
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 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.
|
||
|
||
The vendored `DUMAS H3 Continuum · H3 Continuum Sampler V3.9` also exposes an
|
||
optional `RefMods (Optional)` socket. Connect the `H3_REF_MODS` output from a
|
||
RefMod loader or creator directly to that socket; the sampler clones the model
|
||
and attaches the RefMod bridge only for that run. `RefMod Retention` and
|
||
`RefMod Token Budget` are available beside the socket, while ordinary image
|
||
reference routing remains unchanged. The DUMAS V3.9 surface removes the
|
||
duplicated legacy resolution widgets and uses the connected `Width` and
|
||
`Height` values as its single manual-dimension source. The separate model
|
||
bridge node is still available for V3.8 and other samplers.
|
||
|
||
### DUMAS H3 RefMods to Continuum
|
||
|
||
`DUMAS H3 RefMods to Continuum` is the minimal compatibility bridge for the
|
||
upstream Continuum sampler. It decodes one visual frame from each selected
|
||
RefMod with the H3 video VAE and emits Continuum's native nine-slot V3.9
|
||
Reference Images bundle. Continuum then performs its normal resize, VAE encode,
|
||
prompt presentation, and physical-group routing.
|
||
|
||
Connect the sequence prompt and choose `Prompt @R tags` to route each RefMod
|
||
only to chunks whose prompt section contains its `@R1`–`@R9` tag. Choose `All
|
||
chunks` to provide every decoded visual reference to every chunk. Audio-only
|
||
RefMods are skipped because Continuum's image-reference socket is visual-only.
|
||
The native image bundle has no per-reference strength field, so picker weights
|
||
are intentionally not carried across this compatibility boundary.
|
||
|
||
This bridge intentionally avoids patching Continuum's internal conditioning
|
||
runtime. Direct latent injection would need to alter its per-group reference
|
||
contracts, storage fingerprints, and prompt-picture mapping, and would be a
|
||
much larger and more fragile fork. The trade-off is one decode followed by
|
||
Continuum's normal reference encode; pooled/training RefMods will therefore
|
||
retain only the visual information present in their stored latent.
|
||
|
||
### DUMAS H3 Continuum Tiled Latent Upscale (Per Clip)
|
||
|
||
`DumasH3ContinuumTiledLatentUpscalePerClip` is a replacement for the upstream
|
||
Second Pass when tiled latent upscale is required. It applies the native H3
|
||
tiled upscale independently to each physical Continuum clip, passes the
|
||
first-pass audio latents through unchanged, and returns the updated assembly
|
||
plan plus status. It accepts the Continuum `refine_context` and uses the
|
||
upstream refine bridge when no direct conditioning is connected. Its sampler,
|
||
scheduler, sigma input, steps, denoise, CFG, and noise seed are separate from
|
||
the base generation pass. Connected sockets take precedence over node
|
||
defaults. The node preserves one LATENT list item per physical clip to avoid
|
||
concatenating a long sequence into one oversized VRAM allocation.
|
||
|
||
The CSGlide `Render Project` control is the generation orchestrator: it renders
|
||
clips sequentially, adopts each completed render, extracts the previous clip's
|
||
tail, fills the next clip's `CONTINUE FROM` guide, and waits before advancing.
|
||
DumasNodes intentionally remains model-agnostic and handles clean individual
|
||
outputs, tail preparation and optional final assembly rather than duplicating
|
||
CSGlide's MiniMax generation loop.
|
||
|
||
### Dumas Prepare Continuation
|
||
|
||
Give this node the raw output of a continuation generation and its reference
|
||
frame count. It produces a clean presentation clip and a `next_reference`
|
||
tail clip. Only the tail is intended to feed the next generation; the entire
|
||
previous clip is never passed forward as the continuity input.
|
||
|
||
### Save Video DUMAS
|
||
|
||
Save an IMAGE batch as an H.264 MP4 in any server-side folder. The folder can
|
||
be typed directly or selected with the Browse folder button; leaving it empty
|
||
uses ComfyUI's output folder. Filename patterns support nested folders and
|
||
`%counter%`, and existing files are never overwritten. Optional audio is
|
||
encoded as AAC, and preview mode writes to ComfyUI's temporary directory.
|
||
|
||
## Other nodes
|
||
|
||
- Dumas Image Compare
|
||
- Emits collision-safe temporary previews for every connected slot while retaining the DUMAS result output for downstream workflows.
|
||
- Save Image Dumas
|
||
- Saves PNG, JPG, or WebP to the ComfyUI output folder or a selected external folder.
|
||
- Uses collision-safe counters for files and nested folders, with batch-safe numbering.
|
||
- Preview mode writes temporary images for inspection without touching the destination folder.
|
||
- Supports filename chips for inputs, date/time, counter, dimensions, and batch number.
|
||
- Load Images from Folder Dumas
|
||
- Pixaroma-style folder browser with recursive listing, thumbnail metadata, selected/all/first-N/random modes, date/name sorting, alpha masks, and batch outputs.
|
||
- Outputs one list item per selected image, including image, mask, dimensions, filename, index, total, and absolute path.
|
||
- Dumas JSON helpers
|
||
- DUMAS Resolution
|
||
- Pixaroma-inspired ratio and AI-friendly size picker with 1:1, 16:9, 9:16, 2:1, 3:2, 2:3, 4:3, 3:4, and 4:5 presets.
|
||
- Includes Custom Ratio, Custom Resolution, 8/16/32/64px snapping, megapixel feedback, batch state, and width/height plus Empty-Latent-compatible outputs.
|
||
|
||
## Installation
|
||
|
||
Copy or clone this repository into `ComfyUI/custom_nodes/DumasNodes` and restart
|
||
ComfyUI. FFmpeg and FFprobe must be available on `PATH` for the video nodes.
|
||
|
||
## Development
|
||
|
||
Run the fast unit tests from the repository root:
|
||
|
||
```bash
|
||
python -m unittest discover -s tests -p 'test_*.py'
|
||
```
|