Visual Component Fusion Configurator

When a VLM encoder can't fit both of your reference images, one answer is to fuse their visual tokens before encoding - and that's a genuinely fiddly operation with five or six ways to do it wrong. UC_VisualFusionConfig is the configurator for that operation: it defines how multiple images' visual token embeddings get combined into one stream, from a boring linear average up to spatial patterns like checkerboards and block interleaves. If you're building multi-image conditioning workflows on a Qwen3-VL encoder, this is the node that makes the choice explicit instead of implicit.

What it is

A configuration node. It collects a method plus its parameters and outputs a Fusion Config object that downstream consumers - the pack's advanced visual conditioning encoders, or the TokenFusion text generator - read when they blend images. On its own it computes nothing; it's the recipe.

The fusion methods

The visual_fusion_method dropdown is where the real decisions live:

• off - no spatial fusion; images stay separate.
• linear - the simple weighted blend of the token vectors. Fast, and as crude as it sounds.
• spatial-checkerboard - selects source vectors by a reproducible token-grid pattern. The default, and the one to start with.
• spatial-block-interleave - groups tokens into spatial patches (visual_block_size) and switches whole patches between sources.
• spatial-dither-random - the seeded one: dither_ratio sets the probability of picking image 1, the rest fill in with a checkerboard, and seed makes the pattern reproducible. dither_secondary_pattern and dither_mask_cleanup tune how images 2+ participate.

The tooltip carries the honest caveat: generation quality is model and prompt dependent. There's no universally correct method - you try checkerboard, you try block-interleave, you look at the output, you move on.

The other knobs

• visual_block_size - patch size for block-interleave (1–8).
• dither_ratio / seed - probability and reproducibility for the random method.
• visual_encoder_path - grid-deepstack (current Core grid MRoPE + DeepStack injection) vs legacy-flat (the pre-change flat 1D route). This is the compatibility switch for older ComfyUI.
• save_blended_embeds + save_path - write the blended tokens to a standalone .safetensors under models/embeddings, if you want to reuse a fusion you like.
• spatial_perturbation - seeded cell swapping between sources for hard fusion methods; higher values reduce spatial coherence, so treat it as a dial to twist carefully.

Output: Fusion Config, into the encoder or textgen node.

Installing it

Part of ComfyUI-UtilsCollection:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-UtilsCollection

Restart ComfyUI (or use Manager, search "ComfyUI-UtilsCollection"). No models, minimal deps, needs a current ComfyUI for the DeepStack/grid path.

Common issues

Expect to experiment - that's the feature, not a bug. Start at spatial-checkerboard and change one variable at a time; the block-size and dither knobs interact in ways you can't predict from reading. If you're on an older ComfyUI, switch visual_encoder_path to legacy-flat before troubleshooting anything else, because the README explicitly says grid-deepstack tracks current Core behavior. And if you enable save_blended_embeds, remember the file lands in models/embeddings and persists across runs - a saved fusion you forgot about will keep quietly influencing later workflows.