Extensions/Mask Editor One
ComfyUI Extension

Mask Editor One

A layer-based modal mask editor for ComfyUI with Photoshop-like controls. Features paint, color selection, alpha extraction, vector (Catmull-Rom spline), shape, and text…

By ketle-man·Created 2 months ago·Updated about a month ago· 1
ketle-man/comfyui-mask-editor-one
Nodes1
On cloudLocal install
Categoryimage/masking
Stars1
Updatedabout a month ago

Nodes (1)

Mask Editor One
image/masking
Readme

Mask Editor One

English | 日本語 | 中文

ComfyUI 用のレイヤーベース・モーダルマスクエディタ。Photoshop ライクな操作感でマスクを作成・編集し、IMAGE と MASK を出力します。マスクに関する操作をこのノード一つで完結することを目的としています。

Mask Editor One

主な機能

  • モーダルエディタ — ノード上の Edit Mask ボタンでブラウザ内エディタを起動
  • ペイントツール — ブラシサイズ・硬さ・スペーシング・角度・add/erase モード。サイズジッター（Amount スライダーで縮小幅を調整）と回転ジッター（スタンプごとに 0°〜360° をランダム化）をチェックボックスで有効化
  • カラー選択ツール — tolerance/feather 調整、add/subtract モード
  • 透過抽出ツール — アルファチャンネルからマスクを生成
  • テキストツール — フォント・サイズ・Bold/Italic・アライメントを指定してテキスト形状のマスクを配置
  • ベクターツール — Catmull-Rom スプラインでなめらかな閉じたパスを描いてマスク領域を生成
  • シェイプツール — ドラッグで矩形・楕円を描画。Shift+ドラッグで中心点から正方形・正円を描画
  • SAM3ツール — テキストプロンプトでAIセグメンテーション（SAM3 / SAM3.1）。モデル選択ドロップダウン付き、候補マスクをサムネイル表示、クリックで選択してレイヤーに適用
  • BiRefNet背景除去ツール — ワンクリックで前景マスクを自動生成。ComfyUI ネイティブの BiRefNet 実装（comfy.bg_removal_model）を使用するため追加ライブラリ不要
  • 全ツール共通 Mode 切り替え — Add / Erase（または Add / Subtract）をボタンクリックで即切り替え
  • レイヤー管理 — 追加・削除・可視切替・add/subtract・ドラッグ並べ替え
  • Undo/Redo — 各レイヤー 30 段
  • 画像ブラシ — グレースケール画像をブラシスタンプとして使用
  • ブラシライブラリ — フォルダツリー UI、PNG フォルダインポート、.abr ファイルインポート
  • 多言語対応（i18n） — フッターの言語セレクターで英語・日本語・中国語を切り替え。設定は localStorage に保存され次回起動時も引き継がれる
  • マスク反転トグル — ノード上のトグルとモーダルの Invert チェックが連動
  • Photoshop クイックマスク表示 — 画像表示時は全体に半透明オーバーレイを重ねて描いた部分を透過表示（Photoshop クイックマスクと同スタイル）。Invert 時は描いた部分にオーバーレイを表示。オーバーレイ色をカラーピッカーで変更可能
  • ブラーフィルター — ノードウィジェットとモーダルのスライダーでガウスぼかしを調整（0〜200 px）、双方向連動
  • BG ドロップゾーン — モーダルフッターのドロップゾーンにクリック（ファイル選択）または画像ファイルをドロップして背景を設定。キャンバスエリアへのドロップにも対応
  • New キャンバス — ツールバーの 📄 New ボタンで幅・高さを指定して新規の空キャンバスを作成。BG 読み込み・New どちらも実行後に新しいレイヤーを自動追加
  • Load Image ボタン — ノード上のボタンまたはプレビューエリアへのドロップで画像を読み込む。読み込んだ画像から自動的に Layer 1 を生成（グレースケール→アルファ変換）。新規読み込み時は既存マスクをクリア
  • ノードプレビュー — 常時表示（固定 160 px）。背景画像または Apply 後のマスクをプレビュー。画像未選択時はファイルドロップゾーンとして機能
  • IMG/MASK 切り替え — ノード上のボタンで画像プレビュー ↔ マスクプレビューを切り替え。新規画像読み込み時は自動的に画像表示に切り替わる
  • キャンバス外ドラッグ対応 — Shape/Paint 描画中にキャンバス端を越えてマウスが出ても描画継続（画像の端まで選択可能）

