Randomize 3d KPS

Kps2dRandomizer shuffles flat points around - position, rotation, scale in a plane. This node does something different: it rotates real 3D facial geometry around three actual axes, so what you get out is a face that's genuinely turned, tilted, or nodded, with proportions that stay physically correct because the underlying data came from an actual 3D extraction rather than a flat point set. It only makes sense downstream of Kps3dFromImage, since that's the only node in this pack that produces the KPS_DATA_3D this one needs as input.

How it works

Each of the three rotation parameters corresponds to one axis of head movement, and the rotation point is the center of the KPS set, not some external origin - so the face rotates in place rather than swinging around a fixed point in the frame. The README's own example: set rotate_x to 20 and the node picks a random rotation angle somewhere between −20 and +20 degrees around that axis for each run. Setting a parameter to 0 effectively disables randomization on that axis.

The inputs and outputs that matter

• kps_data_3d (KPS_DATA_3D) - required, and this is the one input that only Kps3dFromImage can supply. There's no other node in this pack that produces 3D keypoint data.
• seed - tooltip: "The random seed used for randomizing KPS." Same behavior as the 2D randomizer's seed - change it for a new random draw, fix it to reproduce one.
• rotate_x / rotate_y / rotate_z (all default 0, range −180 to 180) - the three axes. Practically, these correspond to something like tilting the head up/down, turning it left/right, and rolling it side to side, though which axis maps to which visual motion depends on how the 3D data is oriented internally - the safest approach is to nudge one at a time and watch what changes.

Output: kps_data (KPS_DATA) - note this collapses back down to the flat 2D type, not KPS_DATA_3D. Once you've applied a 3D rotation, the result is ready to go straight into KpsMaker like any other keypoint output; you can't chain a second Kps3dRandomizer pass onto its own output without going back through Kps3dFromImage first.

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. No direct model dependency for this node, but it's only useful once Kps3dFromImage upstream has antelopev2 installed and working, since that's where your kps_data_3d actually comes from.

Common issues & troubleshooting

Node won't accept your kps_data input. Check the type - this node specifically wants KPS_DATA_3D, not the plain KPS_DATA that KpsDraw or the 2D transform nodes produce. If you're trying to randomize keypoints from a hand-drawn source, you want Kps2dRandomizer instead; this node only works on the 3D extraction from Kps3dFromImage.

Rotation looks subtle even at high values, or the face looks distorted at extreme values. Small rotations on real facial geometry read as natural head turns; pushed toward the ±180 limits, you're asking for angles a real head can't physically reach, and generation will fight that. Keep the ranges modest - the README's own example uses 20, not 180 - unless you're deliberately chasing something exaggerated.

Can't tell which axis does what. Isolate one at a time: zero out the other two, sweep just rotate_x, generate, look at what actually changed, then repeat for rotate_y and rotate_z. It's faster than guessing from the parameter names alone.