DumasNodes/README.md

# DumasNodes

`DumasNodes` is a ComfyUI custom-node pack for generic utility workflows under the Dumas brand.

## Included Nodes

- `Dumas Image Compare`
  - Inputs: optional `image1`, optional `image2`
  - Outputs: `new image`
  - Saves preview images for the built-in compare UI and passes through the second image when present, otherwise the first.
  - Bundles a `js/` frontend extension so the compare viewer renders inside both classic ComfyUI and Nodes 2.0.

- `Save Image Dumas`
  - Inputs: `images`, `folder`, `pattern`, `format`, `quality`, `embed_workflow`, `save_on_run`, optional `name`, optional `name_2`
  - Output: none
  - Saves images to any folder, not just ComfyUI's output directory.
  - Supports filename tokens including `%input%`, `%input2%`, `%date:yyyy-MM-dd%`, `%counter%`, `%width%`, `%height%`, and `%batch_num%`.

- `Load Images from Folder Dumas`
  - Inputs: configured on-node via folder picker and image gallery
  - Outputs: `image`, `mask`, `width`, `height`, `filename`, `index`, `total`
  - Loads one or many images from any folder on disk as ComfyUI list outputs.
  - Supports manual picks, `Select all`, `First N`, and `Select random` so each run can choose one random image from the visible folder tree.

- `Dumas H3 Plan Attach Scene Images`
  - Inputs: `plan`, `scene_index`, optional `image1`..`image9`
  - Outputs: `plan`, `connected_images`
  - Attaches up to nine optional image sockets to one MiniMax H3 plan scene while keeping the plan JSON-serializable for the upstream archive system.
  - Chain one node per scene that needs its own nine-image bundle.

- `Dumas H3 Plan Extract Scene Images`
  - Inputs: `plan`, `scene_index`
  - Outputs: `plan`, `image1`..`image9`, `connected_images`
  - Reads back the nine optional images for a selected MiniMax H3 plan scene, for example by connecting the current `clip_index`.

- `Dumas H3 Long Videos (FL2VA + REF2VA)`
  - Inputs: H3 model stack, prompt socket, optional `first_frame`, optional `ref_1`..`ref_9`, plus the upstream long-video control surface for pacing, continuity, audio, overlays, and guards
  - Outputs: `images`, `audio`, `info`, `script`, `frames_per_shot`, `total_frames`, `shots`, `video_seconds`, `fps`, `fps_int`, `latent`, `soundscape`
  - First-pass Dumas port of the `MiniMax-H3-Longvideos` sampler, brought in as a local starting point for long-form H3 chaining work.
  - Keeps the upstream split-beats / handoff / ref-routing behavior close to source so future Dumas-specific improvements can be compared against a known baseline.
  - Full user guide: [`H3_LONG_VIDEOS_GUIDE.md`](./H3_LONG_VIDEOS_GUIDE.md)
  - Only the canonical `DumasH3LongVideos` node key is exposed now; the older FL2VA/REF2VA alias entries are no longer duplicated in the Add Node menu.
  - Prompt `<Picture N>` tags now map to the actual ref socket numbers you wire, even with gaps such as only `ref_2` and `ref_7` connected.
  - Character refs now contribute appearance and wardrobe context from the same structured object, while location refs contribute environment context from theirs.
  - The default ref2v bias is now stronger: `ref_mode` defaults to `auto ref2v` so untagged prompts condition every shot instead of only shot 1, and `ref_noise_aug` defaults to `0.95` rather than the upstream-literal `0.999`.
  - `Dumas H3 Latent Upscale Params` provides the optional pre-decode latent refinement stage for the long-video node.
  - Per-shot directives now support `continuity:`, `ref_mode:`, `ref_noise_aug:`, `anchor_add:`, `soundscape:`, and `music:` in addition to the existing timing and wardrobe directives.