インストール

ComfyUI Manager（推奨）

ComfyUI Manager の「Install via Git URL」または「Custom Nodes Manager」から以下の URL を入力してインストール：

https://github.com/ketle-man/comfyui-mask-editor-one

または Comfy Registry からノード名 Mask Editor One を検索してインストールできます。

手動インストール

ComfyUI の custom_nodes/ 配下にこのフォルダを配置：

ComfyUI/
└── custom_nodes/
    └── comfyui-mask-editor-one/
        ├── __init__.py
        ├── nodes.py
        ├── server.py
        ├── abr_parser.py
        ├── sam3_inference.py
        ├── birefnet_inference.py
        ├── requirements.txt
        └── web/

依存パッケージ:

pip install -r requirements.txt

SAM3 モデルのセットアップ（任意）

SAM3ツールを使う場合は、SAM3 チェックポイントを ComfyUI/models/sam3/ に配置します。

ComfyUI/
└── models/
    └── sam3/
        ├── sam3.pt                              # SAM3（推奨）
        ├── sam3.safetensors                     # SAM3 safetensors 形式
        ├── sam3.1_multiplex.pt                  # SAM3.1
        └── sam3.1_multiplex_fp16.safetensors    # SAM3.1 FP16 safetensors
  • .pt / .pth / .safetensors いずれも対応。複数配置した場合はドロップダウンで選択可能
  • TorchScript/JIT 形式（torch.jit.save で保存）のファイルは自動的にスキップされます
  • ファイル名に sam3 を含まないファイルはリストに表示されません
  • チェックポイントが見つからない場合は HuggingFace（facebook/sam3）から自動ダウンロードを試みます
  • Gated model の場合: facebook/sam3 はアクセス申請が必要です。huggingface.co/facebook/sam3 でライセンスに同意してから huggingface-cli login を実行するか、HF_TOKEN 環境変数にアクセストークンを設定してください

BiRefNet モデルのセットアップ（任意）

BiRefNet背景除去ツールを使う場合は、BiRefNet モデルを ComfyUI/models/background_removal/ に配置します。

ComfyUI/
└── models/
    └── background_removal/
        └── birefnet.safetensors    # または BiRefNet.safetensors / BiRefNet-general.safetensors
  • モデルは HuggingFace の zhengpeng7/BiRefNet からダウンロードできます
  • ComfyUI が標準サポートする comfy.bg_removal_model を使用するため、追加ライブラリのインストールは不要です
  • ファイルが見つからない場合はツールパネルにエラーが表示されます。推論を実行するまでモデルはメモリにロードされません

ComfyUI を再起動すると、ノードメニューの image/masking カテゴリに Mask Editor One が追加されます。

使い方

基本

<img src="docs/4_menu.png" width="110" align="right" alt="Tool sidebar">
  1. Mask Editor One ノードをワークフローに追加
  2. Load Image ボタンをクリックまたはプレビューエリアに画像をドロップして画像を読み込む
  3. ノードの Edit Mask ボタンをクリック → モーダルエディタが開く
  4. 左サイドバーからツールを選んでマスクを描画
  5. Apply で結果を確定 → ノードを実行すれば image / mask 出力に反映

ノードオプション

| 入力 | 説明 | |------|------| | invert_mask | 出力マスクを反転（黒↔白）。モーダルの Invert チェックと双方向に連動 | | blur_radius | 出力マスクにかけるガウスぼかし半径（0〜200 px）。モーダルのスライダーと双方向に連動 | | layer_data | エディタの状態 JSON（通常は自動更新） |

ノード上の Load Image ボタン

