Vapoursynth SmoothLevels: Difference between revisions

From wiki.selur.net
Jump to navigation Jump to search
Ecenter range and use (via update-page on MediaWiki MCP Server)
Update to current Hybrid behaviour; code as <pre> (via update-page on MediaWiki MCP Server)
 
(3 intermediate revisions by the same user not shown)
Line 35: Line 35:
| Protect || protect || -1–255 || -1 || -1 = off; otherwise pixels at or below this value stay unchanged, so black borders don't turn grey.
| Protect || protect || -1–255 || -1 || -1 = off; otherwise pixels at or below this value stay unchanged, so black borders don't turn grey.
|-
|-
| Ecurve || Ecurve || sine, linear || sine || Curve used for the fade and for Protect.
| Ecurve || Ecurve || sine, linear || sine || Curve used for the fade and for Protect; only enabled when Lmode or Protect is in use.
|-
|-
| Smode || Smode || -2 … 2 || -2 || Smoothing mode: -2/-1 smooth only where the difference is below 255/Mfactor or 128/Mfactor, 0 no smoothing, 1/2 always smooth.
| Smode || Smode || -2 … 2 || -2 || Smoothing mode: -2/-1 smooth only where the difference is below 255/Mfactor or 128/Mfactor, 0 no smoothing, 1/2 always smooth.
Line 52: Line 52:
== Example ==
== Example ==
Expanding limited range to full range (''Input'' 16/235, ''Output'' 0/255) on a 10-bit YUV 4:2:0 source:
Expanding limited range to full range (''Input'' 16/235, ''Output'' 0/255) on a 10-bit YUV 4:2:0 source:
<syntaxhighlight lang="python">
<pre>
# adjusting color using SmoothLevels
# adjusting color using SmoothLevels
clip = color.SmoothLevels(clip, input_low=64, input_high=940, output_low=0, output_high=1023, Ecurve=0, tools={'expr': 'akarin', 'rg': 'zsmooth', 'median': 'zsmooth', 'f3kdb': 'vszip'})
clip = color.SmoothLevels(clip, input_low=64, input_high=940, output_low=0, output_high=1023, Ecurve=0, tools={'expr': 'akarin', 'rg': 'zsmooth', 'median': 'zsmooth', 'f3kdb': 'vszip'})
</syntaxhighlight>
</pre>


== How Hybrid calls it ==
== How Hybrid calls it ==
Line 68: Line 68:


=== VapourSynth ===
=== VapourSynth ===
The VapourSynth documentation has no page for SmoothLevels; the core counterpart without the smoothing is <code>std.Levels</code>, see [[Vapoursynth Levels|Levels]].
The core counterpart without the smoothing is <code>std.Levels</code>, see [[Vapoursynth Levels|Levels]].


=== AviSynth ===
=== AviSynth ===
SmoothLevels comes from LaTo's AviSynth work (later the SmoothAdjust plugin with SmoothLevels, SmoothCurve and SmoothTweak); the AviSynth+ documentation does not cover it.
SmoothLevels comes from LaTo's AviSynth work (later the SmoothAdjust plugin with SmoothLevels, SmoothCurve and SmoothTweak).


== Sources ==
== Sources ==

Latest revision as of 09:52, 16 November 2026

SmoothLevels is a levels adjustment like Levels (input/output range and gamma), with extras against the side effects of strong level changes: it can weaken the change in dark and/or bright areas, protect near-black pixels, and smooth the difference between original and result so that no banding or posterization appears.

Filtering → Vapoursynth → Color → Levels

SmoothLevels controls in Hybrid
SmoothLevels controls in Hybrid

What it does

SmoothLevels first builds the classic levels mapping (input range → output range with gamma). The change can then be faded out towards black and/or white (Lmode) and skipped below a protect value. Finally the difference between the original and the adjusted image is smoothed with a small blur kernel (and optionally debanded) and added back, which hides the steps that a plain levels change produces in gradients.

