Reference Image Selector (参考图选择器)

The hardest problem in character animation isn't generating the motion - it's keeping the face looking like the same person, and the standard trick is feeding the model reference images from the right angle. Reference Image Selector automates that: you give it a batch of reference shots (front, left profile, right profile, back), a mapping of which angle each shot represents, and a per-frame yaw sequence of which way the character is facing in the motion - and it returns the references sorted and filtered so the model always has the best view of the character for each part of the video.

It's the pack's answer to a real WanAnimate failure mode: when the character turns around and your only reference is a front shot, the face collapses. Feed it multi-angle references plus the yaw signal (from the pack's Estimate Yaw nodes), and it picks the coverage that matches.

What you set

• reference_images - the batch of reference shots, N images.
• angle_map - JSON saying what angle each image represents, e.g. [-90, -45, 0, 45, 90]. Length must equal the reference count, or the node just passes everything through.
• yaw_angles - the target yaw sequence (per frame). Not connected → all references pass through. This is what activates the filtering.
• select_references - true = filter and sort by angle; false = only sort, keep all references.
• allow_switch_main - true (default) lets it promote whichever reference covers the most frames to be the main (first) reference; false pins the first image in place.
• background_images - extra background shots inserted into the output order.

Outputs: selected_images (the sorted/filtered batch, original images, no fancy 1+4n repacking - that's the downstream node's job), raw_reference_images (the untouched originals, for feeding a context-window node that re-sorts internally), info (a debug string showing candidate indices and the main-ref decision), and reference_angle_map (the validated angle JSON, which you hand to the context window for dynamic per-segment selection).

How the choosing works

It computes the yaw range of the motion (handling the -180°/180° wraparound), keeps references inside that range plus one neighbor on each side, then promotes the reference covering the most frames to main position, sorts the auxiliaries by how far they are from the first frame's yaw, and appends a copy of the main reference at the end if it's the best fit for the first frame. If no references fall in range, it falls back to outputting everything.

Install

Part of user2318/ComfyUI-CustomNodeKit. ComfyUI Manager: search "CustomNodeKit". Or:

cd ComfyUI/custom_nodes
git clone https://github.com/user2318/ComfyUI-CustomNodeKit.git
cd ComfyUI-CustomNodeKit
pip install -r requirements.txt

then restart. No extra models - the yaw sequence comes from the pack's SDPoseEstimateYaw* nodes, which need a pose pipeline.

The gotcha

The angle_map is only as good as the thought you put into it. If your five reference images don't actually correspond to the angles you wrote, the node confidently sorts garbage into a confident order - read the info output on your first run to confirm the mapping parsed and the main reference is who you think it is. And remember yaw_angles unconnected means pass-through: if you're wondering why nothing gets filtered, that's almost always why. When it's wired into a context-window graph, use raw_reference_images + reference_angle_map for the prefix path and selected_images for the direct feed - mixing them up re-sorts already-sorted images and you'll get subtly wrong ordering.