Vapoursynth SpotLess

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

SpotLess removes short-lived spots, dirt and dust, typical of film scans, with a motion-compensated temporal median. The optional DeltaRestore stage puts back moving objects that were removed by mistake.

Filtering → Vapoursynth → Artifacts

SpotLess controls in Hybrid
SpotLess controls in Hybrid

What it does

For each frame the neighbor frames are motion-compensated onto it and the temporal median is taken. A spot that appears on only one frame (or on up to Temporal radius frames) is replaced by the matching area of the neighbors. Fast moving bright or dark objects, such as a ball or a hand, can be mistaken for spots; DeltaRestore builds brightness, color and edge masks from the difference and restores the source there. SpotLess is meant for live action, not for cartoons.

Settings

Control Parameter Range / values Hybrid default Meaning
Chroma chroma on/off on Use the chroma planes in the block matching (off for gray clips).
Temporal radius radT 1 – 10 1 Frames before and after; 1 = median of three frames.
Iterations iterations 1 – 10 1 Runs the whole chain again on its own output.
Analysis Blocksize ablksize auto, block sizes auto Auto: 8 up to 960 pixels width, 16 up to 2400, 32 above (with DeltaRestore 32 above 1920).
Analysis Overlap aoverlap auto, list auto Auto = half the block size.
Analysis Search asearch auto, OneTime, NStep, Logarithmic, Exhaustive, Hexagon, Uneven Multi Hexagon, pure horizontal, pure vertical Uneven Multi Hexagon Search method; disabled with mvgpu, which ignores it.
Recalculate rec on/off off Extra refinement pass; enables its own Blocksize, Overlap and Search (auto = the analysis values, overlap half the block size).
ThSAD thsad 1 – 64000 10000 Blocks matching worse use the source block; 10000 is practically off.
ThSAD2 thsad2 1 – 64000 10000 Threshold for frames further than one away; from a radius of 3 the average of both is used.
TrueMotion truemotion on/off on Smoother, more coherent vectors.
Blur blur on/off off 3×3 blur of the clip used for the motion search (not of the output).
Fast HBD fasthbd on/off off Motion search on an 8-bit copy (10 – 16-bit input only).
RFilter rfilter 0 – 4 2 Reduce filter of the super clip: simple averaging, triangle shifted, triangle, quadratic, cubic.
Pel pel auto, full, half, quarter auto Search precision; auto = full above 960 pixels width, else half (the script's own rule).
SSharp ssharp soft, bicubic, sharper bicubic Subpixel interpolation; only with half or quarter pel.
Mirror Start/End mStart, mEnd on/off off / off Mirrors frames at the start and end so the first and last frames get the full temporal window.
DeltaRestore – on/off off Restores wrongly removed moving objects (calls SpotDelta).
Dark (ratio/limit) dark2_brt, dark2_brt_limit 0.5 – 1, 0.3 – 1 0.85 / 0.85 Thresholds of the secondary dark mask, as ratios to mid gray. The limit is kept at or below the ratio; above it the secondary dark mask would be empty.
Bright (ratio/expand) luma_brt, luma_expand 1.01 – 1.5, 0 – 20 1.1 / 3 Bright mask threshold (lower, e.g. 1.02, keeps more bright fast objects) and mask growth.
Light ratio light_brt 1.01 – 1.5 1.04 Threshold of the light mask.
Restore Grain rgr, rgr1, rgr2 on/off, 1 – 50, 1 – 50 off, 10 / 20 Puts grain back; the two values are difference thresholds (8-bit scale).
sLog slog on/off off Auto-levels the luma used for the masks (washed-out or S-Log material).
Sharpen sharpen_it, usharp_strength, usharp_radius, usharp_th on/off, 0 – 200 %, 1 – 20, 0 – 255 on, 80 / 5 / 1 Unsharp mask on luma before SpotLess; threshold on the 8-bit scale.
Tools: MV – mvgpu, mvutensils, mv mvgpu with a discrete GPU, else mvutensils Motion vector implementation; mvgpu ignores the search settings.
Tools: Expr – akarin, cranexpr, std akarin Expression implementation (DeltaRestore masks).
Tools: TMedian – zsmooth zsmooth Temporal median implementation.
Tools: BoxBlur – vszip, std vszip Box blur implementation (DeltaRestore).
Tools: Hysteresis – hysteresis, misc hysteresis Hysteresis implementation (DeltaRestore masks).

Example

Default settings on a 10-bit YUV 4:2:0 source (machine with a discrete GPU):

# Spot removal using SpotLess
clip = SpotLess.SpotLess(clip, asearch=5, truemotion=True, pel=1, tools={'mv': 'mvgpu', 'expr': 'akarin', 'tmedian': 'zsmooth', 'boxblur': 'vszip', 'hysteresis': 'hysteresis'})

How Hybrid calls it

  • SpotLess works on 8 – 16-bit integer YUV and gray clips; other formats are converted first. With DeltaRestore gray clips are converted to YUV, since the masks need chroma.
  • With DeltaRestore the call goes to SpotDelta instead of SpotLess.
  • Most values are only written when they differ from the defaults. Pel is always written (auto resolved by the width with the script's rule), Search unless auto, block size and overlap unless auto. TrueMotion is always written, because SpotDelta's own default is off. ThSAD2 is written whenever it differs from ThSAD, so the shown value is the one used.
  • Recalculate values are only written with Recalculate, the grain values only with Restore Grain, the unsharp values only with Sharpen.
  • Hybrid does not scale values; the script scales its 8-bit thresholds (grain, unsharp, mask thresholds) to the bit depth.
  • SpotLess also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

SpotLess

The VapourSynth function is a port of StainlessS' AviSynth SpotLess, based on an idea by Didée. It targets spots that last up to RadT frames. The AviSynth defaults differ from Hybrid's: ThSAD 4080, fixed pel 2, block size 8.

SpotLess + DeltaRestore

SpotDelta is a port of chmars' AviSynth "SpotLess + DeltaRestore" (2021). It restores wrongly removed objects in stages: large bright groups first, then colorful dark objects, then edge sharpness to tell dirt from real objects.

Sources