📖 Full node & parameter reference

NODE_REFERENCE.md documents every node in this pack: each input's type, default, valid range and what it actually does, plus every output. It is generated directly from the live NODE_CLASS_MAPPINGS, so the descriptions there are the same strings you see as tooltips in ComfyUI and cannot drift out of date. Start there when you want to know what a knob does; read on here for how the pieces fit together.

ComfyUI-CustomNodePacks

MaskEditControl (MEC) + FolderIncrementer + VFX Suite
Production-grade mask editing, SAM1/2/3 segmentation, alpha matting, inpainting, diagnostics,
temporal mask interpolation, luminance keying, color science, EXR I/O, render-pass
compositing, plate tools, VAE merging & analysis, and auto-versioned file output for ComfyUI.

Installation • Node Reference • Workflows • Troubleshooting • Acknowledgements • License

---

⚠️ Non-Commercial Model Notice: The RMBG-2.0 model weights (briaai/RMBG-2.0) are subject to the BRIA AI RMBG License, which restricts commercial use. If you use the Background Remover node with the rmbg_2.0 backend for commercial purposes you must obtain a commercial licence from Bria AI at https://bria.ai. All other models used in this pack (SAM, SAM2, BiRefNet, ViTMatte, SeC, etc.) are Apache-2.0 or MIT licensed and may be used commercially. See NOTICE.md for full attribution and license details.

---

Overview

ComfyUI-CustomNodePacks ships 72 nodes organized into the following packs:

All nodes are prefixed with (MEC) in the ComfyUI node menu for easy discovery.

Who is this for?

• VFX / compositing artists who need Nuke-quality mask control inside ComfyUI
• Video creators who need temporally consistent masks across hundreds of frames
• Inpainters who want crop → inpaint → stitch pipelines with edge-aware blending
• Anyone tired of SAM giving 3 masks and not knowing which one to pick
• Beginners who want one-click background removal or a node that tells them why their mask failed

---

Installation

1. Clone the repo

cd ComfyUI/custom_nodes
git clone https://github.com/Code2Collapse/ComfyUI-CustomNodePacks.git

Or install via ComfyUI Manager → search "CustomNodePacks".

2. Install dependencies

⚠️ IMPORTANT: Check your existing package versions before installing.

ComfyUI bundles its own torch, torchvision, numpy, and Pillow. Blindly running pip install -r requirements.txt can overwrite them with incompatible versions and break your ComfyUI installation.

Recommended approach: Open requirements.txt, comment out anything already installed, and only install what you're missing:

# Check what you already have:
pip list | grep -i "opencv\|scipy\|safetensors\|transformers"

# Then install only what's missing:
pip install opencv-python>=4.7.0 scipy>=1.10.0 safetensors>=0.4.0

The requirements.txt lists:

Core packages (torch, torchvision, numpy) are already provided by ComfyUI — do not reinstall them.

3. Place SAM model checkpoints

Download SAM 2.1 / SAM 3 weights and place them in:

ComfyUI/models/sams/        ← SAM 3
ComfyUI/models/sam2/        ← SAM 2.1

The SAM Model Loader node auto-detects model type from the filename.

Note: Legacy SAM 1 (ViT-H/L/B) and the original SAM 2.0 line are no longer supported. Only SAM 2.1 and SAM 3 are exposed.

4. (Optional) ViTMatte matting

For the highest-quality edge refinement (hair, fur, glass, lace):

pip install transformers pillow

The ViTMatte model (~400 MB) auto-downloads from HuggingFace on first use. For offline setups, place model files in ComfyUI/models/vitmatte/.

5. Restart ComfyUI

Look for [MEC] Loaded 44 MaskEditControl nodes. in the console to confirm.

---

Detailed Documentation

📚 Start here: docs/README.md — the central documentation index with quick-nav by task, pack-by-pack reference, and image-vs-video pipeline guidance.

Every node's parameters, modes, and outputs are documented in depth in the docs/ folder:

---

Node Reference

Legend

All nodes appear in the ComfyUI menu under MaskEditControl/ categories.

---

Segmentation & SAM

SAM Model Loader (MEC)

Loads SAM 2.1 / SAM 3 checkpoints with optional VRAM offload.

Output: SAM_MODEL — connect to SAM Mask Generator, SAM Multi-Mask Picker, or SAM + ViTMatte Pipeline.