| 操作 | 動作 | |------|------| | Load Image クリック | ファイル選択ダイアログを開く | | プレビューエリアにドロップ | 画像ファイルをドロップして読み込む | | 👁 表示: マスク クリック | ノードプレビューをマスク表示に切り替え | | 👁 表示: 画像 クリック | ノードプレビューを画像表示に切り替え |

  • 画像を読み込むと既存のマスクレイヤーがクリアされ、画像のグレースケールから Layer 1 が自動生成される
  • 画像読み込み後はプレビューが自動的に画像表示に切り替わる
  • Apply するとマスクプレビューに自動切り替わり、ノード上に白黒マスクが表示される
  • モーダルを開いたまま BG を変更するにはモーダルフッターの Image ドロップゾーンを使用
<p> <img src="docs/1_node.png" width="220" alt="Node — image preview"> <img src="docs/2_node_mask.png" width="220" alt="Node — mask preview"> </p>

テキストツール

  1. ツールバーの T (Text) を選択
  2. 右パネルでテキスト・フォント・サイズ・太字/斜体・アライメント・モードを設定
  3. キャンバス上をクリック → テキスト入力オーバーレイが表示
  4. テキストを入力して Stamp または Ctrl+Enter で確定、Esc でキャンセル

| オプション | 説明 | |---|---| | Text | スタンプするテキスト（改行で複数行対応） | | Font | フォントファミリー（Arial, Georgia, Impact など 11 種） | | Size | フォントサイズ（8 〜 400 px） | | Style | B (Bold) / I (Italic) | | Align | Left / Center / Right | | Mode | Add / Erase ボタンをクリックで切り替え |

ベクターツール

  1. ツールバーの ✦ (Vector) を選択
  2. キャンバスをクリックしてアンカーポイントを追加（黄色の点）
  3. マウス移動でパスのプレビューをリアルタイム確認
  4. 閉じたパス: 最初のポイント（赤くハイライト）をクリックで閉じて塗りつぶし確定
  5. 開いたパス: Enter で確定（Undo 可）

| ショートカット | 動作 | |---|---| | クリック | アンカーポイントを追加 | | 最初の点をクリック | パスを閉じて確定 | | Enter | 開いたパスで確定 | | Backspace / Delete | 最後のアンカーポイントを削除 | | Esc | パスをリセット |

スプラインは Catmull-Rom → Bézier 変換 で描画されるため、全アンカーを通る滑らかな曲線が自動生成されます。

シェイプツール

  1. ツールバーの ⬜ (Shape) を選択
  2. 右パネルで形状（Rectangle / Ellipse）とモード（Add / Erase）を選択
  3. キャンバスをドラッグして描画

| 操作 | 動作 | |---|---| | ドラッグ | 開始点 → 終了点を対角とする矩形・楕円を描画 | | Shift + ドラッグ | 開始点を中心とした正方形・正円を描画 |

ドラッグ中は青い点線でリアルタイムプレビューが表示されます。

SAM3ツール

  1. ツールバーの ✨ (SAM3) を選択
  2. 右パネルの Model ドロップダウンで使用するチェックポイントを選択（models/sam3/ にある有効なファイルが一覧表示。1つのみの場合は非表示）
  3. プロンプトを入力して Segment または Enter で推論を実行
  4. 候補マスクのサムネイルがスコア順に表示される
  5. サムネイルをクリックでアクティブレイヤーに適用

| オプション | 説明 | |---|---| | Model | 使用するチェックポイントファイル名 | | プロンプト | セグメント対象を英語で指定（例: "dog", "red ball"） | | Mode | Add（白で描画）/ Erase（マスクを消去） |

BiRefNet背景除去ツール

  1. ツールバーの 🔲 (BG Remove) を選択
  2. 右パネルのステータスを確認（モデルが配置済みなら "Model found" と表示）
  3. Remove BG ボタンをクリック → BiRefNet が前景マスクを自動生成してアクティブレイヤーに適用
  4. Mode で結果の適用方法を選択

