============================================================
  binyuan · Multi Image Compare (N) 使用说明
============================================================

一个支持 N 张图片对比的 ComfyUI 自定义节点:多端口输入、多帧、
每端口打印自定义文字、所有端口合成一张大图导出。

适配 ComfyUI v0.26 / 新前端(comfyui-frontend-package 1.45.x)。


------------------------------------------------------------
一、节点位置
------------------------------------------------------------
添加节点 -> image 分类 -> binyuan · Multi Image Compare (N)


------------------------------------------------------------
二、输入
------------------------------------------------------------

【图片输入(动态端口)】
- 节点有 image_1、image_2... 端口,连满一个自动加下一个空槽(最多 16 个)。
- 断开中间连线会自动删除该空槽并重排编号。
- 也可右键节点 -> "➕ 添加图片输入" 手动加。
- 每个端口接 IMAGE(如 VAEDecode 的输出)。batch 多帧会全部进入对比。

【参数(控件)】
  label        多行文本,每行对应一个端口(第1行->image_1,第2行->image_2...)。
               印到图片左上角。默认空。
  print_label  是否把 label 烧到图片上。默认 true。
  label_size   字号(8~200)。默认 32。

备注:
  - label 支持中文(微软雅黑 msyh.ttc)。
  - 端口数超出行数时,多出的端口不打印。
  - 鼠标悬停 label 控件有提示。


------------------------------------------------------------
三、输出
------------------------------------------------------------
  grid   一张大图:所有端口的所有帧拼成 2D 网格,每帧左上角印各自端口的文字。

保存方法:把 grid 连到 SaveImage(存 PNG)或 PreviewImage(预览)。


------------------------------------------------------------
四、节点内对比操作(深色框)
------------------------------------------------------------

【工具栏(顶部)】
  Slider / Grid   Slider=拖分割线对比 A/B 两张;Grid=所有图并排
  A vs B 下拉     Slider 模式下选要对比的两张
  ↔              左右翻转
  ⟲              重置缩放

【图片区】
  滚轮          放大/缩小(0.2x ~ 10x)
  放大后拖动    平移
  双击          重置缩放
  Slider 模式   在图片区拖动 = 移动分割线


------------------------------------------------------------
五、典型用法
------------------------------------------------------------

场景 A:对比 3 个模型,导出带名字的合成图
  1. 三个 VAEDecode 分别连到 image_1、image_2、image_3。
  2. label 填(每行一个):
        Krea-2
        Flux-1.1
        SDXL
  3. print_label=true,label_size=48(图大就调大)。
  4. 运行 -> 节点里可 Slider / Grid 对比。
  5. grid 连 SaveImage -> 得到一张含 3 张图、各自印着模型名的大图。

场景 B:只看不存
  连图运行,节点内用 Slider 拖分割线对比,或 Grid 并排看。
  不连 SaveImage 即可。

场景 C:多帧对比
  某端口接 batch(如视频帧/多步采样),所有帧都进对比序列和 grid 大图。


------------------------------------------------------------
六、常见问题
------------------------------------------------------------
  现象                       原因 / 解决
  -------------------------  ----------------------------------------
  图片区不在节点内/乱跑       浏览器没刷新到最新 JS -> Ctrl+F5 硬刷新
  文字没印上                 print_label 是否 true;label 是否填了对应行
  某端口没字                 label 行数不够,补一行
  grid 没输出                没连图或没运行
  改了参数没生效             后端改动需重启 ComfyUI(不只是刷新浏览器)
  字体显示异常               系统缺少微软雅黑;脚本会回退到默认字体


------------------------------------------------------------
七、文件结构
------------------------------------------------------------
插件位置:custom_nodes/binyuan_multi_image_compare/

  nodes.py                   后端:输入/输出定义、标签烘焙、合成大图
  js/multi_image_compare.js  前端:对比界面、滚轮缩放、DOM 覆盖层定位
  __init__.py                节点注册(WEB_DIRECTORY = "./js")
  使用说明.txt               本文档


------------------------------------------------------------
八、技术备注(给二次开发者)
------------------------------------------------------------
- 动态端口:image_* 输入由前端 JS 动态增减,后端不声明,靠 VALIDATE_INPUTS
  返回 True 接受未声明输入。
- DOM 覆盖层定位:新前端对 computeLayoutSize 的 widget 不调用 draw(),故本
  节点用 computeSize + ctx.getTransform()(参考 comfyui-animatediff-evolved
  的 gif_preview.js 的 offsetDOMWidget)定位,不依赖 app.canvas.ds。
- ui 字典:value 必须是列表(否则 ComfyUI 合并多次执行 ui 时报
  'int' object is not iterable)。
- 多帧:每个 IMAGE 张量 [B,H,W,C] 的每一帧都被保存为独立图片。