---

SAM Mask Generator (MEC)

Runs SAM 2.1 / SAM 3 inference with point + bbox prompts, iterative refinement, and auto-negative point sampling.

Outputs: masks, best_score, info

---

SAM Multi-Mask Picker (MEC)

Run SAM inference and view all 3 candidate masks side-by-side with IoU scores. An interactive JS widget renders thumbnails — click a mask or press 1 / 2 / 3 to select it instantly.

How it works: SAM always outputs 3 masks ranked by confidence. Instead of guessing which mask_index is best, this node shows all three with quality scores and lets you pick visually. Works with SAM1, SAM2, and HQ-SAM.

Outputs: selected_mask, all_masks (3×H×W), selected_index, scores (JSON), info

Who is it for? When SAM gives you 3 options and you don't know which is best — see them all at once, pick with one click, and pipe the winner downstream.

---

Unified Segmentation (MEC)

One-node dispatcher for SAM 2.1, SAM 3, SeC, VideoMaMa with automatic image vs. video detection.

Outputs: masks, best_score, info

---

SAM + ViTMatte Pipeline (MEC)

End-to-end pipeline: SAM coarse segmentation → iterative refinement → neural alpha matting in a single node. Best possible masking quality for single images.

Outputs: refined_mask, coarse_mask, edge_mask, preview, detected_bbox, score, info

Pipeline stages:

1. SAM coarse mask from point/bbox prompts
2. Iterative refinement (re-run SAM with mask-derived prompts)
3. Edge-aware matting (ViTMatte / guided filter / LAB color)
4. Edge contrast boost
5. Post-processing (hole fill, small region removal)

---

SeC + MatAnyone2 Pipeline (MEC)

End-to-end pipeline: SeC MLLM segmentation → MatAnyone2 temporal alpha matting in a single node. Best for video masking with temporal consistency.

Outputs: rgb (premultiplied), alpha_mask, coarse_mask, preview, info

Pipeline stages:

1. SeC/SAM coarse segmentation (text or point/bbox prompts)
2. MatAnyone2 temporal alpha matting with warmup protocol
3. Optional edge refinement (ViTMatte / guided filter)
4. Post-processing (hole fill, small region removal)

Key advantages over SAM + ViTMatte:

• SeC uses a Vision-Language Model for semantic understanding (text prompts)
• MatAnyone2 provides temporal consistency across video frames
• Better for long sequences with occlusions and re-appearances

---

Semantic Segment (MEC)

Face / body / clothes semantic parsing using SegFormer. Select classes by name to build a combined mask.

Face classes: skin, l_brow, r_brow, l_eye, r_eye, eye_g, l_ear, r_ear, ear_r, nose, mouth, u_lip, l_lip, neck, necklace, cloth, hair, hat

Clothes classes: hat, hair, sunglasses, upper_clothes, skirt, pants, dress, belt, left_shoe, right_shoe, face, left_leg, right_leg, left_arm, right_arm, bag, scarf

Output: mask, info

Who is it for? Portrait retouchers who need to isolate specific facial features or clothing items without manual masking.

---

Alpha Matting

Background Remover (MEC)

One-click background removal using RMBG-2.0 or BiRefNet. Outputs a clean foreground and alpha mask.

Outputs: foreground (premultiplied RGB), mask, info

Who is it for? E-commerce product photography, quick compositing, batch background removal.

---

Matting Node (MEC)

Unified alpha matting with 7 backends. Takes a coarse mask and returns compositing-grade alpha.

Outputs: rgb (premultiplied), alpha_mask

---

ViTMatte Edge Refiner (MEC)

Standalone edge refinement — feed any coarse mask and get clean edges.

---

Trimap Generator (MEC)

Generates a 3-region trimap (white = foreground, black = background, gray = unknown) for ViTMatte input.

Outputs: trimap, foreground, unknown

---

Keying

Luminance Keyer (MEC)

Professional luminance keyer inspired by Nuke's LumaKeyer. Extracts a matte based on image brightness using ITU-R BT.709 luminance with smooth S-curve falloff and gamma correction.

How it works: Converts the image to BT.709 luminance (0.2126R + 0.7152G + 0.0722B), then applies a threshold range with Hermite smoothstep falloff. Five modes target different brightness ranges — auto mode analyzes the image and picks the best range automatically.

