Vapoursynth AutoGain

From wiki.selur.net
Jump to navigation Jump to search

AutoGain adjusts the brightness range of the luma plane automatically on every frame: it can stretch it towards full black and white or compress it. Within a scene the correction is smoothed over time to avoid flicker; at scene changes it starts anew.

Filtering → Vapoursynth → Color → Auto

AutoGain controls in Hybrid
AutoGain controls in Hybrid

What it does

For each frame the luma statistics are measured and a scale and an offset are computed:

  • without Darken the luma range is expanded towards the full range,
  • with Darken it is compressed around the average.

The scale is limited to 0.3–3.0, smoothed with an exponential moving average and reset at each detected scene change, and applied as Y × scale + offset. The result is mixed with the original by Strength. Chroma stays unchanged.

Settings

Control Parameter Range Hybrid default Meaning
Limit gain_limit 0 – 100 1.00 Share of the full gain; 0 = no change, 1 = full gain, higher values overshoot up to the 3× limit. Smaller values make the smoothing faster, larger ones slower.
Strength strength 0 – 1 0.50 How strongly the correction is applied; lower values blend back to the original.
Darken darken on/off off On: compress the luma range, off: expand it.
Tools: Expr tools akarin, cranexpr, std akarin (std without AVX2) Expression evaluator.
Tools: PlaneStats tools vszip, std vszip Plugin that measures the luma statistics.
Tools: SCD tools scd, misc, std, mv scd Scene change detector.

Example

Default settings on a 10-bit YUV 4:2:0 source:

# adjusting dynamic luma range using AutoGain
clip = color.AutoGain(clip, tools={'expr': 'akarin', 'planestats': 'vszip', 'scd': 'scd'})

How Hybrid calls it

  • AutoGain works on YUV clips; RGB clips are converted to YUV first.
  • Limit, Strength and Darken are only written when they differ from the defaults.
  • AutoGain also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

The script

The function measures minimum, maximum and average luma per frame (std.PlaneStats, or vszip's PlaneMinMax and PlaneAverage), detects scene changes (misc.SCDetect or another detector) and applies the per-frame scale and offset with std.FrameEval and an expression.

AviSynth

AviSynth's ColorYUV has autogain, which stretches luma to the measured minimum and maximum like a camera's auto levels, per frame and without smoothing. For a temporally stable correction see AutoAdjust or AutoLevels.

Sources