ComfyUI 的 ControlNet 辅助预处理器

即插即用的 ComfyUI 节点集，用于生成 ControlNet 提示图。

“动漫风格，街头抗议场景，赛博朋克城市，一位粉色头发、金色眼睛的女性（正注视着观众）手持标语，上面用粗体霓虹粉字写着‘ComfyUI ControlNet Aux’”——基于 Flux.1 Dev 模型。

代码直接从 https://github.com/lllyasviel/ControlNet/tree/main/annotator 中相应文件夹复制而来，并与 Hugging Face Hub 相连。

所有版权及署名权归 https://github.com/lllyasviel 所有。

更新

请前往 更新页面 查看最新动态。

安装：

使用 ComfyUI 管理器（推荐）：

安装 ComfyUI 管理器，并按照其说明步骤安装本仓库。

其他方式：

如果您使用的是 Linux 系统，或在 Windows 上以非管理员账户运行，请确保 /ComfyUI/custom_nodes 和 comfyui_controlnet_aux 文件夹具有写入权限。

现在提供了一个 install.bat 脚本，若检测到便携式安装环境，则会自动执行便携式安装；否则将默认为系统安装，并假定您已按照 ComfyUI 的手动安装步骤操作。

如果您无法运行 install.bat（例如，您是 Linux 用户），请打开终端或命令行，执行以下操作：

• 导航至您的 /ComfyUI/custom_nodes/ 文件夹。
• 运行 git clone https://github.com/Fannovel16/comfyui_controlnet_aux/。
• 进入 comfyui_controlnet_aux 文件夹：
  • 对于便携式或虚拟环境：
    • 运行 path/to/ComfUI/python_embeded/python.exe -s -m pip install -r requirements.txt。
  • 对于系统 Python：
    • 运行 pip install -r requirements.txt。
• 启动 ComfyUI。

节点

请注意，本仓库仅支持用于生成提示图的预处理器（如人体轮廓、Canny 边缘等）。除 Inpaint 外的所有预处理器均已集成到 AIO 辅助预处理器 节点中。该节点可快速获取预处理结果，但无法设置预处理器自身的阈值参数。如需调整阈值，需直接使用对应的预处理器节点。

节点（分类按 Comfy 菜单中的类别划分）

线条提取器

预处理器节点	sd-webui-controlnet/其他	ControlNet/T2I-Adapter
二值线条	binary	control_scribble
Canny 边缘	canny	control_v11p_sd15_canny control_canny t2iadapter_canny
HED 软边缘线条	hed	control_v11p_sd15_softedge control_hed
标准线稿	standard_lineart	control_v11p_sd15_lineart
写实线稿	lineart（若启用 coarse 模式则为 lineart_coarse）	control_v11p_sd15_lineart
动漫线稿	lineart_anime	control_v11p_sd15s2_lineart_anime
漫画线稿	lineart_anime_denoise	control_v11p_sd15s2_lineart_anime
M-LSD 线条	mlsd	control_v11p_sd15_mlsd control_mlsd
PiDiNet 软边缘线条	pidinet	control_v11p_sd15_softedge control_scribble
涂鸦线条	scribble	control_v11p_sd15_scribble control_scribble
XDoG 涂鸦线条	scribble_xdog	control_v11p_sd15_scribble control_scribble
假涂鸦线条	scribble_hed	control_v11p_sd15_scribble control_scribble
TEED 软边缘线条	teed	controlnet-sd-xl-1.0-softedge-dexined control_v11p_sd15_softedge（理论上）
PiDiNet 涂鸦线条	scribble_pidinet	control_v11p_sd15_scribble control_scribble
AnyLine 线稿		mistoLine_fp16.safetensors mistoLine_rank256 control_v11p_sd15s2_lineart_anime control_v11p_sd15_lineart

法线与深度估计器

