Skip to content

Tonemap

dnjulek edited this page Oct 30, 2026 · 2 revisions

HDR tone and gamut mapping on the CPU, a port of vs-placebo's Tonemap.

Usage

vszip.Tonemap(
    clip: vs.VideoNode,
    src_csp: int = 1,
    dst_csp: int = 0,
    dst_prim: int | None = None,
    src_max: float = 0,
    src_min: float = 0,
    dst_max: float = 0,
    dst_min: float = 0,
    dynamic_peak_detection: bool = True,
    smoothing_period: float = 20.0,
    scene_threshold_low: float = 1.0,
    scene_threshold_high: float = 3.0,
    percentile: float = 100.0,
    black_cutoff: float = 1.0,
    gamut_mapping: int = 1,
    tone_mapping_function: int = 5,
    tone_mapping_function_s: str | None = None,
    tone_mapping_param: float = (per function),
    metadata: int = 0,
    use_dovi: bool = (src_csp == 3),
    dovi_el: vs.VideoNode | None = None,
    show_clipping: bool = False,
    contrast_recovery: float = 0.0,
    contrast_smoothness: float = 3.5,
    lut_size: int = 256,
    mastering_clip: float = 1.0,
    film_strength: float = 0.3,
    inverse_tone_mapping: bool = False,
    knee_adaptation: float = 0.4,
    knee_minimum: float = 0.1,
    knee_maximum: float = 0.8,
    knee_default: float = 0.4,
    knee_offset: float = 1.0,
    slope_tuning: float = 1.5,
    slope_offset: float = 0.2,
    spline_contrast: float = 0.5,
    reinhard_contrast: float = 0.5,
    linear_knee: float = 0.3,
    exposure: float = 1.0,
    gamut_expansion: bool = False,
    lut3d_size: Sequence[int] = (48, 32, 256),
    lut3d_tricubic: bool = False,
    perceptual_deadzone: float = 0.3,
    perceptual_strength: float = 0.8,
    colorimetric_gamma: float = 1.8,
    softclip_knee: float = 0.7,
    softclip_desat: float = 0.35,
    cache_frame: bool = True,
)

Coming from vs-placebo:

  • Shared arguments keep vs-placebo's names and defaults.
  • The positional layout differs. vszip inserts black_cutoff after percentile and has no visualize_lut or log_level. A positional call can therefore bind a different argument without failing.
  • So convert positional arguments to keywords before replacing core.placebo.Tonemap with core.vszip.Tonemap.

See also Differences from vs-placebo.

Examples

# HDR10 -> SDR BT.709
sdr = clip.vszip.Tonemap(src_csp=1, dst_csp=0)

# Dolby Vision (profile 5/8, or the base layer of 4/7): every frame must
# carry the DolbyVisionRPU frame prop. Use BestSource R22 or newer (see the
# note below)
src = core.bs.VideoSource("dv.mkv")
sdr = src.vszip.Tonemap(src_csp=3)

# Dolby Vision with its FEL enhancement layer as a second clip of the same
# frames: the RPUs are then read from the EL clip
bl = core.bs.VideoSource("bl.hevc")
el = core.bs.VideoSource("el.hevc")
sdr = bl.vszip.Tonemap(src_csp=3, dovi_el=el)

# by name instead of number
sdr = clip.vszip.Tonemap(tone_mapping_function_s="bt2390", gamut_mapping=0)

Source filter for Dolby Vision. Use BestSource R22 or newer (pip install -U vapoursynth-bestsource). Both BestSource and FFMS2 export DolbyVisionRPU, but only R22 got every frame right in testing. Tested against the RPU NAL units in the streams themselves:

  • BestSource R22 attached each frame its own RPU on every tested file (MP4, MKV, raw HEVC), in any access order.
  • FFMS2 5.2.1 (the latest on PyPI) gets some MP4s wrong. On Dolby's Sol Levante MP4s (profiles 5, 8.1 and 8.4) it gives one frame per 48 (45, 93, 141, …) the previous frame's RPU, losing 86–125 of each file's distinct RPUs. With random access it sometimes gets them right, so the result depends on access order. No error is raised; those frames just decode with their neighbour's metadata. MKV files were correct.
  • BestSource R18 and older dropped the prop on those same frames instead. A frame without its RPU fails Dolby Vision processing; with peak detection on, so does any later frame whose detection window reaches it.

