nodes/malkuthro-ComfyUI-Koolook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
dependabot/github_actions/github-actions-30f7f1d3b7
malkuthro-ComfyUI-Koolook/README.md
T
malkuthroClaude Opus 4.8AI Machine
 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

144 lines
7.3 KiB
Markdown
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](https://www.kforgelabs.com/comfyui-projects/comfyui-koolook/)
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](https://www.kforgelabs.com/comfyui-projects/comfyui-koolook/).
Using it inside ComfyUI? Open the operational guide:
- **Browse on the web:** [malkuthro.github.io/ComfyUI-Koolook/web/guide/](https://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`](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
1. Open ComfyUI Manager.
2. Choose **Install Custom Nodes**.
3. Install by Git URL:
`https://github.com/malkuthro/ComfyUI-Koolook.git`
4. Restart ComfyUI.
5. Open the **Kforge Labs** sidebar tab.
### Manual
Clone this repository into `ComfyUI/custom_nodes/`:
```bash
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/](https://www.kforgelabs.com/comfyui-projects/comfyui-koolook/)
- **In-app visual guide:** [malkuthro.github.io/ComfyUI-Koolook/web/guide/](https://malkuthro.github.io/ComfyUI-Koolook/web/guide/)
(offline copy: [`web/guide/index.html`](web/guide/index.html))
- **Support / bug reports:** [`SUPPORT.md`](SUPPORT.md)
- **User guide:** [`docs/user_guide/`](docs/user_guide/)
- **Change history:** [`CHANGELOG.md`](CHANGELOG.md)
- **Maintainer docs:** [`docs/maintainers/`](docs/maintainers/)
- **Fork attribution and provenance:** [`forks/THIRD_PARTY.md`](forks/THIRD_PARTY.md)
- **Versioning reference:** [`docs/reference/versioning.md`](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`](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](https://github.com/malkuthro/ComfyUI-Koolook/issues/new/choose).
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`](SUPPORT.md) for the exact checklist.
If Koolook helps your ComfyUI work, you can support development on
[Ko-fi](https://ko-fi.com/kforgelabs).
## 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`](LICENSE).
This package incorporates and adapts GPL-3.0 code from
[fxtdstudios/radiance](https://github.com/fxtdstudios/radiance) under
`forks/radiance_koolook/`. Attribution and per-fork modification notes are
tracked in [`forks/THIRD_PARTY.md`](forks/THIRD_PARTY.md) and
[`forks/forks_manifest.yaml`](forks/forks_manifest.yaml).
Reference in New Issue View Git Blame Copy Permalink