Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-WanAnimatePreprocessV2

ComfyUI Extension: ComfyUI-WanAnimatePreprocessV2

Repo Name

ComfyUI-WanAnimatePreprocessV2

Author
code2collapse (Account age: 0 days)
Nodes
View all nodes(1)
Latest Updated
2026-11-12
Github Stars
0.02K

How to Install ComfyUI-WanAnimatePreprocessV2

Install this extension via the ComfyUI Manager by searching for ComfyUI-WanAnimatePreprocessV2
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-WanAnimatePreprocessV2 in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

ComfyUI-WanAnimatePreprocessV2 Description

ComfyUI-WanAnimatePreprocessV2 prepares images and video frames for Wan 2.2 Animate, extracting body, hand, face, iris and gaze data while producing stable face crops, skeleton images and debug previews.

ComfyUI-WanAnimatePreprocessV2 Introduction

ComfyUI-WanAnimatePreprocessV2 prepares images or video frames for Wan Video 2.2 Animate. It identifies a person’s body position, hand and facial landmarks, and eye movement, then turns those detections into data and images that an animation workflow can use.

For you, the practical benefit is steadier motion guidance. A pose detector can otherwise make a limb disappear for a frame, shift a face crop from side to side, or mistake image noise for eye movement. This extension offers controls to reduce those problems and a visual debug output so you can see what was detected before using it in a generation.

Its main outputs include:

  • Pose data describing body, hand, and face positions.
  • Face crops at 512 × 512 pixels, one for each frame.
  • Iris and gaze data describing detected pupil positions and eye direction.
  • Skeleton images from a separate drawing node, for workflows that need visual pose guidance.
  • Debug images that mark detections directly on your source frames.

The author designed the extension for Wan 2.2 Animate. Compatibility with other Wan versions is not guaranteed.

How ComfyUI-WanAnimatePreprocessV2 Works

Think of the extension as making an annotated motion guide from your footage. It does not generate the finished animation by itself; it prepares information for the animation workflow.

  1. Find the person. A YOLO detection model locates the person in each frame.
  2. Mark body and facial positions. A whole-body ViTPose model estimates 133 keypoints across the body, hands, and face. A keypoint is a location such as an elbow, fingertip, or mouth corner.
  3. Keep useful detections. Confidence thresholds determine which person detections and keypoints are reliable enough to use.
  4. Make the face framing consistent. The extension finds the face region, can smooth its movement between frames, and produces a 512 × 512 crop from the original image.
  5. Estimate eye movement. It looks inside the detected eye regions for pupil positions and derives gaze direction. Optional smoothing reduces small frame-to-frame jumps.
  6. Show you the result. A debug image overlays landmarks, eye markers, gaze arrows, and detection boxes on the frame. If your workflow needs a skeleton image, Draw ViT Pose (V2) renders one from the pose data.

Contrast enhancement and blur can help the detection models read difficult footage. They do not blur the face crops: those are taken from the original frames to preserve facial detail.

A typical node chain is:

ONNX Detection Model Loader (V2)
              │
              ▼
Pose and Face Detection (V2) ──► face crops / iris data / debug preview
              │
              ▼
     Optional pose editors
              │
              ▼
       Draw ViT Pose (V2) ──► skeleton images for Wan Animate

For a guide to which nodes you need and how to connect them, see NODE_GUIDE.md.

ComfyUI-WanAnimatePreprocessV2 Features

Person and whole-body pose detection

Pose and Face Detection (V2) accepts frames and produces body, hand, and face pose data. Two controls help balance missing detections against unwanted ones:

SettingWhat it changesPractical starting point
detection_thresholdHow confident the person detector must be before accepting a person.Start at 0.05. Lower it if the person disappears in some frames; raise it if background objects are being accepted.
pose_thresholdWhich detected keypoints are retained as visible.Start at 0.3. Lower it toward 0.1–0.2 if obscured limbs keep disappearing.

A low threshold preserves more uncertain information; a high threshold gives cleaner but potentially incomplete detections. For example, a dancer partly outside the frame may need more lenient settings than someone standing in a clear studio shot.

Help for noisy or difficult lighting

  • use_clahe improves local contrast for pose detection. Leave it on for low-light footage or when clothing and background have similar brightness.
  • use_blur_for_pose smooths fine texture and compression noise before person and pose detection. It is on by default.
  • blur_radius controls how large an area is smoothed; blur_sigma controls the blur’s spread. The defaults, 5 and 2.0, are a starting point for ordinary video. If a small person’s hands lose detail, try less blur; if grainy footage produces unstable detections, try more.

These adjustments are for analysis, not for softening your final face crops.

Stable face crops

