🇬🇧 English version (default) 🇫🇷 [Lire la version française](README_FR.md) # 🚀 Orion4D_Metanode — Custom Nodes ComfyUI

![ComfyUI](https://img.shields.io/badge/ComfyUI-Custom_Nodes-blue?style=for-the-badge&logo=python&logoColor=white) ![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white) ![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge) ![Nodes](https://img.shields.io/badge/Nodes-29+-orange?style=for-the-badge) This project brings together all my work on ComfyUI. **Orion4D_Metanode transforms ComfyUI into a true programmable environment.** Thanks to the **PyCode Max** engine, execute Python directly within your workflows and build your own tools, logic, and interfaces. Dynamic routing, variable buses, enriched UI, file management, image processing... Everything is designed to push beyond the limits of traditional node-based systems. ✔ Compatible with the Nodes V2 ## ✨ Why Orion4D_Metanode? - Create dynamic and scalable workflows - Eliminate complex wiring with an intelligent bus system - Develop your own tools directly in ComfyUI - Transform a workflow into a true programmable pipeline

## 🚧 Status **Version: 1** (2/05/2026) --- ## 🔧 Nodes ### ⚙️ PyCode Max > The true "brain" of this suite, run Python code directly inside your workflows. >

- **Two modes**: direct input (`text_input`) or external file (`file`) - **Universal inputs**: text, integers, floats, images, masks, latents, conditioning, model, clip, vae, audio, video, and custom types - **Persistent STATE** per node between executions (resettable) - **Configurable timeout** (5–600 sec) against infinite loops - **Security mode**: text mode execution is locked by default (requires `"developer_mode": true` in `config.json`) - **Automatic documentation**: comments at the top of a `.py` script are displayed in the console - **Built-in console** with execution time and structured logging ✨ **Built-in LLM & GPU Helpers** The execution scope now includes powerful dictionaries (`llm` and `gpu`) to interact with local AI models and hardware without writing boilerplate code. - 🧠 **Native Ollama Integration (`llm`)**: - Communicate with local models easily: `llm["generate"]("prompt", model="gemma4:e4b")`. - **Vision support**: Pass ComfyUI image inputs directly to models like LLaVA or Qwen2.5-VL (`images=IN["img_in_1"]`). PyCodeMax handles the PIL to Base64 conversion automatically. - **Advanced features**: Supports streaming (`stream=True`), conversational mode (`llm["chat"]`), and reasoning token injection (`think=True` for Gemma 4). - *Optimized*: HTTP sessions are persisted in the node's STATE to avoid connection overheads. - **VRAM Management**: Unload models on the fly before a heavy ComfyUI generation using `llm["unload"]("model_name")`. - 📊 **Hardware Monitoring (`gpu`)**: - Track memory usage inside your scripts to prevent Out-Of-Memory errors. - Read PyTorch allocated memory with `gpu["torch_vram"]()`. - Read total system VRAM usage (including external processes like Ollama) with `gpu["vram"]()` *(requires `pip install nvidia-ml-py`)*. #### 💡 Quick Example (Vision LLM): ```python # Pass an image to a local Vision model and output the description prompt = f"Describe this image based on the user request: {IN['txt_in_1']}" response = llm["generate"]( prompt=prompt, model="qwen2.5-vl:7b", images=IN["img_in_1"], # Direct pass from ComfyUI IMAGE input temperature=0.7 ) OUT["txt_out_1"] = response ``` --- ### 📂 Folder File Max > A complete visual file explorer, directly inside a ComfyUI node. >

- **Grid or list view** with thumbnails generated on the fly - **Filtering** by extension, regex (include/exclude), sorting by name/date/size - **Navigation**: go up folders, double-click to open - **Integrated Lightbox** to preview images, videos, and audio - **"Explore" button** to open the folder in the system explorer (Windows/macOS/Linux) - **Seed modes**: fixed, random, increment... - Returns: `file_path`, `filename`, `dir_used`, `files_json`, `file_info`, `IMAGE` --- ### 📄 Load Text File > Loads any text file and exposes its content in an editable widget. >

- **Drag-and-drop** or file selection from the interface - The content appears in a multiline `STRING` widget **directly editable** in the node - Supported formats: `.txt`, `.json`, `.csv`, `.py`, `.js`, `.md`, `.yaml`, `.toml`, `.xml`, `.html`, `.sh`, `.bat`, `.ini`, `.cfg`, `.env`, `.log` - Automatic encoding detection (UTF-8, Latin-1, CP1252...) - Returns: `text` (STRING) --- ### 💾 Super Saver > Advanced image and text saving with fine management of filenames and metadata. >

- **Image**: PNG, JPEG, WEBP, TIFF — configurable quality per format - **Dynamic Alpha**: additional `alpha_N` ports to save layers (managed by JS) - **Text**: simultaneous saving of a `.txt` (or other extension) file alongside the image - **Metadata**: JSON or free text injection into the `iTXt` chunk of the PNG (native UTF-8) - **Naming**: prefix, timestamp (Date_Time / HHMMSS / Unix_Epoch), auto-counter, subfolders - **Strip Workflow**: removes workflow data from PNG before saving - Returns: `image_path`, `text_path` (STRING) --- ### 🔀 Dynamic Road > Dynamic input router — connect N universal inputs and choose which one to transmit. >

- The `*` input ports automatically appear upon connection - Each input has a **memo field** (customizable label) and a **radio toggle** - Selection via visual interface or Python index - Returns: the selected value, its text representation, and a detailed log --- ### 📝 Text Road > Multi-input text concatenator with fine control per input. >

- Dynamic `STRING` inputs (ports appear upon connection) - Each input has a **memo**, an **active/inactive toggle**, a **prefix**, and a **suffix** - **Configurable separator** (supports `\n`, `\t`, or any string) - Returns: `text_out` (STRING) --- ### 🔀 Dynamic Splitter > Broadcasts a single input to N dynamic outputs, with selective activation per output. >

- **1 input → N outputs**: the same data is broadcast to all active outputs - Outputs appear dynamically (managed by JS) - **Disabled** outputs emit an `ExecutionBlocker` — the downstream flow is cleanly stopped without crashing - Each output has a **customizable label** and an **active/inactive toggle** - Returns: up to 32 `out_N` outputs + a `log` (STRING) --- ### 🚦 Execution Gate > Cleanly allows or blocks a flow based on a boolean. >

- **Open ✅** → the data passes as is - **Blocked 🚫** → emits an `ExecutionBlocker`: the entire downstream graph is stopped without error - Compatible with the `boolean` output of the **Boolean Switch** - Accepts any type as input (`*`) - Returns: `output` (`*`) --- ### 🚌 Variable Bus (Set) + Variable Bus (Get) + Variable Bus (Clear) > Share any data between distant nodes **without visible cables**, with intelligent auto-connection and strong typing. **Principle** The bus relies on a common identification triplet for Set and Get: - `variable_name`: logical name of the variable (e.g., `my_image`, `main_prompt`) - `data_type`: strong type (`IMAGE`, `LATENT`, `MASK`, `STRING`, `INT`, `FLOAT`, `MODEL`, `CONDITIONING`, `CLIP`, `VAE`, `LIST`, `*`) - `execution_phase`: execution phase (1 to 8) to order multiple Sets/Gets sharing the same name As soon as a Set and a Get share the same triplet, a `sync → dependency` link is **automatically created** by JavaScript — the user has no cables to draw. This link is invisible by default ("wireless bus" effect) but actually exists in the graph, ensuring the execution order on the ComfyUI side. **Variable Bus (Set)** - Stores the data in a global bus (Python `OrderedDict` in memory) under the declared triplet - `passthrough` output: returns the original data, typed according to `data_type` (corresponding slot color) - `sync` (INT) output: write tick, auto-connected to the corresponding Get's `dependency` - `OUTPUT_NODE = True` + `IS_CHANGED = NaN`: executes on every run, ensuring the written value is always fresh - FIFO of 64 variables max with eviction of the oldest and VRAM release (`torch.cuda.empty_cache()`) **Variable Bus (Get)**

- Retrieves the data from the global bus by its triplet - `output` output: dynamically typed according to `data_type` - `dependency` port: auto-connected to the corresponding Set's `sync` (rendered invisible) - Intelligent auto-reconnection: if `variable_name`, `data_type`, or `execution_phase` changes, the link is remade to the correct Set - If the variable is not found → clean `ExecutionBlocker` (no crash) **Variable Bus (Clear) — central controller** Mainly used to **control the display of bus cables** in the graph: - `show_bus_links` (hidden/visible toggle): toggles the visibility of all `sync → dependency` links in the workflow in real-time - `clear_mode`: - `none` (default): does nothing, the node serves solely as a visual controller - `all`: completely empties the bus - `single`: deletes only the named variable - `all_except`: empties everything except the named variable - **🧹 Clear now** button: executes the clear immediately via an HTTP route, without having to run the workflow - **🔄 Refresh bus links** button: forces a complete rescan of Set/Get auto-connections (useful after importing a workflow or manual manipulations) - The first `Variable Bus (Clear)` found in the graph acts as the authority for the visibility toggle; without a Clear placed, cables are hidden by default > 💡 Ideal for sharing a model, an image, a text, or a latent between distant branches without extending cables. Auto-connection via triplet makes usage seamless: you declare it, it connects itself. --- ### 📋 List Selector Max > A "must-have" for prompt generation: Multi-group line selector from `.txt` / `.csv` files, with independent seed per group. > - Bonus: **lists_starter_pack** included containing 82 files > Tip: the result can be enriched via PyCode Max with an LLM model, entirely automatically! >

- **Multi-groups**: each group points to a different file, with its own seed and separator - **Selection modes per group**: `select` (manual index), `randomize`, `increment`, `decrement` - **Inline editing**: modify the selected line directly in the node before sending it - **Manual override**: enter free text in the preview field to bypass the selection - **Path tokens**: `{COMFY}` and `{CUSTOM}` for portable paths between machines - **Security**: access is restricted to the ComfyUI root and the defined custom folder - Returns: `concatenated` (STRING), `lines_json` (STRING), `total_count` (INT) --- ### 🎚️ Parametric Slider > Dynamically configurable slider from JSON files. >

- Load your **range presets** from the `json_slider/` folder - Supports `min`, `max`, `step`, `default`, `label`, `precision`, `unit` - **Modes post-generation**: `fixed`, `increment`, `decrement`, `randomize` - Returns: `float_val`, `int_val`, `text_val` (with unit), `label`, `min`, `max`, `step`, `log` **Preset example (`json_slider/px_1_to_8192.json`):** ```json { "min": 1, "max": 8192, "step": 64, "default": 512, "label": "Resolution", "precision": 0, "unit": "px" } ``` --- ### 🔽 Master Combo Box > Double dropdown menu linked to JSON files in the `dropdowns/` folder. >

- **Menu 1**: chooses the JSON file (category) - **Menu 2**: displays the content of the selected file - **Refresh** button to reload without restarting ComfyUI - Returns: `selected_text` (STRING) --- ### 📂 Model Selector > Navigate through `models/` subfolders with a two-level selector. >

- **Menu 1**: category (`checkpoints`, `loras`, `upscale_models`...) - **Menu 2**: file in that category - Automatic filter on `.safetensors`, `.gguf`, `.pth`, `.bin` extensions - Returns: `absolute_path`, `relative_path`, `filename_only`, `any_path`, `any_filename` --- ### 🎨 Color Picker > Opens the native OS color palette to select a color. >

- Color preview drawn directly on the node - Returns: `hex_value` (e.g., `#F54927`), `rgb_string` (e.g., `245, 73, 39`), `R`, `G`, `B` channels --- ### 📈 Curves Pro + 🖼️ Curves Pro Image > Photoshop-style RGB curves editor, with live preview. >

**Curves Pro (editor):** - Interactive canvas for **RGB**, **R**, **G**, **B** channels - **Live histogram** calculated from the connected image - **Grid snapping** (3 density levels) - **Preset system**: save/load from `json_curves/` - Returns: `curves_json` (STRING) **Curves Pro Image (receiver):** - Loads an image (native Load Image style) - Receives `curves_json` and applies curves in real-time - **Live preview** sent back to the editor node via WebSocket - Returns: `IMAGE`, `MASK`, `log` --- ### 🎨 LUT Generator + 🎬 LUT Manager > Creation and application of `.cube` 3D LUTs directly in ComfyUI. >

**LUT Generator:** - Generates a 3D LUT from two images (before/after) — ideal for **capturing the look of an existing grading** - Fine parameters: LUT size (9–65), number of samples, interpolation method (`linear`, `nearest`, `cubic`), gaussian blur, identity anchoring - **No-save mode** (`save_lut = False`): calculates the LUT in memory to test without writing to disk - Export formats: `.cube`, `.3dl`, `.csp` - Calibration images stored in `lut_files/images_calibration/` to facilitate comparisons - Returns: `preview_image`, `tested_image`, `lut_path` **LUT Manager:** - Applies any `.cube` LUT to an image, via direct path or selection in `lut_files/` - Control **intensity** (0–2) and **opacity** (0–1) independently - Choice of data/table orders (`BGR`/`RGB`) for maximum compatibility with commercial LUTs - **Memory cache**: the LUT is only reloaded from disk if the file has been modified - Returns: `IMAGE`, `lut_path` --- ### 🔍 Image Comparer *(Legacy)*

> Interactive image comparer, optimized for the classic ComfyUI interface (LiteGraph). - **Direct interaction**: toggle between A and B by clicking the image, or via the two indicator circles under the image - **HD rendering**: native drawing on the LiteGraph canvas, remains sharp at all zoom levels - **Different sizes**: automatic alignment to the largest dimension, letterbox on black background — ideal for comparing an original and its upscale - **Compatible with Nodes 2.0** with two limitations: clicking in the image does not toggle (use the circles at the bottom of the node); hovering darkens the image (native Nodes 2.0 rendering superimposes) - **Ideal use**: users of the classic ComfyUI interface (LiteGraph) ### 🔍 Image Comparer V2 *(beta, optimized for Nodes 2.0)*

> Interactive image comparer, designed for the new ComfyUI Nodes 2.0 interface. - **Two modes**: `slide` (vertical slider reveals B over A) and `click` (toggle between A and B on click) - **Swap A/B button**: reverses the two images without rewiring connections (slide mode only) - **Different sizes**: automatic alignment on the largest dimension, letterbox on black background — ideal for comparing an original and its upscale - **Limitation**: when ComfyUI canvas is zoomed (values above 100%), progressive pixelation of image display - **Ideal use**: users of the new Nodes 2.0 interface --- ### 🎨 Color Pro — Modular color grading chain

> A pipeline color effect system: **emitter** nodes produce `COLOR_FX` descriptors, which the **receiver** node applies in order to an image. Each emitter can also work in **standalone** mode (direct image in/out). **🎨 Color Pro Receiver** — Receiver / application point - Receives an `IMAGE` + dynamic slots `fx_1`, `fx_2`, ... of type `COLOR_FX` - Applies effects in the numerical order of the slots - Slots are automatically added upon connection (dynamic pattern) - Returns: `image` (IMAGE), `log` (STRING) **Available emitters:** | Node | Description | |------|-------------| | **🎨 Channel Mixer FX** | Mixes R/G/B channels to rebuild each output channel. Monochrome mode and luminosity preservation. Photoshop Channel Mixer equivalent. | | **🎨 Color Balance FX** | Shadows / Midtones / Highlights adjustment like Photoshop. "Preserve Luminosity" toggle. | | **🎨 CSS Filters FX** | Applies standard CSS filters: `brightness`, `contrast`, `saturate`, `hue-rotate`, `sepia`, `grayscale`, `invert`. | | **🎨 Hue/Sat/Light FX** | Global HSL adjustment or targeted by hue family (Reds, Yellows, Greens, Cyans, Blues, Magentas) with smooth gaussian transition. Colorize mode included. | | **🎨 Photo Filter FX** | Color warming/cooling filter with opacity and luminosity preservation mode, inspired by Photoshop's Photo Filter. | | **🎨 Vibrance FX** | Vibrance adjustment (skin tone protection) and global Saturation, independently controllable. | | **🎨 Curves Pro** | Compatibility with the tool | | **🎨 Matrix 3x3 FX** | Full RGB matrix transform using a 3x3 channel matrix with RGB offsets. Includes strength, luminosity preservation and output clamp. Presets are handled through the unified JSON preset system. | | **🎨 DCTL Tone Mapper FX** | Creative / technical filmic tone mapper inspired by Resolve DCTL workflows. Includes Filmic Soft, Filmic Strong, ACES Approx, Reinhard and Cineon-ish modes, with exposure, contrast, pivot, highlight rolloff, shadow lift, black floor, saturation and luminosity preservation controls. | > 💡 Emitters can be used in **chain mode** (`fx` output → `fx_N` slot of Receiver) or **standalone mode** (direct image in/out), or both simultaneously. --- ### 📦 List Packer / Dict Packer / 📤 List Unpacker / 🖨️ Logger

| Node | Behavior | |------|-------------| | **List Packer (Infinite)** | Dynamic `item_N` ports → `list_out` output | | **Dict Packer (Infinite)** | `val_N` ports + dynamic `key_N` fields → `dict_out` output | | **List Unpacker (Dynamic)** | `list_in` input → up to 32 `item_N` outputs | | **Logger (Debug Console)** | Displays type, shape, and value of any data | > All Packer/Unpacker ports appear and disappear automatically based on connections. --- ## 🔧 Installation ```bash cd ComfyUI/custom_nodes git clone [https://github.com/your-username/Orion4D-coder.git](https://github.com/your-username/Orion4D-coder.git) ``` Restart ComfyUI. The nodes will appear in the **`Orion4D_MetaNode`** category. > **Optional dependencies** for LUT Generator: `pip install scipy opencv-python` --- ## ⚙️ Configuration ### Developer mode (PyCode Max) By default, code execution in `text_input` mode is **disabled** to protect against malicious shared workflows. Edit `config.json` at the root of the custom node: ```json { "developer_mode": true } ``` > ⚠️ Only enable this option on your personal machine. Never share workflows containing unverified code in `text_input` mode. --- ### 📂 Folder File Max — Custom Folders #### Why an allow-list? The HTTP routes for **Folder File Max** are exposed on the ComfyUI server. Without restriction, any client on the same network could enumerate and read any file on the disk. By default, only ComfyUI's internal roots are accessible: | Label | Resolved path | |-------|--------------| | `{COMFY}/input` | `ComfyUI/input/` | | `{COMFY}/output` | `ComfyUI/output/` | | `{COMFY}/temp` | `ComfyUI/temp/` | | `{COMFY}/models` | `ComfyUI/models/` | Any path outside these roots is **silently refused** (the node returns empty outputs and logs the reason in the console). #### Add folders via environment variable Declare the **`ORION4D_FOLDER_ROOTS`** variable before launching ComfyUI. Paths are separated by your OS separator (`;` on Windows, `:` on Linux/macOS). **Windows — Command Prompt (cmd)** ```bat set ORION4D_FOLDER_ROOTS=F:\lists;C:\Users\orion4d\Desktop\IN python main.py ``` **Windows — PowerShell** ```powershell $env:ORION4D_FOLDER_ROOTS = "F:\lists;C:\Users\orion4d\Desktop\IN" python main.py ``` **Windows — Permanent (user session)** ```bat setx ORION4D_FOLDER_ROOTS "F:\lists;C:\Users\orion4d\Desktop\IN" ``` > Restart your terminal after `setx` for the variable to be recognized. **Linux / macOS — Current session** ```bash export ORION4D_FOLDER_ROOTS="/home/orion4d/photos:/mnt/nas/shoots" python main.py ``` **Linux / macOS — Permanent** — add the following line in `~/.bashrc` or `~/.zshrc`: ```bash export ORION4D_FOLDER_ROOTS="/home/orion4d/photos:/mnt/nas/shoots" ``` #### Verify that roots are loaded When ComfyUI starts, the node displays the complete list of allowed roots in the console: ``` [FolderFileMax] Allowed roots (6): {COMFY}/input → C:\ComfyUI\input {COMFY}/output → C:\ComfyUI\output {COMFY}/temp → C:\ComfyUI\temp {COMFY}/models → C:\ComfyUI\models F:\lists → F:\lists C:\Users\orion4d\Desktop\IN → C:\Users\orion4d\Desktop\IN ``` If a declared folder does not exist at startup, it is silently ignored (no error, no entry in the list). #### Security behavior - Paths containing `..` are rejected (no directory traversal). - Only media extensions are served by the `/thumbnail` and `/view` routes — no `.py`, `.json`, `.exe`, etc. files are ever transmitted to the browser. - Navigation is **locked to the chosen root** in the dropdown: it is impossible to go up above it via the interface. - Windows Junction Points pointing outside an allowed root are **blocked**. > ⚠️ **Network use / workflow sharing**: any root added via `ORION4D_FOLDER_ROOTS` is accessible to **all clients** that can reach your ComfyUI instance. Do not expose ComfyUI to the Internet with personal folders in the allow-list. --- ### 📋 List Selector Max — Allow a custom root folder #### Security model By default, **List Selector Max** restricts access to `.txt` / `.csv` files located in the ComfyUI root folder (and all its subfolders). The `{COMFY}` token always points to this root. ``` {COMFY}/custom_nodes/Orion4D_MetaNode/Lists/styles.txt ✅ allowed C:\Users\orion4d\Desktop\prompts\abstract.txt ❌ refused by default ``` #### Allow an external folder via the `custom_root` widget The node exposes a **`custom_root`** field directly in its interface. Enter the absolute path of the root folder you want to allow: ``` C:\Users\orion4d\Desktop\prompts ``` Once defined, the `{CUSTOM}` token is resolved to this folder. You can use it in your group paths: ``` {CUSTOM}/styles/abstract.txt {CUSTOM}/moods.csv ``` Validation occurs at each execution: if the folder does not exist or if the path attempts to break out of the root via `..`, access is refused and the group returns an empty selection. #### Use `{COMFY}` and `{CUSTOM}` together Both tokens can be used together within the same node. One group can point to `{COMFY}/Lists/cameras.txt` and another to `{CUSTOM}/moods.csv` — each path is validated independently against its root. ``` Group 1 → {COMFY}/Lists/cameras.txt (in ComfyUI, portable) Group 2 → {CUSTOM}/abstract_moods.txt (local personal folder) ``` #### ⚠️ Warning for workflow sharing and network use > **Custom root = local absolute path.** A workflow that contains a `custom_root` or `{CUSTOM}` paths **will not work** as is on another machine, or if ComfyUI is shared on a network with other users. > > - **Do not share** workflows with `custom_root` filled in if other people have access to your ComfyUI instance — the HTTP route `/orion4d/lsm/list_dir` and `/orion4d/lsm/read_file` will respond to **all network clients** for files in this root. > - **Prefer `{COMFY}`** for anything that needs to remain portable: place your lists in a ComfyUI subfolder (e.g., `ComfyUI/Lists/`) and reference them with `{COMFY}/Lists/file.txt`. > - If you must share a workflow using `{CUSTOM}`, **clear `custom_root`** before exporting or replace the paths with `{COMFY}` equivalents. ---

Made with ❤️ for the ComfyUI community · **Orion4D**

Name	Type	Default	Description
toggle	BOOLEAN	false	—
road_Aopt	*		—
road_Bopt	*		—

Name	Type	Description
boolean	BOOLEAN	—
selected_item	*	—

🔀 Boolean Switch

Inputs (3)

Outputs (2)