Academia SD Multi Image Reference 🖼️

Why this node exists

Multi-image editing is what turned the Qwen-Image-Edit line from a toy into a workflow component: the 2509 revision added person+person, person+product and person+scene conditioning, and you point at those pictures in the prompt with tags like <image1> and <image2>. It works well. The wiring around it is the tedious part - a row of Load Image nodes, a rescale node copied from the last workflow, and a numbering scheme you keep straight in your head.

Academia SD's Multi Image Reference folds that row into one panel: ten slots, drag-and-drop, per-slot on/off, and a hero image whose size sets the canvas. It's an opinionated convenience node - if you only ever feed two references, five Load Image nodes are honestly fine.

How it actually works

State for all ten slots lives in one hidden STRING widget, refs_data, holding JSON: which file sits in which slot, whether it's on, where you dragged the hero, where the crop window sits. Deliberate - twelve file/toggle widget pairs would be twenty-four entries in the saved workflow, and adding an eleventh reference later would shift every saved value.

An off or empty slot outputs nothing - literally None, the same null the Qwen text encoder skips. No bypassing, no unplugging.

On the canvas the node shows no outputs at all. Its images leave the graph through a companion node, Academia SD Multi Image Reference Out 🖼️, which is frontend-only and mirrors the ten image_1…image_10 outputs plus Reference_active. The Out node picks its source by the main node's title, not a cable, so you can run several in one workflow - rename each main node. It's virtual: its output N is swapped for the main node's output N at queue time, so files load and rescale once even if three Out nodes pull the same slot.

The output worth understanding is Reference_active: an INT counting the slots switched on and holding a file. That number is exactly how many <imageN> tags reach the encoder - the thing to log when your prompt's tags and your panel's pictures disagree.

The inputs you actually touch

width and height apply to image 1 only, and both at 0 means "don't touch it" - the node becomes a plain multi-loader. Only the hero is resized because the Qwen text encoder takes its latent from the first reference it receives, so image 1 is the one whose dimensions change the output; everything else gets rescaled by the encoder itself.

crop decides how image 1 gets into that frame. pad (the default) fits the whole picture in and fills the rest with pad_color; center and stretch are literally ComfyUI's own Upscale Image behaviour, crop-to-fill and distort-to-fit; custom is crop-to-fill with the window wherever you dragged it. pad_color takes hex or the names white / black / grey.

outpaint is the switch worth poking at. Off, image 1 sits centred and whole. On, the node obeys the placement you dragged in the panel - push the box past the edge and the outside simply doesn't exist, which is how you build an outpaint canvas in front of an edit model. scale_method is the same five filters as the native Upscale Image node, lanczos by default.

One feature that isn't in the README: any slot can carry a ControlNet map instead of the picture. Generate canny, depth, pose, lineart, soft edge, scribble, normal, segmentation or MLSD from the reference (needs comfyui_controlnet_aux; the processors you don't have just don't appear), and the map is saved next to the original as <name>_<suffix>.png and leaves through that slot. That's the current advice from the ControlNet side anyway: hand an edit model a preprocessed map rather than loading a ControlNet checkpoint.

Install

ComfyUI Manager, search comfyui_AcademiaSD, or:

cd ComfyUI/custom_nodes
git clone https://github.com/AcademiaSD/comfyui_AcademiaSD

Restart ComfyUI. There's no requirements.txt - everything it imports (torch, numpy, Pillow, aiohttp, ComfyUI's folder_paths and node_helpers) already ships with ComfyUI, and the only optional extra is comfyui_controlnet_aux for the map button. Model-side you need a Qwen-Image-Edit stack: checkpoint, VAE, VL text encoder. The pack's example_workflows/ ships a couple of dozen JSONs and none use this node yet, so expect to wire it yourself.

Where people get burned

The error you'll actually hit is file missing in slot(s) N. Not fussiness: the model numbers <imageN> by position in the compacted list, so one lost file silently renumbers every reference behind it and your prompt starts describing a different picture. The node refuses instead.

If the panel doesn't render or the project buttons 404, you haven't restarted ComfyUI since cloning - the frontend extension and the HTTP routes only come up at startup.

Two smaller traps. Overwriting a reference in place doesn't fool the cache (mtime and size are hashed, so a re-queue reloads it). And the slot count is ten because that's what Qwen Image 2.1 handles; the 2509 cards only promise one to three inputs, so don't assume ten will behave. Two well-chosen references still beat ten.