🎨 ComfyUI Mask Canvas Editor

English  |  中文说明

Interactive canvas-like visual editor for positioning images behind mask regions in ComfyUI.

---

Overview

Mask Canvas Editor is a ComfyUI custom node that provides an interactive visual editor for positioning a background image behind a mask region. The mask acts as a fixed "window" — you can scale, rotate, flip, and pan the background image behind it, and the node outputs the image content exactly as seen through the mask.

Think of it as cropping an image to a mask, but with full interactive control over how the image aligns within that crop region.

✨ Key Features

• 🎛️ Interactive Canvas Editor — Drag, scroll, and rotate in real-time via a full-screen modal
• 🖼️ Mask as Window — The mask stays centered; the background image moves behind it
• 🔄 Full Transform Control — Scale (0.01×–10×), rotation (±180°), horizontal/vertical flip, pixel-precise offset
• 🖱️ Intuitive Controls — Mouse drag (pan), scroll wheel (zoom), Shift+scroll (rotate), keyboard shortcuts
• 🎯 Grid Overlay — Checkerboard pattern shows the background image bounds and transforms
• 📦 Zero Dependencies — Works with ComfyUI's built-in torch; no extra packages required
• 🌐 Bilingual — Supports both English and Chinese workflows

---

Installation

Via ComfyUI Manager (Recommended)

Search for Mask Canvas Editor in ComfyUI Manager and click install.

Manual Installation

cd ComfyUI/custom_nodes/
git clone https://github.com/ku1x/ComfyUI-MaskCanvasEditor.git

No extra dependencies — just restart ComfyUI.

---

Usage

Quick Start

1. Add Mask Canvas Editor from the node menu: Mask/CanvasEditor > Mask Canvas Editor
2. Connect a MASK and an IMAGE to the node inputs
3. Click the 🎨 Open Canvas Editor button on the node
4. Use the interactive canvas to position your image behind the mask:
   • 🖱️ Drag to pan the background image
   • 🖱️ Scroll to zoom in/out
   • 🖱️ Shift+Scroll to rotate
   • 🎚️ Use sliders for fine control
   • ⌨️ Press R to reset, Esc to close
5. Click Apply to save transforms and queue the workflow
6. The node outputs the cropped image and cropped mask at the mask's bounding-box size

Node Inputs

Parameter	Type	Default	Range	Description
mask	MASK	(required)	—	Mask defining the crop window
image	IMAGE	(required)	—	Background image to position
scale	FLOAT	1.0	0.01 – 10.0	Uniform zoom factor
rotation	FLOAT	0.0	-180° – 180°	Rotation in degrees
flip_horizontal	BOOLEAN	False	—	Mirror horizontally
flip_vertical	BOOLEAN	False	—	Mirror vertically
offset_x	INT	0	-8192 – 8192	Horizontal shift (pixels)
offset_y	INT	0	-8192 – 8192	Vertical shift (pixels)

Node Outputs

Output	Type	Description
cropped_image	IMAGE	Transformed image cropped to the mask's bounding box
cropped_mask	MASK	Mask cropped to its own bounding box

Example Workflow

%%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 25}}}%%
flowchart LR
    subgraph Input["📥 Input"]
        direction TB
        M["LoadImage\n(mask channel)"]
        I["LoadImage"]
        S["SAM / RMBG /\nMaskEditor"]
    end

    subgraph Editor["🎨 Mask Canvas Editor"]
        N["MaskCanvasEditor\nscale / rotate / flip / offset"]
    end

    subgraph Output["📤 Output"]
        P["PreviewImage"]
        K["KSampler +\nother nodes"]
    end

    M -->|"mask"| N
    I -->|"image"| N
    S -->|"mask"| N
    N -->|"cropped_image"| P
    N -->|"cropped_mask"| P
    N -->|"cropped_image"| K

---

How It Works

The node computes the bounding box of the mask, then builds a reverse sampling grid — for every output pixel, it calculates where in the source image that pixel should come from after applying the inverse of all user transforms (pan → rotate → scale → flip). This grid is passed to torch.nn.functional.grid_sample for efficient GPU-accelerated sampling.

Output pixel → (inverse offset) → (inverse rotate) → (inverse scale) → (inverse flip) → Source pixel

The JavaScript frontend renders the same transform chain visually on an HTML5 Canvas, giving you real-time feedback as you adjust parameters.

---

Project Structure

ComfyUI-MaskCanvasEditor/
├── __init__.py                           # Extension entry point
├── py/
│   └── nodes/
│       └── mask_canvas_editor.py         # Python backend node
├── js/
│   └── mask_canvas_editor.js             # JavaScript interactive editor
├── requirements.txt
├── LICENSE
└── README.md

