Keep Black:
Keep Black helps preserve clean, dark areas when a shot has been converted from SDR to HDR. That conversion can introduce unwanted noise into areas that were originally black or nearly black. Instead of applying noise reduction across the entire shot, this node restores the original SDR values in the darkest regions, retains the HDR values in brighter regions, and blends smoothly between them across a selected luminance range. Luminance describes how bright an area is, so the correction is guided by brightness rather than a manually painted mask. This targeted approach helps protect the original appearance of black areas without unnecessarily replacing brighter HDR detail. It is designed for images in ACEScg, a scene-linear color space commonly used in visual-effects workflows, and is not itself an SDR-to-HDR converter or a general-purpose denoiser.
Keep Black Input Parameters:
hdr
Required IMAGE input containing the frames produced by your SDR-to-HDR conversion, in ACEScg scene-linear color. These frames supply the HDR appearance that is retained above the upper luminance threshold and blended with the original SDR values in the transition region. Connect the converted version of the same shot supplied to sdr, with matching framing, resolution, and frame order. The node processes frames in corresponding pairs and does not perform alignment, resizing, or color-space conversion. If the two image batches contain different numbers of frames, only the number available in the shorter batch is processed. This input has no numeric minimum, maximum, or default value.
sdr
Required IMAGE input containing the original SDR shot from which the HDR frames were made, expressed in ACEScg. Although the source is described as SDR, it must already be converted into the expected color space rather than supplied as unconverted display-encoded imagery. Its pixel values provide the replacement for the darkest regions, preserving the original black appearance instead of any noise introduced by the HDR conversion. In the transition region, these values are blended with the HDR version. Use the actual corresponding source frames: an unrelated or misaligned shot can introduce incorrect detail or visible changes where the SDR version is restored. This input has no numeric minimum, maximum, or default value.
low
Required FLOAT input defining the lower luminance threshold, below which the node uses the original SDR values. The minimum is 0.0, the maximum is 1.0, the default is 0.001, and the adjustment step is 0.0001. Increasing this value extends full SDR preservation into brighter shadow areas; decreasing it restricts full preservation to darker regions. Between low and high, the node gradually transitions from SDR to HDR rather than switching abruptly. These thresholds refer to brightness in the expected scene-linear working space, not display brightness percentages. Keep low strictly below high to establish a meaningful transition interval; the provided interface allows both values to be adjusted independently and does not enforce that relationship.
high
Required FLOAT input defining the upper luminance threshold, above which the node uses the HDR values. The minimum is 0.0, the maximum is 1.0, the default is 0.01, and the adjustment step is 0.0001. Raising this value extends the SDR-to-HDR blend farther into the shadows, so more low-brightness areas receive some contribution from the original SDR shot. Lowering it brings the transition back toward black, retaining HDR values sooner. The distance between low and high controls the brightness range over which the smooth transition occurs: a wider interval spreads the blend across more shadow tones, while a narrower interval concentrates it. Keep high greater than low; the supplied code does not document the behavior of equal or reversed thresholds.
Keep Black Output Parameters:
image
The IMAGE output contains the processed frame batch, combining original SDR values in the darkest areas, HDR values in brighter areas, and a smooth blend between the two in the transition range. It is intended to remain in the shared ACEScg working space and can be passed to subsequent processing or an appropriately color-managed export workflow. This is an image result, not a mask or a measurement report. Frames are returned in their original paired order, and the output frame count equals the smaller of the two input batch sizes; extra frames in the longer input are not included. The output preserves the original SDR black values rather than necessarily forcing dark pixels to absolute zero.
Keep Black Usage Tips:
- Start with
low = 0.001andhigh = 0.01, then inspect the darkest areas through your normal color-managed viewing setup before changing either value. - Place the node after your SDR-to-HDR conversion. Supply that conversion’s result to
hdrand the corresponding original SDR shot, converted to ACEScg, tosdr. - If unwanted noise remains in near-black areas, increase
lowslightly to restore SDR values over a broader dark range. If necessary, also increasehighwhile keeping it abovelowso the correction fades smoothly into the HDR image. - If the correction changes too much shadow detail, lower the thresholds to restrict its influence closer to black. Compare corrected and uncorrected frames, especially where faint textures or subtle lighting are important.
- Keep both inputs spatially aligned and frame-synchronized. The node pairs frames by their batch position; it does not identify matching frames or compensate for camera movement between mismatched sources.
- Check batch lengths before processing a sequence. A single SDR reference frame is not automatically repeated across a longer HDR batch; with one SDR frame, the node produces only one output frame.
- Preview several frames from a moving shot, not just a still. Watch for changes in shadow appearance as areas move through the selected luminance range.
Keep Black Common Errors and Solutions:
ValueError: need at least one array to stack
- Explanation: This NumPy error can occur if either input contains no frames. The node processes only the available frame pairs, so an empty input leaves no processed images to assemble.
- Solution: Check that both upstream branches successfully produce at least one image. Verify your loader’s frame range and any batch-selection settings before running the node again.
Possible shape error: operands could not be broadcast together
- Explanation: This type of NumPy error can occur when corresponding images have incompatible dimensions or channel layouts. The node passes the images directly to the pixel-processing operation without resizing them.
- Solution: Resize both inputs to the same width and height and use compatible image channels, normally matching RGB images. Also confirm that both branches represent the same crop and framing. The exact error wording depends on where the mismatch occurs.
Incorrect black levels or unexpectedly strong shadow changes
- Explanation: This is a visual problem rather than a dedicated error message. Both inputs are expected to be in ACEScg, with the HDR frames explicitly scene-linear. Display-encoded imagery or mismatched color spaces can make the brightness thresholds act on inappropriate values.
- Solution: Convert both branches to the expected ACEScg working space before this node, and inspect the result through the appropriate viewing transform. Do not assume that an IMAGE connection guarantees the correct color encoding.
Abrupt or unexpected transition between SDR and HDR
- Explanation: Equal or reversed thresholds do not define the intended smooth transition interval. The input controls allow these settings, but the provided code does not specify how the underlying operation handles them.
- Solution: Set
lowbelowhigh. Restore the defaults of 0.001 and 0.01 as a starting point, then adjust gradually while maintaining a positive gap.
Output contains fewer frames than expected
- Explanation: This is the node’s defined batch behavior, not an explicit error. It processes the smaller input batch length and ignores remaining frames in the longer batch.
- Solution: Supply the same number of corresponding frames to both inputs. If you intentionally need a repeated reference, prepare that batch upstream rather than expecting this node to repeat it.
Ghosting, incorrect details, or flickering in dark regions
- Explanation: These visual problems can result from mismatched source frames, crops, or alignment. Because dark areas receive SDR image values, any disagreement between the two versions can become visible.
- Solution: Confirm that the HDR shot was generated from the supplied SDR shot and that frame order, starting frame, resolution, and framing match. Correct any timing or alignment differences before applying Keep Black.
Dark areas remain noisy after processing
- Explanation: Keep Black restores the original SDR values rather than performing general noise removal. Noise already present in the SDR source can remain, and HDR noise outside the selected dark range may be retained.
- Solution: Compare the SDR source with the result to identify where the noise originates. Adjust the thresholds cautiously if the affected areas fall outside the correction range; use a separate denoising step when the source itself is noisy.
