Image Mask Editor (C2C)
Paint a mask that actually reaches the node
- image
- input_mask
- mask
- preview
- info
- positive_coords
- negative_coords
- bboxes
- neg_bboxes
- points_json
- bbox_json
- primary_bbox
- spline_data_out
- painted_image
ComfyUI's built-in mask editor is a right-click ritual: you open it on a LoadImage, paint something, save, and then discover the mask lives on that widget and is a pain to reuse, resize, or adjust. This is a full-window editor where the mask belongs to the node and - the part that matters - is a real MASK output you can wire anywhere.
You reach for it when a mask needs a human. Detectors are great until the subject holds an object in front of their face, and segmentation models are great until the edge is hair. Sometimes you just want to brush it in, at native resolution, over the exact image the node received.
How it works
The node keeps only an editor_id in the workflow. The painted masks are PNGs on the server under input/c2c_masks/<editor_id>/, so they survive a restart, and the workflow file stays small. The content hash of those masks is part of the cache key, which is the bit that makes it feel native: edit a mask and the graph re-runs, leave it alone and the graph stays cached.
What the editor shows depends on what you wire into image. A directly connected LoadImage or a C2C/VHS video loader shows its frames with no run needed. Anything computed - a crop, an upscale, a VAE decode - shows the exact frames the node received on its last run. Before that first run you get the nearest upstream preview with a banner telling you so, which is the honest way to handle it.
Tools are the set you'd expect and a couple you wouldn't: brush and eraser with size/hardness/opacity, rectangle, ellipse, polygon, lasso, bucket fill with tolerance, plus colour-range select and SAM smart-select if a SAM 2.1 model is available. Alt+stroke subtracts. View modes cycle overlay → matte → rubylith (the compositing convention: red tint over what's not selected) → outline → bare image. Batches get a frame strip with one mask per frame, and "Copy previous frame" is the shortcut that makes rotoscoping tolerable.
The parameters, and why this is the good design
grow, feather, threshold and invert are node parameters, not baked into the painting. Change a feather and nothing needs repainting. Note the sequencing the tooltip spells out: any non-zero grow hardens the edge first (every partly covered pixel counts), then feather softens it back. So grow +1 and feather 2 is a different mask from feather 2 alone.
frame_mode picks per_frame (each batch index uses its stored frame) or shared (frame 0 applies to everything). combine decides how the painted mask merges with an optional input_mask: replace, add, subtract, intersect - and without an input_mask connected, only replace does anything, since there's nothing to combine with.
Outputs: mask (the final [B,H,W] result, painted frames combined, then grown/feathered/thresholded/inverted), preview (your image with the mask tinted over it), and info (frame count, stored masks, mode, and any notes such as resized frames).
Install
cd ComfyUI/custom_nodes
git clone https://github.com/Code2Collapse/ComfyUI-CustomNodePacks.git
Or "CustomNodePacks" in ComfyUI Manager, then restart ComfyUI. The editor is a JS frontend component shipped with the pack, so a hard browser refresh after a pack update is worth doing if the dialog looks stale. The node itself needs no models; SAM smart-select needs a SAM 2.1 checkpoint and the sam2 package, and edge refine needs ViTMatte weights.
Where people get burned
The masks live on the server, not in the workflow. Send someone your .json and they get an empty mask, because their input/c2c_masks/<editor_id>/ doesn't have your PNGs. Export PNG from the frame menu if you need the mask to travel.
Second: editor_id says "auto-set by the editor UI - don't edit by hand" and it means it. Duplicating a node carries the id; two nodes sharing an id fight over the same stored masks, which looks like the editor randomly reverting frames.
Third: nothing is painted until you open the editor and press Enter to save. The growth stage will happily run on an all-black mask and produce an all-black mask, and it will not be the node's fault.
Inputs (100)
| Name | Type | Default | Description |
|---|---|---|---|
| editor_id | STRING | Auto-set by the editor UI. Don't edit by hand. | |
| frame_mode | COMBO | per_frame | per_frame: each batch index uses stored frame i; shared: stored frame 0 applies to all. |
| grow | INT | 0-256–256 | Grow (positive) or shrink (negative) the mask by this many pixels. Any non-zero value makes the edge hard first (every partly covered pixel counts); feather softens it again afterwards. |
| feather | FLOAT | 00–256 | Soften the mask edge, in whole pixels (0 = off). Gaussian with sigma = 0.33 x this value, the same feather the Smart Crop/Stitch nodes use. |
| threshold | FLOAT | 0.000–1 | Binarize after feather. 0 = keep soft mask. |
| invert | BOOLEAN | false | Invert mask after threshold. |
| imageopt | IMAGE | The picture to draw on (B,H,W,3); drives B/H/W. paint and video need it; points, shape and spline take their size from it when connected. | |
| input_maskopt | MASK | Optional mask to combine with the painted mask. points + box and shape draw onto it; video uses it on the frames your keyframes do not fill. | |
| combineopt | COMBO | replace | How painted mask combines with input_mask. Without input_mask only replace applies. |
| modeopt | COMBO | paint | How the mask is drawn. paint: brush, shapes, lasso, fill and smart select in the editor (and a colour layer); points + box: clicks and boxes for SAM / SeC; shape: a parametric shape; spline: a spline shape or a pattern along it; roto: Bezier shapes keyed over frames; video: painted keyframes, tweened between. Each mode shows only its own controls. |
| canvas_layeropt | COMBO | mask | [paint] mask: paint the mask in the editor; colour: paint colour strokes on the canvas (painted_image), their alpha also becomes mask. |
| canvas_widthopt | INT | 51264–4096 | [paint: colour] Canvas width in pixels. |
| canvas_heightopt | INT | 51264–4096 | [paint: colour] Canvas height in pixels. |
| canvas_brush_typeopt | COMBO | paint | [paint: colour] paint: composite color strokes onto the image. mask_only: build the mask without coloring. |
| canvas_brush_coloropt | STRING | #000000 | [paint: colour] Hex color used by the paint brush (ignored in mask_only mode). |
| canvas_brush_opacityopt | FLOAT | 1.000–1 | [paint: colour] Brush stroke opacity (0 = invisible, 1 = fully opaque). |
| canvas_brush_hardnessopt | FLOAT | 0.800–1 | [paint: colour] Brush profile hardness (0 = soft, 1 = hard edge). |
| canvas_brush_sizeopt | INT | 201–500 | [paint: colour] Brush diameter in pixels. |
| canvas_mask_hardnessopt | FLOAT | 0.500–1 | [paint: colour] Threshold for the solid inner core: pixels brighter than (1 - hardness) clamp to 1.0. |
| canvas_mask_expansionopt | INT | 0-100–100 | [paint: colour] Morphological dilate (positive) / erode (negative) in pixels. |
| canvas_mask_blur_radiusopt | FLOAT | 0.00–100 | [paint: colour] Gaussian blur radius applied to the mask edge in pixels. |
| canvas_mask_blur_strengthopt | FLOAT | 1.000–1 | [paint: colour] Blend factor between the hard mask (0) and the fully-blurred mask (1). |
| canvas_dataopt | STRING | [paint: colour] Internal base64 PNG payload from the JS canvas widget. Do not edit manually. | |
| points_widthopt | INT | 5121–16384 | [points + box] [draw_*/points_bbox] canvas width |
| points_heightopt | INT | 5121–16384 | [points + box] [draw_*/points_bbox] canvas height |
| points_editor_dataopt | STRING | {"points":[],"bboxes":[]} | [points + box] JSON from the interactive canvas |
| points_default_radiusopt | FLOAT | 3.00.5–256 | [points + box] default brush radius |
| points_softnessopt | FLOAT | 1.00–10 | [points + box] gaussian sigma multiplier |
| points_normalizeopt | BOOLEAN | true | [points + box] clamp output to [0,1] |
| shape_inputopt | COMBO | parameters | [shape] parameters: the shape from the controls below; JSON: the shapes from shape_json (power mode). |
| shape_widthopt | INT | 5121–16384 | [shape] [draw_*/points_bbox] canvas width |
| shape_heightopt | INT | 5121–16384 | [shape] [draw_*/points_bbox] canvas height |
| shape_kindopt | COMBO | circle | [shape] geometry |
| shape_cxopt | FLOAT | 256.0-16384–16384 | [shape] |
| shape_cyopt | FLOAT | 256.0-16384–16384 | [shape] |
| shape_radiusopt | FLOAT | 50.00–8192 | [shape] |
| shape_size_wopt | FLOAT | 200.00–16384 | [shape] |
| shape_size_hopt | FLOAT | 100.00–16384 | [shape] |
| shape_rxopt | FLOAT | 100.00–8192 | [shape] |
| shape_ryopt | FLOAT | 50.00–8192 | [shape] |
| shape_top_left_xopt | FLOAT | 100.0-16384–16384 | [shape] |
| shape_top_left_yopt | FLOAT | 100.0-16384–16384 | [shape] |
| shape_x2opt | FLOAT | 400.0-16384–16384 | [shape] |
| shape_y2opt | FLOAT | 400.0-16384–16384 | [shape] |
| shape_thicknessopt | FLOAT | 5.00–500 | [shape] |
| shape_outer_ropt | FLOAT | 100.00–8192 | [shape] |
| shape_inner_ropt | FLOAT | 40.00–8192 | [shape] |
| shape_num_pointsopt | INT | 53–50 | [shape] |
| shape_corner_radiusopt | FLOAT | 20.00–4096 | [shape] |
| shape_cross_sizeopt | FLOAT | 100.00–8192 | [shape] |
| shape_arrow_lengthopt | FLOAT | 200.00–16384 | [shape] |
| shape_head_lengthopt | FLOAT | 60.00–8192 | [shape] |
| shape_head_widthopt | FLOAT | 80.00–8192 | [shape] |
| shape_points_jsonopt | STRING | [[100,100],[400,100],[400,400],[100,400]] | [shape] polygon vertices when shape=polygon |
| shape_valueopt | FLOAT | 1.000–1 | [shape] fill intensity |
| shape_rotationopt | FLOAT | 0.0-360–360 | [shape] rotation deg |
| shape_operationopt | COMBO | set | [shape] blend op |
| shape_batch_sizeopt | INT | 11–256 | [shape] number of frames |
| shape_jsonopt | STRING | {"cx": 256, "cy": 256, "radius": 50} | [shape] raw shape_params JSON (see MaskDrawFrame) |
| shape_featheropt | FLOAT | 0.00–128 | [shape] [transform/draw] feather radius |
| spline_dataopt | STRING | [] | [spline] Spline payload from the JS canvas. edit/flow_path: single shape list. track: keyframes list [{frame:int, points:[[x,y],…]}, …]. |
| spline_typeopt | COMBO | catmull_rom | [spline] interpolation method. catmull_rom/natural_cubic/cardinal pass through the points; b_spline/nurbs are smooth approximating curves; bezier uses tangent handles; polyline = straight. |
| spline_closedopt | BOOLEAN | true | [spline] closed loop vs open path |
| spline_samples_per_segmentopt | INT | 202–128 | [spline] curve resolution per segment |
| spline_feather_radiusopt | FLOAT | 0.00–64 | [spline] gaussian edge feather |
| spline_invertopt | BOOLEAN | false | [spline] invert mask |
| spline_smoothingopt | BOOLEAN | true | [spline] enable spline smoothing |
| spline_centripetal_alphaopt | FLOAT | 0.500–1 | [spline] Catmull-Rom alpha (0.5 = centripetal) |
| spline_widthopt | INT | 00–16384 | [spline] output width (0 = inherit image) |
| spline_heightopt | INT | 00–16384 | [spline] output height (0 = inherit image) |
| spline_mask_coloropt | STRING | #ff00ff | [spline] preview overlay color (hex) |
| spline_mask_opacityopt | FLOAT | 0.400–1 | [spline] preview overlay opacity |
| spline_fillopt | COMBO | mask | [spline] mask: fill (closed) or stroke (open) the spline; flow pattern: a procedural pattern along it (ribbon, wave, dust, smoke...), animated over frames. |
| spline_flow_patternopt | COMBO | ribbon | [spline: flow pattern] procedural pattern |
| spline_flow_thicknessopt | FLOAT | 12.00–1024 | [spline: flow pattern] base stroke thickness |
| spline_flow_amplitudeopt | FLOAT | 8.00–1024 | [spline: flow pattern] modulation amplitude |
| spline_flow_frequencyopt | FLOAT | 2.00–64 | [spline: flow pattern] modulation frequency |
| spline_flow_turbulenceopt | FLOAT | 0.000–4 | [spline: flow pattern] noise turbulence strength |
| spline_flow_turbulence_scaleopt | FLOAT | 1.000.01–32 | [spline: flow pattern] noise spatial scale |
| spline_flow_edge_softnessopt | FLOAT | 1.00–32 | [spline: flow pattern] edge softness in pixels |
| spline_flow_taper_startopt | FLOAT | 0.000–1 | [spline: flow pattern] start-end taper amount |
| spline_flow_taper_endopt | FLOAT | 0.000–1 | [spline: flow pattern] tail-end taper amount |
| spline_flow_framesopt | INT | 11–4096 | [spline: flow pattern] number of animation frames |
| spline_flow_animation_speedopt | FLOAT | 0.0500–4 | [spline: flow pattern] phase advance per frame |
| spline_flow_flow_directionopt | COMBO | forward | [spline: flow pattern] flow direction |
| spline_flow_mod_decayopt | FLOAT | 0.000–4 | [spline: flow pattern] modulation falloff over time |
| spline_flow_seedopt | INT | 00–4294967295 | [spline: flow pattern] noise seed |
| spline_flow_use_embedded_editoropt | BOOLEAN | true | [spline: flow pattern] show embedded spline preview |
| roto_jsonopt | STRING | {"canvas": {"w": 1024, "h": 1024}, "frames": [{"frame": 0, "splines": []}]} | [roto] |
| roto_frame_countopt | INT | 11–4096 | [roto] |
| roto_widthopt | INT | 102416–8192 | [roto] |
| roto_heightopt | INT | 102416–8192 | [roto] |
| roto_samples_per_segopt | INT | 242–256 | [roto] |
| roto_feather_pxopt | FLOAT | 0.00–64 | [roto] |
| roto_frameopt | INT | 00–4096 | [roto] Which keyframe the editor is on. Scrub here, move the shape, and a key is written at this frame. With one key the shape holds for the whole clip; with several the renderer interpolates between them. Does not affect the render on its own. |
| video_session_idopt | STRING | [video] Auto-set by the editor UI. Don't edit by hand. | |
| video_tween_modeopt | COMBO | distance_transform | [video] Frames BETWEEN two painted frames: distance_transform morphs the shape, linear blends, hold keeps the previous painted mask, none leaves them unpainted (frame by frame). |
| video_featheropt | FLOAT | 0.00–32 | [video] Gaussian feather radius (px). 0 = none. |
| video_thresholdopt | FLOAT | 0.000–1 | [video] Binarize after tween. 0 = keep soft mask. |
| video_outside_keysopt | COMBO | empty | [video] Frames before the first / after the last painted frame: empty (the mask stays on the frames you painted) or hold the nearest painted mask. |
Outputs (12)
| Name | Type | Description |
|---|---|---|
| mask | MASK | The final mask [B,H,W] in 0-1: the active mode's mask, combined with input_mask, then grow, feather, threshold and invert. |
| preview | IMAGE | The input image with the mask tinted over it (the mask as a grey picture without an image). |
| info | STRING | Frame count, stored masks, mode and notes (resized frames, frame recording skipped). |
| positive_coords | STRING | points + box: positive points for SAM / SeC; spline: points along the spline. '[]' otherwise. |
| negative_coords | STRING | points + box: negative points. '[]' otherwise. |
| bboxes | BBOX | points + box: the positive boxes. Empty otherwise. |
| neg_bboxes | BBOX | points + box: the negative boxes. Empty otherwise. |
| points_json | STRING | points + box: every point as JSON. '[]' otherwise. |
| bbox_json | STRING | points + box: the first positive box [x1,y1,x2,y2]; spline: the spline's box. '[]' otherwise. |
| primary_bbox | BBOX | points + box: the first positive box [x,y,w,h]; spline: the spline's box. [0,0,0,0] otherwise. |
| spline_data_out | SPLINE_DATA | spline: the spline data, for a tracker or another spline node. |
| painted_image | IMAGE | paint: the colour layer composited over the image (the image itself without colour strokes). |