预处理器节点	sd-webui-controlnet/其他	ControlNet/T2I-Adapter
MiDaS 深度图	（法线）depth	control_v11f1p_sd15_depth control_depth t2iadapter_depth
LeReS 深度图	depth_leres	control_v11f1p_sd15_depth control_depth t2iadapter_depth
Zoe 深度图	depth_zoe	control_v11f1p_sd15_depth control_depth t2iadapter_depth
MiDaS 法线图	normal_map	control_normal
BAE 法线图	normal_bae	control_v11p_sd15_normalbae
MeshGraphormer 手部精修器（HandRefiner）	depth_hand_refiner	control_sd15_inpaint_depth_hand_fp16
Depth Anything	depth_anything	Depth-Anything
Zoe Depth Anything （本质上是 Zoe，但编码器被 DepthAnything 替换）	depth_anything	Depth-Anything
Normal DSINE		control_normal/control_v11p_sd15_normalbae
Metric3D 深度		control_v11f1p_sd15_depth control_depth t2iadapter_depth
Metric3D 法线		control_v11p_sd15_normalbae
Depth Anything V2		Depth-Anything

人脸与姿态估计器

预处理节点	sd-webui-controlnet/other	ControlNet/T2I-Adapter
DWPose 姿态估计器	dw_openpose_full	control_v11p_sd15_openpose control_openpose t2iadapter_openpose
OpenPose 姿态估计器	openpose (detect_body) openpose_hand (detect_body + detect_hand) openpose_faceonly (detect_face) openpose_full (detect_hand + detect_body + detect_face)	control_v11p_sd15_openpose control_openpose t2iadapter_openpose
MediaPipe 人脸网格	mediapipe_face	controlnet_sd21_laion_face_v2
动物姿态估计器	animal_openpose	control_sd15_animal_openpose_fp16

光流估计器

预处理节点	sd-webui-controlnet/other	ControlNet/T2I-Adapter
Unimatch 光流		DragNUWA

如何获取 OpenPose 格式的 JSON？

用户端

此工作流会将图像保存到 ComfyUI 的输出文件夹（与输出图像相同的位置）。如果您没有找到 Save Pose Keypoints 节点，请更新此扩展。

开发者端

对于 IMAGE 批次中的每一帧，可以使用 UI 上的 app.nodeOutputs 或 /history API 端点，从 DWPose 和 OpenPose 中获取对应于每帧的 OpenPose 格式 JSON 数组。AnimalPose 的 JSON 输出格式与 OpenPose JSON 类似：

[
    {
        "version": "ap10k",
        "animals": [
            [[x1, y1, 1], [x2, y2, 1],..., [x17, y17, 1]],
            [[x1, y1, 1], [x2, y2, 1],..., [x17, y17, 1]],
            ...
        ],
        "canvas_height": 512,
        "canvas_width": 768
    },
    ...
]

对于扩展开发者（例如 Openpose 编辑器）：

const poseNodes = app.graph._nodes.filter(node => ["OpenposePreprocessor", "DWPreprocessor", "AnimalPosePreprocessor"].includes(node.type))
for (const poseNode of poseNodes) {
    const openposeResults = JSON.parse(app.nodeOutputs[poseNode.id].openpose_json[0])
    console.log(openposeResults) //包含每帧 OpenPose JSON 的数组
}

对于 API 用户： JavaScript

import fetch from "node-fetch" //请确保在 "package.json" 中添加 "type": "module"
async function main() {
    const promptId = '792c1905-ecfe-41f4-8114-83e6a4a09a9f' //懒得 POST /queue
    let history = await fetch(`http://127.0.0.1:8188/history/${promptId}`).then(re => re.json())
    history = history[promptId]
    const nodeOutputs = Object.values(history.outputs).filter(output => output.openpose_json)
    for (const nodeOutput of nodeOutputs) {
        const openposeResults = JSON.parse(nodeOutput.openpose_json[0])
        console.log(openposeResults) //包含每帧 OpenPose JSON 的数组
    }
}
main()

Python

import json, urllib.request

server_address = "127.0.0.1:8188"
prompt_id = '' #懒得 POST /queue