| オプション | 説明 | |---|---| | Mode | Add（前景を白でマスク追加）/ Erase（前景領域のマスクを消去） |

  • モデルが初回ロード時（約1〜3秒）はボタンが無効化されスピナーが表示されます
  • 推論中もボタンは無効化されます。完了後にレイヤーへ自動適用されます
  • エラーが発生した場合はパネルにエラーメッセージが表示されます

ペイントツール

ブラシ描画は Photoshop 互換の動作：

  • Hardness — 不透明な中心コアの半径を制御。100% でシャープエッジ、0% で全体がソフト
  • Spacing — スタンプ間隔（ブラシサイズに対する割合）
  • Angle — 画像ブラシの回転角度
  • Size Jitter — チェックで有効化。スタンプごとにブラシサイズをランダムに縮小。Amount スライダー（0〜100%）で最大縮小幅を指定（50% の場合 50%〜100% の範囲）
  • Rotation Jitter — チェックで有効化。スタンプごとに 0°〜360° の回転をランダム化。画像ブラシで特に効果的
  • アスペクト比保持 — 画像ブラシのスタンプは元画像の縦横比を維持（brushSize は高さ基準、幅は自動計算）
  • ストローク内累積なし — 1ストローク中に重なった箇所は lighten で最大値を取り、同一ストロークでの過剰な濃度積み上がりを防ぐ

ブラシライブラリ

ペイントツール選択時に Browse Brushes… ボタンからブラシライブラリを開けます。

Brush Library

  • Import Folder — PNG/JPG/WebP/BMP を含むフォルダを再帰的に取り込み
  • Import .ABR — Photoshop の .abr ブラシファイルを取り込み（後述）

ブラシは custom_nodes/comfyui-mask-editor/brushes/ 配下に保存されます。
サムネイルは黒背景に白いブラシシェイプで表示されます（Photoshop のブラシプレビューと同形式）。

ABR ブラシのインポート

対応バージョン:

| バージョン | 対応状況 | |------------|----------| | ABR v1 (Photoshop 5) | ✅ | | ABR v2 non-sub6 (Photoshop 5.5–7, block-length format) | ✅ Unicode ブラシ名対応 | | ABR v2 sub6 / v6 (Photoshop 7+) | ✅ ActionDescriptor パース | | ABR v6 UUID-keyed samp (Photoshop CC+) | ✅ canvas bounds 固定小数点パース | | ABR v6 Atenais 形式 (05_Flames 等) | ✅ offset 320 の BE u16 行カウントテーブル + PackBits | | ABR v10 | ✅ |

インポートされたブラシは RGBA PNG として保存されます：

  • RGB = (255, 255, 255) 白固定
  • A = ブラシ密度（明るいほど不透明 = 強くペイント）

既存ブラシの再インポートについて
ABR 保存形式を変更した場合は、ブラシライブラリの該当フォルダを削除してから ABR を再インポートしてください。

アーキテクチャ

comfyui-mask-editor/
├── nodes.py              # MaskEditorOne (process / layer合成)
├── server.py             # PromptServer API (image cache, brush, SAM3, BiRefNet endpoints)
├── abr_parser.py         # ABR ファイルパーサー
├── sam3_inference.py     # SAM3 推論バックエンド
├── birefnet_inference.py # BiRefNet 背景除去バックエンド
└── web/
    ├── css/maskEditor.css
    └── js/
        ├── maskEditor.js              # ComfyUI 拡張エントリ
        └── editor/
            ├── MaskEditorModal.js     # モーダル UI 全体
            ├── CanvasCompositor.js    # レイヤー合成
            ├── LayerManager.js        # レイヤー管理（Undo/Redo）
            ├── BrushLibrary.js        # ブラシライブラリ UI
            ├── i18n.js               # 翻訳辞書（en/ja/zh）
            └── tools/
                ├── BaseTool.js
                ├── PaintTool.js        # ペイントツール
                ├── ColorTool.js        # カラー選択
                ├── TransparencyTool.js # アルファ→マスク
                ├── TextTool.js         # テキスト形状マスク
                ├── VectorTool.js       # Catmull-Rom スプラインベクター
                ├── ShapeTool.js        # 矩形・楕円シェイプ
                ├── Sam3Tool.js         # SAM3.1 AIセグメンテーション
                └── BiRefNetTool.js     # BiRefNet 背景除去

