Extensions/ComfyUI_Swwan
ComfyUI Extension

ComfyUI_Swwan

Collection of image processing utility nodes for ComfyUI including intelligent cropping, aspect ratio scaling, and crop box restoration capabilities. (Description by CC)

By aining2022·Created 10 months ago·Updated 6 days ago· 34
aining2022/ComfyUI_Swwan
Nodes118
On cloudLocal install
CategorySwwan/Utils, Swwan/Advanced/Utils
Stars34
Updated6 days ago

Nodes (118)

Any Boolean Switch (Swwan)

A switch that skips work it doesn't need

Swwan/Utils
Any Switch (Swwan)

Use A if you've got it, else B

Swwan/Advanced/Utils
Batch Slice (Swwan)

Cut a list down to the frames you actually want

Swwan/Advanced/Batch
Bounded Image Crop (Swwan)

Crop with a bounding box, not a blind guess

Swwan/Advanced/Image
Bounded Image Crop With Mask (Swwan)

Find the mask, crop around it, keep the box

Swwan/Advanced/Image
Image Blend (Swwan)

Layering images without leaving ComfyUI

Swwan/Image
Image Resize By Megapixels (Swwan)

Target megapixels, not random pixel sizes

Swwan/Image
Resize Image (Swwan)

The resize node that finally settles crop-vs-pad-vs-blur

Swwan/Image
Image Resize Sum (Swwan)

Resize, pad or crop an image — and keep the receipt to undo it

Swwan/Advanced/Image
Image Resize Sum Data (Swwan)

Unpack the resize math from Image_Resize_sum

Swwan/Advanced/Image
Image Resize Sum Restore (Swwan)

Paste a resized image back onto its original canvas

Swwan/Advanced/Image
Insert Latent To Index (Swwan)

The name is a lie — it replaces, it doesn't insert

Swwan/Advanced/Batch
IO Save Image (Swwan) · 旧版兼容

A save node with real control over the filename

Swwan/Legacy
IO Save Image Format (Swwan) · 旧版兼容

A saver tuned for the tail end of a queue

Swwan/Legacy
ColorImage (Swwan)

A solid-color canvas in one node

Swwan/Image
CropByMask V4 (Swwan) · 旧版兼容

Smart crop that knows what the mask means

Swwan/Legacy
RestoreCropBox V2 (Swwan) · 旧版兼容

Put the crop back where it came from

Swwan/Legacy
List Merge (Swwan)

Splice any number of lists into one

Swwan/Advanced/Batch
List Num Range (Swwan)

Generating evenly spaced number sequences in ComfyUI

Swwan/Advanced/Batch
List Slice (Swwan)

Python slicing, as a node

Swwan/Advanced/Batch
List Value (Swwan)

Keyframed, eased value schedules for ComfyUI animation

Swwan/Advanced/Batch
Mask Transform Sum (Swwan)

The all-in-one mask preview, crop, and style node

Swwan/Advanced/Mask
Math Calculate (Swwan) · 旧版兼容

One node instead of ten to do arithmetic in your workflow

Swwan/Legacy
Math Expression (Swwan)

One node for every calculation — with image width/height and a few tricks

Swwan/Utils
Math Remap Data (Swwan)

Rescale a value into a new range, with easing

Swwan/Advanced/Utils
Merge Batch (Swwan)

Concatenate every batch you feed it

Swwan/Advanced/Batch
MiniMax H3 Mem Eff Sage Attention Patch (KJ Alternative) (Swwan)

The VRAM patch

Swwan/Advanced/Model
Patch Sage Attention KJ (KJ Alternative) (Swwan)

SageAttention, minus the KJNodes dependency

Swwan/Advanced/Model
Raise Exception On True (Swwan)

Kill a ComfyUI run the moment a check fails

Swwan/Advanced/Utils
RGBA Multi Save (Swwan) · 旧版兼容

Saving transparent PNGs without the white fringes

Swwan/Legacy
RGBA Safe Post (Swwan)

How to get your colors back after RGB-only nodes wreck your alpha

