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

- `Dumas H3 Plan Attach Scene Images`
  - Inputs: `plan`, `scene_index`, optional `image1`..`image7`
  - Outputs: `plan`, `connected_images`
  - Attaches up to seven 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 seven-image bundle.

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

- `Dumas Character Helper`
  - Inputs: `image1`, `image2`, `image1_picture_id`, `image2_picture_id`, `character_id`, `name`, `height_feet`, `height_inches`, `accent`, `general`
  - Outputs: `image1`, `image2`, `character_text`
  - Passes both images through unchanged and builds a character reference string such as `<Picture 2> and <Picture 3> reference the same character who is called Dave.`
  - Appends optional sentences for character ID, height, accent, and freeform notes only when those fields are filled in.

- `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`. The upstream H3 plan node cannot dynamically grow six 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 six IMAGE sockets per scene through chained helper nodes.

`Dumas Character Helper` lives in `Dumas/String`. Use the picture ID dropdowns to decide which `<Picture N>` tags get mentioned in the generated text, while the two IMAGE sockets continue downstream unchanged.

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