当前版本：1.8.0 — 新增 WanAnimate2ToVideoCustom 节点（Wan2.1-I2V 底座 + 二代 pose 分支 K/V 注入，支持多参考图）；WanUni3CApply 重构为 render_video 输入（内置 VAE 编码 + 参考帧偏移，修复 render_latent 归一化偏差问题）；移除已退役的 WanSCAILSparseAttention 节点（长序列下掩码为 O(S²) 稠密矩阵，导致内存爆掉，实测在 SCAIL 上无收益）；另有一个实验性 / 测试性节点 Context Window Anchor（窗口首帧锚定）——其有效性与副作用尚未充分验证，仅供测试参考；不接入工作流时既有行为完全不变（详见 Context Window Anchor (窗口首帧锚定)）。

本版另修复了 SDPose 偏航角在短片段素材下的必崩问题、BatchImageReplace 的 repeat_end 填充逻辑（3 张替换 4 张由 0,2,2,2 修正为 0,1,2,2），并对智能视频裁剪、交互式批量裁剪等节点做了内存/性能优化（后者预览缓存从 2600 帧约 12.5GB 降到约 48MB）。升级前请先阅读文末的更新日志（其中含不兼容变更说明）。

安装

将本仓库克隆到 ComfyUI 的 custom_nodes 目录下：

cd ComfyUI/custom_nodes
git clone https://github.com/user2318/ComfyUI-CustomNodeKit.git

安装 Python 依赖：

cd ComfyUI-CustomNodeKit
pip install -r requirements.txt

重启 ComfyUI。

注意：请确保你的 ComfyUI 环境已安装 PyTorch 与相关核心依赖。

节点列表

WanLoop 视频生成

| 节点名 | 类别 | 说明 | |--------|------|------| | WanAnimateToVideoCustom | WanLoop/整合节点 | WanAnimate 视频生成核心节点，支持 pose/face 控制、尾帧分段掩码、中性灰混合、上下文模式、prev_latent 潜变量接续等完整参数 | | WanAnimate2ToVideoCustom | WanLoop/整合节点 | WanAnimate2（官方二代架构）视频生成核心节点。保留一代多参考图（逐帧独立编码）与 fix/legacy/vanilla 掩码处理、中性灰混合、yaw 角度输出；叠加官方二代 pose_strength / pose_start_percent / pose_end_percent / reference_image_strength / positive_pose / clip_vision_output_pose。已适配二代 pose 分支帧数校验（多参考前补 latent 帧） | | 单帧独立 VAE 编码 | WanLoop/工具节点 | 将 N 张图片逐帧独立 VAE 编码后在时间维度拼接为 latent，为 ComfyUI-EverAnimate 项目提供锚点 latent | | WanUni3CLoader | WanVideo/Control | 加载 Uni3C ControlNet 模型，支持 fp32/bf16/fp16 精度选择（可选） | | WanUni3CApply | WanVideo/Control | 在 KSampler 中注入 Uni3C 运镜控制，支持 strength/start_percent/end_percent 等参数（可选） |

SCAIL/SCAIL-2 多参考图生成

| 节点名 | 类别 | 说明 | |--------|------|------| | Wan SCAIL To Video (Multi Ref) | model/conditioning/video_models | SCAIL/SCAIL-2 多参考图视频生成 conditioning 节点。支持多张参考图自动编码、SCAIL-2 多身份 colored mask 注入、pose 视频引导、运动接续（prev_latent）等 | | Create SCAIL-2 Colored Mask (Multi Ref) | conditioning/video_models/scail | 渲染 SAM3 追踪数据为 SCAIL-2 使用的 colored mask。支持参考图和驱动视频的共享调色板排序（left_to_right/area），确保多人物场景下同一身份颜色一致 | | Wan SCAIL-2 Phase Sampler | sampling | 独立两阶段采样节点。完整复刻 SCAIL2LoopSampler 的两阶段采样核心逻辑。用像素帧（IMAGE）作为锚定输入，内部完成 VAE 编码、锚定帧回写、noise_mask 管理 | | CLIP Vision Multi-Ref Switch | conditioning/video_models/scail | 多参考图 CLIP 特征合并节点。将批次中 N 张图的 CLIP Vision 特征拼接到 token 维度，使所有参考图都参与 conditioning | | Auto Color Drift Correction V4.3 | CustomNodes/Video | 自对齐色彩漂移校正节点 V4.3。两遍校正：① 第一遍全局偏移——多帧均值检测段间跳变后统一校正所有新帧；② 第二遍残余微调——在钳制上限内逐帧向基准靠拢。支持 standard/auto/off 三种模式，max_offset 控制单通道偏移上限 |

SDPose 姿态系统

| 节点名 | 类别 | 说明 | |--------|------|------| | Draw SDPose Keypoints (V2) | SDPose | 将姿态关键点数据渲染为可视化图像，支持全身骨骼、手部、面部、脚部的分层绘制，并根据偏航角自动调整骨骼粗细与遮挡顺序。新增 foot_mode 参数支持 dots（圆点）和 line（踝→大趾线条）两种脚部绘制模式 | | Save SDPose Keypoints as JSON | SDPose | 保存姿态关键点数据为 JSON 文件，支持覆盖模式与自动递增编号 | | Load SDPose JSON | SDPose | 加载 JSON 姿态文件，支持按目标帧率自动抽帧/补帧（线性插值或复制），支持空帧自动修复 | | Slice SDPose Keypoints | SDPose | 对姿态序列进行时间切片（按起始帧与帧数截取） | | Concat SDPose Keypoints | SDPose | 将两段姿态序列前后拼接 | | Estimate Yaw (Simple) | SDPose | 简化版偏航角估计，从姿态关键点推算人物朝向角度（核心参数：置信度阈值、是否解缠、肩部权重） | | Estimate Yaw (Advanced) | SDPose | 完整版偏航角估计，可调节所有底层参数（平滑窗口、EMA alpha、角度限制、侧向校准等），并输出详细调试表格 | | Resize SDPose Keypoints | SDPose | 缩放姿态关键点坐标并更新画布尺寸，支持保持宽高比、智能裁剪（基于关键点包围盒） | | Resample SDPose Keypoints | SDPose | 对姿态关键点序列进行帧率重采样（抽帧/补帧），独立于 JSON 载入逻辑，支持空帧自动修复 | | Load GroundingDINO Model | SDPose/GD | 加载 GroundingDINO 模型（全局缓存，常驻 GPU），为官方 SDPose 提供 bbox 检测基础 | | GD BBox Detect | SDPose/GD | GroundingDINO 一站式检测：文本检测 → 多模式筛选 → 输出 bbox 给官方 SDPoseOODProcessor | | Reference Image Selector | CustomNodes/SDPose | 参考图选择器：根据偏航角范围自动筛选和排序参考图批次 |

视频工具

| 节点名 | 类别 | 说明 | |--------|------|------| | VideoFrameCounter | video | 获取输入视频/图像序列的帧数统计信息与帧率 | | ImageSequenceToVideo | video | 使用 ffmpeg 将图片序列合成为视频文件，支持 CRF、音频合成、帧偏移等参数 | | SmartVideoCrop | video | 基于 SAM3 追踪数据的智能视频裁剪：按人物质心做水平跟随裁剪（EMA 平滑 + 切镜检测），固定保留全高后按输出宽高比缩放。支持多 ID 追踪、空 mask 回退策略（保持最后位置/回到中心）、可选第二路图像同步裁剪 | | VideoGridCompose | video | 把 1~4 路视频/图片按布局拼成网格（水平排列 / 垂直排列 / 田字格2×2 / 左一右N / 上一+下N），支持自适应填满或保持比例、时长对齐（超长截断、不足冻结补帧）、音频来源选择；全程 ffmpeg 流式处理，不占内存 |

交互式工具

| 节点名 | 类别 | 说明 | |--------|------|------| | Interactive Batch Crop | Interactive | 交互式批量裁剪节点，配合前端 JS 实现图形化区域选择与批量处理 |

通用工具

| 节点名 | 类别 | 说明 | |--------|------|------| | Path Collector | Utility | 从指定目录收集文件路径 | | Index Selector | Utility | 根据索引从列表中选取元素，支持 last_folder 输出 | | Path Validator | Utility | 验证文件路径是否存在 | | Integer Setting (整数设置) | CustomNodes/Utils | 将整数对齐到目标步长（start + step×n），支持负整数 |

图像批次工具

| 节点名 | 类别 | 说明 | |--------|------|------| | Folder Image Loader | image | 从文件夹按文件名升序载入图片批次，支持跳过、数量限制与尺寸同步 | | Image Batch Concat | image | 将两个图像批次拼接，任意一路无输入时透传另一路 | | Image Batch Resize | image | 缩放图像批次到指定宽高，可选按方向裁剪保持宽高比 | | Batch Image Replace | image | 批量图像替换节点。在图像批次中按起始索引和数量替换指定位置的图像。支持溢出模式和下溢模式，替换源可选连接 | | Batch Frame Replicate | image | 图像批次指定帧复制节点。在图像批次中复制指定图像并插入到其后。支持负索引和双路独立输入。用于延长首/尾帧时长、关键帧停留效果 | | MaskCompositeRef | image | 遮罩批次合成节点 — 用于 WanSCAILToVideo 的 reference_image 预处理。支持替换模式和动作迁移模式，自动剔除全黑遮罩帧、背景合成 |

