Files

T

040b30733d feat(matte): first-party mask-guided one-step video matting nodes (#269 )

* feat(matte): first-party mask-guided one-step video matting nodes

Adds matte/ — an independent implementation of the published VideoMaMa
one-step SVD method (matte/pipeline.py) plus Koolook's temporal windowing,
subject-focused crop/stitch, resolution control (/64, shortest-side) and
auto OOM resolution-backoff. Nodes: KoolookMatteLoader, KoolookMatteSampler,
KoolookMatteFocusCrop, KoolookMatteFocusStitch.

Registered via the existing guarded _merge_node_group("Koolook Matte",
".matte"), so a missing diffusers disables only these nodes. diffusers is
already pulled in by the radiance/whatdreamscost forks, so no new dependency.

Loads (never bundles) the VideoMaMa UNet (CC-BY-NC) + SVD VAE at runtime;
matte/NOTICE records the model licenses and user responsibility.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(dev-sync): include matte/ in RUNTIME_PATHS

So `sync_to_dev` copies the new matte node package into the live ComfyUI
install alongside the rest of the koolook pack.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(matte): raw cond latents; fp16 default; preserve checkpoints on dev-sync

pipeline.py: _encode_latents must NOT divide by vae scaling_factor. The
VideoMaMa UNet is trained on raw VAE latents (matching okdalto's
VideoInferencePipeline, which multiplies by scaling_factor then divides it
back out -> net x1). Dividing over-scaled the conditioning ~5.5x and produced
a systematically blurry matte on every frame. Verified 5/5 vs the desktop /
vanilla reference on identical single-frame inputs.

nodes.py: harden the loader precision fallback so fp16 is the true default -
only an explicit "bf16" opts out; a stale "auto" widget now resolves to fp16
instead of bf16.

sync_to_dev.py: the rmtree+copytree mirror deleted matte/checkpoints/ (the
gitignored ~10GB SVD+VideoMaMa weights) on every matte sync, forcing a
re-download. Add PRESERVE_IN_DEST + selective _clean_dest so runtime-
downloaded model data survives a sync.

docs: add docs/maintainers/matte-pipeline.md (latent-scaling invariant,
black-output causes, fidelity levers, single-frame + vanilla-oracle debug
loop, checkpoint preservation).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(matte): address PR #269 review

- license: align matte to the repo's GPL-3.0 (was self-contradictory: claimed
  "MIT licensed - see LICENSE" while LICENSE is GPL-3.0). pipeline.py header,
  NOTICE, and the maintainer doc updated. NOTICE still credits VideoMaMa
  (CC BY-NC) + SVD (Stability Community License).
- nodes.py _ensure_2d_mask: squeeze first, then handle [H,W,C]/[C,H,W]
  explicitly and RAISE on ambiguous shapes -- previously [H,W,3] silently
  became [W,3] (wrong geometry).
- nodes.py OOM backoff: catch RuntimeError (OutOfMemoryError subclasses it, but
  cuBLAS/cuDNN/older paths raise plain "RuntimeError: CUDA out of memory"); the
  existing message guard still filters non-OOM errors.
- nodes.py: warn when the guide mask is empty instead of silently falling back
  to full-frame.
- sync_to_dev.py: PRESERVE_IN_DEST is now an exact relative path
  ("matte/checkpoints"), not a bare name matched at any depth; handle symlinks
  before is_dir() in _clean_dest so a symlinked dir isn't recursed/rmtree'd.
- CHANGELOG: add the Koolook Matte nodes under [Unreleased] with the
  non-commercial model-license caveat.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(matte): address PR #269 re-review

- sync_to_dev.py [BLOCKING]: a top-level symlinked dest (e.g. target/matte -> X)
  was passed straight into _clean_dest()/copytree(), which follow the link and
  can mutate files outside the target. Now unlink a symlinked dest and own the
  path as a real dir (checked before exists(), which follows symlinks). Verified
  with a repro: the symlink target's file survives.
- nodes.py: force float32 on a CPU fallback (CUDA unavailable). Half precision
  is unreliable on CPU; fp16 kernels would error. Warn that CPU is very slow.
