Neo Reference Grid (参考图宫格)

Reference-image workflows grow ugly fast. Nine LoadImage nodes, a text box, and a wire from each image into a reference-to-video node whose slot numbers you have to keep straight in your head because <Picture 3> in the prompt has to mean slot 3. Neo Reference Grid collapses all of that into one node: a grid of up to twelve thumbnails, a prompt box, and outputs for both.

It's the node for the two things reference images are actually for. Feeding MiniMax H3's Reference-to-Video node, which takes up to nine reference images and refers to them by number in the prompt. And the turnaround-sheet pattern - generate a character from several angles in one pass, then reuse any panel of that sheet as the reference for everything downstream - which is what kept sheet-based character work useful long after the training-a-LoRA answer stopped being the default.

How it works

The grid is the frontend. The node's real inputs are two hidden strings: refs, which is a JSON array of filenames living in ComfyUI's input/ directory in slot order, and prompt_text, the node's own prompt box. The filename list is what gets saved with your workflow - the slot count doesn't, because you adjust it at runtime (the toolbar's −/+ takes it from 1 to 12), and neither the slot count nor the layout has any meaning on its own.

On execute it decodes each filename to a tensor, re-encodes it as a PNG data URI, and packs the prompt plus the references into a runtime BUNDLE. The bundle is deliberately typed empty - the node can't know whether you're heading for an image model or a video model, so the consumer decides.

Inputs and outputs

The inputs are refs and prompt_text, both strings, both hidden behind the grid UI. There's nothing to configure beyond how many slots you want and which pictures go in them. Thumbnails keep the image's real aspect ratio and the layout reflows with node width, so a two-slot grid and a twelve-slot grid both look sane.

Outputs:

• prompt - the text, out as a plain STRING.
• BUNDLE - the runtime package. Wire it into Neo Image Gen & Edit or the pack's H3 Video Director, which consume prompt and references together.
• image_1 … image_12 - decoded IMAGE tensors, in slot order. Wire them straight into a node that takes images, e.g. the official MiniMax H3 Reference-to-Video's reference slots. If you want the official node's prompt and images from one bundle, run the BUNDLE through the pack's Neo Bundle Expand, which gives you prompt plus image_1 … image_9 in the exact shape that node expects.

Install

ComfyUI Manager, search Neo Nodes (it's on the ComfyUI Registry), or:

cd ComfyUI/custom_nodes
git clone https://github.com/neoneo-ai/ComfyUI-Neo-Nodes.git

Restart. requirements.txt pulls openai, Pillow, PyYAML and pypinyin - the README lists requests instead of openai, so trust the file on disk. This node itself needs no models and no GPU; the heavier parts of the pack need plenty of both.

Where people get burned

Empty slots don't backfill. If a file is missing or unreadable, that slot stays empty and the node moves on - it doesn't shuffle the rest up. So a broken image in slot 3 leaves image_3 empty while image_4 stays full. Positional slots are the right call for prompt numbering, but it means a silently empty slot can shift what <Picture 3> refers to if you later compact the grid.

Unused slots emit an empty batch, not nothing. Wiring all twelve outputs into a twelve-input node when you've only filled four is a good way to make the downstream node complain. Connect the ones you use.

The grid stores filenames, not pictures. Which means the images have to exist in input/ on the machine that runs the workflow. Copy the JSON to another rig without those files and you get a grid of empty slots. Delete something out of input/ later and the same thing happens to a workflow that was working yesterday. If you're archiving, archive the input files too.

Slot count and recipes. The grid takes part in the pack's recipe save/restore, and the toolbar's ☰ can load an existing recipe complete with its images - that's the intended way to carry a reference set between sessions rather than trusting the workflow JSON alone.