Extensions/ComfyUI QBB PenTool
ComfyUI Extension

ComfyUI QBB PenTool

Pen tool editor for ComfyUI: paths, shapes, selections, text, brushes, and multi-image layers. Outputs composite image, mask, stroke layer, alpha image, and path JSON.

By rhinoflavored·Created 19 days ago·Updated 19 days ago· 0
rhinoflavored/ComfyUI_QBB_PenTool
Nodes—
On cloudLocal install
Stars0
Updated19 days ago
Readme

ComfyUI_QBB_PenTool — ComfyUI 钢笔工具节点

在 ComfyUI 中用钢笔（含贝塞尔曲线）在底图或空白画布上绘制路径，输出合成图、蒙版、透明描边层、带 alpha 的合成图与路径 JSON。

安装

方式一：ComfyUI Manager / Registry（推荐）

  1. 打开 ComfyUI Manager → Install Custom Nodes
  2. 搜索 QBB PenTool 或 qbb-pentool
  3. 安装后 重启 ComfyUI

也可用 CLI：

comfy node install qbb-pentool

节点需已发布到 Comfy Registry。若搜不到，说明尚未完成 Registry 发布，请用下方手动安装。

方式二：手动安装

将整个 ComfyUI_QBB_PenTool 文件夹复制到：

ComfyUI/custom_nodes/ComfyUI_QBB_PenTool

然后 完全重启 ComfyUI。

若曾安装过旧目录名 comfyui_QBB_penTool / penTool，请从 custom_nodes 中 删除旧文件夹，只保留本目录，避免重复加载或节点冲突。

依赖：ComfyUI 自带 torch、numpy、Pillow（无需额外 pip 安装）。

节点：QBB_PenTool

在节点菜单 QBB → ComfyUI_QBB_PenTool 中查找，或直接搜索 QBB_PenTool。

节点类型 ID 仍为 QBB_PenTool（与工作流 JSON 兼容）；安装目录与菜单分类使用 ComfyUI_QBB_PenTool。

输入

| 名称 | 说明 | |------|------| | image（可选） | 底图，可不连接。可接 单张或批量 IMAGE；连接后会自动出现下一个 image_2… 口，可同时接多路加载图像。编辑器右侧 图层 可移动/叠放/显隐；画布宽高在「画布」页设置。旧工作流无图层数据时，仍按「第 0 张铺满画布」兼容。 | | path_data | 内部路径数据（节点界面已隐藏，由编辑器自动写入；查看/导出请用 path_json 输出）。 |

画布宽高、背景（纯色/线性/径向渐变）、路径与选区填充渐变、线宽、蒙版羽化等均在 钢笔编辑器 内设置（写入 path_data / path_json 的 canvas 与 styles）。

输出

| 名称 | 说明 | |------|------| | image | 底图 + 描边/选区可视化合成（RGB）。 | | mask | 闭合选区蒙版；无闭合选区时为全黑。 | | stroke_image | RGBA 透明底纯描边/选区叠加层。 | | image_alpha | image 的 RGB + mask 作 alpha 的 RGBA 图（选区外透明）。 | | path_json | 与本次栅格化一致的 v2 路径 JSON。排队执行时会自动把未关闭的编辑器内容写入 path_data。 |

使用（重要）

Queue Prompt / 运行工作流不会弹出钢笔界面。 钢笔编辑器是前端工具，需要手动打开：

  1. 添加 QBB_PenTool 节点（若节点是更新插件前添加的，请删掉重新拖一个）。
  2. 在节点参数区点击 「打开钢笔编辑器」 按钮；或 双击节点；或 右键 → 打开钢笔编辑器。
  3. 弹层顶部 画布 / 样式：画布宽高背景；样式随左侧工具切换路径或选区属性。左侧有 移动 / 画笔 / 钢笔 / 形状 / 文字 / 选区；顶栏有 撤销 / 重做（Ctrl+Z / Ctrl+Y）。选中 文字 时顶栏出现字体属性；选中 画笔 时顶栏以缩略图选择笔刷（brush/ 支持 .abr、Procreate .brush / .brushset，可附同名 .jpg/.png 预览）。
  4. 点左侧 选区 进入选区模式，用左侧 选区运算 选择布尔方式后绘制闭合区域：
    • 新选区 / 添加 / 减去 / 交集（仅按钮，无快捷键）
    • 选区内可用 形状 画矩形等框选；再点 选区 可回到钢笔选区
    • 形状工具：Shift 等比、Alt 从中心绘制
    • 曲线手柄：选区模式下 Ctrl+点击 锚点拖手柄
  5. 点 完成 保存并关闭；✕ 关闭不保存；⛶ 全屏/还原；标题栏可拖拽，边缘可缩放窗口。

修改 JS 后请 Ctrl+F5 强制刷新浏览器；修改 Python 后需 重启 ComfyUI。

验证前端是否加载

打开浏览器开发者工具（F12）→ Console，应看到：

[ComfyUI_QBB_PenTool] 前端扩展已加载...

若没有此行，说明 JS 未加载，请确认路径为 custom_nodes/ComfyUI_QBB_PenTool/js/pen_tool_extension.js 且已重启/刷新。

路径 JSON 格式

见 OUTLINE.md 第 5 节。支持 segment 类型：M、L、C（Q 可选）。

文件结构

ComfyUI_QBB_PenTool/
  __init__.py
  nodes.py
  path_raster.py
  gradients.py
  js/pen_tool_extension.js
  OUTLINE.md

节点找不到 / 编辑器打不开时

  1. 确认文件夹名为 ComfyUI_QBB_PenTool，且位于 ComfyUI/custom_nodes/ComfyUI_QBB_PenTool/。
  2. 删除 custom_nodes 下旧的 comfyui_QBB_penTool / penTool 目录（若仍存在）。
  3. 完全重启 ComfyUI（不是只刷新页面）。
  4. 查看启动终端是否有 [ComfyUI_QBB_PenTool] 节点加载失败 及 traceback。
  5. 常见原因：环境缺少 torch / Pillow，或与其他插件的 nodes 模块冲突（本包已用独立模块名 ComfyUI_QBB_PenTool_nodes 规避）。

说明

  • stroke_image / image_alpha 为 4 通道 RGBA；若下游节点只接受 3 通道 RGB，请先用支持 RGBA 的节点或自行拆分 alpha。
  • 有底图时前端弹层会尝试显示上游节点预览图；若未显示预览，仍按底图尺寸编辑，执行后 Python 侧使用真实张量。