- `Dumas H3 Latent Upscale Params`
  - Inputs: `mode`, `model_name`, `method`, `width`, `height`, `device`, `precision`, `sampler_name`, `scheduler`, `steps`, `denoise`, `megapixels`, `tile_width`, `tile_height`, `overlap`, `fade_width`, `fade_height`, `overlap_mode`, `overlap_blend`, `tile_size_mode`, `grid_rows`, `grid_cols`, `spatial_w_overlap`, `spatial_h_overlap`, `min_tile_size`, `masked_area_noise`, `brightness_match`, `dynamic_fade`, `dynamic_fade_min`, `chunk_length`, `temporal_overlap`, `resize_conditioning`, `anchor_strength`
  - Output: `latent_upscale_param`
  - Bundles the optional latent-space upscaler settings used by `Dumas H3 Long Videos` before decode, so the main node can rebuild conditioning at the target size and run a short refinement pass with your chosen sampler, scheduler, step count, denoise, and the full upstream spatial split controls.

- `Dumas H3 Beat Prompt`
  - Inputs: authored through the custom front-end beat editor
  - Output: `prompt`
  - Builds one H3 prompt block per beat, with quick controls for per-shot timing, continuity, ref behavior, anchor additions, soundscape, and music while staying compatible with direct text editing.

- `Dumas H3 Prompt Curator`
  - Inputs: `action_prompt`, `anatomy_guard`, `subject_count_guard`, optional `anchor`, optional `soundscape`, optional `bgm`, optional `ref_1` through `ref_9`
  - Outputs: `prompt`, `ref_image_1` through `ref_image_9`, `reference_count`, `debug`, `anchor`, `sounds`, `bgm`, `original_ref_1` through `original_ref_9`, `reference_description`, `original_ref_description_1` through `original_ref_description_9`
  - Builds one standalone MiniMax H3 prompt from your final action text plus structured character/location references.
  - The action text can mention references by character/location name, alias, `<Picture N>`, or `<refN>`. Only mentioned references are emitted, and the output images are compacted/renumbered so skipped inputs do not leave gaps.
  - Extra component outputs expose the cleaned anchor, sounds, BGM, selected structured references in compacted order, the compiled reference-description block used inside the prompt, and one individual description per selected reference.
  - Adds curated reference context, anatomy guard text, optional subject-count guard text, anchor/style text, `overall_soundscape:` text, and `background_music:` text while respecting MiniMax H3's reference-generation shape: one prompt plus up to nine reference images.

- `Dumas H3 Shot Length`
  - Inputs: `shot_seconds`, `fps`, optional `cap_to_h3_max`
  - Outputs: `seconds`, `frames`, `info`
  - Emits one H3-safe shot length as both seconds and a grid-aligned frame count for wiring into the long-video sampler and preview helpers.

- `Dumas H3 Model Inspector`
  - Input: `model`
  - Outputs: `format`, `report`
  - Reports the detected H3 base precision / quant format and the relevant compute-capability hints for the current card.

- `Dumas Character Reference`
  - Inputs: `image`, `character_id`, `name`, `alias`, `gender`, `age`, `nationality`, `occupation`, `height_feet`, `height_inches`, `accent`, `description`, `general`, `wardrobe`
  - Output: `reference`
  - Builds one structured `REFERENCE` object carrying the conditioning image, identity description, wardrobe, general notes, and simple facts together.

- `Dumas Location Reference`
  - Inputs: `image`, `location_id`, `name`, `alias`, `description`, `general`
  - Output: `reference`
  - Builds one structured `REFERENCE` object for a location/environment so H3 can use the same socket type for both character and scenic refs.

- `Dumas Character Helper`
  - Inputs: `image1`, `image2`, picture IDs, character identity fields, `general`, `wardrobe`
  - Outputs: `image1`, `image2`, `reference_prompt`, `wardrobe`, `reference1`, `reference2`
  - Restores the original general-purpose helper shape while also emitting two structured `REFERENCE` objects for the prompt curator.
  - The structured references carry the same character name, alias, age, height, gender, nationality, occupation, accent, wardrobe, and notes, so mentioning the character name in `Dumas H3 Prompt Curator` can include both helper images and the character facts automatically.

- `Dumas Location Helper`
  - Inputs: `image1`, `image2`, picture IDs, `location_id`, `name`, `alias`, `description`, `general`
  - Outputs: `image1`, `image2`, `reference_prompt`, `reference1`, `reference2`
  - Matching general-purpose helper for environments/locations: pass two images through unchanged, emit location reference prompt text, and provide two structured `REFERENCE` objects for the prompt curator.
  - The structured references carry the same location name, alias, description, and notes, so mentioning the location name in `Dumas H3 Prompt Curator` can include both helper images and the location context automatically.