- docs: correct the preserved-path guidance to the target-relative
  "matte/checkpoints" (was a bare "checkpoints" name); reword "near-verbatim
  reimplementation" -> "independent implementation targeting behavioural parity"
  to match the NOTICE/pipeline framing.
- nodes.py: also warn on a degenerate (<8px) guide-mask region before the
  full-frame fallback (was silent).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(matte): address PR #269 re-review (CI red + FocusCrop frame check)

- nodes.py: KoolookMatteFocusCrop now validates images vs coarse_mask frame
  counts (raises like KoolookMatteSampler.run_inference). A mismatch previously
  made cropped_images/cropped_mask diverge and silently drop/misalign frames at
  FocusStitch.
- pipeline.py: split "vae.to('cpu'); _clear_cache(...)" onto two lines (Ruff
  E702 was failing Lint & Smoke).
- constraints-test.txt: bump pillow 12.2.0 -> 12.3.0 (pip-audit CVE, fixed in
  12.3.0). Pillow is a leaf dep so the closure is unaffected; CI re-audits.
- README: note the Koolook Matte nodes need diffusers (already via the LTX /
  Radiance forks) and huggingface_hub for runtime weight downloads.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: AI Machine <ai.machine@x.baconcph.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-19 17:03:12 +02:00

7.3 KiB

Raw Permalink Blame History

ComfyUI-Koolook

Kforge Labs for ComfyUI: a project-kit sidebar plus Koolook nodes for VFX, image, and video workflows.

Start here: KForge Labs ComfyUI-Koolook overview

That overview explains the sidebar, snapshots, saved workflows, modules, recovery tools, and included nodes for new users.

The main experience is the Kforge Labs sidebar. It helps you keep a project setup together: favorite nodes, saved workflows, reusable modules, tags, snapshots, and recovery tools.

Kforge Labs Sidebar

Use the sidebar as a reusable project kit.

Feature	What it does
Snapshots	Save and load the whole Kforge Labs state: favorite nodes, workflows, modules, tags, archive, and recovery data.
Search	Find nodes, workflows, directories, and tags from one field. Tags keep exact capitalization, so `Depth` and `depth` can be separate folders.
Nodes	Keep favorite nodes close, grouped by theme or repository name.
Workflows	Save the whole script, save a selection of nodes, load workflows, or insert saved modules into the current canvas.
Recovery	Use autosaves, starter presets, snapshot library settings, and missing-pack install helpers.

New here? Start with the KForge overview. Using it inside ComfyUI? Open the operational guide:

Browse on the web: malkuthro.github.io/ComfyUI-Koolook/web/guide/
Inside ComfyUI: Kforge Labs sidebar → Tools row → Help (H icon). The in-app button opens the bundled offline copy at web/guide/index.html.

Included Nodes

Node ID	Display name	Category
`EasyWan22Prompt`	Wan 2.2 Easy Prompt (Koolook)	`Koolook/Wan_Video`
`EasyResize_Koolook`	Easy Resize (Koolook)	`Koolook/Image`
`EasyAIPipeline`	Easy AI Pipeline (Koolook)	`Koolook/Pipeline`
`easy_ImageBatch`	Easy Image Batch (Koolook)	`Koolook/Image`
`KoolookLoadCameraPosesAbsolute`	Koolook Load Camera Poses (Absolute Path)	`Koolook/Camera`
`Easy_hdr_VAE_encode`	Easy HDR VAE Encode (Koolook)	`Koolook/VAE`
`Easy_hdr_VAE_decode`	Easy HDR VAE Decode (Koolook)	`Koolook/VAE`
`Easy_Pattern`	Easy Pattern (Koolook)	`Koolook/Testing`
`Easy_LoadVideo`	Easy Load Video (Koolook)	`Koolook/Video`
`Easy_VideoCombine`	Easy Video Combine (Koolook)	`Koolook/Video`
`Easy_Utility`	Easy Utility (Koolook)	`Koolook/Utility`
`Koolook_LoopStatus`	Koolook Loop Status	`Koolook/Loop`
`Koolook_PublishInput`	Koolook Publish Input	`Koolook/Publish`
`Koolook_PublishOutput`	Koolook Publish Output	`Koolook/Publish`
`Koolook_PublishRouter`	Koolook Publish Router	`Koolook/Publish`
`Koolook_PublishResult`	Koolook Publish Result	`Koolook/Publish`
`LTXDirector__koolook`	LTX Director (Koolook)	`Koolook/PromptRelay`