Outputs: mask, info (mode, thresholds, luminance stats, per-frame coverage)

Who is it for? VFX artists pulling luminance keys (sky replacement, highlight isolation, shadow grading), colorists building luminance-driven masks for selective color grading, anyone who needs brightness-based masking without a model.

---

Mask Editing & Transform

Mask Transform XY (MEC)

Independent per-axis mask manipulation: erode/expand, directional blur, offset, feather, threshold, invert.

---

Mask Draw Frame (MEC)

Low-level shape drawing. Accepts a shape + JSON shape_params_json. Supports all 12 shapes (circle, rectangle, ellipse, polygon, line, triangle, star, diamond, cross, rounded_rectangle, heart, arrow) with SDF rendering, feathering, rotation, and blend operations.

Prefer Draw Shape (MEC) for new workflows — it exposes all parameters as named inputs instead of raw JSON.

---

Draw Shape (MEC) ★ New

Unified 12-shape drawing node with a single dropdown. All parameters are visible as named inputs with tooltips — irrelevant ones are ignored per shape. Replaces the 5 legacy per-shape wrapper nodes.

Optional: coords_json (per-frame position override), existing_mask, reference_image

Output: mask (MASK)

---

Mask Composite Advanced (MEC)

Combine two masks with compositing operations.

Automatically resizes masks to match if spatial dimensions differ.

---

Mask Math (MEC)

Mathematical operations on a single mask.

All outputs are clamped to [0, 1].

---

Inpainting

Inpaint Crop Pro (MEC)

Crop image tightly around the mask region for focused inpainting, with separate inpaint and stitch blend masks. Feed the crop to any inpaint model, then stitch back seamlessly.

How it works: Computes tight bounding box around the mask, expands by context_expand, produces two separate masks — one for the inpaint model (crisp or feathered) and one for compositing back (Gaussian, edge-aware, Laplacian pyramid, or FFT frequency blend). Supports video-stable cropping (union bbox across all frames).

Outputs: stitch_data, cropped_image, inpaint_mask, stitch_blend_mask, crop_mask, cropped_composite, info

cropped_composite is a red-tinted debug preview showing the mask overlay on the crop — useful for verifying region coverage.

Who is it for? Inpainting power users who want crop → inpaint → stitch with professional blend modes (Laplacian pyramid, frequency blend, edge-aware).

---

Inpaint Composite (MEC) — unified Stitch + Paste Back

Single node that combines Inpaint Stitch Pro and Inpaint Paste Back behind one mode dropdown. The frontend hides parameters that don't apply to the current mode so the UI stays clean.

Outputs: image, mask, info

• In stitch_pro mode mask is the actual blend mask used (Laplacian / edge-aware / FFT etc).
• In paste_back mode mask is the paste rectangle (feathered if enabled), so downstream nodes always get a usable mask.

When to use which mode

Backward compatibility: the legacy Inpaint Stitch Pro (MEC) and Inpaint Paste Back (MEC) nodes are still registered (now labelled "legacy") so existing workflows keep working. New workflows should use Inpaint Composite (MEC).

---

Inpaint Stitch Pro (MEC) — legacy, prefer Inpaint Composite

Composite inpainted image back into the original using stitch data from Inpaint Crop Pro.

How it works: Takes the inpainted result and the stitch data, resizes and places it back at the original crop location, blending using the stored blend mask. Optional mean+std color matching reduces color shift at boundaries.

Outputs: image, blend_mask_used, info

---

Inpaint Mask Prepare (MEC)

Standalone mask cleanup and dual-mask preparation for inpainting workflows.

How it works: Fills holes, removes small disconnected blobs, dilates the mask, then produces two outputs — a clean inpaint mask (for the model) and a stitch blend mask (for compositing). Optional temporal smoothing for video batch consistency.

Outputs: inpaint_mask, stitch_blend_mask, debug_preview, info

---

Inpaint Paste Back (MEC) — legacy, prefer Inpaint Composite

Simple paste-back node: resize the inpainted crop and composite it onto the original with optional Gaussian-feathered alpha blending.

Outputs: image, info

Paste Back vs Stitch Pro vs Composite: All three live in the same suite. The new Inpaint Composite (MEC) node merges Stitch Pro and Paste Back behind one mode dropdown — prefer it for new workflows. The two legacy nodes remain for backward compatibility.