Notes

  • Formats. Input is RGB or YUV (4:4:4, 4:2:2, 4:2:0, 4:4:0):

    • HDR10/HLG: 9..16-bit integer or 32-bit float;
    • Dolby Vision (src_csp=3) and its EL: 9..16-bit integer YUV only.

    Output is RGB48/YUV444P16 for integer input, RGBS/YUV444PS for float input.

  • Integer depths below 16 bit.

    • Limited range: read as if shifted to 16 bit, bit-identical to converting the clip with resize.Point first (what vs-placebo needs).
    • Full-range HDR10/HLG: BT.2100 full-range scaling to 16 bit (luma × 65535 / (2^bits − 1), chroma likewise around mid-grey), unrounded. That stays within resize.Point's rounding, but is not a plain shift.
    • Dolby Vision: reads code / 2^bits, the RPU's own scale. For a full-range base layer (profile 5), pass the native depth: a 16-bit conversion rescales the codes instead of shifting them.
  • YUV matrix. YUV input is decoded as BT.2020 NCL, as vs-placebo does.

  • Frame props read:

    • _Range (or _ColorRange) and _ChromaLocation;
    • ContentLightLevelMax, ContentLightLevelAverage;
    • MasteringDisplayMinLuminance, MasteringDisplayMaxLuminance;
    • MasteringDisplayPrimariesX, MasteringDisplayPrimariesY;
    • MasteringDisplayWhitePointX, MasteringDisplayWhitePointY;
    • PLSceneMax, PLSceneAvg, in nits: a 1-value PLSceneMax is CIE Y, a 3-value one is HDR10+.

    Without mastering primaries, Display P3 is assumed, as in vs-placebo.

  • Frame props written. _Matrix, _Transfer, _Primaries and _Range are set for the target, and _ChromaLocation is removed.

  • Chroma. Subsampled chroma is upsampled with lanczos, honoring _ChromaLocation.

  • DolbyVisionRPU metadata applies whatever src_csp is, as in vs-placebo. When the prop is present and valid:

    • Source peak: the RPU's source maximum replaces the props' mastering peak. Compressed DM data carries no range, so the props' value is kept.
    • Source black: the RPU's source minimum replaces the props' too, except for compressed DM data. For Dolby Vision to HDR10 (src_csp=3, dst_csp=1), the target black is set to the source black instead.
    • L1 supplies the scene's CIE Y peak and average.
    • L6 supplies MaxCLL/MaxFALL when either is missing from the props.
    • Errors: with src_csp=3 a missing or invalid RPU is an error. With other values an invalid RPU is ignored.
  • Partial Dolby Vision RPUs (use_prev, without DM data, or with compressed DM data) continue the last complete RPU at or before them, in frame order. That reconstruction walks back at most 300 frames: a longer chain without a complete RPU raises an error, with peak detection on or off.

  • Peak detection is deterministic. Frame n replays the detection over a fixed window of earlier frames (5 × smoothing_period, at most 300 frames). The result doesn't depend on request order, seeking or thread count. Requesting frame n also fetches the earlier window frames that aren't measured yet.

