ComfyUI-Koolook-Nodes

This repository provides custom nodes for ComfyUI tailored for VFX and AI image/video generation workflows.

For change history see CHANGELOG.md. For workflow conventions and naming see CLAUDE.md and Glossary.md.

Koolook nodes (root package)

Node	Display name	Category	Source
Easy_Version	Easy Version	VFX/Utils	k_easy_version.py
EasyWan22Prompt	Wan 2.2 Easy Prompt	Koolook/Wan_Video	k_easy_wan22_prompt.py
EasyResize	Easy Resize	Koolook/Image	k_easy_resize.py
EasyAIPipeline	Easy AI Pipeline	Koolook/VFX	k_ai_pipeline.py
easy_ImageBatch	Easy Image Batch	Koolook/VFX	k_easy_image_batch.py
KoolookLoadCameraPosesAbsolute	Koolook Load Camera Poses (Absolute Path)	Koolook/Camera	k_easy_track.py

Brief descriptions:

• Easy Version: Generates a padded version string like v001 from an integer. Ideal for naming renders, sequences, or iterations in VFX pipelines.
• Wan 2.2 Easy Prompt: Dynamic prompt builder driven by config.json (light source, lighting type, time of day, etc.). Outputs a comma-separated prompt string and optional CLIP conditioning.
• Easy Resize: Aspect-aware image resize that enforces divisibility (e.g., 32) for model compatibility. Modes: stretch, letterbox, pillarbox; padding and cropping supported. Inspired by the Resize Image V2 node from ComfyUI-KJNodes.
• Easy AI Pipeline: Aggregates VFX shot parameters (shot duration, seed, base path, shot name, AI method, version) into a fully formatted output file path with overwrite protection. For organized writes from Save EXR / Save Image.
• Easy Image Batch: Builds an IMAGE + MASK batch of length total_frames from 1–4 keyframe images placed at explicit frame indices (with start_frame offset). Empty frames are filled with black/gray and the mask marks empty=white / occupied=black. Useful for sparse keyframe control with Wan-style video models.
• Koolook Load Camera Poses (Absolute Path): Loads RealEstate10k-style CAMERACTRL_POSES from any absolute path (no ComfyUI path stripping), with overrideable pose width/height. Pairs with AnimateDiff CameraCtrl downstream.

Radiance Koolook nodes (forked, namespaced)

These come from forks/radiance_koolook/versions/v1_0_1/ and load through the root __init__.py. All IDs are namespaced with the suffix __koolook_v1_0_1 (display suffix (Koolook v1.0.1)) to avoid collisions with upstream Radiance.

• HDR / EXR / color: ImageToFloat32, Float32ColorCorrect, HDRExpandDynamicRange, HDRToneMap, ColorSpaceConvert, SaveImageEXR, LoadImageEXR, LoadImageEXRSequence, SaveImage16bit, HDRHistogram, LogCurveEncode, LogCurveDecode
• OCIO: RadianceOCIOColorTransformV2 (also exposed under the compact ID k_easy_OCIO_v101), RadianceLogCurveDecode

See forks/README.md for the full fork workflow.

Features

• Dynamic Inputs for Prompts: Fields and dropdowns in Wan 2.2 Easy Prompt are defined in config.json, allowing easy customization without code changes—great for VFX artists iterating on lighting or camera parameters.
• Image Resizing with Aspect Control: Easy Resize ensures precise resolutions for AI models, with options for keep_proportion preservation, padding colors, and device selection (CPU/CUDA). Supports masks for compositing in VFX.
• Pipeline Path Generation: Easy AI Pipeline assembles VFX-style output paths and filenames from shot/version inputs, with optional version disabling and overwrite protection.
• Sparse Keyframe Batches: Easy Image Batch constructs aligned IMAGE + MASK batches from up to four keyframe images, ready for sparse video-model control.
• Camera Pose Loading: Koolook Load Camera Poses (Absolute Path) reads RealEstate10k pose TXT files from any disk location and emits CAMERACTRL_POSES.
• Startup Loading: Nodes load configurations at ComfyUI launch; edit config.json and restart to update.
• Output Formatting: Wan 2.2 Easy Prompt outputs comma-separated strings (skipping "none"), compatible with prompt builders. Easy Resize outputs resized images, masks, and width/height integers. Easy Version provides padded strings for filename appending.
• Error Handling: Fallbacks for missing/invalid JSON in Wan 2.2 Easy Prompt; validation for aspect ratios and divisibility in Easy Resize.
• Compatibility: Works with ComfyUI-Manager for easy installation via Git URL. The Koolook root nodes have no extra Python dependencies; the Radiance Koolook nodes optionally use OpenEXR, Imath, PyOpenColorIO, colour, opencv-python, and imageio (imports are guarded — if a dep is missing, the affected Radiance node is unavailable but the rest of the package still loads).