---

Image Comparer (MEC)

Interactive before/after comparison widget with 3 modes: drag-slider split, overlay blend, and difference heatmap.

Modes: ◧ Compare (drag slider) · ⊕ Overlay (alpha blend) · ≠ Diff (heatmap)

Who is it for? Quick visual comparison of before/after results — inpainting QA, model comparison, parameter tuning.

---

Batch & Video

Mask Batch Manager (MEC)

Manipulate mask batches for video workflows.

---

Mask Propagate Video (MEC)

Draw mask on frame 1 → propagate across all frames.

---

Temporal Anchor System (MEC)

Mask interpolation over time using Signed Distance Fields (SDF). Define masks on a few key frames and let the node smoothly morph between them across the full video.

How it works: Computes an SDF for each anchor mask (distance from boundary, negative inside, positive outside), then interpolates the SDF fields between anchor frames using configurable easing. The zero-crossing of the blended SDF produces the interpolated mask boundary. Optional optical flow refinement (Farneback or FFT phase correlation) warps the SDF to follow motion.

Outputs: full_masks (total_frames × H × W), confidence (per-frame float list), info

Who is it for? Video editors who need smooth mask morphing between keyframes — rotoscoping helpers, animated mask transitions, temporal mask interpolation where SAM tracking is overkill.

---

Video Frame Extractor (MEC)

Extract a single frame from a video batch.

Outputs: frame (IMAGE), total_frames (INT), is_video (BOOLEAN)

---

BBox Tools

Six nodes for bounding box manipulation:

All BBox nodes clamp outputs to valid canvas bounds — no negative dimensions, no out-of-bounds errors.

---

Diagnostics

Mask Failure Explainer (MEC)

Diagnose why a mask failed and get actionable fix suggestions. Pure tensor analysis — no models, no VRAM.

How it works: Runs a 5-metric analysis pipeline on your image + mask pair:

Each metric contributes up to 20 points to a severity score (0–100). The node outputs a human-readable explanation, a problem-regions heatmap, the severity score, and a suggested method (e.g. "try ViTMatte for complex edges" or "use BiRefNet for busy backgrounds").

Outputs: explanation (text), problem_regions_mask (heatmap), severity_score (0–100), suggested_method (string)

Who is it for? Anyone whose mask looks wrong and doesn't know why. Plug in your image + bad mask, read the diagnosis, follow the suggestion. Especially useful for beginners learning which segmentation method works for which scenario.

---

Interactive Editor

Points Mask Editor (MEC)

Full-featured interactive canvas editor for placing points and bounding boxes directly on your image.

Toolbar: Pill counters for +pts / −pts / bbox count / radius. Buttons for ✕ Pts, ✕ BBox, ✕ All, ↶ Undo / Redo ↷, ▣ Fit.

Outputs (8):

Connect a reference_image to see it as the editor background for precise placement.

---

Spline Mask Editor (MEC) ★ New

Interactive canvas for drawing spline-based masks directly on your image. Supports Catmull-Rom (smooth curves through points), Bezier (with tangent handles), and polyline (straight segments) modes.

Key improvements: Normalized [0,1] coordinates (resolution-independent), zoom-relative point sizes, segment insertion, close-by-clicking-first-point affordance (highlighted orange), property-based persistence.

Outputs: mask (MASK), coords_json (SAM-compatible points), spline_data_out (for Motion Mask Tracker)

---

Motion Mask Tracker (MEC) ★ New

Per-frame motion detection with 4 independent methods and camera stabilization. Feed a video batch — get a motion mask highlighting what moved between frames.

Outputs: motion_mask (MASK), motion_intensity (FLOAT), info (STRING)

Who is it for? Video editors who need automatic motion masks for selective effects, stabilization-aware change detection, or motion-triggered workflows.

---

Preview

Video Frame Player (MEC)

In-graph video scrubber with drag-crop overlay, trim range, frame stride, lanczos resize, and upscale — all in one node so you don't have to chain Load → Trim → Crop → Resize → Preview. Plays inside the node, supports play/pause + ping-pong loop + I/O hotkeys (mark IN/OUT), and emits the trimmed/cropped/resized batch ready to feed a sampler.