上下文工具

| 节点名 | 类别 | 说明 | |--------|------|------| | Custom Context Windows (Manual) | context | 通用上下文窗口调度节点。将长序列拆分为滑动窗口逐段处理，支持参考帧前缀、噪声混洗、多种调度策略（均匀/静态/循环/批处理）与融合模式（金字塔/线性叠加/相对加权） | | Wan SCAIL-2 Context Windows | context | SCAIL-2 专用上下文窗口节点。自动处理 SCAIL-2 的特殊 conditioning 字段（ref_mask_28ch、driving_mask_28ch、pose_video_latent），无需前缀参考帧。与 WanSCAILToVideoMultiRef 配合使用 | | Context Window Anchor (窗口首帧锚定) | context | 【实验性·测试性】上下文窗口跨窗口对齐锚定节点（有效性与副作用尚未充分验证，仅供测试参考）。把每个窗口的驱动视频 latent 首帧（animate2: pose_latents；SCAIL-2: pose_latents + 驱动遮罩 sam_latents）替换为当前片段窗口 0 的首帧，让各窗口以同一基准对齐，缓解窗口融合处的比例/位置跳变。必须接在上下文窗口节点之后 |

复杂节点详解

WanAnimate2ToVideoCustom

基于官方 WanAnimate2ToVideo（Wan2.1-I2V 底座 + pose 分支 K/V 注入）与一代 WanAnimateToVideoCustom 融合的二代 animate 节点。保留一代的多参考图（逐帧独立编码，兼容 EverAnimate LoRA；原模式 1+4n 批量编码在 animate2 上表现不佳已移除）、fix/legacy/vanilla 掩码处理、黑帧检测+过渡、尾帧分段掩码、中性灰混合、yaw_angles→latent_yaw_angles 输出；叠加官方二代的 pose_strength / pose_start_percent / pose_end_percent（pose 时间窗口，窗口外跳过 pose 分支可提速）/ reference_image_strength / positive_pose / clip_vision_output_pose。pose 分支按二代模型 pose_latents.shape[2] == f_gen - 1 的帧数校验要求前补 latent 帧，多参考图场景可直接使用。已去掉二代架构不支持的 face/background/character_mask/prev_latent。

WanAnimateToVideoCustom

WanAnimate 视频生成的核心整合节点，将参考图、姿视频、面部视频、背景视频、角色遮罩等多路输入统一编码后拼接为合适的 conditioning 和 latent 格式，直接送入 KSampler 即可生成视频。

参数说明

必选参数：

| 参数 | 类型 | 说明 | |------|------|------| | positive | CONDITIONING | 正向提示词条件 | | negative | CONDITIONING | 负向提示词条件 | | vae | VAE | 用于编码图像为 latent 的 VAE 模型 | | width / height | INT | 输出分辨率（默认 832×480，步长 16） | | length | INT | 总输出帧数（像素帧，步长 4） | | batch_size | INT | 批大小（通常为 1） | | continue_motion_max_frames | INT | 运动接续的最大参考帧数（从上一段视频尾部取帧） | | video_frame_offset | INT | 视频帧偏移量（多段拼接时递增） | | transition_width | INT | fix 模式下黑帧过渡宽度（0-128，步长 4） | | mode | 枚举 | vanilla=官方行为 / legacy=旧版尾帧分段掩码模式 / fix=硬替换中性灰+过渡扩散模式 | | tail_frame_count | INT | legacy 模式下尾帧掩码覆盖的帧数 | | tail_start_strength | FLOAT | legacy 模式下尾帧掩码起始强度 | | tail_end_strength | FLOAT | legacy 模式下尾帧掩码结束强度 |

可选参数：

| 参数 | 类型 | 说明 | |------|------|------| | clip_vision_output | CLIP_VISION_OUTPUT | 用于注入 CLIP Vision 特征 | | reference_image | IMAGE | 参考图像批次（首帧×1 + 其余各×4 拼接） | | face_video | IMAGE | 面部视频输入（自动缩放到 512×512，归一化到 [-1, 1]） | | pose_video | IMAGE | 姿态视频输入（编码为 pose_video_latent） | | continue_motion | IMAGE | 上一段视频的尾部帧，用于运动接续 | | background_video | IMAGE | 背景视频，覆盖参考图批次中运动接续帧之后的区域 | | character_mask | MASK | 角色遮罩，在运动接续帧之后替换 concat_mask | | prev_latent | LATENT | 前一段输出的完整 latent（concat_latent），接入后忽略 continue_motion，直接用前一段潜变量替换中性灰帧编码后的 latent | | face_strength | FLOAT | 面部视频强度系数（0-1，默认 1.0） | | mid_frame | INT | legacy 模式下中间帧锚点位置（-1=禁用） | | mid_strength | FLOAT | legacy 模式下中间帧锚点强度 | | neutral_mix_min / neutral_mix_max | FLOAT | legacy 模式下中性灰混合范围（掩码→中性灰的混合比例） |

输出

| 输出 | 类型 | 说明 | |------|------|------| | positive | CONDITIONING | 已注入 concat_latent_image、concat_mask 等条件的正向条件 | | negative | CONDITIONING | 已注入对应条件的负向条件 | | latent | LATENT | 空的 latent 占位（samples 形状已匹配总帧数） | | trim_latent | INT | 需要跳过的首部 latent 帧数（用于后续 VAE Decode 时裁剪） | | trim_image | INT | 需要跳过的首部像素帧数 | | video_frame_offset | INT | 累积帧偏移（用于多段拼接时传递给下一段） | | concat_latent | LATENT | 拼接后的完整 latent 图像（用于解码输出） |

典型工作流

[上一段视频尾部帧] → continue_motion ─┐
[参考图批次]        → reference_image ─┤
[姿态视频]          → pose_video ──────┤
[面部视频]          → face_video ──────┤
[正向提示词]        → positive ────────┤
[负向提示词]        → negative ────────┤
                                        ↓
                               WanAnimateToVideoCustom
                                        ↓
                     positive / negative / latent → [KSampler]
                                                        ↓
                                                [VAE Decode]
                                                        ↓
                                                   输出视频

Custom Context Windows (Manual)

用于 WAN 类视频生成模型的上下文窗口调度节点。当视频帧数超过模型单次处理上限时，将长序列拆分为多个滑动窗口逐段处理，再通过融合策略合并结果。此节点对模型进行封装，配合后续的 KSampler 使用即可。

参数说明

| 参数 | 类型 | 说明 | |------|------|------| | model | MODEL | 待封装的模型 | | context_length | INT | 上下文窗口长度（像素帧数，自动转换为 latent 帧数，每 4 帧→1） | | context_overlap | INT | 窗口重叠长度（像素帧数，自动转换） | | context_schedule | 枚举 | 窗口调度策略（见下文） | | context_stride | INT | 均匀调度策略中的步长指数上限（1-10） | | closed_loop | BOOLEAN | 是否闭合窗口循环（仅循环调度有效） | | fuse_method | 枚举 | 窗口融合方式（见下文） | | freenoise | BOOLEAN | 是否启用 FreeNoise 噪声混洗（改善窗口间连续性） | | prefix_latent_num | INT | 前缀参考帧的 latent 数量。接参考图选择器 raw_reference_images 的图片数量即可（每张图片编码为1个 latent）。这些帧会作为稳定参考拼接到每个窗口前 | | split_conds_to_windows | BOOLEAN | 是否将多个 conditioning 按区域索引分配给各窗口 |

调度策略 (context_schedule)

| 策略 | 说明 | 适用场景 | |------|------|----------| | looped_uniform | 均匀循环调度：窗口在时间轴上循环分布，步长按指数递增 | 需要多次迭代覆盖的场景 | | standard_uniform | 标准均匀调度：与 looped 类似但不循环，去除重复窗口 | 大多数通用场景的首选 | | standard_static | 标准静态调度：固定步长的滑动窗口（步长 = context_length - context_overlap） | 需要简单分段处理的长视频 | | batched | 批处理调度：按 context_length 直接切分，无重叠 | 不需要过渡融合的快速批处理 |

融合方式 (fuse_method)

| 方式 | 说明 | 适用场景 | |------|------|----------| | pyramid | 金字塔权重：窗口中心权重最大，向两侧递减 | 通用场景，过渡自然 | | flat | 平坦权重：所有帧权重相同 | 简单平均融合 | | overlap-linear | 线性重叠：重叠区域线性渐变（首帧 1→0，末帧 0→1） | 需要明确边界过渡的场景 | | relative | 相对加权运行平均：基于窗口中心距离的动态加权，平滑分批采样累积 | 需要精细权重控制的高级场景 |

使用要点

帧数转换：context_length、context_overlap 均以像素帧为单位输入，节点内部自动转换为 latent 帧（每 4 像素帧 → 1 latent 帧）。
前缀参考帧：设置 prefix_latent_num > 0 后，该数量的参考图 latent 会被追加到每个窗口开头作为稳定参考，适合需要全局上下文信息的生成任务。
freenoise：启用后会混洗噪声以改善窗口间的纹理连续性，建议在总帧数较长且重叠较小时开启。

典型工作流

[加载模型] → model ──┐
                      ↓
           Custom Context Windows (Manual)
                      ↓
               model (已封装) → [KSampler] → [VAE Decode] → 输出

Context Window Anchor (窗口首帧锚定)

