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

当前版本：1.4.2 — 新增 WanSparseAttention 稀疏注意力节点、SCAIL 混合编码模式、参考图选择器背景图位置优化、上下文窗口金字塔融合边界修正。

• 安装
• 节点列表
  • 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 运镜控制
• 依赖
• 工作流
  • 长视频姿态检测工作流
  • 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）从多角度参考图中选取最佳匹配。

1. 未接入 yaw_angles 或 angle_map 无效：直接输出全部参考图（第 0 张×1 + 其余各×4）。
2. 有 yaw_angles 输入：
   • 计算偏航角范围 [min, max]
   • 筛选所有在此范围内的参考图 + 左右各最邻近一张
   • 选出覆盖帧数最多的参考图作为主参考图（排在第 0 位）
   • 辅助参考图按与首帧偏航角的偏差从大到小排列
   • 若主参考图恰好最贴合首帧偏航角，末尾追加主参考图副本
3. 输出批次格式：第 0 张（主参考图）×1，其余辅助参考图各×4（符合 WanAnimate 的 concat 格式要求）

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

提示：angle_map 输入可直接连接前端 JS 节点 Angle Map Config 来可视化配置角度映射。

在 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 节点。

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