Hotkeys (canvas focused): Space play/pause, ←/→ step ±1 (Shift = ±10), Home/End jump to trim bounds, I/O mark IN/OUT at current frame, R reset crop to full frame.

Full parameter table, pipeline order, and recipes (TikTok 9:16, half-rate stride, 2× lanczos upscale, hero-frame img2img): see docs/video-frame-player.md.

---

Mask Preview Overlay (MEC)

Visualize masks with 5 display modes:

Handles batch size mismatches automatically (expands or repeats to match).

---

Utilities

Universal Reroute / Dot (MEC)

Nuke-style reroute dot that accepts any connection type (IMAGE, MASK, LATENT, STRING, INT, FLOAT, etc.). Use it to keep your workflow wires clean and organized.

Parameter History (MEC)

Tracks every parameter change across ComfyUI runs in a local SQLite database. Query with:

---

FolderIncrementer

Filesystem-aware auto-versioning for output files.

Key features:

• Filesystem-based — no global counter file; scans the actual directory
• Cancel-safe — if you cancel mid-execution, no version is wasted
• Extension-preserving — photo.png → photo/v001/photo.png
• Optional suffix — set the new suffix widget (e.g. _Inpaint) and the basename of filename_prefix / output_filename becomes photo_Inpaint (folder + version_string are unchanged). No more downstream Concatenate nodes just to tag a pass.

Outputs:

---

Node Quick-Reference Table

All 47 nodes at a glance:

VRAM Tiers: 1 = pure tensor math (CPU/GPU, no models), 2 = loads a model (~1–4 GB), 3 = loads multiple models

---

Workflows

Best Quality Masking (Single Image)

[SAM Model Loader]          [Load Image]
  offload_to_cpu: true         ↓
  dtype: float16          [Points Mask Editor]
        ↓                    ↓ points_json, bbox_json
[SAM + ViTMatte Pipeline] ←─┘
  sam_iterations: 2–3
  refine_method: auto
  detail_preservation: 0.85
  edge_contrast: 1.2
        ↓
  refined_mask → compositing

Fast Iteration

[SAM Mask Generator]  →  [ViTMatte Edge Refiner]
  refine_iterations: 2       method: multi_scale_guided

Pick the Best SAM Mask

[Load Image]  →  [Points Mask Editor]  →  [SAM Multi-Mask Picker]
                                              ↓ click thumbnail
                                         selected_mask → downstream

Inpaint Pipeline

[Load Image] + [Mask]  →  [Inpaint Crop Pro]     →  [Any Inpaint Model]
                              context_expand: 1.5        ↓
                              stitch_blend: edge_aware   [Inpaint Stitch Pro]
                                    ↓ stitch_data ──────→     ↓
                                                         seamless result

Video Masking

[Load Video]  →  [Video Frame Extractor]  →  [Points Mask Editor]
                   mode: first                      ↓
                                            [SAM Mask Generator]
                                                    ↓
                                            [Mask Propagate Video]
                                              mode: sam2_video
                                                    ↓
                                              per-frame masks

Temporal Mask Morphing

[Define masks on frames 0, 15, 30]  →  [Temporal Anchor System]
                                          anchor_frames: "0,15,30"
                                          total_frames: 60
                                          easing: smooth_step
                                                ↓
                                          60 interpolated masks

Alpha Matting (From Any Coarse Mask)

[Any Segmentation Node]  →  [Matting Node]
                               backend: auto
                               edge_radius: 15
                                    ↓
                              alpha_mask → compositing

Diagnose a Bad Mask

[Load Image] + [Bad Mask]  →  [Mask Failure Explainer]
                                    ↓
                              explanation: "Dark scene (mean=0.12), low boundary contrast"
                              suggested_method: "Try ViTMatte with edge_radius=20"
                              severity: 65/100

Luminance Keying

[Load Image]  →  [Luminance Keyer]
                    mode: auto
                    falloff: 1.0
                    gamma: 1.0
                       ↓
                  luminance mask (highlights / shadows / midtones)

SeC + MEC (Video Object Segmentation)

SeC handles tracking, MEC handles edge quality:

[SeC Video Segmentation]  →  [ViTMatte Edge Refiner (MEC)]  →  refined masks

Install SeC: cd ComfyUI/custom_nodes && git clone https://github.com/9nate-drake/Comfyui-SecNodes

Spline Mask Drawing

