3d KPS from image

KpsDraw lets you place five points by hand, but you're eyeballing distances and relationships between them. This node does something smarter: it runs insightface on an actual face photo, extracts real 3D keypoints, and then lets you rotate, scale, and reposition that point cloud while preserving the true distances between eyes, nose, and mouth. If you're generating a face purely from a text prompt but want the keypoint geometry to come from a real face rather than something you drew freehand, this is the node.

How it works, and why it's 3D specifically

Regular drawn KPS is flat - you can drag any point anywhere, which means you can accidentally create a geometrically impossible face (eyes too far apart relative to the nose, say). This node instead extracts an actual 3D keypoint structure from a real photo, so when you then rotate that structure - tilt the head, turn it slightly - the proportions stay physically correct the way a real head's would when you turn it. That's the tradeoff against KpsDraw: you get correctness, but you give up total manual freedom. The README is explicit about that limit: "you cannot manually change the distance between KPS in this node."

How you use it

Connect an image, then click the "Get KPS From Image" button - this is the step that actually runs insightface detection. After that, use the "Change KPS" button to adjust position, scale, and rotation. Ctrl+drag moves, Ctrl+wheel zooms, Alt+wheel scales the keypoints. Once positioned, the node shows the rotation angle needed to align the face, same as KpsDraw does.

One practical warning straight from the README: clicking "Get KPS From Image" runs InsightFace live, and depending on your hardware that's not instant - don't click it repeatedly mid-generation-loop, do it once up front while you're setting up the graph.

The inputs and outputs that matter

• width / height (both default 1024) - canvas dimensions.
• image (optional) - the face photo to extract 3D keypoints from. Technically optional in the schema, but without it there's nothing to click "Get KPS From Image" against.

Two outputs: kps_data_3d (KPS_DATA_3D) - the full 3D structure, which only this node produces, and which Kps3dRandomizer needs - and kps_data (KPS_DATA), the flattened 2D version ready to go straight into KpsMaker or through KpsRotate/KpsScale/KpsCrop like any other keypoint data.

Install

ComfyUI Manager: search comfyui-instantId-faceswap. Manual: git clone https://github.com/nosiu/comfyui-instantId-faceswap into custom_nodes/, pip install -r requirements.txt. This node needs InsightFace's antelopev2 models in place - ComfyUI/models/insightface/models/antelopev2 - since "Get KPS From Image" is running the same face-detection pipeline as LoadInsightface feeds elsewhere in the pack.

Common issues & troubleshooting

"Get KPS From Image" is slow or seems to hang. This is running actual face detection, not a cached lookup - expect it to take a real moment depending on your GPU. It's not meant to be clicked repeatedly during a generation loop; set your KPS once, then generate.

No 3D keypoints extracted, or the button does nothing. Same root cause as "No face detected in pose image" elsewhere in this pack - the reference photo needs a clear, detectable face. Try a more frontal, higher-quality reference image.

Only this node's output feeds Kps3dRandomizer. If you want to use the 3D rotation randomizer, this is the only node in the pack that produces KPS_DATA_3D in the first place - KpsDraw and the 2D transform nodes can't supply it.