SapiensLoader

SapiensLoader is the node that finally made "turn a photo of a person into every map diffusion models care about" a one-stop shop. Instead of installing a depth pack here, a pose pack there, and a matting pack somewhere else, this one loader hands you segmentation, depth, normal, pose, pointmap, albedo, and matting from a single dropdown each. It's all Meta's Sapiens family of human-vision models - the ones that got a real community spike when they dropped in late 2024 - wrapped by smthemex (a prolific ComfyUI node author, also behind packs like ComfyUI_TwinFlow).

Why you'd reach for it: you want ControlNet-style conditioning from a real photo or a render. The seg map gives you region-level composition control, the depth map constrains spatial structure, the normal map is gold for relighting, and pose gives you the skeleton. Rather than juggling five packs with five different model conventions, this is one workflow - and it's person-specific, which generic estimators aren't. It's the sibling to the controlnet_aux stack, but tuned for humans.

What it actually is

Despite the "loader" name, this is a model picker + predictor factory, not a checkpoint loader in the usual sense. Each combo input lists the files sitting in ComfyUI/models/sapiens/, filtered by what they are (files with "seg" or "mIoU" in the name show up under seg, "normal" under normal, and so on). Pick what you want, hit execute, and the output - awkwardly typed as a MODEL - is an opaque predictor object that does not go into a KSampler. It wires straight into the pack's SapiensSampler. That's the single most common beginner mistake here: treating it like a UnetLoader. It's not. It's a handle to the whole multi-model bundle you assembled.

There are two generations behind the curtain, switched by the V2 toggle (default on). V2 loads a Sapiens2 predictor - the newer collection, which adds pointmap, albedo, and matting on top of the classic four. Turning V2 off drops you to the original Sapiens predictor, which only supports TorchScript .pt2 checkpoints.

The inputs that matter

• seg / depth / normal / pose / pointmap / albedo / matting - the seven selectors. Each is none or a model filename. seg is the backbone: the source code literally raises an error if you pick a pointmap without a seg model, because pointmap needs the person mask to know where the person is.
• dtype - float32 or bfloat16. Pick bfloat16 unless you're on hardware that hates it; roughly halves the memory footprint of these chunky 1B-parameter models.
• V2 - leave it on. It's the current code path and gets the updates (matting, body split).
• mini_person_h (default 0.5) - the minimum person height as a fraction of the image; how small a detected person still gets processed. Drop it if small background figures are being ignored.
• convert_torchscript - v1-only. Converts a selected FP32 TorchScript model to BF16 and saves a _bf16 copy next to it so you only pay that conversion cost once.

Installing and getting models

The standard route: ComfyUI Manager, search ComfyUI_Sapiens, install, restart. Or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/smthemex/ComfyUI_Sapiens
pip install -r requirements.txt   # adds ultralytics, opencv, huggingface_hub, termcolor, prettytable

The requirements are the honest part of this pack's README: ultralytics (YOLOv8) is non-negotiable for pose - the pose path needs a person detector first. Models live in ComfyUI/models/sapiens/, and the README is emphatic: don't rename the checkpoint files, or the loader's filename filters won't recognize them. If every selector is none, the loader auto-downloads a 1B seg model on first run, so you can be up and running before you've fetched the rest. A 1B model runs around 2GB in fp16 - download the sizes you actually plan to use, because "all seven loaded" is a real VRAM commitment.

Where people get burned

• Wiring the model output into a regular sampler. It won't work - route it to SapiensSampler.
• Pointmap without seg → hard error from the pack. Just load both.
• Pose with no YOLO detector - although the detector is smart enough to auto-download yolov8m.pt from Ultralytics/YOLOv8 if it's missing.
• Renaming checkpoints and then wondering why the dropdowns come up empty.
• Forgetting bfloat16 exists, then OOMing on a 2B model that fits fine in half precision.

SapiensLoader is one of those "install once, use constantly" nodes once you've internalized that its model output is a bundle, not a weight file.