[Load Image]  →  [Spline Mask Editor]
                    spline_type: catmull_rom
                    closed: true
                    feather_radius: 2.0
                       ↓
                  mask → any mask input
                  coords_json → SAM Mask Generator
                  spline_data → Motion Mask Tracker

Motion Detection (Video)

[Load Video Frames]  →  [Motion Mask Tracker]
                           camera_compensation: true
                           detection_mode: combined
                           grow_pixels: 4
                                ↓
                          motion_mask → compositing / routing
                          motion_intensity → Switch node

Draw Shape (Quick Masking)

[Draw Shape (MEC)]
   shape: star
   cx: 256, cy: 256
   outer_r: 100, inner_r: 40
   num_points: 5
   feather: 4.0
        ↓
   mask → downstream

---

VRAM Management

All nodes are designed to work on low-end GPUs (4–6 GB VRAM):

• VRAM monitoring — model loading logs a warning when free VRAM drops below 2 GB
• OOM recovery — if GPU runs out of memory, nodes fall back to CPU instead of crashing
• Offload to CPU — SAM Model Loader has offload_to_cpu to keep models in system RAM
• Auto memory cleanup — all nodes run gc.collect() + torch.cuda.empty_cache() in finally blocks
• dtype control — use float16 or bfloat16 to halve VRAM usage
• Torch-only fallbacks — if opencv-python is not installed, all nodes fall back to pure PyTorch implementations (slightly slower but functional)
• VRAM tiers — each node declares its tier (1 = no model, 2 = one model, 3 = multiple models) so you can plan your workflow

---

Running Tests

The test suite covers all pure-tensor nodes (no GPU models required):

# Run all tests:
python -m pytest tests/ -v --tb=short

# Run a specific node's tests:
python -m pytest tests/test_luminance_keyer.py -v
python -m pytest tests/test_inpaint_suite.py -v
python -m pytest tests/test_mask_failure_explainer.py -v
python -m pytest tests/test_temporal_anchor.py -v
python -m pytest tests/test_sam_multi_mask_picker.py -v

---

Troubleshooting

---

Project Structure