A face crop is the square image passed along for expression-focused animation. Several controls affect how it behaves across a clip:

  • use_face_smoothing reduces side-to-side crop jitter while allowing the crop to follow movement. Its default is on.
  • face_smoothing_strength sets the amount of smoothing. Start at 0.6; use less for fast action and more for a nearly still talking head.
  • use_constant_face_box keeps the crop region at a fixed size instead of changing its zoom from frame to frame. This is on by default.
  • face_box_size_px controls the region selected before it is resized to 512 × 512. Start at 224. Increase it if the forehead or chin is cut off; decrease it if the crop contains too much background.

For example, increasing face_box_size_px from 224 to 320 shows more of a close-up subject’s head. Decreasing it makes a small face fill more of the crop, but enlarging a tiny source region can look blurry. A fixed-size box is useful when the subject stays at a similar distance from the camera; a variable-size box may suit footage where they move much closer or farther away.

Iris and gaze tracking

The detector estimates each pupil’s position from the eye image and produces gaze direction data. Its debug overlay shows magenta pupil markers and orange gaze arrows, making it easier to judge whether the result follows the footage.

  • use_iris_smoothing reduces small jumps between frames; it is on by default.
  • iris_smoothing_strength defaults to 0.4. Increase it if the pupil marker jitters while the subject looks steadily ahead. Lower it if quick eye movements are being softened too much.

Eye tracking depends on visible, correctly detected eyes. It is less reliable when the face is very small, obscured, or poorly lit.

Skeleton drawing and optional edits

Draw ViT Pose (V2) converts pose data into coloured skeleton images. You can set its output width and height to match the resolution you intend to generate.

  • pose_draw_threshold controls which joints appear in the image. If a joint is present in the detection but missing from the skeleton, try lowering this setting.
  • retarget_padding adds space around the figure. Increase it if limbs touch the edge.
  • body_stick_width and hand_stick_width change line thickness. -1 chooses an automatic width; 0 omits that part of the drawing.
  • draw_head includes or omits the head representation.

The Face/Pose Delta Editor is an optional node between detection and drawing. It lets you move selected facial landmarks—such as an eyebrow, eye corner, or mouth corner—on chosen frames. Edits are stored relative to the face so they can follow its movement through the clip. See the face landmark editing guide.

For every node’s inputs, defaults, valid ranges, outputs, and ComfyUI tooltip descriptions, use NODE_REFERENCE.md.

Outputs you can inspect

OutputWhat it is useful for
pose_dataPose information for drawing or downstream animation nodes.
face_imagesOne 512 × 512 face crop per frame. Preview these to check framing.
key_frame_body_pointsKey body points from the first frame, provided as text data.
bboxesThe person detection box from the first frame.
face_bboxesFace crop regions across the frames.
iris_dataPer-frame pupil positions, confidence values, and gaze vectors.
debug_imageAn annotated view of the detections; connect it to a preview to diagnose problems.

ComfyUI-WanAnimatePreprocessV2 Models

The main detection chain uses one person detector and one whole-body pose estimator, selected in ONNX Detection Model Loader (V2). The loader can run them through an NVIDIA GPU using CUDAExecutionProvider, or through the CPU using CPUExecutionProvider; CPU processing is substantially slower.

ModelRoleWhen to choose it
YOLOv10m ONNXFinds the person in each frame.The recommended person detector in the original documentation.
ViTPose-Large whole-body ONNXEstimates body, hand, and face keypoints.Choose when faster processing matters. The listed model size is approximately 350 MB.
ViTPose-Huge whole-body ONNXEstimates the same kinds of keypoints with a larger model.Try when you want the more accurate option and can accommodate a model of approximately 1 GB.

Use a whole-body ViTPose model: a body-only model will not provide the facial and hand landmarks this workflow expects. ViTPose-Huge is split into a .onnx file and a companion .bin data file; both must be together for it to load.

The wider node pack also includes features that can use other models, such as MediaPipe face landmarks, L2CS gaze weights, MiDaS depth, NLF 3D pose refinement, and optional face super-resolution models. These are not all required for the basic YOLO → ViTPose → Draw ViT Pose chain. If you use a feature that needs one of them, consult its node reference. Some nodes offer an allow_download switch, which is off by default; with it off, a missing optional model is reported rather than fetched.

What's New with ComfyUI-WanAnimatePreprocessV2

V2 compared with the original preprocessing approach

V2 adds contrast enhancement and detection-only blur to improve pose stability, along with a constant-size face box and frame-to-frame smoothing to reduce crop jitter. It also adds image-based iris and gaze estimation, iris smoothing, and a debug image that lets you inspect the results instead of guessing why an animation input looks wrong.