Swwan/RGBA
RGBA Safe Pre (Swwan)

The reason your transparent PNGs don't end up with ugly fringes

Swwan/RGBA
RGBA Save (Swwan)

The dedicated PNG writer that finally keeps your transparency

Swwan/RGBA
Schedule Image (Swwan)

Pick one frame out of a batch by index

Swwan/Advanced/Scheduling
Schedule Mask (Swwan)

Pick one mask out of a batch by index

Swwan/Advanced/Scheduling
Schedule Prompt (Swwan)

Keyframe Prompt Scheduling Straight to CONDITIONING

Swwan/Advanced/Scheduling
Schedule Split Text (Swwan)

Split a String and Pick One Piece per Frame

Swwan/Advanced/Scheduling
Schedule Text (Swwan)

Raw Keyframe-Scheduled Prompt Text, Before It Hits CLIP

Swwan/Advanced/Scheduling
Schedule Value (Swwan)

Schedule a Number (CFG, Strength, Denoise) Across Frames

Swwan/Advanced/Scheduling
Add Label (Swwan)

Burn text onto a whole batch without opening Photoshop

Swwan/Advanced/IO
Blockify Mask (Swwan)

Snap any ragged mask to a clean grid of blocks

Swwan/Mask
Color Converter (Swwan)

One colour in, three formats out, no calculator

Swwan/Image
Color Match (Swwan)

Make this image wear that image's palette

Swwan/Advanced/Image
Color Shift Fix (Swwan)

Fix the washed-out color cast that video inpainting leaves behind

Swwan/Advanced/Image
CropByMask V2 (Swwan) · 旧版兼容

The legacy crop that still hands you a BOX

Swwan/Legacy
CropByMask V3 (Swwan) · 旧版兼容

The mask-image variant, and its two odd quirks

Swwan/Legacy
Mask Crop (Swwan)

Batch-aware mask cropping that keeps one stable box across a whole video

Swwan/Image
Cross Fade Images (Swwan)

Fade out of one batch, into another

Swwan/Advanced/Image
Cross Fade Images Multi (Swwan)

Chain five clips with fades between them

Swwan/Advanced/Image
Draw Mask On Image (Swwan)

The node that eats Wan workflows, and how to un-break it

Swwan/Advanced/Image
Fast Preview (Swwan)

Base64 previews so you stop filling your temp folder

Swwan/Advanced/IO
Get Image Range From Batch (Swwan)

Slice the frames you actually want

Swwan/Batch
Get Images From Batch Indexed (Swwan)

Pick frames by number, in any order

Swwan/Advanced/Batch
Get Image Size & Count (Swwan)

The node that tells you what you actually have

Swwan/Advanced/Image
Get Latent Range From Batch (Swwan)

Slice frames before you ever decode them

Swwan/Advanced/Batch
Get Latent Size & Count (Swwan)

Is this a video latent or just an image batch?

Swwan/Advanced/Batch
Image Add Multi (Swwan)

Blend N images with add, subtract, multiply or difference

Swwan/Advanced/Image
Image And Mask Preview (Swwan)

See the mask on the image before you burn GPU time

Swwan/Advanced/IO
Image Batch Extend With Overlap (Swwan)

The two-pass node that makes long clips possible

Swwan/Advanced/Batch
Image Batch Filter (Swwan)

Throw out the black frames and get told which ones

Swwan/Advanced/Batch
Image Batch Join With Transition (Swwan)

Slide, wipe or iris between two clips

Swwan/Advanced/Batch
Image Batch Multi (Swwan)

Glue five separate images into one batch

Swwan/Advanced/Batch
Image Batch Repeat Interleaving (Swwan)

How to make every frame of a batch hold still for two beats

Swwan/Advanced/Batch
Image Batch Test Pattern (Swwan)

The numbered-frame trick for debugging batch order

Swwan/Advanced/IO
Image Batch to Image List (Swwan)

One tensor in, many separate images out

Swwan/Batch
Image Concatenate (Swwan) · 旧版兼容