Parameters

  • clip:
    Input clip.

  • src_csp (int, default: 1):
    Source color space. There is no SDR source mode.

    • 1: HDR10 (PQ, BT.2020)
    • 2: HLG (BT.2020)
    • 3: Dolby Vision (needs the DolbyVisionRPU frame prop)
  • dst_csp (int, default: 0):
    Target color space.

    • 0: SDR (BT.1886, BT.709 primaries)
    • 1: HDR10 (PQ, BT.2020)
    • 2: HLG (BT.2020)

    Dolby Vision output (3) is not supported, as in vs-placebo.

  • dst_prim (int, default: the target's own primaries):
    Target primaries, as libplacebo's pl_color_primaries:

    Value Primaries Value Primaries
    0 unknown 9 ProPhoto
    1 BT.601 525 10 CIE 1931
    2 BT.601 625 11 DCI-P3
    3 BT.709 12 Display P3
    4 BT.470 M 13 V-Gamut
    5 EBU 3213 14 S-Gamut
    6 BT.2020 15 Film C
    7 Apple 16 ACES AP0
    8 Adobe 17 ACES AP1
  • src_max, src_min (float, default: 0, range: 0..10000):
    Source peak and black in nits. 0 takes them from the frame props or metadata.

  • dst_max, dst_min (float, default: 0, range: 0..10000):
    Target peak and black in nits. 0 uses the target's nominal values (SDR: 203 nits).

  • dynamic_peak_detection (bool, default: True):
    Measure each frame's brightness.

    • Which fields it fills: only the dynamic metadata fields the source leaves empty, field by field. Authored values win.
    • When it doesn't run:
      • the target peak is at least the source transfer's nominal peak (10000 nits for PQ, so for example HDR10 → dst_csp=1 with the default dst_max; for HLG, the source's peak);
      • metadata is 1, 2 or 3;
      • the source carries both HDR10+ and CIE Y metadata.
  • smoothing_period (float, default: 20, range: 0..60):
    Time constant of the peak detection's smoothing, in frames. 0 disables smoothing.
    vs-placebo accepts any value. vszip stops at 60 so that the replay window (5 periods) fits 300 frames.

  • scene_threshold_low, scene_threshold_high (float, default: 1, 3, range: 0..100):
    Scene-change thresholds in units of 1% PQ. Between them, the smoothing is progressively reset. Either one at 0 disables scene-change detection.

  • percentile (float, default: 100, range: 0..100):
    Brightness percentile used as the measured peak. Values strictly between 0 and 100 use a histogram percentile, which ignores a few very bright pixels. Both 0 and 100 use the true maximum.

  • black_cutoff (float, default: 1, range: 0..100):
    Smoothly suppresses near-black pixels, up to this PQ level in percent, in peak detection's averages. It also keeps black bars out of the measurement. 0 disables it. vszip only; libplacebo's default (upstream description).

  • gamut_mapping (int, default: 1):
    Gamut mapping function.

    • 0: clip
    • 1: perceptual
    • 2: softclip
    • 3: relative
    • 4: saturation
    • 5: absolute
    • 6: desaturate
    • 7: darken
    • 8: highlight (out-of-gamut colors shown as a mask)
    • 9: linear
  • tone_mapping_function (int, default: 5):
    Tone mapping curve.

    Value Function Value Function
    0 clip 6 reinhard
    1 st2094-40 7 mobius
    2 st2094-10 8 hable
    3 bt2390 9 gamma
    4 bt2446a 10 linear
    5 spline 11 linearlight
  • tone_mapping_function_s (string):
    The same curve by name ("clip", "st2094-40", "st2094-10", "bt2390", "bt2446a", "spline", "reinhard", "mobius", "hable", "gamma", "linear", "linearlight"). It overrides tone_mapping_function.

  • tone_mapping_param (float, range: 0..10):
    The curve's tuning parameter. A nonzero value overrides the function's own constant. 0 leaves that constant unchanged; it does not set it to zero.

    Function Constant it sets Default
    st2094-40/10 knee_adaptation 0.7
    bt2390 knee_offset 1.0
    spline spline_contrast 0.5
    reinhard reinhard_contrast 0.5
    mobius, gamma linear_knee 0.3
    linear, linearlight exposure 1.0

    How the value is chosen:

    • Neither argument passed: the defaults in this table apply, as in vs-placebo.
    • Only the constant passed: your constant is used (the implicit default above is not applied).
    • Nonzero tone_mapping_param passed: it wins over an explicit constant.
  • metadata (int, default: 0):
    Which source metadata selects the tone curve's input range.

    • 0: any (the best available)
    • 1: none. Source luminance metadata, including manual src_max/src_min, is ignored for the tone range; the transfer's nominal bounds are used. Use 2 to tone map from static mastering or manual source luminance.
    • 2: HDR10 (static mastering metadata, and src_max/src_min)
    • 3: HDR10+ (dynamic scene metadata)
    • 4: CIE Y (dynamic luminance metadata, also from peak detection)
  • use_dovi (bool, default: src_csp == 3):
    Whether to use dovi_el. Without it, dovi_el is ignored, as in vs-placebo.

  • dovi_el (clip):
    The Dolby Vision FEL enhancement layer, composed with the base layer when the RPU signals a FEL (a MEL changes nothing).

    • Format: 9..16-bit integer YUV (4:2:0, 4:2:2, 4:4:0 or 4:4:4).
    • Size: the base layer's size, or half of it in either or both dimensions.
    • Frames: the same frames as clip.
    • RPU source: with an EL the DolbyVisionRPU props are read from this clip, as vs-placebo does.
  • show_clipping (bool, default: False):
    Highlight pixels that the tone or gamut mapping clipped.

  • contrast_recovery (float, default: 0, range: 0..10):
    Re-adds high-frequency detail lost by tone mapping. 0 disables it; libplacebo's high-quality preset uses 0.3.

  • contrast_smoothness (float, default: 3.5, range: 1..32):
    Downscale factor of the low-frequency image that contrast recovery compares against. vszip only.

  • lut_size (int, default: 256, range: 2..4096):
    Size of the tone curve LUT (for curves evaluated through a LUT). vszip only.

  • mastering_clip (float, default: 1, range: 0..1):
    Strength of the soft clip of channels above the mastering display's peak. It fades out when the measured brightness exceeds the mastering peak. vszip only.

  • film_strength (float, default: 0.3, range: 0..2):
    Strength of the film-like hue/saturation response in the tone stage. vszip only.

  • inverse_tone_mapping (bool, default: False):
    Let a supported HDR source expand toward a brighter target, instead of capping the mapping at the source's range. vszip only.

    • It needs an invertible curve: clip, bt2446a, spline, linear or linearlight. With the others the output still stops at the source peak.
    • It does not add an SDR source mode: src_csp stays HDR10, HLG or Dolby Vision.
  • knee_adaptation, knee_minimum, knee_maximum, knee_default, knee_offset, slope_tuning, slope_offset, spline_contrast, reinhard_contrast, linear_knee, exposure (float):
    libplacebo's pl_tone_map_constants, with libplacebo's defaults and ranges. vszip only. See libplacebo's tone-mapping constants:

    Constant Default Range
    knee_adaptation 0.4 0..1
    knee_minimum 0.1 0..0.5
    knee_maximum 0.8 0.5..1
    knee_default 0.4 0..1
    knee_offset 1.0 0.5..2
    slope_tuning 1.5 0..10
    slope_offset 0.2 0..1
    spline_contrast 0.5 0..1.5
    reinhard_contrast 0.5 0..1
    linear_knee 0.3 0..1
    exposure 1.0 0..10
  • gamut_expansion (bool, default: False):
    Let the perceptual and saturation functions expand colors into a wider target gamut. vszip only.

  • lut3d_size (int[3], default: (48, 32, 256)):
    Size of the gamut-mapping 3D LUT along intensity, chroma and hue. vszip only.

    • Each value is 0 (keep the default) or 2..1024.
    • The product is at most 16777216 (the LUT is 16 bytes per entry).
  • lut3d_tricubic (bool, default: False):
    Sample the 3D LUT with a cubic B-spline instead of trilinearly. It smooths the LUT, so the output changes noticeably. vszip only.
    Measured example: 1080p HDR10 → SDR on a Ryzen 7 5700X3D went from 20.1 to 9.4 fps at 1 thread.

  • perceptual_deadzone, perceptual_strength, colorimetric_gamma, softclip_knee, softclip_desat (float):
    libplacebo's pl_gamut_map_constants. vszip only:

    Constant Default Range
    perceptual_deadzone 0.3 0..1
    perceptual_strength 0.8 0..1
    colorimetric_gamma 1.8 0..10
    softclip_knee 0.7 0..1
    softclip_desat 0.35 0..1
  • cache_frame (bool, default: True):
    Speed/memory trade-off; the output is identical either way. vszip only.

    • What it does. Peak detection and contrast recovery have to decode each frame to linear light before the output pass starts. With cache_frame, that decoded frame is kept for the output pass instead of being decoded a second time.
    • Speed (measured example). 3840x2160 YUV420P16 → SDR (Sol Levante profile 8.4, also as HDR10), Ryzen 7 5700X3D, 1 and 16 threads:
      • with detection: 12–19% faster;
      • with detection and contrast_recovery=0.3: 14–28% faster.
    • Memory. Each frame being processed needs 12 bytes per pixel: about 25 MB at 1080p and 100 MB at 4K.
      • How long it's held. The buffers are pooled and reused. The pool grows to the largest number of frames processed at once and keeps them until the filter is freed. There is no cap.
      • Measured. At 4K with 16 threads, peak RAM went from 2.95 to 4.43 GiB.
    • When to set it to False. If memory is tight. With detection off and no contrast recovery, the argument has no effect and allocates nothing.