def get_history(prompt_id):
    with urllib.request.urlopen("http://{}/history/{}".format(server_address, prompt_id)) as response:
        return json.loads(response.read())

history = get_history(prompt_id)[prompt_id]
for o in history['outputs']:
    for node_id in history['outputs']:
        node_output = history['outputs'][node_id]
        if 'openpose_json' in node_output:
            print(json.loads(node_output['openpose_json'][0])) #包含每帧 OpenPose JSON 的列表

语义分割

预处理节点	sd-webui-controlnet/other	ControlNet/T2I-Adapter
OneFormer ADE20K 分割器	oneformer_ade20k	control_v11p_sd15_seg
OneFormer COCO 分割器	oneformer_coco	control_v11p_sd15_seg
UniFormer 分割器	segmentation	control_sd15_seg control_v11p_sd15_seg

仅 T2IAdapter

预处理节点	sd-webui-controlnet/other	ControlNet/T2I-Adapter
色彩调色板	color	t2iadapter_color
内容打乱	shuffle	t2iadapter_style

重新着色

预处理节点	sd-webui-controlnet/other	ControlNet/T2I-Adapter
图像亮度	recolor_luminance	ioclab_sd15_recolor sai_xl_recolor_256lora bdsqlsz_controlllite_xl_recolor_luminance
图像强度	recolor_intensity	不清楚。也许和上面一样？

示例

一张图片胜过千言万语

测试工作流

https://github.com/Fannovel16/comfyui_controlnet_aux/blob/main/examples/ExecuteAll.png 输入图像：https://github.com/Fannovel16/comfyui_controlnet_aux/blob/main/examples/comfyui-controlnet-aux-logo.png

问答：

为什么安装了这个仓库后有些节点没有出现？

该仓库采用了一种新机制，会跳过无法导入的自定义节点。如果遇到这种情况，请在 Issues 标签页 上提交问题，并附上命令行日志。

DWPose/AnimalPose 只使用 CPU，速度很慢。如何让它使用 GPU？

加速 DWPose 的方法有两种：使用 TorchScript 检查点（.torchscript.pt）或 ONNXRuntime（.onnx）。TorchScript 方法比 ONNXRuntime 略慢，但不需要额外的库，而且仍然比 CPU 快得多。

TorchScript 边界框检测器与 ONNX 姿态估计器是兼容的，反之亦然。

TorchScript

按照这张图设置 bbox_detector 和 pose_estimator。如果输入图像质量较好，可以尝试使用以 .torchscript.pt 结尾的其他边界框检测器，以缩短边界框检测时间。

ONNXRuntime

如果 ONNXRuntime 已成功安装，并且所使用的检查点文件名以 .onnx 结尾，则会替换默认的 OpenCV 后端，从而利用 GPU 加速。请注意，如果您使用的是 NVIDIA 显卡，目前此方法仅适用于 CUDA 11.8 版本（ComfyUI_windows_portable_nvidia_cu118_or_cpu.7z），除非您自行编译 ONNXRuntime。

1. 确认您的 ONNXRuntime 构建版本：
   • NVIDIA CUDA 11.x 或更低版本/AMD GPU：onnxruntime-gpu
   • NVIDIA CUDA 12.x：onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-12/pypi/simple/
   • DirectML：onnxruntime-directml
   • OpenVINO：onnxruntime-openvino

请注意，如果您是首次使用 ComfyUI，请先测试其是否能在您的设备上正常运行，再进行后续步骤。

2. 将其添加到 requirements.txt 文件中。

3. 运行 install.bat 脚本，或按照安装说明中的 pip 命令进行安装。

预处理工具的资产文件