Dated changes noted by the author

  • November 4, 2026 — Retargeting and FLUX-related fixes: The use_flux setting is passed through, reference imagery reaches FLUX correctly, and edited results are re-detected. Failures in reference detection, FLUX, or retargeting now stop with a reason instead of silently using an unretargeted pose. When hires_images is supplied, it must contain the same number of frames as images. FLUX requires its separate model weights and a GPU; the preprocessing node does not run FLUX by itself.
  • November 5, 2026 — Controls restored: The face super-resolution model selector lists available upscale models while remaining compatible with older saved workflow values. Controls for jitterless, auto, and action crop modes are visible again.
  • November 6, 2026 — Optional model downloads made explicit: Nodes that use certain optional models expose allow_download, off by default. If an optional model is absent, the log or error identifies the missing file and its expected location rather than downloading it without permission.
  • November 12, 2026 — More resilient downloads: MediaPipe face landmarker and NLF model downloads can resume after an interrupted transfer. Temporary network failures are retried, and an incomplete file is not presented as a finished model.

The original documentation also records fixes without a separate version number. These include correctly applying NLF pose refinement when there is no retarget, correcting facial landmark edits, drawing iris data in Iris ControlNet, measuring saccades from unsmoothed gaze, and keeping an unretargeted skeleton aligned when source and target image sizes differ. For artists, these fixes make previews and editing controls more dependable.

Troubleshooting ComfyUI-WanAnimatePreprocessV2

The quickest first step is to preview both debug_image and face_images. The debug image shows where the extension thinks the person, facial landmarks, and pupils are; the face images show what the animation workflow will receive as face crops.

The person disappears in some frames

  1. Check the debug image to see whether the body detection box disappears.
  2. Lower detection_threshold from 0.05 toward 0.02 or 0.01.
  3. Keep detection blur on; try CLAHE if lighting is difficult.
  4. If the person is tiny or mostly outside the frame, try footage with a larger, more visible subject. Lowering the threshold cannot recover detail that is not present.

Limbs or hands vanish from the skeleton

  1. Lower pose_threshold to around 0.15–0.2 to retain less-certain keypoints.
  2. Lower Draw ViT Pose (V2)’s separate pose_draw_threshold to around 0.05–0.1 if points are detected but not drawn.
  3. Check whether hands were deliberately hidden with hand_stick_width: 0.
  4. Inspect the source frame for occlusion or motion blur.

The face crop jitters or cuts off the head

  1. Turn on use_face_smoothing and use_constant_face_box.
  2. For jitter, begin with face_smoothing_strength: 0.6; increase it if a mostly stationary face still jumps.
  3. For a clipped forehead or chin, increase face_box_size_px in steps, such as 224 → 256 → 320.
  4. Preview face_images again. If the subject moves quickly and the crop seems slow to follow, reduce the smoothing strength.

The iris marker or gaze arrow looks wrong

  1. In debug_image, check the green eye landmarks first. If they do not outline the eyes, pupil detection has a poor starting point.
  2. Check whether the eyes are large and clear enough in the source image. Distant faces provide little pupil detail.
  3. Keep CLAHE on for difficult lighting.
  4. If the marker is in roughly the right place but jitters, turn on iris smoothing or increase its strength slightly. Smoothing will not fix a consistently misplaced marker.

A model, CUDA, or retargeting error stops the workflow

  1. Read the complete ComfyUI error or log: missing optional models and retargeting failures are intended to report their reason.
  2. Check that the loader selects a whole-body ViTPose model and a YOLO ONNX model. For ViTPose-Huge, check that its companion .bin file is alongside the .onnx file.
  3. If GPU execution fails, select CPUExecutionProvider to test whether the workflow runs on CPU. CPU processing will be slower.
  4. If using retarget_image, resolve the reported reference, FLUX, or retargeting problem rather than assuming the workflow continued with a retargeted pose.
  5. If using hires_images, provide the same number of frames as in images.

Frequently asked questions

Do I need Draw ViT Pose (V2)?
Use it when your Wan Animate workflow needs skeleton images. The model loader and detection node produce the underlying pose and face outputs; the drawing node turns pose data into images.

What is the difference between pose_threshold and pose_draw_threshold?
pose_threshold filters keypoint confidence during detection. pose_draw_threshold controls which available keypoints appear in the rendered skeleton. If you filtered a keypoint out during detection, lowering only the drawing threshold will not restore it.

Why are the face crops 512 × 512 even when I change face_box_size_px?
face_box_size_px changes how much of the source frame is selected—effectively the zoom. The selected region is then resized to the fixed 512 × 512 output.

Can I use a single image instead of a video?
Yes. Frame-to-frame face and iris smoothing offers no benefit when there is only one frame.

Which width and height should I choose?
Match the resolution you plan to use for generation, especially for skeleton images. The original documentation gives 832 × 480, 1280 × 720, and 512 × 512 as examples.

Will the extension automatically fetch every model it needs?
No. For optional features with allow_download, downloads are off by default. A missing model is reported so you can decide whether to enable its download.

Learn More about ComfyUI-WanAnimatePreprocessV2

ComfyUI-WanAnimatePreprocessV2 Related Nodes

RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

ComfyUI-WanAnimatePreprocessV2 detailed guide | ComfyUI