Differences from vs-placebo

  • Not available.

    • visualize_lut (debug overlay).
    • log_level (vszip has no libplacebo to log).
  • Extra arguments. All the remaining pl_color_map_params/pl_peak_detect_params fields that change the output (listed above as "vszip only"), plus cache_frame.

  • Positional layout. It differs (see Usage); pass arguments by keyword.

  • Input formats. vs-placebo takes 16-bit integer input only.

    • HDR10/HLG accept 9..16-bit integer or 32-bit float.
    • Dolby Vision and its EL accept 9..16-bit integer YUV; float is not supported for either.
  • Precision. vszip computes in f32 throughout and doesn't emulate the GPU's lower-precision steps:

    • half-float intermediate textures (most visible on 4:2:0 chroma, with peak detection on very bright frames, and on the FEL);
    • the 16-bit gamut LUT;
    • output dithering (vszip rounds the 16-bit output).

    On the test material the average difference was 0.2–7 16-bit codes. That is not a maximum: single pixels can differ much more. Examples are a peak-detection bias of 30–40 codes on very bright frames, and saturated pixels at a steep spot of clip gamut mapping, where vs-placebo's own output jumps by thousands of codes for a tiny input change.

  • Deterministic results. Peak detection and partial Dolby Vision RPUs are resolved in frame order. Results don't depend on request order, seeking or threads. vs-placebo updates one shared state in request order.

    • Peak detection replays a finite window (see smoothing_period). vs-placebo's state keeps its whole history, so results agree closely but not exactly even in sequential playback.
    • Partial RPU chains stop at 300 frames (see Notes).
  • Compressed Dolby Vision DM data keeps the previous frame's matrices. vs-placebo decodes those frames black.

  • smoothing_period is limited to 0..60.

  • Speed (measured example). 3840x2160 YUV420P16 Dolby Vision (Sol Levante profile 8.4) → SDR, vszip on a Ryzen 7 5700X3D against vs-placebo on an RTX 3070 Ti:

    Detection vszip, 16 threads vszip, 1 thread vs-placebo
    off ~50 fps ~6 fps ~25–29 fps
    on ~42 fps ~5 fps ~25–26 fps

    vszip scales with CPU threads. vs-placebo runs on the GPU and doesn't scale with VapourSynth threads.

Clone this wiki locally