It works on luma; Chroma sets how much of the change is applied to the color planes.

Settings

Control Parameter Range Hybrid default Meaning
Input (low/high) input_low / input_high 0–255 0 / 255 Input range that is stretched to the output range.
Output (low/high) output_low / output_high 0–255 0 / 255 Target range.
Gamma gamma 0.01–10 1.00 Nonlinearity of the mapping; > 1 brightens, < 1 darkens.
Chroma chroma 0–100 50 0 = luma only, 100 = full chroma processing, values in between scale the chroma change.
Limiter limiter no, input, output, input & output no Clamps to the input range, the output range or both.
Lmode Lmode no, dark & bright areas, dark areas, bright areas no Fades the change out towards black and/or white.
Dark strength DarkSTR 0–100 100 Strength of the change in dark areas (with Lmode dark & bright or dark).
Bright strength BrightSTR 0–100 100 Strength of the change in bright areas (with Lmode dark & bright or bright).
Ecenter Ecenter 1–254 128 Center between dark and bright areas for the fade; only used with Lmode dark & bright areas.
Protect protect -1–255 -1 -1 = off; otherwise pixels at or below this value stay unchanged, so black borders don't turn grey.
Ecurve Ecurve sine, linear sine Curve used for the fade and for Protect; only enabled when Lmode or Protect is in use.
Smode Smode -2 … 2 -2 Smoothing mode: -2/-1 smooth only where the difference is below 255/Mfactor or 128/Mfactor, 0 no smoothing, 1/2 always smooth.
Mfactor Mfactor 0–255 (0 is rejected by the script) 2 Higher values give more precision but allow a smaller maximum difference.
RemoveGrain RGmode 19, 12, 20, 21 12 Kernel used to smooth the difference (19 strongest, then 12, 20, 21).
Deband useDB on/off off Adds an f3kdb deband step on top of the smoothing.
Range signaling – unchanged, full, limited unchanged Overwrites the clip's color range flag before the filter.
Tools tools – – Implementations used inside the script: Expr (expression evaluator), RG and Median (smoothing), F3kdb (deband).

Example

Expanding limited range to full range (Input 16/235, Output 0/255) on a 10-bit YUV 4:2:0 source:

# adjusting color using SmoothLevels
clip = color.SmoothLevels(clip, input_low=64, input_high=940, output_low=0, output_high=1023, Ecurve=0, tools={'expr': 'akarin', 'rg': 'zsmooth', 'median': 'zsmooth', 'f3kdb': 'vszip'})

How Hybrid calls it

  • SmoothLevels accepts YUV and gray clips (no RGB) of any bit depth.
  • The range values (Input, Output) are entered on the 8-bit scale and scaled to the clip's bit depth: 255 becomes the format's maximum, other values are shifted (16 becomes 64 at 10 bit). Ecenter and Protect are shifted the same way.
  • Most parameters are only written to the script when they differ from the script's defaults.
  • SmoothLevels also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

The script

The VapourSynth version is a script function (SmoothLevels v1.02 by LaTo, ported from AviSynth via havsfunc). It builds the levels expression, weights it with the Lmode fade (sine or linear, set by the dark/bright strengths) and with the protect ramp, then takes the amplified difference to the original, smooths it with the chosen kernel (optionally debanded) and merges it back; Smode decides between the plain result and the smoothing passes. It rejects RGB input, gamma ≤ 0, Ecenter outside the valid range and Mfactor ≤ 0.

VapourSynth

The core counterpart without the smoothing is std.Levels, see Levels.

AviSynth

SmoothLevels comes from LaTo's AviSynth work (later the SmoothAdjust plugin with SmoothLevels, SmoothCurve and SmoothTweak).

Sources

  • havsfunc (origin of the VapourSynth port)
  • The script's own documentation in Hybrid's vsscripts
  • Hybrid's tooltips