• anime_face_segment: bdsqlsz/qinglong_controlnet-lllite/Annotators/UNet.pth, anime-seg/isnetis.ckpt
• densepose: LayerNorm/DensePose-TorchScript-with-hint-image/densepose_r50_fpn_dl.torchscript
• dwpose:
• • bbox_detector: 可以是 yzd-v/DWPose/yolox_l.onnx、hr16/yolox-onnx/yolox_l.torchscript.pt、hr16/yolo-nas-fp16/yolo_nas_l_fp16.onnx、hr16/yolo-nas-fp16/yolo_nas_m_fp16.onnx 或者 hr16/yolo-nas-fp16/yolo_nas_s_fp16.onnx
• • pose_estimator: 可以是 hr16/DWPose-TorchScript-BatchSize5/dw-ll_ucoco_384_bs5.torchscript.pt 或者 yzd-v/DWPose/dw-ll_ucoco_384.onnx
• animal_pose (ap10k):
• • bbox_detector: 可以是 yzd-v/DWPose/yolox_l.onnx、hr16/yolox-onnx/yolox_l.torchscript.pt、hr16/yolo-nas-fp16/yolo_nas_l_fp16.onnx、hr16/yolo-nas-fp16/yolo_nas_m_fp16.onnx 或者 hr16/yolo-nas-fp16/yolo_nas_s_fp16.onnx
• • pose_estimator: 可以是 hr16/DWPose-TorchScript-BatchSize5/rtmpose-m_ap10k_256_bs5.torchscript.pt 或者 hr16/UnJIT-DWPose/rtmpose-m_ap10k_256.onnx
• hed: lllyasviel/Annotators/ControlNetHED.pth
• leres: lllyasviel/Annotators/res101.pth, lllyasviel/Annotators/latest_net_G.pth
• lineart: lllyasviel/Annotators/sk_model.pth, lllyasviel/Annotators/sk_model2.pth
• lineart_anime: lllyasviel/Annotators/netG.pth
• manga_line: lllyasviel/Annotators/erika.pth
• mesh_graphormer: hr16/ControlNet-HandRefiner-pruned/graphormer_hand_state_dict.bin, hr16/ControlNet-HandRefiner-pruned/hrnetv2_w64_imagenet_pretrained.pth
• midas: lllyasviel/Annotators/dpt_hybrid-midas-501f0c75.pt
• mlsd: lllyasviel/Annotators/mlsd_large_512_fp32.pth
• normalbae: lllyasviel/Annotators/scannet.pt
• oneformer: lllyasviel/Annotators/250_16_swin_l_oneformer_ade20k_160k.pth
• open_pose: lllyasviel/Annotators/body_pose_model.pth, lllyasviel/Annotators/hand_pose_model.pth, lllyasviel/Annotators/facenet.pth
• pidi: lllyasviel/Annotators/table5_pidinet.pth
• sam: dhkim2810/MobileSAM/mobile_sam.pt
• uniformer: lllyasviel/Annotators/upernet_global_small.pth
• zoe: lllyasviel/Annotators/ZoeD_M12_N.pt
• teed: bdsqlsz/qinglong_controlnet-lllite/7_model.pth
• depth_anything: 可以是 LiheYoung/Depth-Anything/checkpoints/depth_anything_vitl14.pth、LiheYoung/Depth-Anything/checkpoints/depth_anything_vitb14.pth 或者 LiheYoung/Depth-Anything/checkpoints/depth_anything_vits14.pth
• diffusion_edge: 可以是 hr16/Diffusion-Edge/diffusion_edge_indoor.pt、hr16/Diffusion-Edge/diffusion_edge_urban.pt 或者 hr16/Diffusion-Edge/diffusion_edge_natrual.pt
• unimatch: 可以是 hr16/Unimatch/gmflow-scale2-regrefine6-mixdata.pth、hr16/Unimatch/gmflow-scale2-mixdata.pth 或者 hr16/Unimatch/gmflow-scale1-mixdata.pth
• zoe_depth_anything: 可以是 LiheYoung/Depth-Anything/checkpoints_metric_depth/depth_anything_metric_depth_indoor.pt 或者 LiheYoung/Depth-Anything/checkpoints_metric_depth/depth_anything_metric_depth_outdoor.pt

2000 颗星 😄

感谢大家的支持！真没想到星星数量的增长会这么线性，哈哈。

ComfyUI ControlNet Aux 快速上手指南

