OpenKatana · Chroma matte:
OpenKatanaMatte creates a soft foreground matte using chroma keying, a technique for separating a subject from a background with a distinct color, such as a green screen or blue screen. It compares each pixel’s RGB color with a chosen background color: close matches are treated as background, while colors farther away are treated as foreground, with a gradual transition between them. This makes it useful for preparing cutouts and compositing artwork or footage onto another background. The process runs directly on ComfyUI image tensors and requires no model download. Because it relies on color differences rather than recognizing objects, it works best with evenly colored backgrounds that are clearly different from your subject. It does not automatically remove color spill, clean up isolated regions, or recognize which objects you intend to keep.
OpenKatana · Chroma matte Input Parameters:
image
The required IMAGE to analyze for foreground and background separation. The node expects a standard ComfyUI image tensor arranged as a batch of images, with height, width, and color channels, and uses only the first three channels as RGB. Standard ComfyUI image values are normally normalized from 0 to 1; this is important because the selected background color is converted to that same scale before comparison. If an additional alpha channel is present, it is ignored rather than incorporated into the result. Each image in a batch is processed independently using the same settings, without resizing or spatial smoothing. There is no default image, numerical minimum, maximum, or selectable option defined for this parameter.
key
The required STRING specifying the background color to remove. The default is #00ff00, which represents pure green. You must enter a hash sign followed by exactly six hexadecimal digits in RGB order, such as #0000ff for blue or #FFFFFF for white; uppercase and lowercase hexadecimal letters are both accepted. Color names, three-digit shorthand, and eight-digit colors with alpha are not accepted. The node converts this color into normalized RGB values and measures how different each image pixel is from it. Choosing a color that accurately represents your actual background generally gives better separation than using a generic green or blue. There is no numerical minimum or maximum and no predefined options list; any valid six-digit RGB color is accepted.
tolerance
The required FLOAT controlling how far a pixel’s color can differ from the key while still being fully classified as background. The default is 0.18, the minimum is 0, and the maximum is 1. The node measures color difference as the RGB distance divided by the square root of three, which places the distance between 0 and 1 for standard normalized images. Pixels whose distance is less than or equal to tolerance receive a mask value of 0. Increasing tolerance removes a broader range of colors, which can help with unevenly lit backgrounds, but may also remove parts of your subject that resemble the key color. Decreasing tolerance preserves more color variation but can leave background areas visible. At a tolerance of 1, all pixels in a standard normalized RGB image are classified as background.
softness
The required FLOAT setting the width of the transition from fully removed background to fully retained foreground in color-distance terms. The default is 0.08, the minimum is 0.0001, and the maximum is 1. Pixels begin transitioning above the tolerance threshold and reach full foreground strength when their normalized color distance reaches tolerance plus softness. Smaller values create a sharper separation; larger values produce a wider range of partially retained pixels and can make similarly colored subject areas appear more transparent. This is not an edge-blur radius: the node evaluates each pixel’s color independently and does not blur neighboring pixels together. If tolerance plus softness exceeds the greatest color distance present in your image, the result may contain no fully white foreground pixels.
OpenKatana · Chroma matte Output Parameters:
mask
The MASK representing foreground strength for each pixel, with values clamped between 0 and 1. A value of 0, typically displayed as black, identifies pixels matching or sufficiently close to the key color; a value of 1, typically displayed as white, identifies pixels sufficiently different from it. Intermediate gray values represent partial foreground strength within the soft transition. For each pixel, the node subtracts tolerance from the normalized RGB color distance, divides the result by softness, and clamps it to the permitted range. The output preserves the input batch size and image dimensions but has no RGB channel dimension, giving a standard mask layout of batch, height, and width. You can connect it to compatible masking or compositing nodes to control how the foreground is used; it is not itself a cutout image or an image with embedded transparency.
OpenKatana · Chroma matte Usage Tips:
-
Sample the key color from a representative area of your actual background rather than assuming it is pure green. For example, a photographed green screen may differ substantially from the default
#00ff00. -
Begin with tolerance 0.18 and softness 0.08, then preview the mask. Increase tolerance gradually if background patches remain visible; decrease it if parts of your subject disappear.
-
For a crisp, graphic-style separation, try reducing softness to 0.01. For a broader transition through mixed background and foreground colors, try increasing it to 0.12, then check that the subject remains sufficiently opaque.
-
Inspect the mask as well as the final composite. Ideally, areas you want to remove are black, solid subject areas are white, and gray is limited to places where partial retention is useful.
-
Keep important subject colors distinct from the key. Green clothing against a green screen can be removed along with the background because this node cannot distinguish objects that share similar colors.
-
Use separate mask-processing nodes if you need spatial feathering, hole filling, removal of isolated patches, or expansion and contraction of the mask. These operations are not performed by OpenKatanaMatte.
-
If a downstream operation treats white as the area to remove rather than the foreground to retain, invert the mask before connecting it. Check the receiving node’s mask convention instead of assuming all mask inputs behave identically.
-
For image sequences, use consistent lighting and key settings where possible. The node processes frames independently and does not provide temporal smoothing, so changing background colors can cause the matte to fluctuate.
OpenKatana · Chroma matte Common Errors and Solutions:
key: expected a six-digit RGB color such as #00ff00
- Explanation: This is the node’s explicit validation error. The key is not a string in the exact
#RRGGBBformat. Common causes include enteringgreen, omitting the hash sign, using#0f0, adding an alpha value, or including surrounding spaces. - Solution: Enter exactly seven characters, such as
#00ff00or#0000FF, with no spaces. Use only hexadecimal digits: 0–9 and A–F.
Image tensor indexing or size mismatch error
- Explanation: PyTorch may report an indexing or incompatible-size error if the supplied image does not have the expected batch, height, width, and RGB-channel structure. The exact error wording depends on the tensor received. A MASK tensor or a grayscale tensor without three color channels is not a suitable replacement for the required IMAGE.
- Solution: Connect a standard ComfyUI IMAGE output. If the source is a mask or grayscale-only tensor, convert it to a standard RGB image before using this node.
Parameter value rejected as outside the allowed range
- Explanation: ComfyUI may reject values outside the declared input limits: tolerance must be between 0 and 1, and softness must be between 0.0001 and 1. This is interface-level validation rather than the node’s explicit key-color error.
- Solution: Restore values within the permitted ranges. In particular, do not use zero softness; use 0.0001 if you need the sharpest transition permitted by the interface.
Mask is entirely black or the subject disappears
- Explanation: This is a result issue rather than an explicit error message. Tolerance may be too high, or the subject’s colors may be too close to the selected key. For normalized RGB images, tolerance 1 removes everything.
- Solution: Lower tolerance, verify the key against the actual background, and inspect whether the subject shares that color. If background and subject colors overlap strongly, consider another masking method.
Background remains white or gray in the mask
- Explanation: The selected key may not match the background closely enough, or tolerance may be too low to include its lighting and color variations.
- Solution: Choose a more representative key color and increase tolerance in small steps. If background pixels fall within the soft transition, increasing tolerance can move them into the fully removed region; increasing softness alone does not make them fully black.
Foreground looks transparent or edges remain green
- Explanation: Excessive softness can leave foreground pixels gray instead of white. Separately, green or blue spill can remain on retained pixels because this node generates a mask without correcting image colors.
- Solution: Reduce softness if the subject is insufficiently opaque, and check whether tolerance is removing too much. For visible color spill, apply a separate despill or color-correction step to the image rather than relying on the mask alone.
