Vapoursynth common filter options

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

Besides its own settings, every Vapoursynth filter in Hybrid can have a few common option groups. They sit to the right of the filter's own controls and decide where and how much the filter is applied: only through a mask, only on part of the frame, only on some frames, blended with the original, or on a turned/scaled copy of the frame. Which groups a filter offers depends on the filter.

The groups can be shown or hidden under Filtering → Vapoursynth → Misc → UI (Show 'Masked'-controls, Show 'Merge'-controls, Show 'Apply only to'-controls, Show 'Only on region'-controls, Show 'Gimmick'-controls, Show 'Tools'-controls, Show 'Reset'-controls). Hiding a group does not reset or switch off its settings.

In the script the groups act from the outside in: Merge keeps a copy of the clip from before the filter, Masked builds its mask from the unfiltered clip, Gimmick changes the frame before the filter and undoes it afterwards, and ApplyOnlyTo and Only on region wrap the filter call itself.

Masked

Masked group
Masked group

Applies the filter only where a mask allows it: the filtered clip is used where the mask is white, the unfiltered clip where it is black (std.MaskedMerge).

Control Range Default Meaning
Mask see below LimitMask Kind of mask.
Expand/Shrink -100 – 100 0 Positive values grow the mask (repeated std.Maximum), negative values shrink it (std.Minimum).

Masks and their extra controls:

  • LimitMask: Limit 1–254 (default 30, on the 8-bit scale): the unfiltered luma is binarized at this value; with invert on (default) the filter is applied to pixels darker than the limit.
  • EdgeMask (Retinex, Kirsch, Sobel fast, Bloated, Sobel, Prewitt, CLAHE), CartoonEdges, RobertsEdges: masks of the edges in the picture; Retinex and CLAHE have a Sigma, CLAHE also Limit and Tiles, CartoonEdges and RobertsEdges low/high thresholds.
  • MotionMask: marks moving areas (low, high, scene change thresholds).
  • FinegrainMask (experimental): marks fine grain; mode RemoveGrain, Bilinear or mClean.
  • RectangleMask: a rectangle given by left/top/right/bottom borders; invert swaps inside and outside. If all four borders are 0, no mask is used and the whole frame is filtered.

Most masks also have invert, scale (multiplies the mask by a factor), binarize (turns it into pure black/white at a threshold) and show (shows the mask instead of the result in the preview; filters after it are skipped).

Example (LimitMask with Levels on a 10-bit source):

clipMask = core.resize.Bicubic(clip=clipMask, format=vs.GRAY10, range_in_s="limited")
clipMask = core.std.BinarizeMask(clipMask, 120)
clipMask = core.std.InvertMask(clipMask)
clipFiltered = core.std.Levels(clipFiltered, min_in=64, max_in=940, min_out=0, max_out=1023, planes=[0])
clip = core.std.MaskedMerge(clip, clipFiltered, clipMask) # LimitMask

Only on region

Only on region group
Only on region group

Applies the filter only to a rectangle of the frame, given by X, Y, Width and Height (0–32768). It only acts when width and height are both set. If ApplyOnlyTo is enabled and a frame range is entered under Range, the region is only filtered in those frames.

ApplyOnlyTo

ApplyOnlyTo group
ApplyOnlyTo group

Applies the filter only to selected frames. If more than one is ticked, SceneChange wins over Every, and Every over Range.

Control Default Meaning
Range – Frame ranges in RemapFrames syntax, e.g. [100 200]; frames outside stay unfiltered (remap.Rfs).
Every: Cycle / Offsets 5 / – In every group of Cycle frames only the frames at the given offsets (e.g. 0 3) are filtered.
SceneChange – Filters only the frames around scene changes: Pre/Post frames before and after each cut (default 2/2), detected with Detector (scd, misc, std or mv) at Threshold (0–1, default 0.1; mv uses thSCD1/thSCD2). Invert filters everywhere except around cuts; Blend filters the whole clip and uses the result only inside the windows.

Example (Range):

clip = core.remap.Rfs(baseclip=clip, sourceclip=core.std.Levels(clip, min_in=64, max_in=940, min_out=0, max_out=1023, planes=[0]), mappings="[100 200]")

Merge

Merge group
Merge group

Blends the filtered result with the unfiltered clip (std.Merge). The value is the share of the filtered result: 0 = unfiltered, 1 = fully filtered, 0.3 = 30 % filtered and 70 % original.

Control Range Default Meaning
Y/U/V 0 – 1 on, 1 One value for all three planes.
Y, U, V 0 – 1 1 Separate values per plane (when Y/U/V is off).

If all three values are 1, no merge is written at all, so the result is fully filtered.

Example (0.3 for all planes):

clipMerge = clip
clip = core.std.Levels(clip, min_in=64, max_in=940, min_out=0, max_out=1023, planes=[0])
clip = core.std.Merge(clipMerge,clip,[0.3, 0.3, 0.3]) # merge filtered and unfiltered by plane

Gimmick

Gimmick group
Gimmick group

Changes the frame before the filter and undoes the change afterwards — useful for filters that only work in one direction or at a certain size.

  • Pre Color: converts the clip to the chosen color format before the filter.
  • Restrict bit depth: lets the filter run only at 8, 10, 16 or 32 bit.
  • Rotate: 90° clockwise, 90° counter-clockwise or 180°.
  • Flip vertical / Flip horizontal.
  • Resize: scales the frame to an absolute size or by a factor (fmtconv kernels, default cubic); with Undo (default on) it is scaled back afterwards. 48 × 48 means "no resize".
  • Compare Effect: in the compare view of the preview, shows the clip before this filter next to the result; filters after it are skipped.

The changes are undone in reverse order: rotation, flip, then resize.

Tools

Many filters use helper functions for which several implementations exist — for example the expression evaluator (akarin, cranexpr or VapourSynth's built-in std), RemoveGrain-style smoothing (zsmooth, neo_smo …) or motion vectors. The Tools group shows one choice per such family, but only for families with at least two implementations on this machine; filters without such families have no Tools group.

  • The choice is passed to the script as tools={…}, e.g. tools={'expr': 'akarin', 'rg': 'zsmooth'}.
  • An implementation that is missing on the machine falls back to the filter's default.
  • tune picks the implementation that was fastest in Hybrid's tools benchmark (Config → Vapoursynth → Tools) for the resolution and bit depth at the filter's position; the script always contains the concrete value. Implementations are not bit-identical, so the output can differ slightly.

Reset and FilterQueue buttons

  • Reset (next to the filter's check box, hidden unless enabled under Misc → UI) resets all settings of the filter, including its Tools, to Hybrid's defaults.
  • Add to FilterQueue / Remove from FilterQueue are shown in FilterQueue and Node Editor mode: Add stores the filter with its current settings (including all groups above) as a new queue entry, Remove deletes the last entry with these settings.

Sources