Load Matting Model

What it does

Load Matting Model is the boring-but-necessary start of every workflow in this pack: it loads the matting model and its preprocessor, both of which Apply Matting needs. Two choices in the dropdown, and that's the whole node:

• vitmatte_small (103 MB) - the sensible default. Fast, light, and honestly good enough for most compositing work.
• vitmatte_base (387 MB) - heavier, trained on the same benchmark, with a bit more headroom on genuinely hard edges. Use it when the small model is failing you, not preemptively.

Both are the Hugging Face hustvl/vitmatte-* weights from the ViTMatte paper (CVPR 2024). Same model family that pops up in a few other ComfyUI integrations - if you've seen "hustvl/vitmatte-small-composition-1k" in a log before and wondered where it came from, this is it.

How it works

The interesting bit is what happens on first use. There are no pre-downloaded files sitting in a models folder waiting for you. The loader calls Hugging Face's from_pretrained, pulls the weights, and saves them into ComfyUI/models/matting_models/hustvl/vitmatte-.../. Every run after that loads the local copy.

Two consequences. First, you need network access to Hugging Face the first time you pick a model - a real wall for people running ComfyUI behind a proxy or on a restricted network. Second, the download location is unusual enough that people get lost: the model lives in a matting_models folder inside ComfyUI's models directory, nested by its Hugging Face repo id.

Inputs and outputs

• model_name - the dropdown, one of the two above. Nothing else to configure.

The outputs both feed Apply Matting:

• MATTING_MODEL - the ViTMatte network itself.
• MATTING_PREPROCESSOR - the image processor that resizes and normalizes your input the way the model expects. Wire both into the matching required inputs on Apply Matting; they're a pair.

Installing it

Shared with the whole pack:

cd ComfyUI/custom_nodes
git clone https://github.com/hackkhai/ComfyUI-Image-Matting

Restart ComfyUI and the nodes appear under the image_matting category. Then the first run of this loader downloads the weights - a ~103 MB or ~387 MB pull depending on which you pick.

One dependency worth knowing about before you install: the pack's requirements.txt installs transformers straight from the GitHub master branch rather than a released version. It works, but you're tracking the bleeding edge of HF's transformers, which is exactly the kind of thing that clashes with another custom node that pinned a stable release. And the requirements install four opencv variants, which is why the pack carries an import_error_install.bat - it uninstalls and reinstalls opencv when cv2 throws its classic import error. Run that from the pack's folder if you see it.

Common issues

• Stuck at "Downloading ... model..." with no progress. Network issue reaching Hugging Face. Get the weights any other way and drop the folder at ComfyUI/models/matting_models/hustvl/vitmatte-small-composition-1k/ (or the -base-composition-1k equivalent) - the loader picks up the local copy. This is a recurring question from real users, so don't feel bad if it stumped you.
• cv2 import errors after installing the pack. That's the four-opencv situation. Run import_error_install.bat.
• Transformers version conflict with another pack. The git-master pin biting. Reinstalling transformers from a normal release sometimes sorts it, at the risk of drifting from what this pack's code expects.

The short version: pick small, wire both outputs into Apply Matting, and let the first run do the downloading. The whole pack is built around that one pipeline.