TRELLIS.2 / Pixal3D BiRefNet Loader ⚡

Image-to-3D lives or dies on the crop. Feed TRELLIS.2 a photo of a mug on a cluttered desk and you get a 3D model of "mug plus desk-ish blur" - the model reconstructs everything it sees, because nothing told it what the subject was. BiRefNet is the matting model both pipelines use to answer that question, and this node loads it as a BACKGROUND_REMOVAL object so core's Remove Background node can do the cutting.

What it is

BiRefNet, in the owner's extras/birefnet/model.safetensors - the ZhengPeng7 checkpoint the sidecar ships as its background remover. The node reads the safetensors, hands it to comfy.bg_removal_model.load_background_removal_model, and returns a BACKGROUND_REMOVAL. There's exactly one input (birefnet) and exactly one output (bg_model). It is a two-widget node and there is no reason for it to be more.

The output doesn't go straight into a 3D node. It goes into core's Remove Background, which produces a mask - and that mask is what your Prepare Image node wants. That chain matters and it's the bit people skip.

Why the mask matters more than the model choice

Here's the thing worth internalising before you spend an evening tuning sampler settings: the preprocessing crop is doing more work for your output quality than most of the knobs downstream. TRELLIS.2's preprocessing takes the alpha channel, finds the bounding box of every pixel above 0.8 alpha, crops a centred square around it, and composites the subject on black. If your mask includes a shadow, a table edge, or a sliver of background on the left, that bounding box grows and your subject gets smaller and further from the frame centre. The reconstruction quality falls off a cliff in a way that looks like a model problem and isn't.

So: BiRefNet for hard-surface props and clean product shots is genuinely good. For a translucent glass, a white-on-white sneaker, or hair, it will leak - and the 3D model will faithfully reconstruct the leak.

Files and folders

The dropdown lists .safetensors with "birefnet" in the name across models/trellis2/ and models/pixal3d/. The README's placement is models/pixal3d/extras/birefnet/ - both pipelines share it, so one copy is enough. Empty dropdown with just none means no file matched the name filter; the node is picky about that string, so don't rename it to matting-model-v2.safetensors and then complain.

That none entry will happily load and then fail at load_background_removal_model returning nothing - the error reads "'…' is not a BiRefNet checkpoint ComfyUI recognises". Two causes, in order of likelihood: you picked none, or the file is a ComfyUI-style repack of BiRefNet rather than the upstream one.

Install

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

Or ComfyUI Manager → search "ComfyUI-GGUF-Loader" → restart. gguf is the only install requirement this node cares about; the rest of the pack's dependency list is for the preprocessor and 3D/rigging families.

Where it fits in the graph

A TRELLIS.2 run looks roughly like this: Load Image → this loader's bg_model into Remove Background → the resulting mask plus the original image into TRELLIS.2 / Pixal3D Prepare Image (pipeline: trellis2) → conditioning → the cascade. For Pixal3D you also feed the prepared image into the MoGe loader's chain for camera estimation. The pack's example_workflows/trellis2_image_to_textured_glb_api.json has all of this wired already - copy it and swap the image.

Two gotchas worth carrying in your head. First, Prepare Image wants a foreground mask, 1 = subject, which is what Remove Background gives you - but if you feed it LoadImage's own alpha output instead, that's 1 = transparent, and you need an InvertMask in between or you'll crop to precisely the area you wanted to throw away. Second, there's no upscale or feathering here. If BiRefNet's mask is ragged, the 3D result is ragged, and no amount of resolution in the cascade fixes it.

If you're doing Pixal3D rather than TRELLIS.2, this is still the loader you want - the same BiRefNet, the same Remove Background - and it's the one piece of the extras folder both pipelines share.