DOGMA Qwen21OptionalReference v2

Two-image conditioning has become the routine way people hold a scene steady while changing how it looks. This node is DOGMA's wrapper around ComfyUI's own Qwen-Image encoder for exactly that: image 1 is the frame you're editing, and an optional image 2 is only allowed to contribute look - grade, lighting, photographic character - not objects.

It exists because the alternative is fussy. You either feed a second reference as a raw extra image and hope the model doesn't copy the wrong things out of it, or you do the whole thing by hand with two encoders and a text-conditioning merge. Here it's a boolean and an instruction.

How it works

The node takes your image as the scene, and when use_reference is on and an actual reference_image is wired, it resizes that reference so its long side fits reference_max_side, rounded up to a multiple of 32 (lanczos, via ComfyUI's own upscaler helper) and passes the pair to TextEncodeQwenImage21 as image_1 and image_2. reference_instruction gets appended to your prompt with a blank line, and its default text is worth reading because it is the whole trick:

Use image 1 as the scene to edit. Use image 2 only as a reference for color grading, lighting and photographic style. Preserve the composition, objects and geometry of image 1; do not copy objects or text from image 2.

That's an instruction, not a guarantee. Qwen's edit line re-emits the whole frame, so if you hand it a reference full of competing subject matter, expect it to wander - which is exactly why the reference is presented to the model as a style input rather than "here are two images, do something."

The inputs and outputs that matter

Only three inputs are ones you'll actually tune:

• image - the scene. This is what determines the canvas.
• use_reference / reference_image - the optional pair. Both are needed; either alone does nothing, and reference_status will tell you which case you're in.
• reference_max_side - the reference's incoming resolution cap, default 1536. Lower it if you're tight on VRAM; the reference is conditioning, not output, so it does not need to be huge.

Outputs are the full encode: positive and negative (CONDITIONING), latent (LATENT) - already built at the right resolution, so don't wire an EmptyLatentImage - plus effective_prompt, the prompt after the reference instruction was appended, and reference_status, a plain-English "Reference ON: image 1 = scene; image 2 = style/light/color." Both strings are there to be displayed. Put effective_prompt on a text preview the first few runs; it's how you confirm the instruction is where you think it is.

Install

Manager, search DOGMA Nodes, or:

cd ComfyUI/custom_nodes
git clone https://github.com/axior/ComfyUI-DOGMA-Nodes

Restart. The pack itself only pulls scipy>=1.10, but this node is a thin delegation to comfy_extras.nodes_qwen.TextEncodeQwenImage21 - a ComfyUI core node. If your install predates it, you get an import error the moment the node executes, and the fix is updating ComfyUI, not the pack.

Common issues

A reference that changes your scene. The likeliest cause is the reference being a photo with a strong subject in a similar position to your scene's subject. Crop it to the area you actually want to borrow - sky, wall, skin tone - and it behaves.

The reference silently doing nothing. Check reference_status. It reads "Reference OFF or absent" whenever the boolean is off or the input is unwired, and a second reference image is dropped outright: the node takes reference_image[:1], one reference only.

Qwen-Image 2.1 is a moving target. The 2.x line is recent and the open-weights situation around it is still settling - the 2511 edit line is the newest thing that definitely runs locally, and the encoder node this leans on is newer than that. Pin your ComfyUI version, or at least note what you're on before you file a bug with the pack.