ComfyUI Custom Node Plugin

AI 人像抠图
智能头像裁切

结合 BiRefNet 前景提取与 SAM3 人脸定位,实现 Photoshop 级别的图层蒙版工作流——干净的人物抠图,配合羽化边缘的圆形或方形裁切,不拉伸、不模糊。

5
核心节点
2
AI 模型
6
BiRefNet 变体
MIT
开源协议

功能特性

从前景提取到最终输出,一站式人像头像处理工作流

BiRefNet 前景抠图

基于 BiRefNet 深度学习模型,精确提取人物前景。支持 6 种模型变体,从通用场景到专业肖像,覆盖不同使用需求。

SAM3 人脸定位

利用 Meta SAM3 分割模型的文本提示能力,智能定位人脸/头部区域。支持多提示词组合,兼容真人、动漫、游戏角色等多种风格。

PS 级裁切蒙版

方形/圆形透明裁切,配合可调羽化边缘。只羽化裁切形状边缘,不模糊人物边缘——真正的 Photoshop 图层蒙版体验。

无损缩放输出

等比缩放到透明画布,不改变裁切形状、宽高比或透明背景。支持多种重采样方式,自动选择最优插值算法。

灵活背景合成

保持透明、叠加背景图或填充纯色。智能检测不透明图像并跳过处理,支持 cover/stretch 两种背景适配模式。

批量图片加载

支持多图上传和文件夹路径批量读取。自动处理尺寸不一致问题,输出标准 ComfyUI IMAGE/MASK batch,可连接任意节点。

节点说明

5 个核心节点,覆盖从图片加载到最终输出的完整链路

ZcutBatchLoadImages 批量图片加载

通用批量图片加载节点。支持多图上传和文件夹路径读取,输出标准 ComfyUI IMAGE/MASK batch,可连接到其他原生或第三方节点。

输入
  • upload_mode
    multi_upload / folder_path
    COMBO
  • folder_path
    文件夹路径(folder_path 模式)
    STRING
  • recursive
    是否递归子文件夹
    BOOLEAN
  • size_mode
    pad_to_largest / resize_to_first / skip_mismatched
    COMBO
  • image_load_limit
    最大加载数量,0 为不限
    INT
输出
  • images
    IMAGE
  • masks
    MASK
  • file_paths
    STRING
  • count
    INT
ZcutBiRefNetSAM3FaceCrop BiRefNet SAM3 人脸裁切

核心节点。结合 BiRefNet 前景抠图与 SAM3 人脸定位,生成透明背景的人像/头像裁切图。支持方形/圆形裁切、边缘羽化、Alpha 去污染等高级功能。

输入
  • image
    ComfyUI 图像输入
    IMAGE
  • birefnet_model
    BiRefNet 模型变体
    COMBO
  • crop_width / crop_height
    裁切尺寸 (64–8192px)
    INT
  • shape
    square / circle
    COMBO
  • feather_edges / feather_px
    裁切边缘羽化开关及半径
    BOOL/INT
  • sam3_prompt
    SAM3 定位提示词(逗号分隔)
    STRING
  • enable_cutout
    是否启用 BiRefNet 抠图
    BOOLEAN
  • source_transparency_mask
    可选,透明 PNG 的 alpha
    MASK
输出
  • cropped_image
    RGBA 透明背景裁切图
    IMAGE
  • crop_mask
    最终 alpha mask
    MASK
  • birefnet_mask
    BiRefNet 原始前景 mask
    MASK
  • shape_mask
    裁切形状 mask(含羽化)
    MASK
ZcutResizeOutput 最终尺寸调整

裁切后调整最终头像输出尺寸。等比缩放并居中放入透明画布,不改变裁切形状、宽高比或透明背景。

输入
  • image
    IMAGE
  • resize_output
    启用/禁用缩放
    BOOLEAN
  • output_width / output_height
    INT
  • resample_method
    auto / nearest / bilinear / area / bicubic / lanczos
    COMBO
  • mask
    可选,同步缩放的 mask
    MASK
输出
  • resized_image
    IMAGE
  • resized_mask
    MASK
ZcutModelUpscale 图像超分放大

使用 ComfyUI models/upscale_models 中的放大模型进行图像超分辨率或尺寸调整。支持超采样、倍数对齐等高级选项。

