FaceShaper Cropper

This is step one of FaceShaper's V2 pipeline, and it's the node that solves the problem V2 exists to solve: tilted faces. The original single-node FaceShaper warped a face's shape directly against a target, but it had no separate alignment step, so a face that wasn't roughly upright in the photo produced a bad result. V2 splits the job into three nodes specifically to fix that, and this is the first one - find the face, level it, crop it out at a consistent size, and hand off both the crop and the metadata needed to paste it back later.

What it does

You give it a full image and a cropper (loaded by one of the three loader nodes - InsightFace, MediaPipe, or FaceAlignment). It detects the face, rotates it so it's level, crops it to a fixed square, and outputs both the crop itself and a crop_info object carrying everything needed to reverse the transform later. You typically run this node twice in a workflow - once on your source photo, once on your target - to feed both crops into FaceShaperMatchV2.

The inputs that matter

• cropper (FSMCROPPER) and source_image (IMAGE) - the detector model and the photo to crop from.
• dsize (default 512, range 64–2048) - the output crop resolution, square. 512 is a sensible default; push it higher if you need more detail for a large final composite.
• scale (default 2.3, range 1–4) - how much context around the detected face to include in the crop. This follows the same convention as LivePortrait's cropping, which FaceShaper's crop code is adapted from.
• vx_ratio / vy_ratio (defaults 0 and -0.125) - fine offsets that shift the crop center relative to the detected landmarks, horizontally and vertically. The default vy_ratio of −0.125 nudges the crop slightly, which is a deliberate framing choice baked into the default rather than an accident - leave it unless your crops look off-center vertically.
• face_index and face_index_order - which face to grab when there's more than one in the photo. face_index_order sorts the detected faces by a criterion (large-small, left-right, top-bottom, distance-from-retarget-face, and their reverses), and face_index (default 0) picks the position in that ordering. If your image has one face, ignore both.
• rotate (default true) - whether to level the crop so the face is upright. This is the actual fix for tilted-face inputs; turn it off only if you have a specific reason to keep the original orientation.

Outputs: cropped_image (IMAGE) - the aligned face crop, feed it into FaceShaperMatchV2's source_image or as the reference for the target. crop_info (CROPINFO) - the transform metadata, feed it into FaceShaperMatchV2 (as source_crop_info or target_crop_info), FaceShaperComposite, FaceShaperFaceMask, or FaceShaperShowLandMarks.

Installing it

Through ComfyUI Manager, search "ComfyUI_FaceShaper" and install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/fssorc/ComfyUI_FaceShaper

then restart. This node itself has no dependencies beyond the base pack - all the heavy install requirements (InsightFace, MediaPipe, or face-alignment, plus the shared landmark.onnx / landmark_model.pth files under models/liveportrait) belong to whichever loader node you plug into its cropper input.

Common issues & troubleshooting

Wrong face picked out of a group photo. That's face_index / face_index_order, not a detection bug. Try a different face_index_order (e.g. large-small to grab the most prominent face) before assuming the detector failed.

Crop looks badly framed or off-center. Adjust vx_ratio / vy_ratio first, and scale second if the crop is including too much or too little context around the face.

Face still looks tilted after cropping. Check that rotate is actually true - it's the setting this whole node exists to provide, and it's easy to have toggled off without noticing.

Downstream nodes complain about a mismatched or missing crop_info. crop_info is only meaningful paired with the cropped_image from the same run of this node - don't reuse a crop_info from a different photo or a different crop settings pass against a mismatched image downstream.