- `Dumas Anchor Style`
  - Inputs: `anchor_style`, `style_description`
  - Output: `anchor`
  - Offers a large preset dropdown of anchor-style titles such as cinematic action movie, comedy, found footage, 90s sitcom, mobile/cell phone captured, news broadcast, mockumentary, heist thriller, cyberpunk neon, nature documentary, courtroom drama, and more.
  - The preset wording is tuned for H3-safe persistent anchors: camera language, lighting, texture, production treatment, and tone, without naming characters or describing one-off actions.
  - Selecting a preset fills the editable description field, and the edited multiline description is the `STRING` value passed downstream.

- `Dumas Soundscape Helper`
  - Inputs: `soundscape`, `soundscape_description`
  - Output: `soundscape`
  - Matching soundscape helper for standalone H3 prompts. Pick a preset such as quiet interior, rainy street, cafe, city night, forest, industrial, or silent; the preset fills the editable textbox, and the edited text flows into `Dumas H3 Prompt Curator`.

- `Dumas Background Music Helper`
  - Inputs: `bgm`, `bgm_description`
  - Output: `bgm`
  - Matching BGM helper for standalone H3 prompts. Pick a preset such as subtle tension, cinematic suspense, emotional piano, dark ambient, hopeful orchestral, retro synth, action pulse, lo-fi, or no vocals; the preset fills the editable textbox, and the edited text flows into `Dumas H3 Prompt Curator`.

- `Dumas JSON String to Object`
  - Input: `json_string`
  - Output: parsed `JSON`
  - Use it to turn raw JSON text into a structured object.

- `Dumas JSON Object to String`
  - Inputs: `json_object`, `pretty`, `sort_keys`
  - Output: serialized `STRING`
  - Use it to compact or pretty-print JSON for prompts, logs, or file output.

- `Dumas Strip Iteration Suffix`
  - Input: `filename`
  - Output: cleaned `STRING`
  - Keeps only the part before the first underscore, for example `asset_build_003.png -> asset.png` and `char123_pose.png -> char123.png`.

- `Dumas Slugify String`
  - Input: `text`
  - Output: slug `STRING`
  - Converts text into a lowercase URL/file-safe slug, for example `Crème brûlée 2026 -> creme-brulee-2026`.

- `Dumas JSON Get Value`
  - Inputs: `json_object`, `path`
  - Output: `JSON`
  - Reads a nested value using dot paths like `user.profile.name` or `items.0.id`.

- `Dumas JSON Set Value`
  - Inputs: `json_object`, `path`, `value_json`
  - Output: updated `JSON`
  - Writes a parsed JSON value into a nested path without mutating the original object.

- `Dumas JSON Has Key`
  - Inputs: `json_object`, `path`
  - Output: `BOOLEAN`
  - Checks whether a nested path exists.

- `Dumas JSON Remove Key`
  - Inputs: `json_object`, `path`
  - Output: updated `JSON`
  - Removes a nested key or array item by path.

- `Dumas JSON Pick Fields`
  - Inputs: `json_object`, `paths`
  - Output: filtered `JSON`
  - Builds a new object from newline-separated paths that exist in the input.

- `Dumas JSON Merge Objects`
  - Inputs: `base_object`, `overlay_object`
  - Output: merged `JSON`
  - Deep-merges dictionaries so overlay values replace or extend the base object.

- `Dumas JSON Keys`
  - Input: `json_object`
  - Outputs: `keys` as JSON array, `count` as integer
  - Lists the top-level keys of an object and reports how many there are.

- `Dumas JSON Array Length`
  - Input: `json_array`
  - Output: `INT`
  - Returns the length of a JSON array.

- `Dumas JSON Array Append`
  - Inputs: `json_array`, `value_json`
  - Output: updated `JSON`
  - Appends a parsed JSON value to the end of an array.