输入
  • image
    IMAGE
  • upscale_model
    放大模型名称
    COMBO
  • mode
    rescale / resize
    COMBO
  • supersample
    超采样至目标尺寸
    BOOLEAN
输出
  • upscaled_image
    IMAGE
  • upscaled_mask
    MASK
ZcutAddBackground 添加背景

只在图像存在透明像素时添加背景。不透明图像直接透传。支持透明保持、背景图合成和纯色填充三种模式。

输入
  • image
    IMAGE
  • background_mode
    transparent / image / color
    COMBO
  • background_color
    使用 ComfyUI 原生拾色器
    COLOR
  • background_fit
    cover / stretch
    COMBO
  • background_mask
    可选,裁切形状 mask
    MASK
  • background_image
    可选,上传背景图
    IMAGE
输出
  • image
    IMAGE
  • mask
    MASK

工作流程

从原始图片到最终头像,五个步骤完成专业级人像裁切

1

加载图片

通过 Zcut Batch Load Images 节点加载单张或多张图片。支持多图上传、文件夹路径批量读取,自动处理尺寸差异。

PIL / Pillow EXIF 自动校正 RGBA Alpha 保留
2

前景抠图 + 人脸定位

BiRefNet 提取人物前景 mask,SAM3 通过文本提示定位人脸/头部区域。评分系统综合位置、大小、肤色等因素选择最佳裁切中心。

BiRefNet SAM3 PyTorch BFloat16 推理
3

裁切 + 形状蒙版

以人脸为中心裁切指定尺寸,叠加方形或圆形裁切蒙版。边缘羽化只影响裁切形状,不模糊人物边缘。Alpha 边界自动去污染。

OpenCV Gaussian Blur 羽化 Distance Transform 去污染
4

尺寸调整 / 超分放大

可选步骤。使用 Zcut Resize Output 等比缩放到目标画布,或使用 Zcut Image Upscale 通过放大模型进行超分辨率增强。

Premultiplied Alpha Spandrel 模型加载 Tiled 推理
5

背景合成输出

最终步骤。保持透明背景、叠加背景图或填充纯色。智能检测不透明图像直接透传,支持 cover/stretch 背景适配。

Alpha 合成 ComfyUI COLOR 拾色器 RGB 清理

模型依赖

首次使用时自动从 Hugging Face 下载,也支持离线手动放置

BiRefNet

BiRefNet-general

通用前景提取模型,默认选项。适用于大多数场景的人物抠图。

分辨率: 1024px 格式: safetensors
BiRefNet

BiRefNet-portrait

专为人像优化的抠图模型,在人物边缘处理上更加精细。

分辨率: 1024px 格式: safetensors
BiRefNet

BiRefNet-HR-matting

高分辨率精细抠图模型,处理复杂背景和毛发细节。

分辨率: 2048px 格式: safetensors
BiRefNet

BiRefNet_512x512

轻量级快速抠图模型,适合对速度要求较高的场景。

分辨率: 512px 格式: safetensors
SAM3

SAM3 Image Model

Meta SAM3 图像分割模型,通过文本提示定位人脸/头部区域,支持多提示词组合。

来源: facebook/sam3 备用: AB498/sam3
SAM3

SAM3 BPE 词表

SAM3 文本编码器使用的 BPE 分词词表文件,支持文本提示解析。

文件: bpe_simple_vocab_16e6.txt.gz 大小: ~4MB

快速安装

三步完成安装,首次运行自动下载模型

bash
# 1. 克隆到 ComfyUI 自定义节点目录 cd ComfyUI/custom_nodes git clone https://github.com/doro1106/ComfyUI-Zcut.git # 2. 安装 Python 依赖(也可让插件自动安装) cd ComfyUI-Zcut pip install -r requirements.txt # 3. 重启 ComfyUI,首次使用节点时自动下载模型 # 模型来源:BiRefNet → 1038lab/BiRefNet # SAM3 → facebook/sam3 (备用: AB498/sam3) # 可选:自定义 Hugging Face 镜像源 export ZCUT_BIREFNET_HF_REPO=1038lab/BiRefNet export ZCUT_SAM3_HF_REPOS=facebook/sam3,AB498/sam3
python — requirements.txt
transformers>=4.39.0 timm opencv-python Pillow numpy safetensors huggingface-hub>=0.19.0 hf-xet iopath>=1.0.9 ftfy regex typing_extensions scipy