API エンドポイント

| メソッド | パス | 用途 | |----------|------|------| | POST | /mask_editor/get_node_image | ノード ID から画像/マスク取得 | | POST | /mask_editor/store_image | ブラウザから画像をキャッシュ | | POST | /mask_editor/save_result | レイヤーデータ保存 | | GET | /mask_editor/brushes/list | ブラシフォルダツリー | | GET | /mask_editor/brushes/raw?path=… | ブラシ画像配信 | | POST | /mask_editor/brushes/import | PNG フォルダインポート | | POST | /mask_editor/brushes/upload_abr | ABR ファイル取り込み | | GET | /mask_editor/sam3/status | SAM3 ロード状態・利用可能モデル一覧（models 配列、ファイル名のみ） | | POST | /mask_editor/sam3/segment | テキストプロンプトでセグメンテーション実行（model フィールドでチェックポイント指定可） | | GET | /mask_editor/birefnet/status | BiRefNet ロード状態・モデルファイルの有無（model_path はファイル名のみ） | | POST | /mask_editor/birefnet/remove_bg | BiRefNet で背景除去を実行し、前景マスク（data URL PNG）を返す |

デバッグ

詳細ログを有効化:

import logging
logging.getLogger("abr_parser").setLevel(logging.DEBUG)
logging.getLogger("server").setLevel(logging.DEBUG)

ブラシ取り込み問題の調査時は ComfyUI ターミナルのログを確認してください。

ロードマップ