RunPod

RunPod management has been moved to a separate private repository for active operations and iteration.

• Runtime/deployment scaffolding is no longer maintained in this public repo.
• This public repo remains focused on the ComfyUI nodes/plugin code.

Release & Stability

For production usage, install a pinned stable tag/commit instead of following moving branch heads.

• Release procedure: RELEASING.md (canonical, step-by-step)
• Per-release checklist template: .github/ISSUE_TEMPLATE/release_checklist.md
• Change history: CHANGELOG.md
• Fork tracking: forks/THIRD_PARTY.md, forks/forks_manifest.yaml
• Fork workflow guide: forks/README.md

Tagging Policy (from now on)

• Repo releases: vMAJOR.MINOR.PATCH (example: v0.2.0).
• Fork code versions in paths use underscore format: v1_0_1, v2_3_3.
• Comfy node ID namespace suffixes match fork version paths: __koolook_v1_0_1.
• External raw checkout naming:
  • pinned: <repo>-v<version>-koolook
  • rolling upstream: <repo>-main-upstream

Sibling Projects

Some related work lives in sibling folders/repositories outside MAIN. They are consulted (read-only knowledge sources, references, etc.) but never imported by MAIN at runtime. To keep the public repo free of machine-specific absolute paths, every sibling is referenced through an environment variable.

Conventions

• Variable prefix: KOLOOK_* (matches the existing KOLOOK_FORKS_DIR).
• Real paths live in a local, gitignored .env file. The committed .env.example declares the variable names with placeholder values.
• Public docs and committed code reference siblings only via the env var name (and an optional portable relative default like ../<folder>). Never hardcode an absolute path with a username.
• A sibling project is a runtime-optional reference. If the variable is unset and no default is documented, agents/code must treat the sibling as unavailable and continue gracefully.

Registered siblings

Role	Env var	Portable default	Status
External forks root (raw upstream clones)	KOLOOK_FORKS_DIR	../ComfyUI-Forks	documented in forks/forks_manifest.yaml
ComfyUI knowledge database	KOLOOK_COMFYUI_KB_DIR	../ComfyUI_knowledge___DB	read-only knowledge source
Personal knowledge database	KOLOOK_PERSONAL_KB_DIR	(no default — user-specific)	optional

Local setup

cp .env.example .env
# Edit .env to point at the real paths on your machine.

Do not commit .env. The default .gitignore already excludes .env, .env.local, and .env.*.local.

External Fork Workflow (No Vendoring in MAIN)

This repository is the MAIN control repo. Large third-party repositories must stay outside MAIN.

• Default external forks root (relative): ../ComfyUI-Forks
• MAIN stores only:
  • wrappers under forks/
  • provenance/tracking under forks/
• MAIN does not store full external trees (no vendored copies).

Radiance Koolook Version Layout

• Package entry path: forks/radiance_koolook/__init__.py
• Version path (current): forks/radiance_koolook/versions/v1_0_1/
• Modified node source is local and tracked in MAIN:
  • forks/radiance_koolook/versions/v1_0_1/nodes_hdr.py
  • forks/radiance_koolook/versions/v1_0_1/nodes_color_management.py
  • forks/radiance_koolook/versions/v1_0_1/nodes_dna.py
• External checkout is reference-only raw upstream:
  • default location: ../ComfyUI-Forks/radiance-v1.0.1-koolook
  • baseline used for comparison: upstream comfyui tag (f1b8ae330848fa08aba24c9d3e355cb432d3515b) because v1.0.1 tag is not published upstream
• Node IDs are namespaced with version suffixes (current: __koolook_v1_0_1) to avoid collisions.
• Each version folder should include UPSTREAM_PIN.yaml to keep parity with external pinned references.