---

Compatibility

• ComfyUI: All recent versions
• Python: 3.8+
• Dependencies: None (uses ComfyUI's built-in PyTorch)

---

License

MIT License — see LICENSE for details.

---

If you find this useful, please ⭐ star the repo!

---

🎨 ComfyUI Mask Canvas Editor

交互式画布可视化编辑器 — 在 ComfyUI 中像 Canvas 一样定位遮罩背后的图片。

---

概述

Mask Canvas Editor 是一个 ComfyUI 自定义节点，提供交互式可视化编辑器，用于在遮罩（Mask）区域背后定位背景图片。遮罩相当于一个固定的"窗口"——你可以对背后的背景图进行缩放、旋转、翻转和平移，节点会输出遮罩窗口范围内对应看到的内容。

简单来说就是：用遮罩裁剪图片，但是可以交互式地控制图片在裁剪区域内的对齐方式。

✨ 核心功能

• 🎛️ 交互式画布编辑器 — 全屏模态窗口中实时拖拽、缩放、旋转
• 🖼️ 遮罩即窗口 — 遮罩固定在画面中央，背景图在其背后移动
• 🔄 完整变换控制 — 缩放（0.01×–10×）、旋转（±180°）、水平/垂直翻转、像素级偏移
• 🖱️ 直觉操作 — 鼠标拖拽（平移）、滚轮（缩放）、Shift+滚轮（旋转）、键盘快捷键
• 🎯 网格覆盖层 — 棋盘格图案直观展示背景图片的边界与变换状态
• 📦 零依赖 — 利用 ComfyUI 内置的 PyTorch，无需额外安装
• 🌐 双语支持 — 同时支持中英文工作流

---

安装

通过 ComfyUI Manager（推荐）

在 ComfyUI Manager 中搜索 Mask Canvas Editor 并安装。

手动安装

cd ComfyUI/custom_nodes/
git clone https://github.com/ku1x/ComfyUI-MaskCanvasEditor.git

无需额外依赖，重启 ComfyUI 即可。

---

使用方法

快速上手

1. 从节点菜单添加节点：Mask/CanvasEditor > Mask Canvas Editor
2. 将 MASK 和 IMAGE 连接到节点输入
3. 点击节点上的 🎨 Open Canvas Editor 按钮
4. 在交互式画布中调整图片位置：
   • 🖱️ 拖拽 平移背景图片
   • 🖱️ 滚轮 缩放
   • 🖱️ Shift+滚轮 旋转
   • 🎚️ 使用滑块进行精细调节
   • ⌨️ 按 R 重置，按 Esc 关闭
5. 点击 Apply 保存变换参数并加入队列
6. 节点输出裁剪后的图片和遮罩，尺寸为遮罩的边界框大小

节点输入

参数	类型	默认值	范围	说明
mask	MASK	(必填)	—	定义裁剪窗口的遮罩
image	IMAGE	(必填)	—	需要定位的背景图片
scale	FLOAT	1.0	0.01 – 10.0	等比例缩放
rotation	FLOAT	0.0	-180° – 180°	旋转角度
flip_horizontal	BOOLEAN	False	—	水平镜像翻转
flip_vertical	BOOLEAN	False	—	垂直镜像翻转
offset_x	INT	0	-8192 – 8192	水平偏移（像素）
offset_y	INT	0	-8192 – 8192	垂直偏移（像素）

节点输出

输出	类型	说明
cropped_image	IMAGE	变换后的图片，裁剪至遮罩边界框
cropped_mask	MASK	裁剪至其自身边界框的遮罩

---

工作原理

节点首先计算遮罩的边界框（bounding box），然后构建一个反向采样网格——对于输出图像的每个像素，逆向计算在源图像中应该从哪里采样（逆平移 → 逆旋转 → 逆缩放 → 逆翻转）。该网格传递给 torch.nn.functional.grid_sample 进行高效的 GPU 加速采样。

输出像素 → (逆偏移) → (逆旋转) → (逆缩放) → (逆翻转) → 源图像像素

JavaScript 前端在 HTML5 Canvas 上实时渲染相同的变换链，让你在调整参数时获得即时视觉反馈。

---

兼容性

• ComfyUI: 所有近期版本
• Python: 3.8+
• 额外依赖: 无（使用 ComfyUI 内置的 PyTorch）

---

开源协议

MIT License — 详见 LICENSE 文件。

---

如果这个项目对你有帮助，请 ⭐ Star 支持！