ComfyUI-CustomNodePacks/
├── __init__.py                     # Node registration (47 nodes)
├── folder_incrementer.py           # FolderIncrementer nodes (3)
├── conftest.py                     # Pytest root configuration
├── pyproject.toml                  # Package metadata
├── requirements.txt                # Dependencies
├── js/
│   ├── folder_incrementer.js       # Frontend: FolderIncrementer
│   ├── image_comparer.js           # Frontend: before/after comparison widget
│   ├── points_bbox_editor.js       # Frontend: interactive canvas editor
│   ├── parameter_memory.js         # Frontend: parameter history UI
│   ├── sam_multi_mask_picker.js    # Frontend: 3-mask thumbnail picker
│   ├── spline_mask_editor.js       # Frontend: spline drawing canvas (normalized coords)
│   └── universal_reroute.js        # Frontend: Nuke-style dot
├── nodes/
│   ├── sam_model_loader.py         # SAM 2.1 / SAM 3 model loader
│   ├── sam_mask_generator.py       # SAM inference engine
│   ├── sam_multi_mask_picker.py    # Multi-mask picker + JS widget
│   ├── sam_vitmatte_pipeline.py    # SAM → ViTMatte end-to-end pipeline
│   ├── sec_matanyone_pipeline.py   # SeC → MatAnyone2 video pipeline
│   ├── unified_segmentation_node.py# Unified segmentation dispatcher
│   ├── unified_segmentation.py     # Segmentation backends (deprecated)
│   ├── semantic_segment.py         # SegFormer face/clothes parsing
│   ├── background_remover.py       # RMBG / BiRefNet background removal
│   ├── matting_node.py             # 7-backend alpha matting
│   ├── vitmatte_refiner.py         # Standalone edge refiner
│   ├── trimap_generator.py         # Trimap generation
│   ├── luminance_keyer.py          # BT.709 luminance keyer
│   ├── mask_transform_xy.py        # Per-axis mask transform
│   ├── mask_draw_frame.py          # Shape drawing (12 shapes + DrawShapeMEC unified node)
│   ├── mask_composite.py           # Mask compositing ops
│   ├── mask_math.py                # Mathematical mask ops
│   ├── mask_batch_manager.py       # Batch manipulation
│   ├── mask_propagate_video.py     # Video mask propagation
│   ├── mask_preview.py             # Mask visualization
│   ├── mask_failure_explainer.py   # Mask diagnostics engine
│   ├── temporal_anchor.py          # SDF interpolation system
│   ├── inpaint_suite.py            # Crop/stitch/paste-back/prepare (4 nodes)
│   ├── bbox_nodes.py               # BBox tools (6 nodes incl. BBoxSmooth)
│   ├── points_mask_editor.py       # Interactive point/bbox editor
│   ├── spline_mask_editor.py       # Interactive spline mask drawing
│   ├── motion_mask_tracker.py      # Per-frame motion detection (4 methods)
│   ├── stabilization_utils.py      # Camera stabilization helpers
│   ├── video_frame_extractor.py    # Frame extraction
│   ├── image_comparer.py           # Before/after image comparison
│   ├── universal_reroute.py        # Nuke-style reroute dot
│   ├── parameter_memory.py         # Parameter history + SQLite
│   ├── model_manager.py            # Shared model cache & download
│   └── utils.py                    # Shared utilities
├── docs/
│   ├── inpaint-suite.md            # Inpaint Crop/Stitch/Paste Back/Prepare
│   ├── mask-editing.md             # Transform, Draw, Composite, Math, Batch, Preview
│   ├── sam-segmentation.md         # SAM, Unified Segmentation, Pipelines
│   ├── matting-refinement.md       # Matting, ViTMatte, Trimap, Keyer
│   ├── video-temporal-bbox.md      # Video, Temporal Anchor, BBox tools
│   └── utility-nodes.md            # Editor, Comparer, Diagnostics, Utils
├── tests/
│   ├── test_luminance_keyer.py     # 38 tests
│   ├── test_inpaint_suite.py       # Inpaint suite tests
│   ├── test_mask_failure_explainer.py # Diagnostics tests
│   ├── test_temporal_anchor.py     # Temporal anchor tests
│   └── test_sam_multi_mask_picker.py  # Multi-mask picker tests
├── example_workflows/
│   ├── basic_sam_segmentation.json
│   ├── sam_vitmatte_pipeline.json
│   ├── mask_editing_toolkit.json
│   ├── bbox_pipeline.json
│   └── video_mask_propagation.json
└── third_party/                    # Reference implementations

---

Acknowledgements

This project builds on or references the following open-source work:

---

License

MIT

---

Use in image/video generation pipelines (Flux / Qwen-Image / Wan / Z-Image / ERNIE-VL)

This umbrella pack aggregates ~72 nodes across four sub-namespaces — Folder Incrementer (_FOLDER_MAPPINGS, 3 nodes), MEC tools (_MEC_MAPPINGS, 30 nodes covering masking, SAM/ViT-Matte segmentation, inpaint crop/stitch/paste-back, spline editors, motion mask trackers, draw shapes, VAE merge/inspect, batch version manager, temporal consistency, model metadata, image comparer, parameter history, semantic segment, luminance keyer, mask failure explainer, temporal anchor, SAM multi-mask picker), Paint nodes (_PAINT_MAPPINGS), and MA nodes (_MA_MAPPINGS). The nodes are model-agnostic — they speak ComfyUI's native IMAGE, MASK, LATENT, VAE, and MODEL types — so they slot into any sampler graph regardless of which diffusion family produces the pixels.

Two general patterns recur across all sampler families:

1. Inpaint trio — InpaintCropProMEC → diffusion sampler (any family) → InpaintPasteBackMEC (or InpaintStitchProMEC for soft seams). Allows full-resolution refinement at a fraction of the VRAM, regardless of which model is loaded.
2. Versioned saves — wire BatchVersionManagerMEC (or the standalone FolderIncrementer) version_string into the sampler's Save Image.filename_prefix so every queued prompt produces a clean, ordered file series.

The UniversalRerouteMEC-equivalent typed reroutes (and the SAM / ViT-Matte loaders) keep the graph readable as it scales from a single Flux T2I bench into a multi-model Wan + Qwen-refine + Flux-detail composite.

---

Made with ❤️ for the ComfyUI community

---

Full Node & Parameter Reference

A complete, auto-generated reference covering every node, return type and widget exposed by this pack lives in NODE_REFERENCE.md. It is regenerated whenever INPUT_TYPES change.