XT Matte Toolbox ComfyUI Node

这个仓库是一个独立的 ComfyUI 自定义节点项目，节点名为 XT Matte Cutout。

它复用你原工程里的核心抠图逻辑（src/），只做节点封装，不包含桌面 UI / Photoshop COM / 授权弹窗等 Windows 专属功能。

目录结构

xt-matte-toolbox-comfyui-node/
  __init__.py
  nodes.py
  requirements.txt
  README.md

节点能力

输入：

• image (IMAGE)
• model_name（General/Matting/Portrait 等）
• resolution、semi_transparent、semi_strength
• defringe、defringe_strength
• 可选 roi_mask (MASK) 及 ROI 控制参数

输出：

• foreground (IMAGE)：前景 RGB
• alpha_mask (MASK)：透明度
• mask_preview (IMAGE)：蒙版预览图

安装方式

1. 把本仓库克隆到 ComfyUI/custom_nodes：

git clone <your_repo_url> ComfyUI/custom_nodes/xt-matte-toolbox-comfyui-node

2. 安装依赖（在 ComfyUI 的 Python 环境里）：

pip install -r ComfyUI/custom_nodes/xt-matte-toolbox-comfyui-node/requirements.txt

3. 指定你的核心项目根目录（必须能看到 src/models/loader.py）：

Windows PowerShell:

$env:XT_MATTE_PROJECT_ROOT="E:\抠图工具箱\小T抠图工具箱5.1.0"
python main.py

Linux/macOS:

export XT_MATTE_PROJECT_ROOT=/path/to/your/project
python main.py

关键参数建议

• model_name
  • 质量优先：Matting / Portrait
  • 速度优先：General-Lite
• resolution
  • 建议从 1024 起，显存不足可降到 768/512
• semi_transparent
  • 处理发丝/薄纱/玻璃等半透明边缘
• defringe
  • 去白边，强度建议 0.5~0.8
• roi_mask
  • 做局部抠图、减少误抠

模型加载与目录

节点会沿用你原项目的模型逻辑：

• 先找本地 models_local
• 没有则尝试从 HuggingFace 下载

默认模型目录基于：

• XT_MATTE_BASE_DIR（节点会自动设为项目根目录）
• 结果通常是：<XT_MATTE_BASE_DIR>/models_local

常见问题

1. 节点不显示 检查是否放在 ComfyUI/custom_nodes/xt-matte-toolbox-comfyui-node，并重启 ComfyUI。

2. 报 Project root not found 说明没找到你的 src/，请设置 XT_MATTE_PROJECT_ROOT。

3. 模型下载失败 检查网络、transformers/huggingface-hub 依赖、或手动放置模型到 models_local/<模型目录>/。

4. OOM 显存不足 降低 resolution，换 General-Lite，或降低批量。

二次开发入口

核心封装文件：

• nodes.py

推荐开发顺序：

1. 先改你主项目里的核心逻辑（src/processors/image_processor.py）
2. 再映射到 nodes.py 的 INPUT_TYPES 和 matte() 参数

这样桌面版和 ComfyUI 版逻辑可以保持一致，维护成本最低。