TRELLIS.2 / Pixal3D Prepare Image ⚡

Nothing in an image-to-3D graph is more boring to look at and more consequential than the preprocessing crop. TRELLIS.2 and Pixal3D were both trained on a very specific framing - subject centred, tightly boxed, planted on black - and if your input doesn't match that, the model reconstructs your framing instead of your object. This node is the owner's sidecar preprocessing, verbatim, exposed as one node.

What it does to your image

Four steps, in order, no magic:

1. Cap the long side at 1024, LANCZOS. Everything downstream - DINOv3, the flow DiT - is working at a bounded resolution anyway, and upscaling past 1024 buys nothing but time.
2. Take the alpha you hand it as a mask, and find the bounding box of every pixel above 0.8 × 255. Not 0.5 - 0.8. A soft, semi-transparent edge doesn't count as subject.
3. Crop a centred square around that box, sized at the box's longer dimension times the pipeline's pad factor: TRELLIS.2 1.0×, Pixal3D 1.1×. Pixal3D gets slightly more margin because its conditioning expects a little air around the subject. That pad factor is the whole reason pipeline exists as a widget.
4. Composite the subject on black. TRELLIS.2's variant multiplies straight down (rgb * alpha); Pixal3D's does a proper over-composite (rgb * a + bg * (1 - a)). Tiny arithmetic difference, faithfully copied from the sidecar.

Output is a single IMAGE, cropped and squared, ready for the conditioning node - and for Pixal3D, also for the MoGe chain.

The three inputs

• image - your source frame.
• mask - foreground, 1 = subject. That's the tooltip's rule and it's the one thing to get right. Core's Remove Background gives you exactly this. LoadImage's alpha output is the opposite convention (1 = transparent), so an InvertMask goes in between. Wire it un-inverted and the node crops to the hole you wanted to discard, then either errors with "no foreground: the mask has no pixel above 0.8" or hands the model a black square.
• pipeline - trellis2 or pixal3d. Margin only. It does not change how the mask is read, so there's no reason to flip it hoping for a different crop behaviour.

Masks that don't match the image resolution get bilinearly resized to fit, so you can get away with sloppier wiring than you'd expect. A batch of images with mismatched crop sizes gets resized to the first one's size with a warning in the console - workable, but if you're batching props of different shapes, run them one at a time and save yourself the softness.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/ChrisColeTech/ComfyUI-GGUF-Loader
pip install --upgrade gguf

Manager install (search "ComfyUI-GGUF-Loader") is the same thing with fewer keystrokes. Restart after. No model files: this node is pure PIL and numpy, no weights, nothing to download.

Why this node exists at all

Fair question - ComfyUI has crop nodes. The answer is that "crop to the subject and square it" is not what a generic crop does. ImageCrop needs coordinates. ImageScale doesn't know where your subject is. Doing this by hand means a mask-to-bbox chain plus arithmetic, and getting the pad factor and the 0.8 threshold wrong - which you will, because nobody would guess 0.8.

And the 1.0× versus 1.1× business is not cosmetic. Feed Pixal3D a tight TRELLIS-style crop and its reconstruction loses the outer silhouette; feed TRELLIS.2 a loose Pixal3D crop and you hand it empty margin it happily treats as part of the scene. The tooltip says "crop margin as the sidecar" and that's exactly the claim: this is the number the owner's own pipeline ran, not a guess.

The honest caveats

Garbage mask in, garbage mesh out. Everything above depends on the mask. A BiRefNet matte that includes a contact shadow means the crop includes the shadow, the subject shrinks, and you spend the evening blaming the sampler. Clean mattes are worth more than any sampling setting.

It is genuinely lossy. Tight crop, resample to 1024, composite on black - you've thrown away context and colour around the object. That's the training distribution, so it's correct, but don't expect the node to be reversible. Keep the original around if you're compositing the result back into a scene later.

Premultiplied black is deliberate, and it's not a bug when it looks dark. TRELLIS.2's composite is hard premultiplication, which darkens the fringe of soft edges. It's what the sidecar does, and matching the training data beats looking nice.

Pair it with the BiRefNet loader (for the mask), the DINOv3 loader and the per-stage Model/VAE loaders, and you have the full front half of a TRELLIS.2 run. example_workflows/trellis2_image_to_textured_glb_api.json and its Pixal3D sibling are the wiring, already done.