- `Dumas JSON Array Slice`
  - Inputs: `json_array`, `start`, `end`, `step`
  - Output: sliced `JSON`
  - Returns an array slice. `end=0` means "slice to the end".

- `Dumas JSON Array Iterator`
  - Inputs: `json_input`, `index`, `mode`
  - Outputs: `item`, `current_index`, `total_items`
  - Returns the current array item and position, with `mode` set to `fixed`, `incr`, or `decr`.

- `Dumas JSON Object Iterator`
  - Inputs: `json_input`, `index`, `mode`
  - Outputs: `key`, `value`, `current_index`, `total_items`
  - Returns the current object entry in insertion order, with `mode` set to `fixed`, `incr`, or `decr`.

- `Dumas JSON Flatten`
  - Input: `json_input`
  - Output: flat `JSON`
  - Flattens nested objects and arrays into dot-path keys.

- `Dumas JSON Unflatten`
  - Input: `flat_json_object`
  - Output: nested `JSON`
  - Rebuilds nested JSON from a flat dot-path object.

All nodes live in the `Dumas/JSON` category.

## Installation

1. Change into your ComfyUI custom nodes directory:

   ```bash
   cd /path/to/ComfyUI/custom_nodes
   ```

2. Clone this repository:

   ```bash
   git clone https://git.dumas.ddns.net/chris.dumas/DumasNodes.git
   ```

3. Restart ComfyUI.

## Usage

Use dot paths for nested access:

```text
user.profile.name
items.0.id
settings.render.width
```

`Dumas JSON Set Value` expects `value_json` to be valid JSON, so strings should be quoted:

```json
"Dumas"
```

```json
{"enabled": true, "retries": 3}
```

`Dumas JSON Pick Fields` expects one path per line:

```text
user.name
meta.active
items.0.id
```

`Dumas JSON Array Slice` treats `end=0` as "use the rest of the array".

`Dumas JSON Array Iterator` clamps to valid bounds:

```text
fixed -> use index as-is
incr  -> use index + 1
decr  -> use index - 1
```

`Dumas JSON Object Iterator` uses the same index rules and iterates object entries in their existing key order.

`Dumas JSON Flatten` and `Dumas JSON Unflatten` use the same dot-path format as the other path-based nodes.

`Dumas Image Compare` accepts one or two images. The `new image` socket forwards `image2` when connected so you can keep the "after" image moving through the workflow, and falls back to `image1` if only one input is present.

`Save Image Dumas` leaves `folder` empty to use ComfyUI's output directory. `name` feeds `%input%` and `name_2` feeds `%input2%`, so a pattern like `project/%input%_%input2%_%counter%` can combine two upstream strings into the saved filename.

`Dumas H3 Plan Attach Scene Images` and `Dumas H3 Plan Extract Scene Images` are a companion pair for `ComfyUI-MiniMaxH3-Contex-Loop` and the local `ref2v` lane. The upstream H3 plan node cannot dynamically grow nine new image sockets for every JSON-defined scene, so Dumas stores scene image bindings beside the plan using a lightweight token and an in-memory registry. That keeps `plan.json` archiving intact while still letting you wire up nine IMAGE sockets per scene through chained helper nodes.

`Dumas Character Helper` is the restored two-image/text helper for general H3 workflows, and `Dumas Location Helper` mirrors it for scene/environment references. Both helpers also emit structured `REFERENCE` sockets for the curator. The structured `Dumas Character Reference` and `Dumas Location Reference` nodes remain available separately for workflows that want a single `REFERENCE` socket. `Dumas H3 Prompt Curator` consumes those structured references plus optional anchor, soundscape, and BGM strings, assigns the final `<Picture N>` numbering, and outputs only the compacted images the prompt actually mentions.

`Dumas Strip Iteration Suffix` keeps the part before the first underscore and drops the rest. Names like `char123_pose_final.png` become `char123.png`, while names with no underscore such as `char123.png` are left untouched.

`Dumas Slugify String` lowercases text, strips accents, replaces non-alphanumeric runs with `-`, and trims leading or trailing dashes.

## Roadmap

This repo is intended to grow into a broader set of Dumas-branded generic utility nodes, including JSON helpers and adjacent data-manipulation tools.

## License

MIT.