Vapoursynth AutoAdjust

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

AutoAdjust corrects levels, gamma and saturation (Auto Gain) and the white balance (Auto Balance) automatically. The measurements are averaged over neighboring frames and reset at scene changes, so the correction stays steady within a scene instead of pumping.

Filtering → Vapoursynth → Color → Auto

AutoAdjust controls in Hybrid
AutoAdjust controls in Hybrid

What it does

For every frame the filter measures black point, white point and average brightness (and the average chroma for Auto Balance). These values are averaged over a temporal window that stops at scene changes. From them it computes the new levels, gamma, saturation and color shift and applies them through a lookup table; the change is smoothed and dithered so that no banding appears.

At least one of the two groups has to be enabled, otherwise the filter does nothing and Hybrid only writes a comment into the script.

Settings

Auto Gain

Control Parameter Range Hybrid default Meaning
Limit (dark/bright/gamma) dark_limit / bright_limit / gamma_limit 1 – 10 1.50 / 1.50 / 1.25 How far black point, white point and gamma may be moved; 1 = no change.
Exclude (dark/bright) dark_exclude / bright_exclude 0 – 1 0.50 / 0.50 Percentage of the darkest/brightest pixels ignored when measuring black and white point (0.5 = 0.5 %).
Gain mode gain_mode contrast expansion, levels adjustment contrast expansion Contrast expansion stretches the ranges below and above the average separately, levels adjustment does one linear stretch; both then apply the gamma.
Chroma processing chroma_process 0 – 200 100 How much of the contrast gain is applied to the saturation (in %).
Safety avg_safety 0 – 1 0.25 Blend between the averaged and the most conservative black/white point; 0 = most stable, 1 = most conservative.
TV input input_tv on/off on Limits the measured values to 16–235; turn off for full-range sources.
TV output output_tv on/off on Keeps the target values inside TV range (the output is not clipped).

Auto Balance

Control Parameter Range Hybrid default Meaning
Chroma limit chroma_limit 1 – 2 1.05 Maximum color shift; 1 = no balance, 2 = no limit.
Balance balance_str 0 – 1 0.75 Strength of the color shift.

Always available

Control Parameter Range Hybrid default Meaning
Temporal radius temporal_radius 1 – 120 20 Frames before and after the current one used for averaging, weighted by distance.
Scene change scd_threshold 1 – 100 12 Scene change threshold in %; useful values 8–16, 100 = only the first frame starts a scene.
Interpolation use_interp on/off on Smooths the correction (not the picture) to avoid banding.
High quality high_quality on/off off Smoothing uses every pixel instead of every second one. Only with Interpolation.
Dither use_dither on/off on Fixed-pattern dither when rounding, so the output is reproducible; off = plain rounding.

Example

Auto Gain and Auto Balance with default values on a 10-bit YUV 4:2:0 source:

# adjusting levels, gamma, saturation and white balance using AutoAdjust
clip = core.autoadjust.AutoAdjust(clip, auto_gain=True, auto_balance=True)

How Hybrid calls it

  • AutoAdjust accepts integer YUV (8, 10, 12, 16 bit) and gray clips with even width and height; Hybrid converts other formats first.
  • Only values that differ from the defaults are written; the gain and balance settings only when their group is enabled.
  • The plugin handles the bit depth itself, so no values are scaled.
  • AutoAdjust also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

AutoAdjust (plugin)

AutoAdjust is a clean-room re-implementation of LaTo's closed-source AviSynth plugin AutoAdjust 2.60, as one native plugin for VapourSynth and AviSynth+. Per-frame luma and chroma histograms give black point, white point and a robust average; these are cached and combined over the window with weighted trimmed means. A scene starts when the mean luma difference to the previous frame or the histogram difference is too large. Compared with the original it supports high bit depths natively, dithers reproducibly (the original seeds from the clock), returns gamma 1 for black or full-scale frames and gives the same output on all CPU paths; the debug view is not implemented.

AviSynth

AviSynth's core filter ColorYUV has autogain (stretches luma to the full range per frame) and autowhite (centers U/V to remove a color cast), but without temporal averaging or scene detection. The AutoAdjust plugin itself can also be used in AviSynth+. See Avisynth AutoAdjust.

Sources