Wan Iris ControlNet Conditioning (V2)

WanIrisControlNetV2 turns gaze data into a picture - a ControlNet conditioning image that encodes eye region masks, iris discs, gaze arrows and a gaze-target heatmap. The idea is that if you have (or train) a ControlNet or T2I-Adapter conditioned on eye/gaze control, this node gives it the input it needs, in the same IMAGE format as every other conditioning map in ComfyUI.

Be clear about what this is: it's an experimental tool for a niche that barely exists yet. The node itself is a renderer - it takes iris_data JSON and draws. There's no model inside, and no guarantee your favorite ControlNet was trained on this exact visual language. If you're not actively working on eye-gaze control for a specific model, this is the most skippable node in the pack.

How it works

You feed it the iris_data_json that PoseAndFaceDetectionV2 emits (or any JSON matching its schema: per-frame pupil xy, eye bboxes, gaze yaw/pitch, iris confidence). For each frame it renders, in order:

• Eye region masks - filled ellipses placed anatomically (estimated from the face bbox if no eye bboxes are present in the JSON).
• Iris discs - anti-aliased gradient discs at the exact pupil pixel coordinates.
• Gaze arrows - length proportional to gaze magnitude (arrow_scale_px pixels per radian).
• Gaze-target heatmap - a Gaussian centred where the subject is looking (heatmap_sigma_px controls its spread).

Which of those appear is set by render_style: full (everything), iris_only, heatmap_only, or mask_only. There's a background choice (black / white / neutral_grey), and image_width/image_height define the canvas. If you wire a reference_image, it overlays the render onto that image at overlay_alpha - handy for checking alignment against the actual frame.

Outputs: control_image (the conditioning image), iris_mask (a proper MASK, which is more directly useful than you might think - you could use it for eye-region inpainting or as an attention mask), and an info string with stats.

The inputs that matter

Honestly, only three: iris_data_json (the input), render_style (what you want drawn), and background (black is the safe default - most ControlNets were trained on dark/empty backgrounds and a white canvas is a wildly different input distribution). The rest are fine at defaults. iris_radius_px (6) and arrow_scale_px (80) tune marker size if the render looks cluttered.

Where it fits

The ControlNet context: conditioning images steer generation, but the preprocessor and the trained model must agree on the visual language. A pose skeleton drawn one way won't drive a pose ControlNet trained on another. That's the honest warning for this node - there is no mainstream gaze ControlNet for Wan or Flux yet, so you're either training your own adapter or you're ahead of the ecosystem. What the node is genuinely good at regardless is visualizing gaze data: as a debugging image for the pack's own iris pipeline, it's excellent - you can see at a glance whether the iris discs land on the pupils and whether the arrows point where the subject actually looks.

Install is the shared pack path: ComfyUI Manager search "WanAnimatePreprocessV2", or git clone https://github.com/Code2Collapse/ComfyUI-WanAnimatePreprocessV2 + pip install -r requirements.txt + restart. No model downloads - it's a pure renderer over JSON.