The legacy two-up stitcher, and why you should use Concat Multi instead

Swwan/Legacy
Image Concat From Batch (Swwan) · 旧版兼容

Turn a batch into a contact sheet, legacy style

Swwan/Legacy
Image Concat Multi (Swwan)

Strip, grid, or batch-grid, and none of the black bands

Swwan/Image
Image Crop By Mask (Swwan)

Autocrop to whatever your mask is pointing at

Swwan/Advanced/Image
Image Crop By Mask And Resize (Swwan)

The crop that hands you a bounding box to undo it with

Swwan/Advanced/Image
Image Crop By Mask Batch (Swwan)

One image, many masks, uniform tiles out

Swwan/Advanced/Batch
Image Grab PIL (Swwan)

Screenshot your desktop straight into a workflow

Swwan/Experimental
Image Grid Composite 2x2 (Swwan) · 旧版兼容

Four wires in, one square out

Swwan/Legacy
Image Grid Composite 3x3 (Swwan) · 旧版兼容

Nine images, one contact sheet, no settings

Swwan/Legacy
Image Grid to Batch (Swwan)

Undo a contact sheet back into frames

Swwan/Advanced/Batch
Image List to Image Batch (Swwan)

The boring adapter that unsticks half your node-pair errors

Swwan/Batch
Image Matte (Swwan)

Mask in, transparent PNG out — and no, it doesn't detect anything

Swwan/Advanced/Image
Image Normalize -1 to 1 (Swwan)

The two-line node that exists for range picky consumers

Swwan/Advanced/Image
Image Pad For Outpaint Masked (Swwan)

Grow the canvas and get the mask to fill it

Swwan/Advanced/Mask
Image Pad For Outpaint Target Size (Swwan)

Fit a picture into an exact canvas without stretching it

Swwan/Advanced/Image
Image Pad (Swwan)

Four ways to fill the gap, including the pillarbox blur

Swwan/Advanced/Image
Image Pass (Swwan)

The node that does nothing, on purpose

Swwan/Advanced/Image
Image Prep For IC Lora (Swwan)

Side-by-side the reference and the canvas

Swwan/Advanced/Image
Image Resize (Swwan) · 旧版兼容

The deprecated KJNodes resize, kept alive for old workflows

Swwan/Legacy
Image Resize Range (Swwan)

Resize only when the picture is too small or too big

Swwan/Image
ImageScaleByAspectRatio V2 (Swwan) · 旧版兼容

The LayerStyle aspect node, and why you got black bars

Swwan/Legacy
Images to RGB (Swwan)

The boring node that saves you from a channel-count error

Swwan/Image
Image Tensor List (Swwan)

How you keep images of different sizes in one wire

Swwan/Advanced/Batch
Image Uncrop By Mask (Swwan)

Paste an edited crop back where it came from

Swwan/Advanced/Mask
Image Upscale With Model Batched (Swwan)

The 4x upscaler that doesn't blow your VRAM

Swwan/Advanced/Batch
Insert Images To Batch Indexed (Swwan)

Surgery on a batch with a text field full of numbers

Swwan/Advanced/Batch
Load And Resize Image (Swwan)

The loader that does your resizing and pulls a mask out of any channel

Swwan/Advanced/IO
Load Images From Folder (Swwan)

Point it at a directory and get a batch back

Swwan/Advanced/IO
Load Videos From Folder (Swwan)

Batch video frames, and yes it needs VideoHelperSuite

Swwan/Advanced/IO
Mask Analyze (Swwan)

Turn a blob of mask into numbers you can branch on

Swwan/Advanced/Mask
Mask Combine (Swwan)

Add, subtract, intersect — then crop to the region that's left

Swwan/Advanced/Mask
Mask Process (Swwan)

Five mask algorithms under one roof, and which knob belongs to which

Swwan/Advanced/Mask
Mask Segments (Swwan)

Feed your hand-drawn masks into Impact's detailer loop

Swwan/Advanced/Mask
Merge Image Channels (Swwan)

Rebuild an image one channel at a time

