Extensions/ComfyUI-MaskCanvasEditor

ComfyUI Extension

ComfyUI-MaskCanvasEditor

Mask Canvas Editor is a ComfyUI custom node that provides an interactive visual editor for positioning a background image behind a mask region.

By ku1x·Created 29 days ago·Updated 9 days ago· 0

ku1x/ComfyUI-MaskCanvasEditor

Nodes—

On cloudLocal install

Stars0

Updated9 days ago

Readme

<p align="center"> <img src="https://img.shields.io/badge/ComfyUI-custom__nodes-8A2BE2?style=flat-square" alt="ComfyUI Custom Nodes"> <img src="https://img.shields.io/github/license/ku1x/ComfyUI-MaskCanvasEditor?style=flat-square" alt="License"> <img src="https://img.shields.io/badge/Python-3.8+-blue?style=flat-square&logo=python" alt="Python"> </p> <h1 align="center">🎨 ComfyUI Mask Canvas Editor</h1> <p align="center"> <b>English</b>  |  <a href="#中文说明">中文说明</a> </p> <p align="center"> <i>Interactive canvas-like visual editor for positioning images behind mask regions in ComfyUI.</i> </p>

Overview

Mask Canvas Editor is a graphical ComfyUI custom node with a responsive floating canvas editor. The mask bounding box acts as a fixed "window", while you drag, zoom, rotate, flip, or precisely nudge the background image behind it.

Think of it as cropping an image to a mask, but controlled entirely through visual canvas interaction — just like Photoshop's canvas tool.

✨ Key Features

🖼️ Load Without Queueing — Upload directly or read the selected file from a connected LoadImage node
🎭 Connected Mask Detection — Reads the Alpha/RGB mask channel and computes its exact bounding box in the browser
🎨 Responsive Editor — High-DPI floating canvas with direct manipulation and precise sliders
🖼️ 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, and 0.1-pixel offset nudging
🖱️ Direct Manipulation — Drag to pan, scroll to zoom, Shift+scroll to rotate, click toolbar buttons to flip/reset
🎯 Grid Overlay — Checkerboard pattern with center crosshair shows the background image bounds and transforms
📦 Zero Dependencies — Works with ComfyUI's built-in PyTorch; no extra packages required
🌐 Bilingual — Supports both English and Chinese workflows

⚠️ Tip: Resize the node by dragging its bottom-right corner to give yourself more canvas space!

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

Add Mask Canvas Editor from Mask/CanvasEditor > Mask Canvas Editor.
Connect a MASK.
Choose a background source:
- With no IMAGE connection, click 🖼 Load Background to upload a file and open the editor immediately.
- With a LoadImage node connected to IMAGE, click Load Background or Open Canvas Editor to read that node's selected file without queueing.
- A LoadImage MASK connection is also read directly: its Alpha mask bounding box is available before the first execution.
- Runtime-generated IMAGE or MASK sources must execute once before their tensors are available for preview.
Drag to pan, scroll to zoom, Shift+scroll to rotate, or use the sliders. Arrow keys nudge by 1 px; Alt+Arrow nudges by 0.1 px.
Click Apply, then queue the workflow to generate the cropped outputs.

LoadImage masks are available immediately. For masks generated by SAM, RMBG, or other runtime nodes, a placeholder window is shown until the first execution.

Node Inputs

| Input | Type | Description | |-------|------|-------------| | mask | MASK | Mask defining the crop window | | image | IMAGE, optional | Connected background; LoadImage files can be previewed without execution | | internal_image | File, optional | Background loaded with the node button or selected from ComfyUI input |

All transformation parameters are controlled in the floating editor through direct manipulation, sliders, or keyboard nudging.

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 in the floating canvas editor, giving you real-time feedback while positioning the image.

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.

<p align="center"> If you find this useful, please ⭐ star the repo! </p>

<h2 id="中文说明" align="center">🎨 ComfyUI Mask Canvas Editor</h2> <p align="center"> <i>交互式画布可视化编辑器 — 在 ComfyUI 中像 Canvas 一样定位遮罩背后的图片。</i> </p>

概述

Mask Canvas Editor 是一个带响应式浮动画布的 ComfyUI 图形化节点。遮罩包围盒固定在画布中央作为“窗口”，你可以拖拽、缩放、旋转、翻转或精确微调背后的底图。

简单来说就是：用遮罩裁剪图片，但是通过在节点上直接进行可视化交互来控制图片位置——就像 Photoshop 的画布工具一样。

✨ 核心功能

🖼️ 无需预执行 — 可以直接上传，或自动读取已连接 LoadImage 节点当前选择的图片
🎭 自动读取遮罩 — 在浏览器端解析 LoadImage 的 Alpha/RGB 遮罩通道并计算真实包围盒
🎨 响应式编辑器 — 支持高 DPI 的浮动画布、直接操控和精确滑块
🖼️ 遮罩即窗口 — 遮罩固定在画面中央，背景图在其背后移动
🔄 完整变换控制 — 缩放（0.01×–10×）、旋转（±180°）、水平/垂直翻转、0.1 像素偏移微调
🖱️ 直接操控 — 拖拽平移、滚轮缩放、Shift+滚轮旋转、按钮翻转
🎯 网格覆盖层 — 棋盘格 + 中心十字线直观展示背景图片的边界与变换状态
📦 零依赖 — 利用 ComfyUI 内置的 PyTorch，无需额外安装
🌐 双语支持 — 同时支持中英文工作流

安装

通过 ComfyUI Manager（推荐）

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

手动安装

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

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

使用方法

快速上手

从节点菜单添加：Mask/CanvasEditor > Mask Canvas Editor。
连接 MASK。
选择底图来源：
- 没有连接 IMAGE 时，点击 🖼 Load Background 上传图片并立即打开编辑器。
- IMAGE 连接标准 LoadImage/加载图像 节点时，点击 Load Background 或 Open Canvas Editor 会自动读取上游当前选中的图片，不需要运行工作流。
- MASK 连接 LoadImage 的遮罩输出时，也会直接读取 Alpha 遮罩并在第一次执行前计算真实包围盒。
- 如果 IMAGE 或 MASK 来自 VAE Decode、SAM、RMBG 等运行时节点，仍需先执行一次才能获得其张量。
拖拽平移、滚轮缩放、Shift+滚轮旋转，或使用精确滑块。方向键每次移动 1 像素，Alt+方向键每次移动 0.1 像素。
点击 Apply，然后运行工作流生成裁剪结果。

LoadImage 的遮罩可以立即读取；SAM、RMBG 等运行时生成的遮罩会先显示占位窗口，首次执行后再使用真实包围盒。

节点输入

| 输入 | 类型 | 说明 | |-------|------|-------------| | mask | MASK | 定义裁剪窗口的遮罩 | | image | IMAGE，可选 | 外部连接的底图；LoadImage 文件可在执行前直接预览 | | internal_image | 文件，可选 | 通过加载按钮上传或从 ComfyUI input 目录选择的底图 |

所有变换参数都可以在浮动编辑器中通过拖拽、滑块或键盘微调控制。

节点输出

| 输出 | 类型 | 说明 | |--------|------|-------------| | 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 文件。

<p align="center"> 如果这个项目对你有帮助，请 ⭐ Star 支持！ </p>