Head Orientation Node - by PabloGFX

You've generated forty variations and need the one where the subject is actually facing the camera. Or you want a swapped face to sit at the same head angle as the reference photo so the re-light doesn't fight you. That's the exact gap this node fills: it reads each face, converts it to pitch/yaw/roll, and hands you both the numbers and a batch of images sorted by how close they are to a pose you care about.

It's a small, focused pack - one node, no API, no key, no model you have to hunt down. PabloGFX built it for head-pose-aware workflows, and the README reads like a changelog of real user pain, which is a good sign.

How it works

Under the hood it's MediaPipe + OpenCV, not a diffusion model. Each image goes through Google's FaceLandmarker (the modern mediapipe.tasks.python.vision API), which detects the face and returns 478 landmarks. Six canonical points - eyes, nose, mouth corners, chin - get fed into OpenCV's solvePnP with a simple pinhole camera model, and the resulting rotation is decomposed into pitch (nodding), yaw (turning left/right), and roll (tilting).

A few nice touches in the current version. The node auto-downloads face_landmarker.task (~3.7 MB) from Google's storage on first run, so there's nothing to fetch by hand unless your machine is offline. And v1.4.0 added multi-scale detection: MediaPipe's BlazeFace works on tiny internal tiles and silently fails on 4K phone photos, so the node downscales to detection_max_side (default 1280), and if detection fails it retries at 1600 → 960 → 640 → 480 automatically. Your output images stay at original resolution - only the detection runs on the downscaled copy.

The inputs that matter

image and reference_images are both required IMAGE tensors, so you always feed two batches. Everything else is optional, and most of it you can leave alone:

• sort_source - the one that confused people for two versions. references (default) treats image as your query/target pose and reference_images as the candidate pool: sorted_images is the pool reordered by similarity. inputs is the legacy v1.x meaning, sorting image by similarity to the references. If you have one main image and a stack of candidates to rank, you want the default.
• min_detection_confidence (default 0.3) - lower it toward 0.05 for dim portraits, faces under caps, or heavily cropped heads. The detector rebuilds when you change it.
• detection_max_side (default 1280) - the fix for giant source images that return [0,0,0] orientations.
• data_content / data_format - what the data string reports and how it's shaped. data_content = "outputs" matches sorted_images row-for-row; data_format can be compact, labeled, csv, json, or verbose, with include_distance appending the angular gap to the closest opposite-batch item.

sort_mode (similarity_to_refs, reverse_similarity, match_references, as_is), similarity_metric, and output_count fine-tune the ranking - nice to have, not required reading.

Outputs

• sorted_images (IMAGE) - the batch, reordered per sort_source + sort_mode.
• data (STRING) - per-row pitch/yaw/roll text. Feed it to a text display or parse it for a condition.

Installing

Through ComfyUI Manager, search "Head-Orientation-Node - by PabloGFX" and hit install. Or the manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/lazniak/Head-Orientation-Node-for-ComfyUI---by-PabloGFX.git
cd Head-Orientation-Node-for-ComfyUI---by-PabloGFX
pip install -r requirements.txt

Restart ComfyUI. It needs numpy, opencv-python, Pillow, torch, and mediapipe>=0.10.0 - that last one is the real dependency, because older slimmed-down MediaPipe builds (the old Windows portable shipped one) were missing the legacy face mesh API. v1.1.0 fixed that by using the Tasks API, so keep MediaPipe current.

Where people get burned

• [0,0,0] for every face on big images - that's the BlazeFace large-image failure; raise nothing, just confirm you're on 1.4.0, or nudge detection_max_side down.
• No faces detected at all - drop min_detection_confidence, then check that the model file actually downloaded to models/face_landmarker.task. Offline machine? Grab that file manually and drop it in.
• Wrong-batch sorting - if your outputs don't match what you expected, check sort_source first; the semantics changed at v1.3.0 and old workflows carried over the legacy meaning.

It's a niche tool, but when "which of these 40 faces is looking at me" is your question, it answers in one run.