Vapoursynth Levels

From wiki.selur.net
Revision as of 09:51, 16 November 2026 by Selur (talk | contribs) (Update to current Hybrid behaviour; code as <pre> (via update-page on MediaWiki MCP Server))
Jump to navigation Jump to search

Levels adjusts brightness, contrast and gamma by remapping an input value range to an output value range. Hybrid uses the VapourSynth core filter std.Levels.

Filtering → Vapoursynth → Color → Levels

Levels controls in Hybrid
Levels controls in Hybrid

What it does

All values between In min and In max are stretched (or compressed) to the range between Out min and Out max; values outside the input range are clipped, so the output never leaves the output range. Gamma bends the curve in between: values above 1.0 brighten the mid tones, values below 1.0 darken them.

Typical uses:

  • In 16/235 → Out 0/255: expand limited (TV) range to full (PC) range.
  • In 0/255 → Out 16/235: squeeze full range into limited range.
  • In 0/255 → Out 255/0: invert the image.

Settings

Control Parameter Range Hybrid default Meaning
In (min/max) min_in / max_in 0–255 0 / 255 Input range that gets remapped.
Out (min/max) min_out / max_out 0–255 0 / 255 Output range the input range is mapped to.
Gamma gamma 0–10 1.00 Nonlinearity of the mapping; > 1 brightens, < 1 darkens.
Planes planes all, chroma only, luma only luma only Planes that are processed; the others are copied unchanged. Only used without Use RGB.
Use RGB – on/off on Converts to RGB before filtering, so all three color channels are adjusted the same way.

Example

With the default settings (Use RGB on) on a 10-bit YUV 4:2:0 source, Hybrid converts to RGB, applies Levels and converts back for the encoder:

# adjusting color space from YUV420P10 to RGB30 for vsLevels
clip = core.resize.Bicubic(clip=clip, format=vs.RGB30, matrix_in_s="470bg", range_in_s="limited", range_s="full")
# adjusting color using Levels on RGB30 (10 bit)
clip = core.std.Levels(clip, min_in=0, max_in=1023, min_out=0, max_out=1023)
# adjusting output color from RGB30 to YUV420P10 for NVEncModel
clip = core.resize.Bicubic(clip=clip, format=vs.YUV420P10, matrix_s="470bg", range_in_s="full", range_s="limited")

Expanding limited range to full range on the luma plane only (Use RGB off, Planes luma only, In 16/235, Out 0/255), same source:

# adjusting color using Levels on YUV420P10 (10 bit)
clip = core.std.Levels(clip, min_in=64, max_in=940, min_out=0, max_out=1023, planes=[0])

How Hybrid calls it

  • The In/Out values are always entered on the 8-bit scale. Hybrid scales them to the bit depth of the clip at the filter's position (for example 235 becomes 940 and 255 becomes 1023 at 10 bit); for 32-bit float RGB it divides them by 255.
  • Gamma is only written to the script when it differs from 1.0.
  • With Use RGB Hybrid converts the clip to RGB before Levels, if it isn't RGB already. Without it, the filter runs in YUV or gray, and Planes decides which planes are touched. Anything but luma only in YUV gives unexpected colors, because chroma is centered around the middle value and does not behave like luma; Hybrid writes a warning comment into the script in that case.
  • Like every Vapoursynth filter in Hybrid, Levels also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

VapourSynth (std.Levels)

  • Works on integer clips with 8 to 16 bits and on 32-bit float clips.
  • min_in, max_in, gamma, min_out and max_out can be given per plane; if fewer values than planes are given, the last one is reused.
  • For float clips the default range is 0–1, which also applies to the U and V planes of YUV float clips; the documentation warns that this can give unwanted results there.

AviSynth (Levels)

AviSynth's Levels does the same mapping with the transfer function

output = ((input − input_low) / (input_high − input_low))^(1/gamma) × (output_high − output_low) + output_low

It differs from VapourSynth's version in some points:

  • The parameter order is input_low, gamma, input_high, output_low, output_high.
  • coring (default true) clamps YUV input to limited range, scales it to full range for the calculation and back afterwards; with coring=false only the transfer function is applied.
  • dither adds ordered dithering against banding.
  • In YUV, gamma is applied to luma only; the documentation recommends Tweak or ColorYUV for brightness/contrast changes in YUV, since Levels also changes the chroma.

See also: Avisynth Levels

Sources