Wan Face Controller 3D

WanFaceController3DV2 is the pack's all-in-one face editor, and it does what the other nodes won't: it changes the detected performance instead of just measuring or rendering it. Four independent stages, applied in order - a reference-shape blend, twelve FACS-inspired expression dials, a 3-DoF head rotation, and a gaze offset - and leaving any stage at its defaults makes it a no-op, so the same node covers a full edit or a single tweak.

The mental model: this node sits between detection and drawing. It takes pose_data, mutates the face landmarks / head pose / gaze, and hands the edited bundle downstream. If you then wire the edited pose_data into DrawViTPoseV2 with apply_pose_edits_to_face="warp", the actual face-crop pixels get warped to match - which is the only way Wan Animate's pixel-driven face encoder actually sees the edit. Miss that wiring and your expression dials change a skeleton that does nothing visible.

What it can do

• Reference-shape blend - blend the detected face toward the shape of a reference frame's pose_data (reference_pose_data input), per region: mouth, brows, eyes, jaw. This is how you nudge a performance toward a specific character's resting face.
• Expression dials - 12 FACS-inspired coefficients driven through expression_coeffs_json (the ARKit-52 blendshapes measured by the detection node). expression_strength, expression_clamp, per-axis clamps, and a propagate_expression option for extending an edit across frames.
• Head rotation - yaw/pitch/roll plus translation and scale, applied using a canonical iBUG-68 depth map so the face rotates in 3D rather than skewing. There are neck controls too, and propagate_head to push a keyframe pose across a range.
• Gaze offset - yaw/pitch on the iris data, with propagate_gaze for sustained redirection.

All of that is steered from fc3d_config_json, a big editor-owned JSON that the in-canvas viewer (face_controller_3d.js) writes for you when you drag the iBUG-68 face landmarks, OpenPose-18 body joints, or gaze handles. There are also raw landmark_overrides_json, pose_overrides_json and gaze_overrides_json inputs if you want to inject edits programmatically.

The node can even do its own detection: wire images + model and it runs ViTPose internally (with detection_threshold, pose_threshold, use_clahe, detect_rescale, fallback_to_full_frame), so you don't need a separate detection node. pose_data stays optional for that reason.

Outputs worth knowing

• pose_data - the edited bundle; the one you wire forward.
• preview_image and overlay_video - the in-canvas feedback, so you can see edits without a full render.
• keyframes_csv / pose_diff_json / coeff_time_series_json - edit provenance, useful when you need to know exactly what changed and when.
• lp_rotate_pitch / lp_rotate_yaw / lp_rotate_roll / lp_pupil_x / lp_pupil_y - clamped outputs specifically shaped for LivePortrait's ExpressionEditor (head rotations clamped to ±20°, pupil to ±15). If you're feeding a LivePortrait pipeline downstream instead of Wan Animate, these drop straight onto its inputs.

The honest take

This is the most powerful and the most fiddly node in the pack, and it's unapologetically aimed at people who want frame-accurate performance editing. The in-canvas viewer is the intended interface - editing the raw JSON by hand is a punishment. Two practical notes: the whole thing is optional wiring, so it slots into an existing graph without breaking it (defaults are all no-ops), and if your edits seem to have zero effect on the render, check that apply_pose_edits_to_face="warp" is on in DrawViTPoseV2 and that face_images is wired - that's the delivery path, and it's the first thing to go wrong.

Install is the shared pack path: Manager search "WanAnimatePreprocessV2", or git clone https://github.com/Code2Collapse/ComfyUI-WanAnimatePreprocessV2 into custom_nodes, pip install -r requirements.txt, restart. No extra models for the editor itself; the detection it runs internally reuses the ONNX models from the loader node.