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`, optional `plan`, optional `plan_scene_index`, 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.
  - 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.
  - A connected H3 plan can now supply the current scene’s 9-image bundle directly; any directly-wired `ref_*` socket overrides the same numbered plan slot.
  - 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 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`, `picture_id`, `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`, `picture_id`, `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 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, and news broadcast.
  - Selecting a preset fills the editable description field, and the edited multiline description is the `STRING` value passed downstream into H3 anchor sockets such as `anchor_override`.

- `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 Reference` and `Dumas Location Reference` live in `Dumas/MiniMax`. Both output a structured `REFERENCE` object that carries the image plus its semantic payload. `Dumas H3 Long Videos` accepts those `REFERENCE` sockets directly on `ref_1`..`ref_9`, resolves `<Picture N>` against the wired slot positions, and can also pull character wardrobe context from the structured ref data when `character_memory` is left blank.

`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.