Skip to content

ketle-man/comfyui-mask-editor-one

BranchesTags

Repository files navigation

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 が追加されます。

使い方

基本

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 ドロップゾーンを使用

Node — image preview Node — mask preview

テキストツール

  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

About

Layer-based modal mask editor for ComfyUI — Paint, Color, Alpha, Text, Vector, Shape, SAM3, BiRefNet, ABR brush import, i18n (en/ja/zh)

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

2 forks
Report repository

Releases 10

v0.1.9 — Workflow Studio API compatibility Latest
Jun 29, 2026
+ 9 releases

Packages

 
 
 

Contributors

Languages