Swwan/Advanced/Image
Pad Image Batch Interleaved (Swwan)

Insert blank frames between your frames and get a mask for free

Swwan/Advanced/Batch
Preview Animation (Swwan)

Actually watch your batch before you save it

Swwan/Advanced/IO
Remap Image Range (Swwan)

One line that rescales pixel values, and a clamp that bites

Swwan/Advanced/Image
Replace Images In Batch (Swwan)

Splice re-rendered frames back into a sequence

Swwan/Advanced/Batch
RestoreCropBox (Swwan) · 旧版兼容

Put the repaired patch back exactly where it came from

Swwan/Legacy
Restore Crop Box V3 (Batch) (Swwan) · 旧版兼容

The paste-back half of the crop-process-paste loop, now batch-safe

Swwan/Legacy
Restore Crop (Swwan)

The fast PyTorch paste-back that makes video detail passes actually tolerable

Swwan/Image
Reverse Image Batch (Swwan)

Flip the frame order without touching a pixel

Swwan/Advanced/Batch
Save Image (Swwan)

The saver that tells you the absolute path it wrote

Swwan/IO
Save Image (Swwan) · 旧版兼容

The KJ saver your old workflow still points at

Swwan/Legacy
Save Image With Alpha (Swwan) · 旧版兼容

PNG transparency, and the one inversion that bites

Swwan/Legacy
Save String (Swwan)

Dump the prompt that made that image to a .txt

Swwan/Advanced/IO
Seed (Swwan)

The seed node that remembers the seed that just ran

Swwan/Utils
Shuffle Image Batch (Swwan)

Reproducers for random batches

Swwan/Advanced/Batch
Split Image Channels (Swwan)

Get the alpha back out as a mask

Swwan/Advanced/Image
Transition Images In Batch (Swwan)

Wipes and slides between frames you already have

Swwan/Advanced/Batch
Transition Images Multi (Swwan)

Join separate images with a wipe, in the order you want

Swwan/Advanced/Image
Webcam Capture CV2 (Swwan)

Live frames for realtime diffusion

Swwan/Experimental
Type Any Index (Swwan)

Grab element N from a list or a batch — negatives count from the end

Swwan/Advanced/Batch
Readme

ComfyUI_Swwan

ComfyUI 的图片、遮罩与工作流工具。通过推荐入口和模式切换减少重复选择,同时保留历史节点的兼容接口。

当前有 21 个推荐入口、77 个任务专用工具、18 个 Legacy 兼容节点和 2 个实验功能,共 118 个节点。新工作流优先从推荐入口选择;已有工作流按迁移说明保留行为。

使用者从本页开始。AI agent 请先读 AGENTS.md。

安装与更新

需要 Python ≥3.11 和可正常运行的 ComfyUI。以下 python 必须是启动 ComfyUI 使用的解释器;已有 torch/CUDA 环境继续使用。

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/aining2022/ComfyUI_Swwan.git
cd ComfyUI_Swwan
python -m pip install -r requirements.txt

Windows portable 版可在其根目录安装依赖:

.\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\ComfyUI_Swwan\requirements.txt

安装后重启 ComfyUI,刷新浏览器,在节点搜索中输入 Swwan。本仓对应的图片处理能力无需安装 KJNodes、LayerStyle、rgthree、孤海等原插件。

| 使用范围 | 依赖 | | --- | --- | | 基础注册 | ComfyUI 环境已有的 torch、numpy、Pillow | | 常用图片/遮罩算法 | requirements.txt 安装 OpenCV、SciPy、scikit-image;torchvision 使用与现有 torch 匹配的 ComfyUI 环境版本 | | Color Match 的 color_matcher 模式 | 另执行 python -m pip install color-matcher | | Color Match 的 mean_std 等模式 | 使用 ComfyUI 的 kornia;缺失时在同一环境补装 | | RTX VSR/SageAttention/设备功能 | 按 设备与模型功能 配置对应硬件和库 |

可选依赖在使用对应功能时加载。项目不自动安装 CUDA wheels,也不自动下载模型。