Version Pinning (Portable Across PCs/macOS)

• Track every external repo in forks/forks_manifest.yaml with:
  • source_ref (tag/version)
  • pinned_commit (exact hash used in production)
  • external_checkout.relative_path_from_forks_root
• Keep checkout folder names versioned, e.g.:
  • radiance-v1.0.1-koolook
  • radiance-v2.3.3-koolook

Machine Setup Example

From the parent directory that contains ComfyUI-Koolook:

mkdir -p ../ComfyUI-Forks
cd ../ComfyUI-Forks
git clone https://github.com/fxtdstudios/radiance.git radiance-v1.0.1-koolook
cd radiance-v1.0.1-koolook
git checkout f1b8ae330848fa08aba24c9d3e355cb432d3515b

This external folder is for upstream comparison/sync work only.

Installation

Via ComfyUI-Manager (Recommended)

1. Open ComfyUI and access the Manager interface.
2. Go to "Install Custom Nodes" > "Install via Git URL".
3. Paste the repository URL: https://github.com/malkuthro/ComfyUI-Koolook.git.
4. Install and restart ComfyUI.
5. Nodes appear under these categories in the node search:
   • VFX/Utils — Easy Version
   • Koolook/Wan_Video — Wan 2.2 Easy Prompt
   • Koolook/Image — Easy Resize
   • Koolook/VFX — Easy AI Pipeline, Easy Image Batch
   • Koolook/Camera — Koolook Load Camera Poses (Absolute Path)
   • Radiance categories (set by upstream Radiance) for the namespaced (Koolook v1.0.1) nodes

Manual Installation

1. Clone this repository into your ComfyUI/custom_nodes/ directory:

   git clone https://github.com/malkuthro/ComfyUI-Koolook.git
   

2. Ensure __init__.py and config.json are in the cloned folder.
3. Restart ComfyUI.

The root Koolook nodes have no additional Python dependencies. To enable the Radiance Koolook v1.0.1 nodes that handle EXR / OCIO / HDR work, install the optional packages: OpenEXR, Imath, PyOpenColorIO, colour-science, opencv-python, and imageio.

Usage

Easy Version

1. Add the "Easy Version" node to your workflow under "VFX/Utils".
2. Connect an INT input (e.g., from a Constant node) to the "version" slot.
3. Output is a STRING like "v001" for input 1, "v011" for 11—use for appending to filenames in Save Image nodes or VFX render queues.

Wan 2.2 Easy Prompt

1. Add the "Wan 2.2 Easy Prompt" node to your workflow under "Koolook/Wan_Video".
2. Select options from the dropdowns (e.g., Light Source: "Sunny lighting", Lighting Type: "Soft lighting").
3. Add custom text in the "body" field for main prompt content.
4. Optionally connect a CLIP for conditioning output.
5. Connect the STRING outputs (combined_prompt or fields_only) to a prompt input, such as the "prompt" slot in the PromptJSON node (from NeuralSamurAI/ComfyUI-PromptJSON).
6. To customize fields:
   • Edit config.json (see example below).
   • Restart ComfyUI to apply changes.
7. VFX Tip: Use for generating consistent lighting/shot descriptions in video generation workflows, like with AnimateDiff or SVD.

Example config.json

This is the default configuration based on Wan 2.2 parameters:

{
  "category": "Koolook/Wan_Video",
  "node_name": "Wan_2.2",
  "fields": [
    {
      "name": "light_source",
      "type": "combo",
      "options": ["none", "Sunny lighting", "Artificial lighting", "Moonlighting", "Practical lighting", "Firelighting", "Fluorescent lighting", "Overcast lighting", "Mixed lighting"],
      "default": "none"
    },
    {
      "name": "lighting_type",
      "type": "combo",
      "options": ["none", "Soft lighting", "Hard lighting", "Top lighting", "Side lighting", "Underlighting", "Edge lighting", "Silhouette lighting", "Low contrast lighting", "High contrast lighting"],
      "default": "none"
    },
    // ... (additional fields like time_of_day, shot_size, etc.)
  ],
  "output_type": "STRING"
}

Easy Resize