⚠️ 实验性 / 测试性节点（未充分验证）：本节点保留在仓库中仅供测试与参考。其有效性（能否真正缓解窗口接缝处的比例/位置跳变）与副作用（对画质、人物一致性、动作自然度、采样稳定性等的影响）均未经过充分测试与验证，也不保证在不同模型 / LoRA / 参数组合下都安全无害。请务必先在本地用同一 seed 做“加节点 vs 不加节点”的对比（见下方实验建议）再决定是否长期使用，不建议在正式生产工作流中依赖它。该节点未接入工作流时，其代码路径不参与执行，既有节点行为完全不变。

【实验性】要解决的问题：animate2 / SCAIL-2 的「参考图 ↔ 驱动视频」身体比例与空间位置对齐由模型内部逐窗口推导。上下文窗口采样时，每个窗口的驱动视频 latent 只包含本窗口对应的帧，窗口首帧姿态各不相同 → 每个窗口的对齐基准不同 → 窗口融合后出现比例/位置跳变（接缝错位）。

本节点做什么：把窗口 w>0 的驱动视频 latent 前 K 个 latent 帧，替换为当前片段窗口 0（即本段驱动视频首帧）的同名张量前 K 帧，让所有窗口以同一基准对齐；SCAIL-2 的驱动遮罩（sam_latents）同时锚定。