実装済み:

  • Edit Mask モーダル、ペイント/カラー/透過ツール、レイヤー管理、Undo/Redo
  • 画像ブラシ、ブラシライブラリ、ABR インポート (v1/v2/v6/v10)
  • ブラシ角度、マスク反転トグル（モーダル Invert と連動）
  • Photoshop 互換ブラシ描画エンジン（hardness、アスペクト比保持、ストローク内累積防止）
  • BG ボタン（ローカル画像選択）、ノードプレビュー（画像/マスク切り替え）
  • レイヤー可視アイコン常時表示（斜線でOFF状態を表示）
  • モーダル Reload ボタン（入力画像を再取得）
  • ABR v2 block-length format サポート（Unicode ブラシ名、Photoshop 5.5–7 形式）
  • ABR v6 UUID-keyed samp オフセット修正（canvas bounds 固定小数点パース）
  • TextTool — テキスト形状マスク（フォント/サイズ/Bold/Italic/アライメント、Ctrl+Enter で確定）
  • VectorTool — Catmull-Rom スプラインベクターマスク（リアルタイムプレビュー、閉じたパス/開いたパス対応）
  • ShapeTool — 矩形・楕円マスク（ドラッグ描画、Shift で中心点から正方形・正円）
  • Sam3Tool — SAM3.1 AIセグメンテーション（テキストプロンプト → 候補マスク一覧、スコア表示、add/erase モード）
  • BiRefNet背景除去ツール — ワンクリックで前景マスクを自動生成。comfy.bg_removal_model を使用（追加ライブラリ不要）、add/erase モード対応
  • ブラーフィルター — blur_radius ノードウィジェット + モーダルスライダー（0〜200 px、Gaussian Blur、双方向連動）
  • IS_CHANGED — BG ボタン画像変更時に ComfyUI キャッシュを自動無効化して再実行
  • モーダル内 BG ボタン — モーダルを開いたまま背景画像を変更可能
  • BG 変更時のモーダル自動リロード — ノード側 BG 変更がモーダルに即時反映
  • テキストツールの十字カーソル — テキストツール選択時に画像上のカーソルを十字に変更して挿入位置を明確化
  • Photoshop クイックマスク表示 — composite() をアルファベースに変更し、showImage=true 時に全体オーバーレイ＋描画領域透過のクイックマスクスタイルでプレビュー表示
  • Invert 時のオーバーレイ — Invert 時は描いた部分にオーバーレイ色を表示（ブラシ色として可視化）
  • オーバーレイカラーピッカー — Invert チェック横のカラーピッカーでオーバーレイ色を変更可能
  • 全ツール Mode ボタングループ化 — Mode 選択を <select> から Add/Erase ボタンクリックに変更
  • ノード名変更 — MaskEditorNode → MaskEditorOne、表示名 "Mask Editor" → "Mask Editor One"
  • セキュリティ強化 — リクエストサイズ上限（100 MB）・パストラバーサル修正・エラー情報漏洩防止・torch.load 安全化・ABR サイズ制限（4096 px / 500 件）
  • ABR v6 Atenais フォーマット対応 — 254 バイト固定プリアンブルを持つ Atenais 製 ABR（05_Flames.abr 等）の循環シフトバグを修正（table_off=320 の BE u16 行カウントテーブル形式）
  • ブラシジッター — Size Jitter（Amount スライダーで縮小幅調整）と Rotation Jitter（0°〜360° ランダム回転）をチェックボックスで独立して有効化
  • i18n 多言語対応 — i18n.js モジュールで en/ja/zh の翻訳辞書を管理。フッターの言語セレクターで切り替え時は DOM を再構築してレイヤー状態を保持したまま全 UI テキストを更新。設定は localStorage に永続化
  • BiRefNet バグ修正 — birefnet_inference.py のテンソルインデックス誤り（encode_image() が (B, H, W) を返すのに [0, 0] でアクセスし 1 行分しか取れていなかった）を修正。birefnet_set.json サブグラフ内の InvertMask を削除して前景・背景の逆転を修正
  • image / mask 入力廃止 — ノードの image / mask optional 入力を削除し、画像供給を Load Image ボタン・プレビューエリアドロップのみに統一
  • Load Image ボタン — 常にファイルダイアログを開く（BG ✕ クリアボタンを廃止）
  • 画像→Layer 1 自動生成 — 読み込んだ画像のグレースケール（ITU-R BT.601: 0.299R + 0.587G + 0.114B）をアルファとして Layer 1 を自動生成
  • 新規画像読み込み時のマスク自動クリア — Load Image またはモーダルの Image ドロップゾーンで新しい画像を読み込むと既存のマスクレイヤーを全クリア
  • プレビューエリア常時表示・ノード上ドロップ対応 — BG 有無に関わらず 160 px 固定で常時表示。プレビューエリアへのファイルドロップで画像を読み込み可能
  • 画像読み込み時プレビューモード自動切り替え — 新しい画像読み込み時にプレビューが自動的に「画像表示」に切り替わる

Workflow Studio 連携

ComfyUI Workflow Studio がインストールされている場合、WFS の Image Edit タブから Mask Editor One の機能を直接利用できます（WFS v0.3.64 以降）。

| WFS の機能 | 必要な Mask Editor One の設定 | |---|---| | BG Remove (BiRefNet) | BiRefNet モデルのセットアップ（BiRefNet モデルのセットアップ参照） | | SAM3 セグメンテーション | SAM3 モデルのセットアップ（SAM3 モデルのセットアップ参照） | | ABR ブラシライブラリ | インストールのみで利用可能 |

ブラシは comfyui-mask-editor-one/brushes/ フォルダを共有するため、どちらのツールからインポートしても両方で同じブラシが使えます。

Mask Editor One が未インストールの場合、WFS の BiRefNet・SAM3・ABR ブラシ機能は自動的に無効化（グレーアウト）されます。

ライセンス

MIT License — 詳細は LICENSE を参照。

Acknowledgements

  • SAM3 / SAM 3.1 (Meta FAIR) — テキストプロンプト AI セグメンテーション (Apache-2.0)
  • BiRefNet (ZhengPeng7) — 背景除去モデル (MIT)、ComfyUI ネイティブ実装 (comfy.bg_removal_model) を介して使用
    Zheng et al., "Bilateral Reference for High-Resolution Dichotomous Image Segmentation", CAAI AIR 2024