ComfyUI-MossImageTools 是一款专为 ComfyUI 环境中 MOSS-Image 模型设计的通用工具包。其核心组件 Create Bounding Boxes (MossImage) 节点提供了一个功能完备的可视化编辑器，旨在解决复杂空间布局中手动编写坐标的低效问题。该工具允许用户直接在画布上绘制、调整和编排区域边界框，并输出符合 MOSS-Image 标准格式的布局数据，从而大幅提升多元素构图工作流的开发效率。
- GitHub：https://github.com/hybskgks28275/ComfyUI-MossImageTools
核心功能与技术特性
该编辑器集成了精细的交互控制与状态管理机制，主要特性包括：
- 像素级与百分比双重编辑：支持直接查看和修改每个区域的 X、Y 坐标及宽度、高度，并提供宽度与高度的百分比显示。
- 高精度网格系统：默认提供 32 列 × 32 行的网格，支持棋盘格单元格、行列标签及单元格尺寸显示。用户可独立设置 1 至 32 的轴刻度，并支持一键切换网格吸附功能。
- 灵活的图层管理：支持通过列表直接选择重叠区域，或使用
Alt + 单击在同一位置循环切换选中区域。提供移动、四角手柄缩放、复制、删除及重新排序功能，并内置最高 100 步的撤销/重做历史记录。 - 丰富的元数据编辑：支持编辑区域类型、描述文本、图像内嵌文本及专属颜色。描述文本会实时显示在区域左上角，支持换行并自动裁剪以适应区域边界。
- 状态持久化与跨平台兼容：所有编辑状态（包括描述、文本、颜色及网格设置）在切换标签或导航子图时均会自动保存。支持工作流内嵌保存，以及布局的 JSON 格式导入/导出。内置 Ctrl+C / Ctrl+X / Ctrl+V 文本编辑快捷键，避免触发布局的全局复制/粘贴。
- 多语言 UI：原生支持英语和日语，并自动跟随 ComfyUI 的全局语言设置。
安装与环境配置（核心重点）
该工具包基于 ComfyUI 的最新 V3 API 构建，依赖 io.Array 和 io.BoundingBox 类型，无需额外的 pip 或 npm 安装步骤。它直接复用 ComfyUI 环境中的 NumPy、PyTorch 和 Pillow 库。
安装步骤：
选项 1：通过 Git 克隆（推荐）
在 ComfyUI 的安装根目录下打开终端，执行以下命令：
cd custom_nodes
git clone https://github.com/hybskgks28275/ComfyUI-MossImageTools.git
选项 2：通过 ZIP 压缩包安装
- 访问 GitHub 仓库，点击
Code→Download ZIP下载源码压缩包。 - 解压下载的 ZIP 文件。
- 将解压后的
ComfyUI-MossImageTools-main文件夹移动至ComfyUI/custom_nodes/目录下，并将其重命名为ComfyUI-MossImageTools。
注意：必须确保节点入口文件位于ComfyUI/custom_nodes/ComfyUI-MossImageTools/__init__.py，避免产生额外的嵌套文件夹层级。
完成上述任一操作后，重启 ComfyUI 服务并刷新浏览器。在节点添加菜单的 MossImage/layout 分类下搜索 Create Bounding Boxes (MossImage) 即可找到该节点。
可视化编辑器使用指南
- 初始化画布：在节点的
width和height字段中输入预期的图像生成尺寸，或通过连线接收上游节点的整数（INT）输出。画布尺寸更改后，编辑器会立即更新，现有区域若超出新边界将被裁剪（完全在外的区域保留 1 像素最小尺寸）。 - 绘制与编辑区域：点击
+ Draw按钮并在画布上拖动以创建新区域。绘制完成后，编辑器自动返回选择模式。选中区域后，可拖动其主体进行移动，或拖动白色角手柄进行缩放。 - 属性精细化调整：通过右侧区域列表或画布直接选中目标，修改其坐标、尺寸、类型、描述、图像文本和颜色。数字字段在失去焦点或按下回车时提交；文本和颜色编辑则实时保存。
- 重叠管理与排序：使用区域列表或
Alt + 单击处理重叠区域。列表顶部的区域在渲染时位于最前方。使用Forward和Backward按钮可调整区域层级，区域编号会随排序动态更新（若在其他 MOSS 节点中引用了特定编号，重新排序后需同步检查）。 - 颜色与网格自定义：使用持久化颜色选择器为选定区域指定颜色（支持 HEX 输入）。未指定颜色的区域在输出中不包含
color_palette，但编辑器内仍显示默认轮廓色。可通过Grid background和Alternating cells独立调整网格视觉颜色，此设置仅影响编辑器显示，不影响输出数据。
节点连接与标准工作流集成
该节点设计了标准化的输出接口，以便与 MOSS-Image 生态无缝对接：
| 输出端口 | 数据类型 | 目的与连接目标 |
|---|---|---|
preview | IMAGE | 连接到 Preview Image 或类似节点。用于可视化检查背景、区域轮廓、编号及尺寸标签。 |
bboxes | BOUNDING_BOX | 输出标准像素坐标格式：包含单帧边界框数组及其元数据。 |
elements | ARRAY | 直接连接到标准 MOSS-Image Layout Prompt 节点的 element 输入端口。 |
width | INT | 连接到 MOSS-Image 布局提示节点或图像生成节点的宽度输入，确保布局与生成分辨率严格一致。 |
height | INT | 连接到 MOSS-Image 布局提示节点或图像生成节点的高度输入。 |
工作流集成建议：
在标准 MOSS 节点的提示字段中输入全局场景描述，并将其输出连接至 MOSS-Image 文本编码器。若需将特定对象区域识别为“角色”，可在该节点的 character_boxes 字段中填入对应的区域编号。
此外，该节点支持可选的 background 图像输入。执行后，背景图将显示在编辑器中（会自动拉伸以匹配节点设定的宽高比，建议使用相同宽高比的背景图以获得最佳预览效果）。
坐标系统与已知技术边界
在使用本工具时，需明确以下工程限制与数据规范：
- 坐标系差异：编辑器内部及
bboxes输出使用像素坐标，原点位于左上角。而elements输出则转换为 MOSS-Image 标准的 0–1000 归一化坐标范围，顺序为[ymin, xmin, ymax, xmax]。 - 画布缩放风险：更改画布尺寸会保留原有像素坐标并将其裁剪至新边界。缩小画布可能导致区域形状改变。若需保留原始布局，建议在调整尺寸前先导出 JSON 备份。
- 容量与格式限制：单个布局最多支持 512 个区域。JSON 导入功能仅接受本工具包版本 1 格式的文件，且文件大小上限为 2 MB。该工具不直接兼容或导入标准 MOSS 节点的原生状态 JSON。
- 预览分辨率限制：
preview输出图像的最长边被限制在 1536 像素。此限制仅影响预览显示，不影响实际生成尺寸或坐标数据的精度。网格线不会被包含在最终的输出预览图像中。 - 功能定位：本节点纯粹是一个带 IMAGE 预览输出的布局编辑工具。它不负责图像生成，必须配合标准的 MOSS 模型生成节点才能产出最终图像。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
