👾 Mask Editor:
MaskEditor refines a mask so its boundaries and selected areas better suit an image-editing task. It can expand or contract the selected region, soften its edges, fill small dark regions, turn soft values into a sharp black-and-white selection, and reverse which areas are selected. These adjustments are applied in a fixed sequence, making the node useful for cleaning up a mask before using it elsewhere in your workflow.
👾 Mask Editor Input Parameters:
mask
The required MASK to refine. A mask represents selection strength across an image: values near 1 indicate selected areas, while values near 0 indicate unselected areas. The node accepts a single mask or a batch-shaped mask, but if you provide a batch, it processes only the first mask. There is no default, minimum, or maximum setting for this input.
grow_shrink
Expands or contracts the selected area. Positive values grow bright regions outward; negative values shrink them inward; 0 leaves their size unchanged. The magnitude controls the size of the elliptical processing area, so larger values produce a stronger change and can remove fine details. The default is 0, the minimum is -100, the maximum is 100, and the step is 1.
blur_radius
Softens mask edges with a Gaussian blur, creating a gradual transition between selected and unselected areas. A value of 0 applies no blur; increasing it produces broader, softer transitions. The node applies this after filling and growing or shrinking, but before thresholding and inversion. The default is 0.0, the minimum is 0.0, the maximum is 50.0, and the step is 0.5.
fill_holes
When enabled, fills dark regions whose detected contour area is smaller than hole_size_threshold. This can remove small unwanted gaps in an otherwise bright mask. The operation runs before growing, shrinking, and blurring. Because the code examines contours in the inverted mask without checking whether each region is fully enclosed, it may also fill small dark regions that touch an edge. The options are True and False; the default is False.
hole_size_threshold
Sets the contour-area cutoff used when fill_holes is enabled. Dark regions with an area strictly smaller than this value are filled; regions at or above it are left unchanged. A higher value allows larger gaps to be filled, but may also remove details you intended to preserve. This setting has no effect when fill_holes is False. The default is 500, the minimum is 100, the maximum is 10000, and the step is 100.
invert
Reverses the finished mask so selected areas become unselected and unselected areas become selected. For soft masks, each value becomes 1 minus its previous value. Inversion happens last, after any thresholding. The options are True and False; the default is False.
threshold
Sets the dividing point for a hard black-and-white mask when apply_threshold is enabled. Values strictly greater than the threshold become 1; values equal to or below it become 0. Raising the threshold generally reduces the selected area, while lowering it generally increases the selected area. It has no effect when apply_threshold is False. The default is 0.5, the minimum is 0.0, the maximum is 1.0, and the step is 0.01.
apply_threshold
Controls whether the processed mask is converted to only 0 and 1 values. Enable it when you need a crisp selection; leave it disabled to retain soft transitions, including those created by blurring. Thresholding occurs after blur and before inversion. The options are True and False; the default is False.
👾 Mask Editor Output Parameters:
mask
The refined MASK for use by subsequent nodes. Its values are returned as floating-point numbers between 0 and 1 under normal mask input conditions. It retains soft values unless apply_threshold is enabled, in which case its values are 0 or 1. The output has a batch dimension containing one mask; if the input held multiple masks, this output represents only the first.
mask_preview
An IMAGE representation of the same refined result, with identical values copied into its red, green, and blue channels. It appears as a grayscale view so you can inspect the mask visually. It is not a preview of the original input: it includes every enabled edit, including thresholding and inversion. The output has one image in its batch.
👾 Mask Editor Usage Tips:
- For a slightly undersized selection, start with a small positive
grow_shrinkvalue and increase it gradually while checkingmask_preview. Use a small negative value when the selection spills past the intended boundary. - For a softer blend, increase
blur_radiusand leaveapply_thresholdoff. Enabling thresholding afterward removes the soft transition and restores a crisp edge. - To clean up small dark gaps, enable
fill_holesand begin with the defaulthole_size_thresholdof 500. Increase it only if the unwanted gaps remain, and check that intentional dark details have not disappeared. - For a hard selection after blurring, enable
apply_thresholdand adjustthreshold. A higher threshold retains only stronger selected areas; a lower threshold includes more of the softened edge. - Use
invertwhen the intended edit should affect the opposite area. Since inversion happens last,mask_previewshows the same reversed selection that themaskoutput provides. - Process batch masks individually when you need every mask edited. This node reads only the first item of a batch-shaped input.
👾 Mask Editor Common Errors and Solutions:
ValueError: zero-size array to reduction operation maximum which has no identity
- Explanation: The mask contains no values, so the node cannot check its range.
- Solution: Confirm that the upstream node produces a non-empty mask with valid image dimensions before connecting it to MaskEditor.
IndexError: index 0 is out of bounds for dimension 0 with size 0
- Explanation: A batch-shaped mask was supplied, but the batch is empty. The node attempts to read its first mask.
- Solution: Ensure the upstream batch contains at least one mask. To process multiple masks, provide them one at a time.
AttributeError: 'NoneType' object has no attribute 'shape'
- Explanation: No usable mask reached the required
maskinput, so the node cannot inspect its dimensions. - Solution: Check the connection to
maskand confirm that the preceding node successfully generated a MASK.
OpenCV error during findContours, dilate, erode, or GaussianBlur
- Explanation: These operations expect a usable two-dimensional mask image. An input with unexpected dimensions or an empty image can cause an OpenCV error when the corresponding edit is enabled.
- Solution: Supply a non-empty MASK with height and width dimensions. If the problem appears only when one setting is enabled, turn that setting off temporarily and check the upstream mask’s shape.
AttributeError: object has no attribute 'cpu'
- Explanation: The value connected to
maskis not a PyTorch mask tensor, so the node cannot convert it for processing. - Solution: Connect a compatible MASK output rather than an IMAGE or another type of value.
The output contains only the first mask
- Explanation: This is a limitation of the node’s batch handling, not an error message. When the input has a batch dimension, the code explicitly selects item 0.
- Solution: Send masks through the node individually if every mask in a batch needs refinement.
Blurred edges still look sharp
- Explanation: If
apply_thresholdis enabled, it converts the blurred result back to values of only 0 and 1. - Solution: Turn offapply_thresholdwhen you want to keep a soft edge. If you need a hard edge in a different position, leave it on and adjustthreshold.
Filled areas include details you wanted to keep
- Explanation: With
fill_holesenabled, the node fills qualifying dark contours based on area; it does not verify that each dark region is an unwanted hole. - Solution: Lower
hole_size_threshold, disablefill_holes, or prepare a mask in which the details you need to preserve are clearly separated from the gaps you want filled.
