ARTICLE · 1300040
1.7KB 的插件把 ComfyUI 跑崩了:半调网点插件四个参数三个坑
ComfyUI-Image2Halftone 详细使用方法和壁垒
1.7 KB 的印刷网点插件，四个参数三个坑，全网教程还写错了一半
想给 AI 出图加一层「报纸印刷」的复古质感，ComfyUI 里搜半调（Halftone），跳出来的就是这个 Image2Halftone——2023 年 9 月发布，整个节点就一个 1.7 KB 的 Python 文件，不加载模型、不用显卡，纯 Pillow 画圆点。它把图片拆成 CMYK 四个通道，各按一个角度旋转、打点、再叠回去，模拟百年前印刷机的网点工艺。
但「小」不等于「简单」。这篇的所有结论都来自源码逐行阅读 + 本机实测：它最核心的 scaling 参数，语义和全网教程写的都不一样；antialias 被写死无法关闭，内部画布偷偷放大 4 倍，scaling 拉到 4 以上直接触发 Pillow 的「解压炸弹」保护当场崩溃；批量大于 1 的图片进来直接报错。四道墙，一次讲透。
原理——1.7 KB 跑完印刷机的四色网点工艺
半调（Halftone）是印刷行业的祖传手艺：打印机只会「打点」不会「渐变」，它用点的面积来表现颜色的深浅——深的地方点大、浅的地方点小，人眼远看自动把它们糊成连续影调。这个节点的算法底子是 2012 年 StackOverflow 上的一个经典答案，后来被 philgyford 整理成 python-halftone 库，aimingfail 在 2023 年把它套上了 ComfyUI 的壳。
第一步：拆色。输入的 RGB 图被 convert("CMYK") 分成青、品红、黄、黑四个通道，各自独立处理。注意 PIL 的这个转换不带 ICC 色彩配置文件，是最朴素的数学换算——好消息是本机实测往返转换零偏差，坏消息是它跟真实印刷的 CMYK 分色不是一回事。
第二步：打点。每个通道先按自己专属的角度旋转画布，然后按 samples 参数切网格，逐格取平均亮度，画一个实心圆。圆的直径 = √(格内平均亮度 ÷ 255) × samples × scale——注意是先开平方，这保证点的「面积」与亮度成正比，这正是印刷半调的物理正确做法，也是这个 1.7 KB 脚本里最有含金量的一行。
第三步：合版。画完点阵的通道反向旋转回正、中心裁剪，四个通道合并回 CMYK 再转回 RGB 输出。四层彩色网点叠在一起，远看就是一张「印刷品」。整个过程纯 CPU，不加载任何模型——1024×1024 的图、默认参数下本机实测约 0.75 秒跑完。
算法三步与参数真值表（源码级）
安装——同一个名字，两条完全不同的路线
这是本篇第一个必须分清的事：「Image2Halftone」在社区里有两个落地形态，教程从来不告诉你用的是哪个，装错了就会「教程有这个参数、我的节点上没有」。
路线 A：Civitai 原始单文件版。作者 aimingfail 的原版，从 Civitai 模型页（编号 143293）下载 1.73 KB 的压缩包，把里面的 image2halftone.py 丢进 custom_nodes 目录即可，零依赖。ComfyUI-Manager 的官方列表里也收录了它，但注意条目详情：install_type 是 unzip，下载地址指向 Civitai 的 API 直链——这类直链能否拉取取决于 Civitai 的接口策略，Manager 里点安装没反应、或装完目录是空的，都属于这种情况。
路线 B：YFG Comical 重写版。gonzalu 的 ComfyUI_YFG_Comical 节点包里有一个基于同一算法的重写实现，节点注册名 image_halftone，显示名「🐯 YFG Image Halftone Generator」。功能与原版一致且补上了节点内预览，Manager 搜 "YFG Comical" 即可安装。代价是它拖着整个包一起进来：三十多个节点、GPL-3.0 许可，pyproject 声明的依赖里还有 transformers 和 typer——为了一个 1.7 KB 的功能，往环境里塞一个大模型推理库，值得掂量。
怎么判断自己装的是哪个
节点分类是「🐯 YFG」→ 路线 B（image_halftone）节点带 preview / display 两个控件 → 路线 B都没有 → 路线 A 原始版（本文参数两者通用）
工作流位置——后处理层，一条线的事
它的定位是后处理特效：不参与生成，只对已出图的像素做改造。最小工作流就三个节点——Load Image（或 VAE Decode）→ Image2Halftone → Save Image。想跑通后保存预设，再从 Save Image 换成 SaveImage Plus 之类即可。
YFG 版的节点是 OUTPUT_NODE：它既是中间节点也是输出节点，预览直接画在节点上。输出是双路——Halftone（半调结果）和 Original Image（原样输入），方便下游做左右对比图，不用自己再接一个备份分支。display 控件只决定「节点上显示哪张」，不影响两路输出的内容。
两个高频组合：① 海报/漫画风出图——生成后接半调，再叠一层纸张纹理，AI 味瞬间变印刷味；② 放大后处理——先超分放大 2 倍再进半调，点阵更细腻（原因见第 05 章，samples 相对像素密度变小）。注意它的输入是普通 IMAGE，接在 ImageBatch 这类批量节点后面会直接报错，坑在第 06 章展开。
参数——一共就六个，但一半的语义和直觉相反
samples（1~32，默认 10）：点阵密度，性能旋钮。它决定「多少像素共享一个点」：1024 的图、samples=10 时网格是 102×102 共约 4.2 万次循环；拉到 1 就是每像素一个点，420 万次循环，本机外推要一分钟以上。想细，先降 samples 再谈别的。
scaling（1~5，默认 1）：输出放大倍数，不是点大小。这是全篇最重要的纠偏：输出尺寸 = 输入尺寸 × scaling，本机实测确认——1024 进、scaling=2 出 2048。它的作用是给点阵更多像素去表现层次（sample×scale 才是最大点径），代价是输出跟着变大。想保持尺寸就锁 1，想要印刷级细节就先放大输入再跑。网上教程把它写成「点的大小」「0.1 到 10」，都是没读源码的转述。
grayscale（No/Yes，默认 No）。Yes 时只走黑白灰度分支：只生成黑色点阵，且四个角度只有 angle_c 生效（源码里 angles[:1] 直接截断）。想让灰度点阵斜着排，把 angle_c 从 0 改成 45，否则默认 0 度会排成横平竖直的方阵，观感立刻廉价。
angle_c / m / y / k（0~90 整数，默认 0 / 15 / 30 / 45）。四个通道各自的网屏角度。传统四色印刷的惯用组合是 青 15°、品红 75°、黄 0°、黑 45°（黄版最浅、放 0° 不显眼，各色版互相错开 30° 以上防撞纹）。本节点的默认组合 C0/M15/Y30/K45 与该惯例不同，相邻色版夹角只有 15°，默认出图摩尔纹（moiré）偏重——不是你操作错了，是默认值保守。彩色模式建议照印刷标准改：15 / 75 / 0 / 45。
preview（默认开）与 display。preview 开启时节点把结果写进 ComfyUI 的 temp 目录并在节点上显示；display 切换显示原图还是半调图。注意 YFG 版若节点上不显示预览图，多半不是节点坏了——官方 issue #7 给出的解法是用 --preview-method auto 启动 ComfyUI。
内部机制——antialias 写死 True，画布偷偷放大 4 倍
为什么一个「画圆点」的节点能把 ComfyUI 跑崩？答案在源码的一行：YFG 版调用算法时固定传了 antialias=True，而算法内部为了让圆边平滑，会先把画布放大 4 倍、画完再缩小回来。这个 4 倍用户无法关闭。
算一笔账（输入 1024×1024）：scaling=1 时内部画布是 4096 像素宽，单通道约 32 MB，四通道加旋转中间态约 128 MB——没压力。scaling=3 时画布 12288 像素、单通道 288 MB，已经能感觉到停顿。scaling=4 时画布 16384 像素、约 2.68 亿像素，踩爆 Pillow 的解压炸弹保护阈值（默认 89,478,485 像素，超两倍即拒绝），直接抛 DecompressionBombError——本机实测，四个 scaling 档位里 4 和 5 无一幸免。
更隐蔽的是崩溃线只看「输入边长 × scaling」：大于约 3344 就踩线。1024 的图死在 scaling=4；2048 的 2K 图 scaling=2 就死；512 的小图反而五档全过。这就解释了一个诡异现象——同一个工作流，换张大图就崩，报错却完全没提到是哪个参数的问题。若你的环境关闭了 Pillow 这层保护，同样的参数不会报错，而是转为真实的数 GB 内存分配，直到把系统内存吃满。
五档 scaling 的真实开销与崩溃阈值（本机实测）
四道墙——把坑归类，才记得住
第一道：尺寸墙。scaling 会放大输出，下游所有按尺寸对齐的节点（遮罩、对比、拼接）全部错位；而全网教程普遍把它讲成「点的大小」，你调完只会更困惑。规则一句话：要尺寸稳定就锁 1，要放大出图就自觉把下游当 2K 图对待。
第二道：崩溃墙。antialias 的 4 倍画布 × Pillow 保护阈值 = 「输入边长 × scaling > 3344 必崩」。大图配高 scaling 是这个节点唯一会「硬报错」的场景，报错信息（DecompressionBomb）又完全不指向真凶。记住排查口诀：先查 scaling，再查图有多大。
第三道：角度墙。灰度模式只认第一个角度、其余三个静默失效；角度只收 0~90 的整数；默认组合不是印刷标准、摩尔纹偏重。加上各通道旋转时画布旋转再转回，像素会有细微的重采样偏移——对精度敏感的场合要知道这层损耗的存在。
第四道：兼容与许可墙。三件事：① 批量大于 1 的 IMAGE 进来直接 TypeError（tensor2pil 的 squeeze 只认单张），批量流水线必须先拆批；② Manager 里的原始版条目是 unzip + Civitai 直链，装不上是常态，走 YFG 包更稳；③ 许可链条不干净——底层算法库 python-halftone 在 GitHub 上未声明任何许可证（API 返回 license: null，法律上默认保留所有权利），YFG 包整体是 GPL-3.0 强传染，原始 Civitai 版也未声明。自用无碍，商用产品里内嵌这套代码前，请务必核实并咨询许可原文（本段仅供参考，不构成法律意见）。
排查表——现象、根因、解法
六类现象速查与许可现状
写在最后——小工具的正确打开方式
Image2Halftone 是「用法与壁垒」系列里最小的一个插件：不加载模型、不占显存、算法三十年没变过。它的价值在确定性——同样的输入永远出同样的网点，这是 AI 生成给不了的稳定质感。它的坑也全部来自「小」：没人维护文档、教程以讹传讹、参数语义靠读源码才能确认。
选型参考：要和教程、素材工作流保持一致，用本篇的 Image2Halftone；要中文文档和持续维护，看 LayerStyle 的 HalfTone 滤镜（支持点形状与前后景颜色）；要抖动算法而非网点（Atkinson、Floyd-Steinberg 那一挂的复古颗粒），ComfyUI-Dither 更对口；只是想快速去 AI 味，Comfyroll 的 CR Halftone Filter 开箱即用。工具没有高下，场景匹配才是关键。
最后重复一遍本篇最值钱的三句话：scaling 是输出放大倍数不是点大小；输入边长 × scaling 大于 3344 必崩；灰度模式只有第一个角度生效。记住这三条，这个 1.7 KB 的小工具就再也没有 surprises（意外）了。
本文基于 gonzalu/ComfyUI_YFG_Comical 与底层库 philgyford/python-halftone 的源码阅读及本机 Pillow 实测整理参数行为与崩溃阈值均为实测结果；底层库未声明许可证、插件包为 GPL-3.0，仅供参考，商用前请自行核实许可原文
