mini_color_match:
mini_color_match adjusts a target image’s colors to resemble a reference image while preserving the target’s visual content. You can choose between a simple color shift, per-channel contrast and color matching, a broader color-distribution match, or a correction based on large-scale color differences between similarly composed images. Optional masks let you choose which areas supply the color information, and an adjustable strength lets you blend the correction with the original. This makes the node useful for bringing images into a more consistent palette, correcting a color cast, or matching the look of a reference without replacing the target image.
mini_color_match Input Parameters:
target_image
The required IMAGE you want to recolor. The node measures its colors, applies the selected correction to the entire image, and preserves its image content. If you provide a target mask, the measurements come only from the selected target area, but the correction still affects the whole image. There is no numeric minimum, maximum, or default for this image input.
ref_image
The required IMAGE whose colors guide the correction. The node measures colors from the reference image, or from its selected area if you provide a reference mask. For the Wavelet method, it also uses the reference image’s large-scale color patterns, resizing the reference to the target’s dimensions when needed. There is no numeric minimum, maximum, or default for this image input.
method
The required method selector determines how the target is matched to the reference. Options are Linear, Mean, MKL, and Wavelet; the default is Linear. Linear matches each color channel’s average and spread, so it can change both color balance and contrast. Mean shifts the average color without deliberately matching the spread, making it a useful starting point when you want to retain the target’s contrast. MKL matches broader relationships between color channels as well as their averages and spread. Wavelet transfers differences in broad, blurred color patterns and is best suited to images with similar compositions. The first three methods use masked pixel measurements when masks are supplied; Wavelet checks that the masks select some pixels, but its correction uses the full images rather than restricting the color transfer to masked areas.
strength
The required FLOAT controls how much of the correction is blended into the target. Its minimum is 0.0, maximum is 1.0, default is 1.0, and adjustment step is 0.01. At 0.0, the result retains the original target; at 1.0, it uses the full selected correction. Values between them give you a subtler match. The final pixel values are limited to the normal image range of 0 to 1.
target_mask
An optional MASK that selects which target pixels are measured for Linear, Mean, and MKL. Pixels with mask values greater than 0.1 are included; lower values are excluded. The node resizes the mask to the target image’s dimensions if necessary. Leaving it unconnected selects the whole target for measurement. This is a sampling mask, not a boundary that confines the finished correction: the resulting adjustment applies across the entire target image. There is no declared numeric minimum, maximum, or default for this optional input.
ref_mask
An optional MASK that selects which reference pixels provide color measurements for Linear, Mean, and MKL. Pixels with mask values greater than 0.1 are included, and the mask is resized to the reference image’s dimensions if needed. Leaving it unconnected uses the whole reference for measurement. The mask does not confine where the correction appears on the target. For Wavelet, the correction uses the full reference image even when this mask is connected, provided the mask selects at least some pixels. There is no declared numeric minimum, maximum, or default for this optional input.
mini_color_match Output Parameters:
image
The single IMAGE output is the target image after the chosen color correction has been blended according to strength. It retains the target image’s dimensions and produces one result for each target image in a batch. If either sampling selection contains no pixels above the mask threshold, the corresponding target image is returned unchanged. Output pixel values are clipped to the range 0 to 1 after a correction is applied.
mini_color_match Usage Tips:
- Start with
Meanwhen you mainly want to remove a color cast while keeping the target’s existing contrast. TryLinearwhen you also want the reference’s per-channel variation to influence the result. - Use
MKLfor a general color match when the images do not share the same composition. Begin with a moderatestrengthif the full match looks too pronounced. - Choose
Waveletfor similarly framed images, such as two versions of the same scene with different lighting or color casts. Its broad color correction follows image position, so substantially different compositions can give less useful results. - For
Linear,Mean, orMKL, mask comparable areas in both images—for example, select a wall in each—when unrelated objects would skew the color measurements. Make sure each mask includes a meaningful area above the0.1threshold. - If you need to recolor only part of the target, blend the node’s output with the original image using a separate mask-based compositing step. The masks on this node select measurement areas; they do not limit where the correction is applied.
- When processing a batch, check that your reference images and masks are ordered as intended. The node pairs items by batch position and reuses the first reference image or mask when that batch has fewer items than the target batch.
mini_color_match Common Errors and Solutions:
IndexError: index 0 is out of bounds for axis 0 with size 0
- Explanation: A reference image or connected mask batch may be empty, leaving no first item for the node to reuse while processing a target image.
- Solution: Check that every connected image and mask source produces at least one item, then rerun the workflow.
ValueError: cannot reshape array of size 0 into shape (0,newaxis)
- Explanation:
MKLmay not have enough selected pixels to calculate a reliable color distribution, particularly when a mask selects only one pixel. - Solution: Widen both sampling masks so each includes multiple pixels above
0.1, or useMeanfor a very small selected area.
cv2.error: ... !_src.empty() ... in function 'resize'
- Explanation: OpenCV cannot resize an empty image or mask. This can occur if an upstream step supplies an image or mask with zero width or height.
- Solution: Inspect the upstream image and mask dimensions and ensure they contain valid, nonempty content before connecting them.
ValueError: operands could not be broadcast together with shapes ...
- Explanation: The node expects compatible image and mask dimensions and image color channels. An unusual upstream tensor shape or channel count can make its pixel calculations incompatible.
- Solution: Supply standard, nonempty RGB
IMAGEinputs andMASKinputs, and check any upstream conversion or batching nodes that alter their shapes.
RuntimeError: ... or TypeError: ... when connecting an input
- Explanation: An input may be missing or connected to data that does not match the required
IMAGE,MASK,FLOAT, or method-selector type. - Solution: Verify each connection against the input types above. In particular, connect images to the two image inputs and masks only to the optional mask inputs.
No error message, but the output looks unchanged
- Explanation:
strengthmay be0.0, the target and reference may already have similar colors, or one of the masks may select no pixels above0.1. When either pixel selection is empty, the node returns that target image unchanged. - Solution: Raise
strength, inspect the mask coverage, and try temporarily disconnecting both masks to confirm the correction is working.
No error message, but the correction affects areas outside the mask
- Explanation: The masks control which pixels are measured for color matching; they do not restrict the corrected area.
- Solution: Use a separate masked blend or compositing node to combine the corrected result with the original target only where you want the change.