The root Koolook nodes and the slim Radiance Koolook VAE wrappers have no extra Python dependencies beyond torch, which ComfyUI already requires. The video wrappers require Video Helper Suite, and the LTX Director fork is for workflows that already use the LTX / Prompt Relay node ecosystem. The Koolook Matte nodes additionally need diffusers (already pulled in by the LTX Director / Radiance forks) and use huggingface_hub to download the SVD + VideoMaMa model weights at runtime.

Install

ComfyUI-Manager

Open ComfyUI Manager.
Choose Install Custom Nodes.
Install by Git URL: https://github.com/malkuthro/ComfyUI-Koolook.git
Restart ComfyUI.
Open the Kforge Labs sidebar tab.

Manual

Clone this repository into ComfyUI/custom_nodes/:

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

Restart ComfyUI after installation.

One install at a time. If you already installed Kforge Labs via ComfyUI Manager, it lives at custom_nodes/koolook/ (the Manager / Registry-derived folder name). A second custom_nodes/ComfyUI-Koolook/ created by git clone is a parallel install — ComfyUI loads BOTH on every boot, both register the same routes and sidebar tab, and the workflow store silently corrupts on every restart. From v0.3.8 the plugin detects this and prints a critical log naming both paths, disabling the non-winning copy — but the cleanest fix is to remove one folder. Pick the install method you want and stick with it.

Learn More

Public overview: kforgelabs.com/comfyui-projects/comfyui-koolook/
In-app visual guide: malkuthro.github.io/ComfyUI-Koolook/web/guide/ (offline copy: web/guide/index.html)
Support / bug reports: SUPPORT.md
User guide: docs/user_guide/
Change history: CHANGELOG.md
Maintainer docs: docs/maintainers/
Fork attribution and provenance: forks/THIRD_PARTY.md
Versioning reference: docs/reference/versioning.md

Troubleshooting

What you see	What it usually means	What to do
The Kforge Labs tab does not appear	ComfyUI needs a restart, or the extension did not load	Restart ComfyUI and check the terminal for `[Koolook]` messages.
The Help guide does not open	The browser blocked the popup	Allow popups for the ComfyUI page, or open `web/guide/index.html` directly.
Missing custom nodes after loading a workflow	One or more node packs used by that workflow are not installed	In Kforge Labs, use Tools → Install missing packs, or use ComfyUI Manager's Install Missing Custom Nodes flow.
Snapshot save/load fails	The snapshot library path may be missing, read-only, or unavailable	Use Snapshot → Save to... or Load from... and choose a writable folder.
A loaded snapshot looks older than expected	Named saves and auto-saves are intentionally separate	In Snapshot → Load, select the snapshot and check Recovery auto-saves for a newer periodic/pre-load recovery.

Support

For reproducible bugs, open a GitHub issue. For the fastest answer, include your ComfyUI version, Koolook version, operating system, install method, terminal log, browser console errors, and steps to reproduce. See SUPPORT.md for the exact checklist.

If Koolook helps your ComfyUI work, you can support development on Ko-fi.

Stability

For production work, install a pinned release tag or commit instead of following a moving branch head. Node IDs are treated carefully so saved ComfyUI workflows continue to load across compatible updates.

License

GPL-3.0. See LICENSE.

This package incorporates and adapts GPL-3.0 code from fxtdstudios/radiance under forks/radiance_koolook/. Attribution and per-fork modification notes are tracked in forks/THIRD_PARTY.md and forks/forks_manifest.yaml.

7.3 KiB Raw Permalink Blame History