更新时在仓库目录执行,随后重启 ComfyUI 并刷新浏览器:

git pull --ff-only
python -m pip install -r requirements.txt

如果存在本地修改或分支分歧导致更新失败,先保存并处理自己的改动。

第一个工作流

先导入 无模型图片示例,执行“纯色图 → 比例缩放 → 网格拼接 → RGB → 保存”。它只需要本仓与 ComfyUI 核心节点,可用于检查安装。

透明图示例 演示 RGB 配合实际 alpha 保存。更多连接方式见 快速开始。

按任务选节点

以下是 21 个推荐入口。表中的名称对应节点搜索显示名,均带 (Swwan);保存的节点 ID、完整端口和旧版替代关系见 节点目录。

| 要做什么 | 推荐节点 | 怎么选择 | | --- | --- | --- | | 按遮罩裁剪,再放回原图 | Mask Crop、Restore Crop | 普通边界裁剪用 bounds;局部编辑用 edit_region,配套连接 SEAM 还原 | | 指定宽高或图片比例 | Resize Image | standard 用常规尺寸规则,aspect_ratio 用比例预设;迁移的孤海/Essentials 算法分别用 edit_size/essentials | | 控制总像素量 | Image Resize By Megapixels | 按百万像素约束图片面积 | | 限制最小/最大尺寸 | Image Resize Range | 按尺寸上下限缩放,也支持只输入遮罩 | | 图层混合或按遮罩合成 | Image Blend | 默认模式用于图层混合;mask_composite 提供尺寸匹配、遮罩扩缩和模糊 | | 多图拼接或批次网格 | Image Concat Multi | strip 为条带,grid 为多个输入排网格,batch_grid 为首输入的批次排网格 | | 生成纯色图、转换颜色参数或转 RGB | ColorImage、Color Converter、Images to RGB | 分别输出图片、颜色格式和 RGB 图片;Color Converter 可输出 COLORCODE | | 将遮罩按块归整 | Blockify Mask | 独立的遮罩块化任务 | | 转换或截取图片批次 | Image List to Image Batch、Image Batch to Image List、Get Image Range From Batch | list 可包含不同尺寸;tensor batch 中的图片必须同尺寸 | | 处理和保存透明图片 | RGBA Safe Pre、RGBA Safe Post、RGBA Save | Pre/Post 配套处理实际 alpha,Save 是专用 PNG 保存入口 | | 保存普通或透明图片 | Save Image | 支持多格式、路径、元数据、字幕和工作流 JSON | | 数学计算、条件切换、种子控制 | Math Expression、Any Boolean Switch、Seed | 分别用于安全表达式、选择输入、随机/递增/递减及上次种子 |

需要更细的操作时到 Swwan/Advanced/<任务>。Color Match、Color Shift Fix、BBOX、IMAGE_BOUNDS、视频和模型补丁各有独立用途。Swwan/Legacy 用于历史兼容,Swwan/Experimental 包含设备实验功能。

扩图使用 Image Pad For Outpaint Masked (Swwan):padding_mode=directional 支持 padding_unit 在像素/百分比之间切换,左右按原图宽度、上下按原图高度计算;alignment 控制尺寸对齐,feathering 为高斯羽化。该模式处理单张 RGB 图;默认 legacy 保留原像素扩边与批次行为。四侧均为 0 且启用对齐时,按原扩图算法向下裁齐。

常用遮罩专用工具如下,它们不运行检测或分割模型:

| 工具 | 用途 | | --- | --- | | Mask Process | 清理、填孔、二值化、扩缩和模糊;不同模式保留各自算法 | | Mask Combine | 遮罩运算、边界取景与对齐 | | Mask Analyze | 区域尺寸、位置和面积检测 | | Mask Segments | MASK 与 SEGS 转换,以及区域排序/筛选 | | Image Matte | 用已有遮罩抠图,输出透明 RGBA、填色 RGB 和 MASK |