1. Add the "Easy Resize" node to your workflow under "Koolook/Image".
2. Connect an IMAGE (and optional MASK) input.
3. Set the base dimension (Width or Height), base size, aspect ratio (e.g., "16:9" for landscape, "9:16" for portrait), and other options like keep_proportion (stretch, letterbox, pillarbox), pad_color (e.g., "0, 0, 0" for black), crop_position, divisible_by, and device.
4. Connect the outputs: IMAGE and MASK for further processing, INT width/height for resolution-aware nodes like samplers or upscalers.
5. VFX Tip: Use for preprocessing footage in multi-resolution pipelines, ensuring divisibility for efficient GPU processing in tools like IPAdapter or ControlNet.

Node Code Overview

The core logic is split across files for modularity:

Root Koolook nodes:

• k_easy_version.py — Easy_Version class for padded version-string formatting.
• k_easy_wan22_prompt.py — loads config.json at import time, builds inputs dynamically (combos for dropdowns, strings for text), and formats selections into prompt strings with optional CLIP conditioning.
• k_easy_resize.py — parses aspect ratios, computes divisible dimensions, resizes with common_upscale, and handles padding/cropping. Inspired by Resize Image V2 from ComfyUI-KJNodes.
• k_ai_pipeline.py — EasyAIPipeline builds VFX output paths/filenames from shot/version inputs and creates the output directory.
• k_easy_image_batch.py — easy_ImageBatch builds aligned IMAGE+MASK keyframe batches with placeholder fill.
• k_easy_track.py — KoolookLoadCameraPosesAbsolute loads RealEstate10k pose TXT files from any path.

Forked/wrapped nodes:

• forks/radiance_koolook/ — version-namespaced wrapper for the Radiance fork. Currently exposes the v1_0_1 set; modified node sources live in forks/radiance_koolook/versions/v1_0_1/{nodes_hdr,nodes_color_management,nodes_dna}.py. The wrapper applies the __koolook_v1_0_1 ID suffix and the optional short ID k_easy_OCIO_v101.
• forks/forks_manifest.yaml, forks/THIRD_PARTY.md, forks/README.md — fork tracking metadata.

Glue and frontend:

• __init__.py — imports all node packages, merges NODE_CLASS_MAPPINGS / NODE_DISPLAY_NAME_MAPPINGS, and exposes WEB_DIRECTORY = "./web".
• web/ — JavaScript extensions loaded by ComfyUI for the Koolook nodes (e.g., ai_pipeline.js).

For advanced customizations (e.g., different output formats or additional resize modes), modify the execute or adjust_to_aspect methods in the respective files.

Troubleshooting

• ComfyUI Won't Start: Check console logs for errors (run python main.py). Common: Missing config.json or invalid JSON—use a validator like jsonlint.com.
• No Fields Visible in Wan 2.2 Easy Prompt: Indicates JSON load failure; the node falls back to empty inputs.
• Errors in Easy Resize: Ensure aspect ratio is "w:h" format, divisible_by >=1, and pad_color is "r, g, b" floats (0.0-1.0).
• Updates: Pull latest from GitHub and restart.

Credits

• Based on ComfyUI custom node examples.
• Parameters for Wan 2.2 Easy Prompt derived from Wan 2.2 docs (https://alidocs.dingtalk.com/i/nodes/EpGBa2Lm8aZxe5myC99MelA2WgN7R35y).
• Easy Resize inspired by ComfyUI-KJNodes (https://github.com/kijai/ComfyUI-KJNodes), specifically the Resize Image V2 node in image_nodes.py.
• Compatible with nodes like PromptJSON for LLM workflows.

License

GPL-3.0 (see LICENSE).

This package incorporates and adapts code from fxtdstudios/radiance (also GPL-3.0) under forks/radiance_koolook/. Per GPL-3.0 §5(c), the entire work is licensed as GPL-3.0. Attribution and per-fork modification notes are tracked in forks/THIRD_PARTY.md and forks/forks_manifest.yaml.

Note for downstream users: any work that incorporates, links to, or derives from ComfyUI-Koolook must itself be distributed under GPL-3.0 (or a compatible license). If you need a non-copyleft license for any piece of this code, contact the maintainers — some Koolook-original nodes (those with no upstream Radiance lineage) may be available under a more permissive license on request.