参数说明

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | model | MODEL | — | 已接入上下文窗口节点的模型（必填）：Custom Context Windows (Manual) 或 Wan SCAIL-2 Context Windows 的 model 输出 | | enabled | BOOLEAN | true | 是否启用；关闭时模型直接透传 | | anchor_targets | COMBO | 驱动视频 + 驱动遮罩 (auto) | 要锚定的目标（下拉选择）：驱动视频 + 驱动遮罩 (auto) / 仅驱动视频 (pose only) / 仅驱动遮罩 (mask only)。驱动视频 = pose 分支（animate2 与 SCAIL-2 都是 pose_latents）；驱动遮罩 = SCAIL-2 的 driving_mask（sam_latents）| | anchor_frames | INT | 1 | 每个窗口锚定前 K 个 latent 帧；0=关闭 | | anchor_offset | INT | -1（自动） | 切片内起始帧偏移。-1=自动：跳过切片头部的"前缀派生帧"（max(0, 前缀帧数-1)），从窗口自身的第一个驱动帧开始锚定；也可填 0/1/… 手动指定做实验 | | blend | FLOAT | 1.0 | 1.0=完全替换为窗口 0 的首帧；<1.0 与窗口自身首帧线性混合（用于缓解首帧姿态回跳造成的抖动） | | apply_to_negative | BOOLEAN | true | CFG 下是否同时锚定 negative（两边传入同一份驱动条件，锚定结果一致，不会造成 CFG 偏斜） | | log_debug | BOOLEAN | false | 打印每个窗口命中的键、shape 与首帧数值，用于确认锚定是否生效 | | anchor_steps | INT | -1（全程） | 只在前 N 个采样步锚定：-1=全程（默认）、0=不锚定、N>0=前 N 步。时间门控：每步都给真实信号（要么锚、要么本段），与 blend（幅度混合，会喂合成中间态）是两条不同的路 | | global_pose_frames | IMAGE | 不接 | 【可选】驱动/pose 视频开头的若干像素帧（给多少用多少）：编码成 latent 后替换锚定带的前 M 帧（M=((T-1)//4)+1）。给多了=完全替换、给少了=部分替换；不接=纯本段锚定 | | global_mask_frames | IMAGE | 不接 | 【可选，SCAIL-2】彩色遮罩视频开头的若干像素帧，按 _extract_mask_to_28ch 编码后替换遮罩锚的前 M 帧（animate2 用不到） | | vae | VAE | 不接 | 【可选】仅用于把 global_pose_frames 编码成 latent（接同一个 Wan VAE）；遮罩池不需要 VAE |

生效机制与边界

生效层级：conditioning 层 —— 在每个窗口的 cond 重切分之后做后处理，因此每个采样步都会生效；不触碰 x/latent 层，与窗口融合权重、overlap、FreeNoise 互不干扰。
锚点位置：上下文节点会把前缀索引（chunk 的 0..P-1 帧）拼到每个窗口的 index_list 前面，而驱动视频/驱动遮罩的切片用的正是 index_list → 每个窗口的切片头部都会多出 P-1 帧"前缀派生帧"（多参考图时是零填充帧；单参考图时是 chunk 开头几帧的驱动内容），且它们对所有窗口完全相同 → 锚在这些帧上时，替换前后的数值相同（即不改变数据），故 anchor_offset 默认自动跳过它们：
- 前缀 P = 0 或 1 → 偏移 0（与最早版本行为相同）；
- 前缀 P = 6（6 张参考图）→ 偏移 5（锚点落在窗口 body 的第一个驱动帧）。
不跨 chunk：锚定源始终是"当前这一段"的窗口 0，每段各自锚定（快照在每个采样步的窗口 0 处刷新）。
只改数值、不改长度：animate2 的 pose_latents.shape[2] == f_gen - 1 帧数校验不受影响。
只处理按窗口切分过的张量：仅作用于 model_conds 内的目标键；长度超过窗口帧数的整段条件会被自动跳过（例如 SCAIL 的 ref_mask_latents 这类"参考帧 + 窗口帧"张量默认不在锚定范围内）。
实现方式：对 model_options["context_handler"] 上的 handler 实例做浅拷贝后包装其 get_resized_cond / execute，不修改 handler 的类，也不改动上下文窗口节点的任何代码。

典型接线

[加载模型] → Custom Context Windows (Manual) → Context Window Anchor → [KSampler] → [VAE Decode] → 输出
[加载模型] → Wan SCAIL-2 Context Windows    → Context Window Anchor → [KSampler] → [VAE Decode] → 输出

未接在上下文窗口节点之后时，节点会打印警告并原样透传模型（不会中断工作流）。

混合锚定（全局头部 + 本段锚，可选）

默认锚定源是「本段窗口 0 的首帧」。接上 global_pose_frames（SCAIL-2 再加 global_mask_frames）后，锚定带的前 M 帧改用"全局素材"：

hybrid = [全局池的前 M 帧] + [本段窗口0 锚的其余 K−M 帧]
M = ((T−1)//4)+1        # T = 你接入的像素帧数

给多少用多少（没有"取多少帧"参数）：给的帧数超出锚定带 → 只取前 K 帧（完全替换）；不足 → 部分替换；不接 → 纯本段锚定（与之前行为完全一致）；
分辨率自动对齐：按采样期 latent 的空间尺寸反推（latent×8），你不需要接 width/height；
遮罩按硬替换处理：sam_latents 承载空间/身份信息（8×8 块的颜色覆盖率 × 颜色通道），本版本对其强制硬替换（即使 blend<1 也按 1.0 处理）——线性混合两帧图案会得到与任一帧都不对应的边界（实现选择，后续可再评估）；
窗口 0 不参与替换（它是锚定源），因此本段第一个窗口的驱动条件保持不变；
本节点的输出不变（仍是单个 model），三个新输入都是可选插口，接在参数区末尾，旧工作流的参数不会错位。

接线示例（用你工作流里已有的节点即可）：

[完整驱动/pose 视频] -- ImageFromBatch(start=0, length=5) --> global_pose_frames
[完整彩色遮罩视频]   -- ImageFromBatch(start=0, length=5) --> global_mask_frames   (SCAIL-2)
[同一个 Wan VAE] ----------------------------------------> vae

⚠️ 这两个"全局素材"要取自整段视频（循环之前），不要取循环里已被裁成"当前片段"的视频，否则"开头几帧"会变成本段开头，等于没换。

实验建议

方法提醒：以下对比建议同 seed、同 chunk、每次只改一个变量；单组结果容易受采样随机性影响，建议同组重复跑 2 次以上再比较。

先开 log_debug=true 跑一次，确认日志里既有"记录锚定源窗口0"也有后续窗口的"锚定"行（并对比首帧数值是否不同）。
同 seed、同参数做"加节点 vs 不加节点"对比，重点看窗口接缝处的人物比例与位置。
若出现首帧姿态回跳引起的抖动：先保持 anchor_frames=1，再用 blend（如 0.5~0.8）软化。
SCAIL-2 可把 anchor_targets 依次切到"仅驱动视频 / 仅驱动遮罩 / 两者都锚"，以定位主要影响因素。
该功能不解决跨段（chunk 之间）的对齐漂移，仅作用于同一段内的各窗口。
幅度混合 vs 时间门控：两者是不同取舍——
- blend<1：每一步都喂"锚 ×α + 本段 ×(1−α)"的合成条件（可能对应不存在的中间姿态/边界）；
- anchor_steps=N：只在前 N 步锚定，之后回归真实条件（每步都是真实信号；按采样进度切换条件与官方 pose_start_percent/pose_end_percent 属同一类用法）。建议对比这两组：blend=1.0 + anchor_steps=1~2（门控）vs blend=0.7 + anchor_steps=-1（软混合）。

Reference Image Selector

参考图选择器，用于根据视频片段的偏航角范围自动筛选最合适的参考图批次。典型应用：WanAnimate 视频生成中根据人物朝向（yaw）从多角度参考图中选取最佳匹配。也可用于 SCAIL-2 工作流（通过 raw_reference_images 配合 Custom Context Windows 动态前缀）。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | reference_images | IMAGE | ✅ | 参考图批次（N 张不同视角的参考图） | | angle_map | STRING | ✅ | JSON 格式的角度映射，如 [-90, -45, 0, 45, 90]，数组长度必须与参考图数量一致 | | yaw_angles | FLOAT | ❌ | 目标视频片段的偏航角序列（每帧一个值），不接入时输出全部参考图 | | background_images | IMAGE | ❌ | 背景图批次（原始图片直接插入到最后一张辅助参考图之前）。仅改变输出顺序，不做遮罩合成 | | select_references | BOOLEAN | ❌ | True（默认）=按角度筛选+排序，只保留匹配的参考图；False=仅排序不筛选（全部参考图都使用） | | allow_switch_main | BOOLEAN | ❌ | True（默认）=允许更换第一张主参考图；False=固定第一张不变（当第一张不在候选集时会强制加入） |

输出

| 输出 | 类型 | 说明 | |------|------|------| | selected_images | IMAGE | 筛选排序后的参考图批次（原始图片直接输出，不做 1+4n 拼接）。主参考图排第 0 位 + 辅助参考图 + 背景图块 + 最后一张辅助参考图 | | raw_reference_images | IMAGE | 未排序的原始参考图（用于接入 Custom Context Windows 的 prefix_latent_num，因为上下文窗口需要重新筛选） | | info | STRING | 调试信息（角度范围、候选索引、排序结果等） | | reference_angle_map | STRING | 验证后的角度映射 JSON 字符串（用于 Custom Context Windows 动态前缀） |

工作原理

yaw_angles 未接入或 angle_map 无效/数量不匹配：直接输出全部参考图。
有 yaw_angles 输入（筛选+排序模式）：
- 计算偏航角范围 [min, max]（处理 -180°/180° 环绕）
- 筛选所有在此范围内的参考图 + 左右各最邻近一张
- 从候选中选出覆盖帧数最多的参考图作为主参考图（排在第 0 位）
- 辅助参考图按与首帧偏航角的偏差从大到小排列
- 若主参考图恰好最贴合首帧偏航角，末尾追加主参考图副本
- 背景图插入到辅助参考图的最后一张之前
仅排序模式（select_references=False）：所有参考图都参与，不筛除，仅执行排序和输出构建。
输出格式：原始图片直出，1+4n 拼接由下游节点（WanAnimateToVideoCustom 或 Wan SCAIL To Video）处理。

与 Custom Context Windows 的配合

WanAnimate 使用 Custom Context Windows (Manual) 时，需要将 raw_reference_images（未排序的原始参考图）接入其 prefix_latent_num（传入图片数量）。上下文窗口内部会根据每段视频的实际偏航角重新调用选择逻辑，实现动态参考图分配。同时将 reference_angle_map 传入上下文窗口节点即可。

典型工作流

[多角度参考图] → reference_images ─┐
[角度映射 JSON] → angle_map ───────┤
[偏航角序列]    → yaw_angles ─────┤
                                    ↓
                         Reference Image Selector
                                    ↓
      selected_images → [WanAnimateToVideoCustom] reference_image
      raw_reference_images + reference_angle_map → [Custom Context Windows] prefix

SDPose 空帧修复

在 SDPose 姿态处理流水线中，某些帧可能因检测失败导致 people 列表为空（产生黑帧）。新增的 fix_empty_frames 功能可自动检测并修复这些空帧。

适用节点

Load SDPose JSON：加载 JSON 时修复（参数 fix_empty_frames）
Resample SDPose Keypoints：重采样后修复（参数 fix_empty_frames）

修复逻辑

扫描所有帧，标记 people 为空或所有关键点坐标为零的帧为"无效帧"
对每个无效帧：
- 双侧有有效帧：线性插值填充（若左右帧有突变则直接复制较近侧）
- 仅一侧有有效帧：复制该侧数据
修复过程不修改原帧列表，返回新列表

使用建议

在姿态数据来源不够稳定的情况下建议开启
配合 Estimate Yaw 节点使用时可有效避免因空帧导致的角度跳变

SDPoseDrawKeypointsV2 脚部绘制模式

从 v1.4.0 开始，SDPoseDrawKeypointsV2 新增 foot_mode 参数，提供两种脚部绘制方式：

| 模式 | 说明 | |------|------| | dots | 默认模式。在脚部关键点位置绘制彩色圆点（与之前版本行为一致） | | line | 线条模式。绘制踝关节→大脚趾的连线，更清晰地表现脚部朝向和姿态，不绘制圆点 |

两种模式下都会根据 bottom_side / top_side 参数进行前后侧分层绘制，确保遮挡关系正确。

Folder Image Loader

从指定文件夹按文件名升序读取图片批次。遇到路径错误、文件夹为空等情况不会抛出异常，仅输出空结果并在控制台打印警告。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | folder_path | STRING | ✅ | 图片文件夹路径，支持绝对路径或相对于 ComfyUI 根目录的相对路径 | | size_mode | 枚举 | ✅ | resize_to_first：所有图片缩放至第一张的尺寸；filter_same_size：仅加载与第一张尺寸相同的图片 | | skip_first_n | INT | ✅ | 跳过前 N 张图片（默认 0） | | load_count | INT | ✅ | 最多加载 N 张图片（0=不限制，加载全部） |

输出

| 输出 | 类型 | 说明 | |------|------|------| | images | IMAGE | 载入的图片批次。路径无效或无图片时输出 None | | count | INT | 实际载入的图片数量。异常情况输出 0 |

容错行为

文件夹路径为空 → 输出 (None, 0)，控制台打印警告
文件夹不存在 → 输出 (None, 0)，控制台打印警告
文件夹内无图片 → 输出 (None, 0)，控制台打印警告
跳过数超过图片总数 → 输出 (None, 0)，控制台打印警告
单张图片读取失败 → 跳过该图，继续加载其余图片

Image Batch Concat

将两个图像批次沿 batch 维度拼接（images_b 追加到 images_a 后方）。一路或两路无输入时，透传有输入的那一路；两路都无输入时输出 None。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | images_a | IMAGE | ❌ | 第一个图像批次 | | images_b | IMAGE | ❌ | 第二个图像批次，拼接到 images_a 后方 |

输出

| 输出 | 类型 | 说明 | |------|------|------| | images | IMAGE | 拼接后的图像批次。仅一路有输入时透传该路；两路均无输入时输出 None |

典型工作流

[FolderImageLoader A] → images_a ─┐
[FolderImageLoader B] → images_b ─┤
                                    ↓
                           Image Batch Concat
                                    ↓
                               images (合并批次)

Image Batch Resize

将图像批次缩放到指定宽高。可选择按方向裁剪以保持宽高比。输入无效时输出 None。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | width | INT | ✅ | 目标宽度（默认 512） | | height | INT | ✅ | 目标高度（默认 512） | | crop_mode | 枚举 | ✅ | 裁剪模式。disabled=直接拉伸；center/top/bottom/left/right=先等比缩放至覆盖目标再按方向裁剪 | | images | IMAGE | ❌ | 输入图像批次。无输入时输出 None |

输出

| 输出 | 类型 | 说明 | |------|------|------| | images | IMAGE | 缩放后的图像批次。输入无效时输出 None |

缩放算法

统一使用 Pillow 的 LANCZOS 算法，兼顾缩小和放大的高质量效果。

裁剪模式图解

原图 1920×1080 → 目标 512×512
disabled：直接拉伸，画面变形
center：  等比缩放到 911×512，左右各裁 199px
top：     等比缩放到 911×512，裁底部 399px
bottom：  等比缩放到 911×512，裁顶部 399px
left：    等比缩放到 512×288，裁右侧 176px（需再放大到 512×512）
right：   等比缩放到 512×288，裁左侧 176px（需再放大到 512×512）

裁剪模式始终先缩放至覆盖目标尺寸（取 max 缩放比），再按方向裁剪多余内容，保证最终输出尺寸精确等于目标宽高。

WanAnimate Uni3C 运镜控制

Uni3C 运镜控制为 WanAnimate 视频生成提供可选的相机运动控制能力。它通过在 KSampler 的采样过程中注入 ControlNet 控制信号，引导生成结果按照指定的相机轨迹运动。这是一个可选功能，不使用时不影响正常生成流程。

使用前提

需要下载 Uni3C ControlNet 模型文件（.safetensors）放入 ComfyUI/models/controlnet 目录
需要安装 diffusers 和 accelerate Python 包

WanUni3CLoader — 模型加载

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | model_name | COMBO | ✅ | Uni3C ControlNet 模型文件，自动扫描 controlnet 目录 | | base_precision | 枚举 | ❌ | 基础精度，可选 fp32 / bf16 / fp16（默认 fp16） |

输出：uni3c_controlnet（UNI3C_CONTROLNET）— 加载后的 ControlNet 模型，供 WanUni3CApply 使用。

WanUni3CApply — 控制注入

在 KSampler 中注入 Uni3C 运镜控制信号。节点通过 monkey-patch 模型内部的 forward_orig 方法，在每个 denoising step 中计算并注入控制信号。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | model | MODEL | ✅ | 待注入控制的模型 | | uni3c_controlnet | UNI3C_CONTROLNET | ✅ | 由 WanUni3CLoader 加载的 ControlNet 模型 | | render_video | IMAGE | ✅ | 运镜参考视频（像素帧），节点内部 VAE 编码后作为运镜控制的视觉参考 | | vae | VAE | ✅ | 用于编码 render_video 的 VAE | | strength | FLOAT | ✅ | 控制强度（0.0-10.0，默认 1.0） | | start_percent | FLOAT | ✅ | 控制生效起始百分比（0.0-1.0，默认 0.0） | | end_percent | FLOAT | ✅ | 控制生效结束百分比（0.0-1.0，默认 1.0） | | trim_latent | INT | ❌ | 参考图占用的 latent 帧数，从 WanAnimateToVideoCustom 的 trim_latent 输出接入，用于时序对齐 |

输出：model（MODEL）— 已注入控制的模型，可直接连接 KSampler。

核心原理

v4 架构：采用 monkey-patch 方式修改模型 forward_orig 方法，在 block 循环中精确控制注入时机
参考帧偏移：注入时跳过参考帧 token（与官方 img_offset 语义一致），避免参考帧被污染及控制信号时序错位；支持 WanAnimate concat / ref_conv / SCAIL / context window 场景
latent 归一化：render_video 内部 VAE 编码后应用 latent_format.process_in，与采样中已归一化的 x 尺度对齐，避免控制信号偏向 render 内容
step 控制：通过 start_percent / end_percent 控制控制信号在 denoising 过程中的生效范围

典型工作流

[WanUni3CLoader] → uni3c_controlnet ─┐
[运镜参考视频] → render_video ────────┤
[VAE] → vae ────────────────────────┤
                                       ↓
[模型] → WanUni3CApply → model (已注入控制) → [KSampler] → [VAE Decode] → 输出

注意：旧版提供过 positive/negative 条件接口和 render_mask，实际为无效逻辑（写入的键从未被读取），已在 v4 清理移除。

Interactive Batch Crop (交互式批量裁剪)

通用交互式裁剪节点，提供图形化界面进行区域选择和批量裁剪。不绑定特定工作流，可在任何需要批量裁剪图片的场景中使用。典型应用场景如 360° 图像批次预处理模块中，从 360° 渲染图中裁剪出人物区域。

输入方式

节点支持两种图片源：

| 方式 | 说明 | |------|------| | 路径模式 | 在 path 参数中输入文件夹路径或用 | 分隔的多个文件路径。点击节点上的"选择目录"或"多选文件"按钮可调出系统文件选择器 | | 张量模式 | 将上游节点的图片张量连接到 images 可选输入。优先级高于路径模式（连接后 path 参数被忽略） |

操作流程

设置图片源：填入文件夹路径 / 多文件路径，或连接 images 输入
运行一次：首次执行工作流以建立图片缓存（节点需要知道图片数量用于预览索引）
打开裁剪器：点击节点上的 ✂ 打开裁剪器 按钮，弹出图形化裁剪界面
调整裁剪框：在画布上拖动/缩放裁剪框，设置合适的裁剪区域和填充色
确认：点击 ✅ 确认，裁剪参数自动保存到节点的 crop_params（隐藏）
再次运行：再次执行工作流，节点根据保存的裁剪参数批量处理所有图片

提示：路径模式下，如果文件夹中有多种分辨率的图片，裁剪器会先弹出尺寸选择对话框，选择统一处理的尺寸。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | path | STRING | ❌ | 图片文件夹路径，或用 | 分隔的多个文件路径。与 images 二选一 | | max_preview | INT | ❌ | 前端预览中显示的最大图片数量（默认 10），图片过多时会自动抽样 | | images | IMAGE | ❌ | 直接传入图片张量作为裁剪源（与 path 二选一） |

crop_params、node_id、target_size 为隐藏参数，由前端 JS 自动管理，用户无需手动填写。

裁剪器界面功能

| 功能 | 操作方式 | |------|----------| | 拖动裁剪框 | 鼠标在裁剪框内拖拽移动位置 | | 缩放裁剪框 | 鼠标拖拽裁剪框的 8 个边缘/角点 | | 移动图片 | Shift + 拖拽，调整图片在画布中的位置 | | 平移裁剪框+图片 | Ctrl + 拖拽裁剪框 | | 滚轮缩放 | 鼠标滚轮放大/缩小画布视图 | | 翻页 | ◀ ▶ 按钮或键盘 ← → 方向键切换预览图片 | | 缩略图导航 | 点击底部缩略图跳转到对应图片 | | 吸附 | 裁剪框边缘靠近图片边缘时自动吸附对齐（可关闭） | | 保持比例 | 勾选后锁定宽高比，拖动时自动维持比例 | | 预设比例 | 快速选择 1:1、4:3、16:9 等预设比例，或选择"自由"模式 | | ↕ 交换 | 交换裁剪框的宽和高 | | 填充色 | 裁剪超出图片区域的填充颜色（黑/白/灰/自定义） | | 重置 | 将裁剪框重置为覆盖整张图片 |

输出

| 输出 | 类型 | 说明 | |------|------|------| | images | IMAGE | 裁剪后的图片批次。裁剪区域超出原图部分用填充色填充 |

典型工作流

[图片源（路径/张量）] → Interactive Batch Crop → 裁剪后的图片批次

MaskCompositeRef (遮罩批次合成 Ref)

专门用于 WanSCAILToVideo MultiRef 节点的 reference_image 预处理节点。根据 replacement_mode 分为两种工作模式，对应 SCAIL-2 的两种生成策略。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | images | IMAGE | ✅ | 原图批次 [B, H, W, C]。输入参考图序列，顺序必须与 masks 一一对应 | | replacement_mode | BOOLEAN | ✅ | False=动作迁移模式（白底彩色遮罩，与背景图合成）；True=替换模式（黑底彩色遮罩，背景替换为纯黑，自动剔除全黑帧） | | process_first_frame | BOOLEAN | ✅ | 仅动作迁移模式有效。False 时第 1 张原图保留不动不做合成 | | process_last_frame | BOOLEAN | ✅ | 仅动作迁移模式有效。True 时最后 1 张原图参与合成 | | remove_background | BOOLEAN | ✅ | 替换模式：关闭时仅做全黑帧剔除+透传，不做背景替换。动作迁移模式：关闭时仅做尺寸对齐和背景插入，不做遮罩合成 | | masks | IMAGE | ❌ | 遮罩批次 [B, H, W, C]，顺序与 images 一一对应。未连接时透传原图 | | backgrounds | IMAGE | ❌ | 背景图批次。仅动作迁移模式有效。第 1 张用于遮罩合成填充背景，其余插入到合成序列中 |

两种模式详解

替换模式 (replacement_mode=True)

用于替换背景的场景（如将人物从旧背景迁移到新环境中）。

遮罩要求：黑底彩色（人物区域为彩色，纯黑 RGB<10/255 区域为背景）
处理逻辑：
1. 自动检测并剔除遮罩全黑的帧（原图和遮罩同时剔除）
2. 将剩余原图的背景（黑色区域）替换为纯黑
3. 保留原始彩色遮罩输出
backgrounds 输入：被忽略
典型用途：SCAIL-2 替换模式中，将参考图中的人物从原背景中分离出来

动作迁移模式 (replacement_mode=False)

用于动作迁移的场景（将人物的动作迁移到新的背景中）。

遮罩要求：白底彩色（人物区域为彩色，纯白 RGB>245/255 区域为背景）
处理逻辑：
1. 将原图的人物区域提取出来，与背景图合成到新的背景上
2. 支持首尾帧跳过控制（process_first_frame / process_last_frame）
3. 背景图批次：第 1 张用作遮罩合成的填充背景，多余的背景图会插入到倒数第 1 和第 2 帧之间
backgrounds 输入：有效，第 1 张用于合成，其余插入序列
典型用途：SCAIL-2 动画模式中，将人物动作迁移到新背景上

自动容错

| 情况 | 行为 | |------|------| | masks 未连接 | 透传原图。替换模式输出全黑遮罩，动作迁移模式输出全白遮罩 | | 遮罩尺寸不一致 | 自动缩放到原图尺寸（LANCZOS 算法），控制台打印警告 | | 替换模式所有帧全黑 | 返回空批次（可用于条件判断跳过当前段） | | 批次数量不一致 | 自动截断为较短的数量并打印警告 | | 无背景图 | 使用纯黑作为背景（仅做剔除效果，人物区域无变化） |

输出

| 输出 | 类型 | 说明 | |------|------|------| | images | IMAGE | 合成后的图像批次 | | masks | IMAGE | 处理后的遮罩批次 |

典型工作流

[参考图](4 张) → images ───┐
[参考图遮罩]    → masks ───┤
[背景图]       → backgrounds ─┤
                             ↓
                    MaskCompositeRef
                             ↓
              images + masks → [Wan SCAIL To Video] reference_image + reference_image_mask

SmartVideoCrop (智能视频裁剪)

基于 SAM3 追踪数据的智能视频裁剪：以人物质心为基准做水平跟随裁剪，固定保留原始画面全高，再按输出宽高比缩放到目标尺寸。

参数说明

| 参数 | 类型 | 说明 | |------|------|------| | frames | IMAGE | 当前段原始视频帧批次 (B, H, W, C) | | track_data | SAM3_TRACK_DATA | SAM3_VideoTrack 的追踪数据（接 driving_track_data） | | output_width / output_height | INT | 输出尺寸；裁剪宽度按 H × output_width / output_height 推算 | | object_ids | STRING | 要追踪的人物 ID，逗号分隔（如 1 或 1,2）；空 = 默认 ID 1 | | smoothing | FLOAT | 帧间 EMA 平滑（0 = 完全跟随、抖动明显；1 = 几乎静止） | | mask_fallback | 枚举 | mask 为空时：hold_last 保持最后有效位置 / center 回到画面中心 | | scene_cut_threshold | FLOAT | 切镜检测阈值（归一化）：连续有 mask 的帧间质心跳变超过该值即判定切镜并重置平滑；0 = 关闭 | | fallback_center | FLOAT | mask_fallback=center 时的回退水平中心比例（0=最左, 0.5=居中, 1=最右） | | mask_frames | IMAGE | 可选第二路图像（如遮罩视频），与 frames 共用同一裁剪窗口同步输出 |

输出

cropped_frames：裁剪并缩放后的帧批次
cropped_mask：第二路的同步裁剪结果（未接时为空批次）
debug_info：每帧裁剪位置等 JSON 调试信息

输入比目标更窄时会自动切换为"垂直居中裁剪"（用全宽、按比例算高），因此不会裁掉画面内容。内部按 8 帧分块批处理 grid_sample，长序列比逐帧处理更快（裁剪结果与原逐帧实现逐位一致）。

VideoGridCompose (视频网格拼接)

把 1~4 路视频/图片拼成一个网格视频，全程由 ffmpeg 流式处理，不会把帧读进内存（长视频同样安全）。

参数说明

| 参数 | 类型 | 说明 | |------|------|------| | video_paths | STRING | 多行路径，每行一个（最多 4 路，自动去重去空行）；某一行是图片时会自动以 -loop 1 -t <目标时长> 当作静止视频流处理 | | layout | 枚举 | 水平排列 / 垂直排列 / 田字格2×2（需 4 路）/ 左一右N / 上一+下N（后两者需 ≥3 路）；路数不足时自动降级为水平排列 | | audio_source | 枚举 | 无音频 或 视频1~视频4（取对应输入的音频轨） | | match_method | 枚举 | 自适应(填满)=拉伸铺满 / 自适应(保持比例)=等比缩放+黑边 / 统一到最大 / 统一到最小 | | fps | FLOAT | 输出帧率；0 = 取输入中的最大帧率 | | crf | INT | x264 质量（越小越好，建议 18~28） | | duration_mode | 枚举 | 时长基准：自动(最短) / 自动(最长) / 视频1~视频4；比基准长的截断、短的冻结最后一帧补齐，音频同步 atrim/apad | | output_path_prefix | STRING | 输出路径前缀（相对 ComfyUI 的 output 目录） |

输出 video_path（STRING），文件写入 ComfyUI/output/<output_path_prefix>_0001.mp4（自动递增避免覆盖）。

BatchImageReplace (图像批次替换)

在主图像批次中，从 start_index 开始按 replace_count 替换若干帧。替换源（replace_images）的数量可以与需求不一致，由两个模式决定如何处理。

参数说明

| 参数 | 类型 | 说明 | |------|------|------| | start_index | INT | 从主批次哪个位置开始替换（0-based） | | replace_count | INT | 替换多少张；-1 = 从 start_index 一直替换到末尾；0 = 不替换（原样透传） | | overflow_mode | 枚举 | 替换源多于需求时：take_front 取前 N 张 / take_back 取后 N 张 | | underflow_mode | 枚举 | 替换源少于需求时：as_is 只替换源里实际有的张数（不扩展）/ repeat_begin 前面用第 1 张补齐 / repeat_end 按原顺序保留全部、末尾用最后 1 张补齐 | | images | IMAGE | 主图像批次（未连接时输出为空） | | replace_images | IMAGE | 替换源批次（未连接时原样透传主批次） |

underflow 语义示例（替换源 3 张、需替换 4 张）

| 模式 | 替换结果 | |------|----------| | as_is | 只替换 3 帧（第 4 帧保持原样） | | repeat_begin | 0,0,1,2（第 1 张重复到最前面） | | repeat_end | 0,1,2,2（按原顺序保留，末尾补最后 1 张） |

repeat_end 在 v1.8.0 修正过一次：旧实现会丢弃中间帧得到 0,2,2,2，升级后行为与上表一致。

其它说明

替换源与主批次分辨率不一致时会自动缩放到主批次尺寸
start_index 超出批次长度时打印警告并原样返回主批次

SCAIL-2 节点详解

以下节点为本工具集对 Wan SCAIL-2 模型的支持部分。SCAIL-2 与 WanAnimate 共用 Custom Context Windows (Manual)？不，SCAIL-2 有专用的 Wan SCAIL-2 Context Windows 节点，因为其 conditioning 中包含 SCAIL-2 特有的多通道遮罩字段。

Wan SCAIL To Video (Multi Ref)

SCAIL-2 视频生成的核心 conditioning 节点。将多张参考图、姿态视频、colored mask 等输入统一编码为模型所需的 conditioning 格式。

参数说明

必选参数：

| 参数 | 类型 | 说明 | |------|------|------| | positive / negative | CONDITIONING | 正/负向提示词条件 | | vae | VAE | VAE 模型 | | width / height | INT | 输出分辨率（步长 32） | | length | INT | 输出帧数（像素帧，步长 4，推荐 81） | | batch_size | INT | 批大小（通常为 1） |

参考图参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | reference_image | IMAGE | ❌ | 多张参考图以批次形式传入 (N, H, W, 3)。每张图独立编码为单独的 reference_latent | | reference_image_mask | IMAGE | ❌ | 仅 SCAIL-2。与 reference_image 同分辨率的彩色参考遮罩，数量需匹配 | | ref_encoding_mode | 枚举 | ❌ | 参考图编码模式，见下文详解 |

姿态参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | pose_video | IMAGE | ❌ | 姿态视频，将降低分辨率至主视频的一半后编码为 pose_video_latent | | pose_video_mask | IMAGE | ❌ | 仅 SCAIL-2。与 pose_video 同分辨率的 SAM3 逐人彩色遮罩视频 | | replacement_mode | BOOLEAN | ❌ | False=动画模式（默认）；True=替换模式 | | pose_strength | FLOAT | ❌ | 姿态 latent 强度（默认 1.0） | | pose_start / pose_end | FLOAT | ❌ | 姿态 conditioning 在 denoising 步中的生效范围（0.0~1.0） |

接续参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | video_frame_offset | INT | ❌ | 当前块开始的累计输出帧偏移，从上一块的输出接入（默认 0） | | previous_frame_count | INT | ❌ | 用于锚定的上一块尾帧数（SCAIL-2 训练使用 5，即 81 帧块+76 帧步长） | | previous_frames | IMAGE | ❌ | 仅 SCAIL-2。上一块的完整解码输出，仅最后 previous_frame_count 帧用作锚定 |

可选输入：

| 参数 | 类型 | 说明 | |------|------|------| | clip_vision_output | CLIP_VISION_OUTPUT | CLIP 视觉特征注入 |

ref_encoding_mode 三种模式

| 模式 | 说明 | 适用场景 | |------|------|----------| | 1+4n批量 | 第 1 张×1 + 其余每张×4 → 批处理 VAE 编码（默认）。更接近模型训练时的分布 | 通用场景，推荐用于大多数情况 | | 逐帧编码 | 每张参考图独立升采样+VAE 编码 → 在时间维拼接。每帧独立保真度更高 | 需要高保真参考图细节的场景 | | 混合编码 | 前 N-1 张用 1+4n 批量编码 + 最后 1 张逐帧独立编码。兼顾主体清晰度与减轻段间跳变 | 需要平衡参考图清晰度和视觉连续性的场景 |

输出

| 输出 | 类型 | 说明 | |------|------|------| | positive | CONDITIONING | 已注入 reference_latents、pose_video_latent、ref_mask_28ch、driving_mask_28ch 等条件的正向输出 | | negative | CONDITIONING | 同上，负向输出 | | latent | LATENT | 生成尺寸的空 latent（samples 形状已匹配）。接入 previous_frames 时内置噪声遮罩实现硬切锚定 | | video_frame_offset | INT | 调整后的偏移量 + 长度，接入下一块 |

典型工作流

[多张参考图] → reference_image ────┤
[参考图遮罩]  → reference_image_mask ─┤
[驱动视频]    → pose_video ──────────┤
[驱动遮罩]    → pose_video_mask ─────┤
[条件]        → positive/negative ───┤
[接续帧]      → previous_frames ─────┤
                                     ↓
                      Wan SCAIL To Video (Multi Ref)
                                     ↓
                     positive / negative / latent
                                     ↓
               [Wan SCAIL-2 Context Windows] → [KSampler] → [VAE Decode] → 输出视频

Create SCAIL-2 Colored Mask (Multi Ref)

渲染 SAM3 追踪数据为 SCAIL-2 使用的彩色遮罩。与 WanSCAILToVideoMultiRef 配合使用。

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | driving_track_data | SAM3_TRACK_DATA | ✅ | 驱动姿态视频的 SAM3 追踪数据，渲染为 pose_video_mask | | ref_track_data | SAM3_TRACK_DATA | ❌ | 参考图的 SAM3 追踪数据，渲染为 reference_image_mask。未连接时自动生成纯色背景遮罩 | | object_indices | STRING | ❌ | 逗号分隔的人物索引列表（如 0,2,3），只保留指定人物。空=保留全部 | | sort_by | 枚举 | ❌ | 调色板分配到追踪对象的顺序（同时应用于参考图和驱动视频，确保同一个人物颜色一致） | | replacement_mode | BOOLEAN | ❌ | 影响输出遮罩的背景色 |

sort_by 排序方式

| 方式 | 说明 | |------|------| | left_to_right | 按首帧质心的 x 坐标从左到右分配调色板索引，适用于多人物并排场景 | | area | 按首帧人物面积从大到小分配调色板索引，适用于人物大小差异大的场景 | | none | 保持 SAM3 原始顺序 |

遮罩背景色规则

| 模式 | pose_video_mask 背景色 | reference_image_mask 背景色 | |------|----------------------|--------------------------| | 动画模式 (replacement_mode=False) | 黑色 | 白色 | | 替换模式 (replacement_mode=True) | 白色 | 黑色 |

此背景色规则与 MaskCompositeRef 节点的遮罩检测逻辑完全对应。

输出

| 输出 | 类型 | 说明 | |------|------|------| | pose_video_mask | IMAGE | 渲染后的驱动视频彩色遮罩，接入 WanSCAILToVideoMultiRef 的 pose_video_mask | | reference_image_mask | IMAGE | 渲染后的参考图彩色遮罩，接入 WanSCAILToVideoMultiRef 的 reference_image_mask |

典型工作流

[SAM3 参考图追踪] → ref_track_data ─┐
[SAM3 驱动追踪]    → driving_data ───┤
[人物索引]        → object_indices ──┤
[排序方式]        → sort_by ─────────┤
                                     ↓
                     Create SCAIL-2 Colored Mask (Multi Ref)
                                     ↓
          pose_video_mask → [WanSCAILToVideoMultiRef] pose_video_mask
          reference_image_mask → [WanSCAILToVideoMultiRef] reference_image_mask

Wan SCAIL-2 Context Windows

SCAIL-2 专用的上下文窗口节点，与通用的 Custom Context Windows (Manual) 有重要区别。

与 Custom Context Windows (Manual) 的区别

| 特性 | Custom Context Windows (Manual) | Wan SCAIL-2 Context Windows | |------|-------------------------------|----------------------------| | conditioning 处理 | 通用处理，需要手动配置 prefix_latent_num | 自动处理 SCAIL-2 特殊字段（ref_mask_28ch、driving_mask_28ch、pose_video_latent） | | 前缀参考帧 | 通过 prefix_latent_num 配置 | 不需要，SCAIL-2 的 reference_latents / ref_mask_28ch 是全局保留的 | | 适用模型 | 通用 WAN 模型 | SCAIL-2 模型专用 |

参数说明

| 参数 | 类型 | 说明 | |------|------|------| | model | MODEL | 待封装的 SCAIL-2 模型 | | context_length | INT | 上下文窗口长度（像素帧）。建议设为 SCAIL-2 的 length 参数值（如 81） | | context_overlap | INT | 窗口间重叠帧数（像素帧） | | context_schedule | 枚举 | 窗口调度策略。static_standard（固定窗口）为推荐选项 | | context_stride | INT | 窗口步进（仅对 uniform 策略有效） | | closed_loop | BOOLEAN | 是否闭环窗口（仅 looped 策略有效） | | fuse_method | 枚举 | 窗口融合方法（金字塔权重推荐） | | freenoise | BOOLEAN | FreeNoise 噪声混洗，改善窗口间融合 |

工作原理

conditioning 自动分片：节点内部自动识别 conditioning 中各字段的时间维布局，对 ref_mask_28ch（保留前 N 帧参考 + 按窗口切片视频部分）、driving_mask_28ch（按窗口切片）、pose_video_latent（按窗口切片）分别处理
模型 patch：在模型 forward 入口自动应用 patch，在每次前向时根据当前窗口索引切片 ref_mask_28ch 和 driving_mask_28ch
无需 prefix：SCAIL-2 的 reference_latents 和 ref_mask_28ch 的前 N 帧作为全局条件自动保留在所有窗口中

典型工作流

[SCAIL-2 模型] → model ──┐
                           ↓
              Wan SCAIL-2 Context Windows
                           ↓
           model (已封装) → [KSampler] → [VAE Decode] → 输出视频

工作流

workflow/ 目录下提供了多个完整的 ComfyUI 工作流 JSON 文件，可直接拖入 ComfyUI 界面使用。

长视频姿态检测工作流

文件：Long_Pose_detection_SD_offical.json / Long_Pose_detection_SDpose.json

用途：对长视频进行逐帧骨骼（body）和面部关键点检测，支持将检测骨骼与参考图人物的骨骼进行比例对齐（BodyRatioMapper），最终生成骨骼可视化视频、面部特征 JSON 和姿态 JSON 文件。适用于制作舞蹈骨骼动画、动作捕捉数据提取等场景。

Long_Pose_detection_SD_offical.json：使用官方 SDPoseOODProcessor 进行姿态识别
Long_Pose_detection_SDpose.json：使用 SDPose 流程进行姿态识别（配合自定义节点）

简要使用说明：

在「参数设置」区域内设置分辨率（宽度/高度）、帧率（fps）、每片段帧数等；
在「视频分段循环加载」区域内配置输入视频路径、视频分段参数；
在「识别并保存面部图、面部特征点json、姿态json」区域内设置参考骨骼 JSON 路径和参考图，用于骨骼比例对齐；
在「骨骼对齐、绘制，合成骨骼视频」区域调整骨骼绘制参数（线条宽度、面部/手部关键点大小等）；
运行前请先清除工作目录中的过往文件，尤其是脸图（face）文件夹，避免旧数据残留干扰；
运行后自动分段循环处理长视频，逐段进行 SDPose 姿态识别、骨骼对齐、可视化绘制，最终合成骨骼视频（保留原视频音频）。

视频合成方式：将绘制好的骨骼帧通过 ImageSequenceToVideo 合成为视频文件，可同步附带原视频音频（通过 VHS_LoadAudio 加载）。

本工作流使用到的第三方节点包（不含本工作区 ComfyUI-CustomNodeKit 自身节点）：

| 节点包 | 主要用途 | |--------|----------| | sdpose-ood | SDPose 姿态识别模型加载（SDPoseOODLoader）与处理（SDPoseOODProcessor） | | ComfyUI-WanAnimatePreprocess | ONNX 面部检测模型加载（OnnxDetectionModelLoader）与面部图像截取（PoseAndFaceDetection） | | comfyui-videohelpersuite | 视频文件加载（VHS_LoadVideoFFmpegPath）与音频加载（VHS_LoadAudio） | | comfyui-kjnodes | 常量节点（INTConstant、FloatConstant、StringConstant） | | comfyui-easy-use | While 循环控制（easy whileLoopStart/easy whileLoopEnd）与缓存清理（easy clearCacheAll） | | comfyui-impact-pack | 循环条件比较（ImpactCompare） | | comfyui-custom-scripts | 数学表达式计算（MathExpression\|pysssss） | | ComfyUI-BodyRatioMapper | 骨骼比例对齐（BodyRatioMapperProportionTransfer） | | ComfyUI-Addoor | 临时文件清理（AD_DeleteLocalAny） |

WanAnimate多参考图生成长视频工作流

文件：WanAnimate_ref_pics_loop+context.json

用途：基于 WanAnimate 模型，使用多张参考图生成带有上下文窗口的长视频。该工作流特别包含一个360° 图像批次预处理模块，可将单张参考图处理为 360° 环绕视角的图片批次（配套文件存放于输出目录中），用户可以从生成结果中挑选合适角度的图片作为多参考图输入，从而更好地控制长视频中人物的外观一致性。

简要使用说明：

在「模型、LoRA及VAE加载」区域加载 WanAnimate UNet 模型、CLIP 模型、VAE 及所需 LoRA；
在「设置主参考图」区域加载主参考图并缩放至 512×512；
在「设置副参考图」区域通过 PathCollectorNode 指定副参考图目录（可放入 360° 预处理输出的多角度参考图）；
在「提示词填写」区域输入正/负向提示词；
在「视频生成参数区」设置每段生成帧数、片段间重叠帧数等参数；
选择动作和面部数据加载方式：
- 常规加载：直接载入原视频，实时识别面部和姿态（不支持骨骼对齐）；
- 快速加载：直接载入预先导出的姿态 JSON 和面部 JSON，支持骨骼对齐；
运行后通过循环控制区逐段生成视频帧，利用 Custom Context Windows 实现跨段上下文窗口调度；
生成完成后，手动启用「保存视频」区域，运行 ImageSequenceToVideo 将帧序列合成为视频文件（可附带原视频音频）。

视频合成方式：先通过 KSampler 生成各段视频帧（VAE Decode），再进行跨段淡入淡出融合（CrossFadeImages），最后通过 ImageSequenceToVideo 将完整帧序列合成为视频。

360° 预处理模块说明：

该模块位于工作流下半部分（通常 mute 状态），包含 InteractiveBatchCrop 交互式裁剪、SDPoseLoadJson 加载 360° 关键点 JSON、SDPoseResizeKeypoints 缩放关键点、SDPoseDrawKeypointsV2 绘制姿态视频；
配套文件（360° 关键点 JSON 等）需放置在 output/video/360° 目录下；
用户可运行预处理模块生成 360° 环绕视角姿态视频批次，从中挑选合适角度的帧作为副参考图；
复杂预处理建议使用主工作流（Long_Pose_detection_SD_offical.json 或 Long_Pose_detection_SDpose.json）进行。

本工作流使用到的第三方节点包（不含本工作区 ComfyUI-CustomNodeKit 自身节点）：

| 节点包 | 主要用途 | |--------|----------| | sdpose-ood | SDPose 姿态识别模型加载与处理 | | ComfyUI-WanAnimatePreprocess | ONNX 面部检测模型加载与面部图像截取 | | comfyui-videohelpersuite | 视频文件加载（VHS_LoadVideoFFmpegPath）、图像分割（VHS_SplitImages）与音频加载 | | comfyui-kjnodes | 常量节点、CrossFadeImages 跨段融合、ColorMatch 色彩匹配、PatchSageAttentionKJ 等 | | comfyui-easy-use | While 循环控制、IfElse 条件分支、缓存清理、easy imageSwitch | | comfyui-impact-pack | 循环条件比较（ImpactCompare）、空值检测（ImpactIfNone） | | comfyui-custom-scripts | 数学表达式计算（MathExpression\|pysssss） | | ComfyUI-BodyRatioMapper | 骨骼比例对齐（BodyRatioMapperProportionTransfer） | | rgthree-comfy | Any Switch 多路图像切换、Fast Muter 快速开关 | | pr-was-node-suite-comfyui-47064894 | Image Filter Adjustments 图像滤镜调整、Random Number 随机种子 | | comfyui_memory_cleanup | RAMCleanup / VRAMCleanup 内存/显存清理 | | ComfyUI-EasyColorCorrector | BatchColorCorrection 批量色彩校正 |

WanSCAIL2 多参考图生成长视频工作流

文件：WanSCAIL2_ref_pics_loop+context.json

用途：基于 Wan SCAIL/SCAIL-2 模型，使用多张参考图生成带有上下文窗口的长视频。支持多身份识别（通过 SAM3 追踪 + colored mask），可实现动画模式（Animation Mode）和替换模式（Replacement Mode）两种生成策略。

简要使用说明：

在「模型、LoRA及VAE加载」区域加载 SCAIL 模型及相关组件；
加载参考图并通过 SAM3 生成参考图追踪数据；
加载驱动视频并通过 SAM3 生成驱动视频追踪数据；
使用 Create SCAIL-2 Colored Mask (Multi Ref) 节点生成 colored mask，选择合适的排序方式（left_to_right/area）确保多身份颜色一致性；
将 colored mask 和驱动视频接入 Wan SCAIL To Video (Multi Ref) 节点；
运行后逐段生成视频帧，利用上下文窗口实现长视频生成；
生成完成后将帧序列合成为视频文件。

更新日志

v1.8.0

新增

WanAnimate2ToVideoCustom：WanAnimate2（官方二代架构）视频生成节点
Context Window Anchor (窗口首帧锚定)（实验性 / 测试性——有效性与副作用尚未充分验证）：上下文窗口的跨窗口对齐锚定节点。把每个窗口的驱动视频 latent 首帧（animate2: pose_latents；SCAIL-2: pose_latents + 驱动遮罩 sam_latents）替换为当前片段窗口 0 的首帧，使各窗口以同一基准对齐，缓解窗口融合处的比例/位置跳变。每采样步生效、不跨 chunk、只改数值不改长度；必须接在上下文窗口节点之后。
- 默认参数：anchor_targets=驱动视频 + 驱动遮罩 (auto)、anchor_frames=1、anchor_offset=-1（自动跳过前缀派生帧）、blend=1.0、apply_to_negative=true、log_debug=false；锚定目标与偏移都以下拉/整数呈现，无需手填任何"键名:维度"字符串。
- 未充分验证：有效性取决于模型内部对齐是否依赖窗口首帧，副作用（画质 / 人物一致性 / 采样稳定性）尚未系统评估；请按上文“实验建议”做开/关对比后再决定是否长期使用，不建议在正式生产工作流中依赖它。

移除

WanSCAILSparseAttention：长序列下需要构造 O(S²) 的稠密注意力掩码（2600 帧时可达 TB 级），导致内存直接爆掉，且实测在 SCAIL 上无明显收益，故彻底移除。旧工作流若引用它会提示"缺失节点"，删除该节点即可

修复

SDPoseEstimateYawSimple / SDPoseEstimateYawAdvanced：短片段、多镜头素材下分组为空会触发 IndexError 崩溃（现改为回退到全局基准值）
BatchImageReplace：修正 repeat_end 填充逻辑（3 张替换 4 张由 0,2,2,2 修正为 0,1,2,2）；images 未连线时不再抛 TypeError
ImageSequenceToVideo：ffconcat 列表与音频临时文件在失败/异常路径也会被清理

优化

InteractiveBatchCrop：预览缓存改为"按前端取帧规则缓存帧子集"，2600 帧从约 12.5GB 降到约 48MB，并加了 2GB 总量预算；输出改为预分配
SmartVideoCrop：裁剪改为 8 帧分块批处理（长序列更快，裁剪结果数值不变）
MaskCompositeRef / BatchImageReplace / ImageBatchResize 等：逐帧拼接改为预分配输出（峰值内存约减半）
VideoGridCompose / VideoFrameCounter / ImageSequenceToVideo：同一文件的 ffmpeg 探测由 2 次降为 1 次
GD_BBoxDetect：新增 unload_after_run 开关（默认关闭＝保持常驻显存），需要时可在检测完把模型移回 CPU
文件/文件夹选择弹窗改为工作线程执行，弹窗期间不再阻塞 ComfyUI 事件循环

⚠️ 不兼容变更（升级前请留意）

WanUni3CApply：输入由 render_latent(LATENT) 改为 render_video(IMAGE) + vae；WanUni3CLoader 的模型目录由 models/controlnet 改为 models/model_patches
WanSCAILToVideoMultiRef：ref_encoding_mode 默认值改为 逐帧编码（保真度更高；如需旧行为请手动改回 1+4n批量）
Custom Context Windows (Manual) / Wan SCAIL-2 Context Windows：已移除 causal_window_fix 相关参数与逻辑
WanSCAILSparseAttention 节点已移除（见上文"移除"）

依赖

Python 依赖

核心依赖（已在 requirements.txt 中声明）：

torch — PyTorch 深度学习框架（通常由 ComfyUI 环境提供）
numpy — 数值计算
Pillow — 图像处理
aiohttp — 异步 HTTP 通信
colorsys — 颜色空间转换（Python 标准库）
tqdm — 进度条显示
imageio-ffmpeg — 视频合成（自动下载 ffmpeg，无需系统安装）

使用示例

1. WanAnimateVideo 视频生成

[Reference Image] → WanAnimateToVideoCustom
[Pose Video]       →  (pose_video 输入)
[Face Video]       →  (face_video 输入)
                       ↓
               positive / negative / latent → [KSampler] → [VAE Decode] → 输出视频

2. SDPose 姿态可视化流水线

[SDPose JSON 文件] → Load SDPose JSON
                       ↓
               [Estimate Yaw] → yaw_array
                       ↓
               [Resize Keypoints] → 统一尺寸
                       ↓
               [Draw Keypoints V2] → 可视化图像 (支持 foot_mode=line/dots)

3. 上下文窗口视频生成

[模型] → Custom Context Windows (Manual) → model (已封装)
                                               ↓
[prompt] → CLIP Text Encode → positive ──────┤
[WanAnimateToVideoCustom] → positive/negative/latent → [KSampler] → [VAE Decode] → 视频

4. 参考图自动选择 + 视频生成

[多角度参考图] → Reference Image Selector ← yaw_angles ← [Estimate Yaw]
                       ↓
               selected_images → [WanAnimateToVideoCustom] reference_image

5. SCAIL/SCAIL-2 多参考图视频生成

[SAM3 参考图追踪] → ref_track_data ─┐
[SAM3 驱动追踪]    → driving_data ──┤
                                    ↓
                   Create SCAIL-2 Colored Mask (Multi Ref)
                                    ↓
               pose_video_mask / reference_image_mask
                                    ↓
[多张参考图] → reference_image ────┤
[驱动视频]   → pose_video ────────┤
[条件]       → positive/negative ─┤
                                  ↓
                   Wan SCAIL To Video (Multi Ref)
                                  ↓
                  positive / negative / latent → [KSampler]

致谢

本项目的部分节点为以下第三方节点提供辅助服务（如 bbox 检测、姿态数据预处理等），感谢这些优秀项目的启发：

sdpose-ood — SDPose 姿态系统
ComfyUI-WanAnimatePreprocess & comfyui-kjnodes (Kijai) — WanAnimate 预处理与工具包
GroundingDINO (ShilongLiu) — GD 检测模型接口
ComfyUI-BodyRatioMapper — 骨骼比例对齐
comfyui-videohelpersuite — 视频工具
comfyui-custom-scripts — 实用节点
ComfyUI-Scail2-Sampler-Helper (checknickname) — SCAIL-2 两阶段采样采样器；借此致谢

同时，本项目中的 WanAnimate 多参考图视频生成逻辑、偏航角估计算法、上下文窗口调度策略、骨骼绘制引擎、SCAIL/SCAIL-2 多参考图支持等核心逻辑均为自主实现。

许可证

MIT License