连接与保存时的约定

  • 局部编辑:Mask Crop 的 edit_region 处理首张图片。输出的 IMAGE 和末尾原生 MASK 接处理链,SEAM 接 Restore Crop;Restore 的原图和 BOX 仍需连接。普通 bounds 模式保留既有批次规则。
  • 遮罩与透明度:ComfyUI Load Image 的 MASK 是 1 - alpha;RGBA Safe Pre 输出的是实际 alpha。保存时按输入选择 straight 或 premultiplied RGB,详见 RGBA 说明。
  • 裁剪信息:BOX、BBOX、IMAGE_BOUNDS、SEAM、STITCH3 各有不同协议,不能直接互换。
  • 保存路径:Save Image 的相对路径基于 ComfyUI output,绝对路径按输入使用。每个目录独立编号,不覆盖已有图片或同名字幕/JSON;输出绝对路径列表,output 内文件提供 UI 预览。
  • 格式:PNG/WebP/TIFF 可保留 alpha;JPEG/BMP 按背景色铺平透明度。RGBA Save 保留专用 PNG 入口;Legacy 保存节点继续遵循各自的历史接口。

示例与迁移

| 示例 | 用途与运行条件 | | --- | --- | | CPU 图片工具 | 无模型,可直接检查缩放、拼接、RGB 和保存 | | CPU 透明图 | 无模型,演示实际 alpha 保存 | | Qwen2511 移除 | 图片处理节点已迁移;仍需对应模型、QwenEditUtils 和推理环境 | | Qwen 换脸/换头 | 43 个纯图片/遮罩实例已迁移;RMBG、人体分割、SAM3、DW 姿态、人脸对齐、循环控制、LG 颜色节点及模型依赖保留,见 对照说明 |

1.0.0 为重名节点分配了独立 ID,不注册原插件冲突别名。显示名相似不代表旧节点 ID 可直接使用。 通用迁移工具支持 UI 工作流和 API prompt,默认另存并保留原文件:

python scripts/migrate_workflow.py old.json --dry-run
python scripts/migrate_workflow.py old.json --swwan-node-id 12 --swwan-node-id 35 --comfyui-root /path/to/ComfyUI

12、35 是示意编号,请替换为属于 Swwan 的节点。来源不明的重名节点需要显式选择,只有确认整个文件属于本仓历史工作流时才使用 --assume-swwan。Qwen 专用迁移命令及数据合同见 迁移说明 和 换脸/换头说明。

常见问题

| 现象 | 处理 | | --- | --- | | 搜索不到 (Swwan) 节点 | 确认目录在 ComfyUI/custom_nodes/ComfyUI_Swwan,检查启动日志及 Python 环境,重启服务 | | 更新后控件仍旧或显示异常 | 刷新浏览器;必要时强制刷新。检查网络中的 /extensions/ComfyUI_Swwan/ 脚本是否加载成功 | | 旧工作流出现缺失节点 | 先核对旧 ID 与来源,运行迁移 dry-run;模型或控制类第三方节点仍需原插件 | | 节点执行提示依赖缺失 | 在启动 ComfyUI 的同一 Python 环境安装错误提示中的库;Color Match 的旧模式另需 color-matcher | | 遮罩或透明度反了 | 检查输入是编辑 MASK、Load Image 的 1-alpha,还是实际 alpha,再选择反转/保存参数 | | list 转 batch 失败 | 空 list 不可转换;尺寸不同的图片先统一尺寸,或继续使用 list | | 局部编辑批次只处理首张 | edit_region 的约定是首张处理;逐张编辑需在工作流中逐张调用 |

验证、贡献与许可

本项目提供 CPU 图片/遮罩参考对照、历史接口回归、实际保存文件和前端检查。CPU 通过不代表 CUDA、RTX、检测模型或 Qwen 生成效果通过。 已验证环境和剩余项见 验收报告、安装检查 与 硬件验收。

开发流程和命令见 AI agent 入口、贡献指南 和 节点开发 skill。变更记录见 CHANGELOG。

整包按 GPL-3.0 分发;各来源文件保留原许可、版权和修改说明。详见 LICENSE、来源与资产声明。