Zero123: Image Preprocess

The Zero123: Image Rotate in 3D node is a diva about its input. It wants a square image, an object on a white background, and the subject centered. Feed it a regular photo and you'll get a garbage angle-render, or worse, a rotation of the background instead of the thing you care about. Zero123: Image Preprocess is the node that exists so you never have to argue with it. It takes an image plus a subject mask and returns exactly the square, white-backgrounded, centered plate the rotate node demands.

One honest caveat before you get excited: this is a port of Zero-1-to-3, a 2023 research model, and its output ceiling is exactly that era - fixed 256×256, wobbly geometry. This node is just the makeup artist; it removes the failure mode where the model rotates your tablecloth, but it won't rescue the model's limits.

What it does under the hood. The mechanism is simple and satisfying. It takes your mask, finds the bounding box of everything nonzero (your subject), and crops the image to the square around that box. Then it applies the margin - a percentage of padding around the subject - and composites the subject onto a pure white canvas. One square image, subject centered, background white. That's the whole job, and it lives in the pack's util_preprocess.py as a bbox-crop-and-composite with a Zero123 hat on.

The inputs that matter. Three, and only one of them is a number:

• image (IMAGE) - your photo, any size or aspect ratio.
• mask (MASK) - the subject mask. This is the gotcha. The node is dead weight without a mask, and the pack's sample workflow doesn't even wire one in. You have to produce it elsewhere: a PNG with an alpha channel gives you a mask for free via LoadImage, or run your image through a segmentation node first. The standard plays these days are BiRefNet, InSPyReNet, or rembg-style removal - all available as ComfyUI nodes that expose a mask output (the background-removal essay in our KB is a good map of them).
• margin (FLOAT, default 0.05, range 0.01–1.0) - the padding around the subject as a fraction of the crop, so 0.05 is 5%. Crank it up if your object's silhouette kisses the edges of the frame.

Output: one IMAGE - square, white, subject centered. Wire it straight into the rotate node's image input. Nothing else needed.

Where people get burned:

• Empty mask → hard error. If your mask is blank, the node raises "Empty Mask, no subject found!" and the run dies on the spot. If you see that, the mask never actually made it through - check what's feeding the MASK port.
• Only the first image of a batch is processed. Throw a batch at it and it silently works on image[0] only.
• The output isn't upscaled. Resolution tracks your crop plus margin, so feed it a small photo and you'll be rotating a blur. Upscale the plate if you're going to care about the result.

Installing. This is half of the pack kealiu/ComfyUI-Zero123-Porting - installing the pack gives you both this and the rotate node. ComfyUI Manager: search zero123 and install. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/kealiu/ComfyUI-Zero123-Porting.git
cd ComfyUI-Zero123-Porting
pip install -r requirements.txt

Restart ComfyUI and refresh the browser. Heads-up: the requirements are the original research repo's stack - pytorch-lightning, omegaconf, einops, opencv, plus CLIP and taming-transformers built straight from git. It's a 2023-era dependency list and it's not light; the first install pulls a lot, and it can collide with other packs that pin the same libraries differently.

The honest verdict. If you're already feeding a clean, square, white-background render into Zero123, skip this node entirely - you don't need it. If you're feeding photos - shoes, furniture, any object with a real background - this is the node that makes the whole pipeline work. It's a tiny utility with a single trick, but it's the difference between Zero123 behaving and Zero123 hallucinating.