一套为 ComfyUI 设计的自定义节点工具集，涵盖视频生成、姿态处理、图像交互操作等常见工作流需求。

当前版本：1.5.6 — 新增 AutoColorDriftCorrection V3.1 色彩漂移校正节点、新增 CLIP Vision Multi-Ref Switch 多参考图 CLIP 特征合并节点、新增 WanSparseAttention 稀疏注意力节点。

• 安装
• 节点列表
  • WanLoop 视频生成
  • SCAIL/SCAIL-2 多参考图生成
  • SDPose 姿态系统
  • 视频工具
  • 交互式工具
  • 通用工具
  • 图像批次工具
  • 上下文工具
• 复杂节点详解
  • WanAnimateToVideoCustom
  • Custom Context Windows (Manual)
  • Reference Image Selector
  • SDPose 空帧修复
  • SDPoseDrawKeypointsV2 脚部绘制模式
  • Folder Image Loader
  • Image Batch Concat
  • Image Batch Resize
  • WanAnimate Uni3C 运镜控制
  • Interactive Batch Crop (交互式批量裁剪)
  • MaskCompositeRef (遮罩批次合成 Ref)
• SCAIL-2 节点详解
  • Wan SCAIL To Video (Multi Ref)
  • Create SCAIL-2 Colored Mask (Multi Ref)
  • Wan SCAIL-2 Context Windows
• 依赖
• 工作流
  • 长视频姿态检测工作流
  • WanAnimate多参考图生成长视频工作流
  • WanSCAIL2 多参考图生成长视频工作流
• 使用示例
• 许可证

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

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

2. 安装 Python 依赖：

cd ComfyUI-CustomNodeKit
pip install -r requirements.txt

3. 重启 ComfyUI。

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

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

必选参数：

可选参数：

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

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

1. 帧数转换：context_length、context_overlap 均以像素帧为单位输入，节点内部自动转换为 latent 帧（每 4 像素帧 → 1 latent 帧）。
2. 前缀参考帧：设置 prefix_latent_num > 0 后，该数量的参考图 latent 会被追加到每个窗口开头作为稳定参考，适合需要全局上下文信息的生成任务。
3. freenoise：启用后会混洗噪声以改善窗口间的纹理连续性，建议在总帧数较长且重叠较小时开启。
4. causal_window_fix：启用后会在每个窗口前补入上一窗口 denoised 输出的末帧作为 anchor，有效保留脚印、地面交互等跨窗口连续性细节。注意这会强制窗口串行执行，降低并行度。

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

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

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

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

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

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

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

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

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

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

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

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

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

将图像批次缩放到指定宽高。可选择按方向裁剪以保持宽高比。输入无效时输出 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 缩放比），再按方向裁剪多余内容，保证最终输出尺寸精确等于目标宽高。

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

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

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

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

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

1. v4 架构：采用 monkey-patch 方式修改模型 forward_orig 方法，在 block 循环中精确控制注入时机
2. 时序对齐：通过 trim_latent 参数自动对齐 render_latent 与生成视频的时序偏移
3. 异步预取：控制信号采用 CPU→GPU 异步预取机制，与 block 计算重叠，最小化性能开销
4. step 控制：通过 start_percent / end_percent 控制控制信号在 denoising 过程中的生效范围

[WanUni3CLoader] → uni3c_controlnet ─┐
[渲染好的 latent] → render_latent ────┤
                                       ↓
[模型] → WanUni3CApply → model (已注入控制) → [KSampler] → [VAE Decode] → 输出

注意：WanUni3CApply 节点内置了 WanAnimateChannelPack 逻辑，如果传入了 positive/negative conditioning，会自动从其中提取 concat_latent_image，无需额外连接 WanAnimateChannelPack 节点。

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

节点支持两种图片源：

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

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

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

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

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

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

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

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

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

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

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

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

必选参数：

参考图参数：

姿态参数：

接续参数：

可选输入：

[多张参考图] → 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] → 输出视频

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

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

[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

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

1. conditioning 自动分片：节点内部自动识别 conditioning 中各字段的时间维布局，对 ref_mask_28ch（保留前 N 帧参考 + 按窗口切片视频部分）、driving_mask_28ch（按窗口切片）、pose_video_latent（按窗口切片）分别处理
2. 模型 patch：在模型 forward 入口自动应用 patch，在每次前向时根据当前窗口索引切片 ref_mask_28ch 和 driving_mask_28ch
3. 无需 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 流程进行姿态识别（配合自定义节点）

简要使用说明：

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

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

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

文件：WanAnimate_ref_pics_loop+context.json

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

简要使用说明：

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

文件：WanSCAIL2_ref_pics_loop+context.json

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

简要使用说明：

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

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

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

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

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

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

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

[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 — 实用节点

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

MIT License