Nucleus-Image VAE Decode

Every generation ends at a VAE decode, and this one is the pack's exit door: Nucleus-Image VAE Decode takes the NUCLEUS_LATENT from the Sampler and the NUCLEUS_VAE from the VAE Loader and hands you a normal ComfyUI IMAGE tensor. From here on, it's all stock nodes - preview, save, upscale, whatever.

What's actually happening under the hood

Two things make this node non-trivial, and both are worth knowing when you're debugging.

First, the latents aren't a plain tensor. The sampler produces patch-packed latents - the tokenized form the transformer actually works with - and this node has to unpack them back into a 16-channel spatial latent, then reshape through the VAE's expected channel layout. It also stores the target width and height inside the latent object, so the decode knows the final pixel dimensions.

Second, there's a normalization round-trip. Nucleus-Image's latents are stored normalized (divided by latents_std and shifted by latents_mean), and the decode has to undo that with the VAE config's per-channel values before the VAE touches them. This is why you can't decode this model's latents with a stock VAE Decode node - the channel count and the normalization are both model-specific. If you've ever seen a decoded image that looks like it was dunked in dishwater, this normalization mismatch is usually why.

The actual decode moves the VAE to the GPU, runs it, then offloads it back to CPU and empties the cache - same memory-hygiene pattern as the rest of the pack.

Inputs and output

• vae - NUCLEUS_VAE from the VAE Loader.
• samples - NUCLEUS_LATENT from the Sampler.

Output is a standard IMAGE tensor, in the usual ComfyUI [0,1] float range - wire it to Save Image, Preview Image, or any of your usual post-processing nodes. Because it's standard, you can do img2img-style tricks downstream without extra adapters, though the README's own workflows stick to a straight generation → save.

Installing and troubleshooting

Pack-wide install - ComfyUI Manager (search "Nucleus-Image") or:

cd ComfyUI/custom_nodes
git clone https://github.com/a180265/Nucleus-Image-comfyui-beta

restart. Needs nucleus_image_vae.safetensors (~122 MB) in models/vae/ - it's the smallest download in the set, don't skip it.

The troubleshooting list is short and honest. Output is dark or grey: the VAE file is wrong or missing - the README's FAQ pins this exact symptom to a wrong VAE. Node errors: check that the latents actually came from the pack's Sampler; feeding it a latent from a stock KSampler is a type mismatch the node isn't built to catch gracefully. Slow decode: the VAE loads and offloads per run by design; that's the price of keeping memory free for the transformer, not a leak.

One beta caveat, because it's fair to say: the author verified FP8 inference on 24GB. The VAE path is the most standard part of the pack, so this is the safest node to trust if something else misbehaves.