Reference Image Processing

Instruction editing ate the character-consistency problem. Point Qwen-Image-Edit at a photo and it holds the face better than any IP-Adapter stack ever did - as long as the reference arrives at a sane size. Feed it a 4K phone photo and you've spent your context and VRAM on detail the encoder throws away. Feed it a 512px crop and the model invents a new face from the blur.

HenjiccQwenReferenceList - Reference Image Processing, Henjicc/Image - is the preprocessing step that gets this right, and it gets it right in the specific way that matters: per image, not per set.

The mechanism

It pulls every image out of your media bundle in order, fattens each one to RGBA (alpha reconstructed from its mask channel, so transparent PNGs survive), then for each image independently:

1. Computes a scale factor of sqrt(megapixels × 1,000,000 / (width × height)) - so a portrait and a landscape both land in the same megapixel budget instead of the same pixel dimensions. Aspect ratio is never touched.
2. Rounds both sides to the alignment grid (1, 2, 8, 16, 32 or 64; default 32), never below the grid.
3. Resizes with Lanczos via ComfyUI's own common_upscale, skipping the resize entirely when the size already matches.

Then it checks the total: all references combined may not exceed 33,554,432 pixels. Ten references at 1 MP is comfortable; ten references at 4 MP each is not, and you get a clear "Total pixels exceed 33554432" instead of a CUDA OOM three nodes later.

The inputs

• media - the bundle. Images only; video and audio items are ignored, not errored.
• reference_megapixels - 0 to 32, default 1. Set it to 0 and images pass through at original size, which is the "I already sized these" escape hatch.
• alignment - default "32". Keep it. Qwen-family encoders want multiples of 32; odd sizes get patched badly.

The outputs, all four of them

images is a list - one processed IMAGE per reference, in order. This is the output that goes into a multi-reference encoder, usually through the pack's Image List to Slots because encoders want discrete image1/image2 sockets rather than a list.

text_mode is the one that confuses people: it's true when there are no images. The label in the UI is "Text-to-image mode," and it's a boolean you can branch on - reference images present, do an edit; none present, do a plain generation. If it reads inverted to you, it isn't: true means the text-to-image branch is live.

first_image is the first reference at its original size, unprocessed. Useful when you need the untouched source for a save node, a mask, or an identity check.

prompt is your asset panel's prompt with the reference tags compiled in, so the text and the images agree about which picture is which.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/henjicc/ComfyUI-Henjicc.git ComfyUI-Henjicc
python -m pip install aiohttp av numpy Pillow

Restart and hard-refresh, or grab comfyui-henjicc from Manager. Notably this node needs no model at all - the README says as much, and it's the fastest way to verify the pack installed correctly: Super Input → Reference Image Processing → Preview Image, one megapixel, alignment 32, run. If a preview comes out, the pack is fine and any remaining problem is about weights.

Where people trip

The 32 MP total cap. It's a sum across all references, and it's checked after resizing. Eight references at 4 MP each will fail even though each individual image looks reasonable.

alignment = "1". It parses, it runs, and you get dimensions the encoder dislikes. Only drop below 32 if something downstream explicitly demands it.

A list isn't a batch. Wire the list output straight into an encoder that takes a single IMAGE and ComfyUI happily generates once per reference - N outputs, one per picture, each from one picture. If you wanted one generation with N references, you need the slot allocator in between.

Order is identity. Reference 1 and reference 3 are different claims about your subject. Reordering items in the media panel reorders this list, and the tags in prompt follow, so text and images stay consistent - but the meaning of your prompt may not.