Sapiens2 Loader

This is the boring node at the start of every Sapiens2 workflow, and boring is the right design. Sapiens2 is Meta FAIR's family of human-centric vision transformers - pretrained on a billion human images, per the release - covering pose estimation, body-part segmentation, surface normals, and pointmaps. Each of those is a separate checkpoint family, and instead of giving you four loader nodes kijai built one that serves all four. You pick a checkpoint, it figures out the rest, and you hand the result to the task node you actually want.

How it works

The loader reads a safetensors file from ComfyUI/models/sapiens2 and sniffs the state dict rather than trusting a filename. It detects the backbone size (0.4B, 0.8B, 1B, or 5B) from the patch-embed dimensions, then finds which decode head is present - pose, seg, normal, or pointmap - and builds the matching ported model, wrapped in a ComfyUI ModelPatcher ready for GPU load and offload.

The practical upshot: one loader node handles every checkpoint in the pack, and the custom SAPIENS2_MODEL output carries the task type with it. The task nodes check that type, so if you wire a pose checkpoint into the normals node you get a clean "expected 'normal'" error instead of garbage output.

The one input that matters

• checkpoint - a dropdown of everything in models/sapiens2. That's the entire interface.

So the real decision is which checkpoint to download, because the loader can't choose for you. The four task families on Hugging Face:

| Task | Repo prefix | |------|-------------| | Pose (308 keypoints) | facebook/sapiens2-pose-* | | Body-part segmentation (29 classes) | facebook/sapiens2-seg-* | | Surface normals | facebook/sapiens2-normal-* | | Pointmaps (→ GLB) | facebook/sapiens2-pointmap-* |

Each comes in 0.4B / 0.8B / 1B / 5B sizes. Start at 1B - the 0.4B is a real quality step down on fingers and face landmarks, and the 5B is overkill for most Conditioning work. Download the file, drop it in models/sapiens2, refresh, and it appears in the dropdown.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-Sapiens2

then restart, or search "ComfyUI-Sapiens2" in ComfyUI Manager and let it handle the clone. Worth knowing before you panic about missing requirements: this pack declares zero Python dependencies. It's a thin wrapper over torch, numpy, and ComfyUI's own comfy_api.latest infrastructure, so there's no pip install step and no environment conflicts - a rarity in the custom node world and the reason this loader "just works" on a fresh ComfyUI.

One real gotcha: the pack is written against ComfyUI's newer V3 node-authoring API (io.ComfyNode, comfy_entrypoint), not the classic NODE_CLASS_MAPPINGS style. It coexists fine with old packs, but it needs a recent ComfyUI build - if the nodes don't appear after install, update ComfyUI itself before you debug anything else.

Also note the model license: Sapiens2 weights ship under Meta's custom Sapiens2 License, not Apache or MIT. Fine for personal and most research use, but read it before you put this in a commercial product.