HDR Match:
HDR Match brings an HDR shot into balance with the original plate—the background footage or image onto which your edits are composited. An SDR-to-HDR conversion can introduce its own exposure and white balance, so even areas that were not edited may no longer match the original scene. This node uses those unchanged areas as a reference, measures their mid-tones across the shot, and calculates one overall gain for each of the red, green, and blue channels. It then applies those same gains throughout the shot, avoiding the exposure flicker that independently calculated frame-by-frame corrections could introduce. Because the correction scales values rather than compressing the tonal range, it preserves brightness ratios within each channel and retains the extra highlight range created by the HDR conversion for later grading. This is a global level and color-balance adjustment, not a local relighting, alignment, or tone-mapping operation; when there is not enough unchanged mid-tone information to make a reliable measurement, the HDR shot is left unchanged.
HDR Match Input Parameters:
image
Required input of type IMAGE. This is the shot produced by your SDR processing path, already in the plate’s color space. It acts as the fallback result: if you do not connect an HDR shot, the node returns this image directly without matching it to the plate. When an HDR shot is connected, this input is not used to calculate the correction or produce the matched result. This makes it useful in workflows where you want the same downstream connection to work whether or not an HDR version is available. No numeric minimum, maximum, or default value is specified for this input.
plate
Required input of type IMAGE. This is the original reference plate, with its own scene values in its color space. The node compares its unchanged regions with corresponding regions of the HDR shot to determine the overall red, green, and blue adjustments. For meaningful results, the plate and HDR shot should depict the same scene, be spatially aligned, and already use the same color space; this node does not perform color-space conversion or image registration. Different HDR and plate resolutions are supported by sampling corresponding relative positions. If the plate contains fewer frames than the HDR shot, its last frame is reused for the remaining HDR frames rather than looping the plate or shortening the output. No numeric minimum, maximum, or default value is specified.
grow
Required FLOAT input with a default of 24.0, a minimum of 0.0, and a maximum of 512.0. This controls how far the changed-region mask is expanded before the node decides which pixels are safe to measure, expressed in pixels at the plate’s resolution. Expanding this exclusion area helps keep blended edges, feathering, and nearby edited pixels out of the reference measurement. A larger value is useful when your composite affects pixels beyond the original mask boundary, but it also leaves fewer untouched pixels available for matching. A value of 0.0 adds no extra exclusion margin. The implementation accounts for a mask whose resolution differs from the plate, so you should choose this setting based on plate pixels rather than mask pixels. This setting has no effect when the HDR shot or mask is absent, because matching is bypassed in those cases.
mask
Optional input of type MASK. This identifies the regions changed by your edits, allowing the node to measure the unchanged surroundings instead. Mask values greater than 0.02 are treated as changed before the exclusion region is expanded by grow; consequently, even faint nonzero mask edges can be excluded from the measurement. Both a single two-dimensional mask and a batch of masks are supported, and the last available mask is reused if the HDR shot has more frames than the mask batch. The mask can have a different resolution from the plate, but it must still represent the corresponding image regions. If this input is absent, the HDR shot passes through unchanged because the node has no supplied information identifying untouched areas. An all-zero mask is different from an absent mask: it marks no areas as changed, so the entire sampled image can be considered for measurement. No numeric minimum, maximum, or explicit default value is declared in the interface.
hdr
Optional input of type IMAGE. This is the HDR version of the shot that you want to bring to the plate’s level, already expressed in the plate’s color space. When both this input and a mask are available, the node measures untouched mid-tones and applies a single set of channel gains to every HDR frame. The adjustment affects every pixel, including edited content, while preserving the extended highlight range rather than applying a tone-mapping compression. The number of HDR frames determines the output frame count during matching. If this input is absent, the required image input passes through unchanged; if it is present but the mask is absent, this HDR input passes through unchanged. No numeric minimum, maximum, or default value is specified.
HDR Match Output Parameters:
image
Output of type IMAGE containing the selected or corrected shot. When an HDR shot and mask are supplied and enough untouched mid-tones are available, this is the HDR shot scaled by one constant gain per color channel across the entire sequence. The result is intended to sit at the original plate’s level while retaining the HDR shot’s highlight range for further grading. Matching operates at the HDR shot’s resolution and produces one frame for each HDR input frame; it does not resize the result to the plate or perform the composite itself. If the HDR input is missing, the output is the required image input unchanged. If the mask is missing, or too few untouched mid-tones are available for a reliable fit, the HDR shot is returned without a level adjustment. Measurement details are written to the application log rather than provided as an additional output.
HDR Match Usage Tips:
- Supply the plate and HDR shot in the same color space before matching. A channel-gain adjustment cannot replace a proper color-space conversion, so mismatched encodings can produce misleading exposure and color corrections.
- Use the mask that identifies your composite’s changed regions, not a mask of the untouched background. The node measures outside the changed region, so reversing that meaning would direct it toward the wrong reference pixels.
- Start with
growat its default of 24.0, then adjust it to cover the composite’s expanded and feathered edges. Increase it if edited edges are contaminating the match; reduce it if too little unchanged background remains. - Preserve some unchanged mid-tone areas whenever possible. A frame filled almost entirely with edits, deep shadows, or bright highlights may not provide enough reliable information, even when a mask is connected.
- For a sequence, provide the complete HDR batch and corresponding plate and mask batches together. The node measures across the shot and uses the same gains for every frame, preventing frame-to-frame variation introduced by this correction.
- Check batch lengths before processing moving footage. A single plate or mask can be reused automatically, but its fixed content may not correspond correctly to later frames when the camera or edited subject moves.
- Align the plate and HDR shot upstream. Different resolutions are supported, but camera shifts, crops, or displaced subjects are not automatically corrected by this node.
- Read the application log after matching. The success report includes the sample count, the red/green/blue adjustments in stops, and the median mid-tone error after correction; use these alongside visual inspection to judge the result.
- Keep subsequent processing HDR-compatible if you want to retain the highlight range. This node preserves that range during matching, but later operations that clamp values or export to a limited-range format can still discard it.
HDR Match Common Errors and Solutions:
PaintAPlate HDR Match: no matte, so nothing untouched to measure: the HDR shot as it was made
- Explanation: This is an informational log message, not a processing failure. An HDR shot was supplied without a mask, so the node intentionally returned the HDR shot unchanged.
- Solution: Connect a mask identifying the edited regions if you want level matching. If an unchanged HDR pass-through is what you intended, no action is needed.
Too few mid-tones to measure: the HDR shot as it was made
- Explanation: The log includes the number of untouched samples followed by this message when the measurement cannot find enough usable mid-tones. Possible causes include an edit covering nearly the whole image, a very large exclusion margin, or unchanged areas consisting mostly of shadows or highlights. The HDR shot is left unadjusted.
- Solution: Check that the mask marks changed areas correctly, reduce
growif it excludes unnecessarily large regions, and provide a plate and shot with genuinely unchanged mid-tone areas. If no reliable reference region exists, the node cannot determine the intended level from that material.
Output is identical to the SDR image
- Explanation: This is an expected fallback behavior rather than a specific error message. When
hdris not connected, the node immediately returnsimagewithout running the matching operation. - Solution: Connect your HDR shot to
hdrand provide the appropriate mask if you want HDR matching. Keep the current setup if you want the SDR path to pass through.
Matching produces an unexpected brightness or color shift
- Explanation: This is a possible result issue, not a dedicated error string. The measurement can become misleading if the mask is inverted, edited pixels remain outside the exclusion area, the images use different color spaces, or corresponding image locations do not show the same scene content.
- Solution: Confirm that the mask covers edits, expand
growenough to exclude blended edges, and verify the plate and HDR shot’s alignment and color-space preparation. Inspect the logged channel adjustments and compare unchanged mid-tones before and after matching.
Later frames do not match the plate correctly
- Explanation: This is a possible sequence issue rather than a specific error message. When the plate or mask batch is shorter than the HDR batch, the node reuses the last available plate or mask. That behavior can make the reference incorrect for later frames in moving footage.
- Solution: Supply plate and mask batches that correspond to the full HDR sequence. Reuse a single frame only when its reference content and mask placement remain appropriate throughout the shot.
No useful untouched area remains after mask expansion
- Explanation: This is a troubleshooting condition, not a separate logged error. A mask covering most of the frame, combined with a large
growvalue, can exclude the remaining background and lead to the insufficient-mid-tones fallback. - Solution: Inspect the mask at plate resolution, remove unintended marked regions, and lower
growonly as far as is safe for the composite’s feathered boundary. Do not expose edited pixels merely to force a measurement.
Processing fails with an array shape or indexing error
- Explanation: The supplied code does not define a custom error message for malformed image or mask data. Empty batches, images without the RGB channels expected by the matcher, or inconsistent plate dimensions can cause lower-level array errors. Different resolutions between the HDR shot, plate, and mask are supported and are not, by themselves, an error.
- Solution: Supply valid, nonempty ComfyUI IMAGE and MASK data, ensure images contain RGB channels, and keep the plate’s dimensions consistent throughout its batch. If an error persists, inspect the application traceback to identify the upstream input producing invalid data.