comfyui_controlnet_aux 是 ComfyUI 的插件，提供了一系列即插即用的节点，用于生成 ControlNet 所需的提示图（如线稿、深度图、姿态图等）。其核心算法源自 ControlNet 官方仓库。

环境准备

• 系统要求：Windows、Linux 或 macOS。
• 前置依赖：
  • 已安装并配置好 ComfyUI。
  • 推荐安装 ComfyUI Manager 以简化插件管理。
  • Python 环境（若使用便携版 ComfyUI 则无需单独配置系统 Python）。
• 网络建议：首次运行时会自动从 Hugging Face 下载模型权重。国内用户若下载缓慢，建议配置本地代理或使用 Hugging Face 镜像源。

安装步骤

方法一：通过 ComfyUI Manager 安装（推荐）

1. 启动 ComfyUI，点击右侧菜单的 Manager 按钮。
2. 选择 Install Custom Nodes。
3. 在搜索框输入 controlnet aux。
4. 找到 ComfyUI's ControlNet Auxiliary Preprocessors，点击 Install。
5. 安装完成后重启 ComfyUI。

方法二：手动安装

如果无法使用 Manager 或在 Linux/无管理员权限环境下，请按以下步骤操作：

1. 进入 ComfyUI 的自定义节点目录：

   cd /path/to/ComfyUI/custom_nodes/
   

2. 克隆仓库：

   git clone https://github.com/Fannovel16/comfyui_controlnet_aux/
   

3. 进入插件目录并安装依赖：

   • 如果是 ComfyUI 便携版 (Portable/venv)：

     cd comfyui_controlnet_aux
     /path/to/ComfyUI/python_embeded/python.exe -s -m pip install -r requirements.txt
     

     (注：请将 /path/to/ComfyUI/ 替换为你的实际安装路径)

   • 如果是系统全局 Python 环境：

     cd comfyui_controlnet_aux
     pip install -r requirements.txt
     

4. 重启 ComfyUI。

Windows 用户提示：目录下包含 install.bat，双击运行可自动检测便携版环境并完成安装。

基本使用

安装成功后，重启 ComfyUI，你可以在节点菜单中找到 ControlNet Preprocessors 分类。

核心节点说明

• AIO Aux Preprocessor：全能预处理节点。集成了除 Inpaint 外的所有预处理器，可通过下拉菜单快速切换类型（如 Canny, OpenPose, Depth 等）。
  • 优点：调用快捷，无需查找特定节点。
  • 缺点：无法调整该预处理器特有的阈值参数。
• 独立预处理器节点：如需精细控制（例如调整 Canny 的高低阈值或 OpenPose 的检测模型），请直接搜索并使用对应的独立节点（如 Canny Edge Preprocessor, DWPose Estimator 等）。

最简单工作流示例

以下是一个生成“线稿控制图”的基础流程：

1. 加载图像：添加 Load Image 节点，上传一张参考图片。
2. 预处理：
   • 添加 Canny Edge Preprocessor 节点（或在 AIO Aux Preprocessor 中选择 canny）。
   • 将 Load Image 的输出连接到预处理节点的 image 输入端。
3. 应用 ControlNet：
   • 添加 ControlNet Apply 节点。
   • 加载对应的 ControlNet 模型（例如 control_v11p_sd15_canny）。
   • 将预处理节点的输出连接到 ControlNet Apply 的 image 输入端。
4. 生成图像：连接 KSampler 和 Checkpoint 进行绘图。

节点连接逻辑示意： Load Image -> [Preprocessor Node] -> ControlNet Apply (image) -> KSampler

进阶提示：获取 OpenPose JSON 数据

如果你需要提取姿态数据的 JSON 文件用于其他开发：

• 用户侧：使用 Save Pose Keypoints 节点，它会将 JSON 保存到 ComfyUI 的 output 文件夹中。
• 开发侧：可通过 API /history/{prompt_id} 获取输出结果中的 openpose_json 字段，解析后即可得到标准的 OpenPose 格式坐标数据。