Reference Grid

Contact-sheet reference grids are everywhere in local video work: you've got a character, a handful of reference photos showing them from different angles, and you want one composite image that hands all of them to the model at once. The stock way to do this is a quick grid node, and the stock result is square cells that center-crop everything - half your portrait gets lopped off, and the model never sees it.

Reference Grid is the version where you actually control the layout. It arranges references into a grid with per-cell fit behavior, cell sizing rules, fill order, and alignment for the ragged last row. If you've ever lost the edges of a wide reference to a dumb square cell, this is the node that stops that.

How it works

Every reference (from a MoonPack Image List or a stacked batch) gets normalized into its own cell. columns sets the column count - 0 auto-picks ceil(sqrt(n)), so 12 refs become a 4×3 grid, roughly square. Then the controls do their thing:

• fit_mode - cover scales to fill and center-crops the overflow (the default, but now it's your choice); contain scales to fit and pads the leftover with the fill color; stretch forces an exact fit and distorts the aspect ratio.
• cell_size_source - largest/smallest/average picks which references set the cell size, per axis independently. Feed one 4K and three 512px refs? largest upscales the small ones to match; smallest does the reverse.
• cell_width / cell_height - fixed overrides. Set both and cell_size_source is moot.
• fill_direction - row_major (left→right, then down) or column_major (top→bottom, then across).
• last_row_align - left/center/right for the incomplete trailing row (or column, when column-major).
• fill, interpolation, max_ref_side, invert_mask - the shared knob set: background color, resampling filter, a downscale-only cap on oversized references, and mask flipping.

The mask output is the quietly important one

Outputs: the grid image and a mask. The mask marks exactly the real reference pixels - it excludes empty cells and any contain padding. That's not an afterthought: if you're feeding this composite to a video model that accepts a mask, you can hand it a mask that says "these pixels are the subject, those are padding." It's the difference between the model paying attention to your character and paying attention to dead space.

Reference Grid vs. Reference Concat's auto grid

This pack has two grid-ish paths and they're not interchangeable. Reference Concat with no main_image produces an auto-laid-out justified contact sheet with zero control - it's a convenience. Reference Grid is the full instrument. If you want a specific column count, a contain-fit with padding, or an aligned last row, this is the one.

Installing it

Reference Grid ships in MoonPack (comfyui-moonpack). Install via ComfyUI Manager (search MoonPack) or:

cd ComfyUI/custom_nodes
git clone https://github.com/moonwhaler/comfyui-moonpack.git

Restart ComfyUI. No models to download, no extra dependencies beyond what ComfyUI ships.

Where people trip up

The default cover fit crops - it's the right default for grids, but if your references have unusual aspect ratios you will lose content until you switch to contain. And in contain mode, remember the padding is only fill color; the mask is the only thing that knows where the actual image is. Check it once before you trust the composite.