From Avisynth wiki
Jump to: navigation, search
Author Kevin Atkinson , Fizick, cretindesalpes
Version v3.6.3.1
Download DeSpot3631.7z
Category Film Restoration
License GPLv2
Discussion Doom9 Forum


[edit] Description

This filter is designed to remove temporal noise in the form of dots (spots) and streaks found in some videos. The filter is also useful for restoration (cleaning) of old telecined 8mm (and other) films from spots (from dust) and some stripes (scratches).
Version is a modified version of the DeSpot plug-in, allowing to dump the masks of the detected spots in an Aegisub file for further editing.

The plugin is based on Conditional Temporal Median Filter v.0.93 by Kevin Atkinson.

[edit] Requirements

[edit] Syntax and Parameters

DeSpot (clip, int "mthres", int "mwidth", int "mheight", int "merode", bool "interlaced", bool "median", int "p1", int "p2", int "pwidth", int "pheight", bool "ranked", int "sign", int "maxpts", int "p1percent", int "dilate", bool "fitluma", int "blur", int "tsmooth", int "show", int "mark_v", bool "show_chroma", bool "motpn", int "seg", bool "color", int "mscene", int "minpts", clip "extmask", bool "planar", string "outfile", bool "mc", int "spotmax1", int "spotmax2")

clip   =
Input clip.

int  mthres = 16
A pixel needs to be different from the another frame by at least 'MTHRES' in order to be considered moving. This number should be larger than 'P2' in order to prevent noise from being identified as motion.

int  mwidth = 7
int  mheight = 5
These define the width and height of block for motion map denoising algorithm (erode and dilate stages).

int  merode = 33
These define a threshold value of percent of motion pixels in the block at erode stage.

bool  interlaced = false
Whether to treat the video as interlaced or not (progressive). The default is false (progressive) for DeSpot since version 1.3. (In older versions, the Field based video was processed as interlaced by default - it was a bug).

bool  median = false
The filter may work in 2 main modes:
  • false - Spots removing mode - filter will attempt to identify noise and eliminate it.
  • true - Simple Median mode - filter will apply a simple temporal median filter to the non-moving areas of the image.

int  p1 = 24
int  p2 = 12
A pixel needs to be at different from its neighbors by at least 'P1' in order for it to be considered noise. The surrounding pixels must be different by at lease 'P2' in order for the pixel to be considered part of the same spot.

int  pwidth = 6
int  pheight = 5
A spot can be no larger than pwidth x pheight.

bool  ranked = true
Enables ranked ordered difference spot detector with 6 points instead of 2.

int  sign = 0
Set mode for removing of only black or white spots or both:
  • sign = 0 - any spots and outliers (default)
  • sign = 1 - only black (dark) spots and outliers
  • sign = -1 - only white (light) spots and outliers
  • sign = 2 - only black (dark) spots, any outliers
  • sign = -2 - only white (light) spots, any outliers

int  maxpts = 0
Set upper limit of points (pixels) per every spot.
Range: from 0 to 10000000, default=0 - no limit

int  p1percent = 10
Set lower limit of relative fracture of high-contrasted (by criterion P1) pixels per spot (in percent).
Range: from 0 to 100

int  dilate = 1
Set range of morphological dilate (growing) of removed spots (in pixel units).
Range: from 0 to 255

bool  fitluma = true
Enables some frame luminosity correction in places of deleted spots.

int  blur = 1
Value (length) of local spatial blur near borders of deleted spots
Range: from 0 to 4, default 1

int  tsmooth = 0
Control temporal smoothing in static areas (except spots and motion).
Set approximate threshold of pixel luma variance in 3 frames,
The more variance exceed this threshold, the less temporal smoothing.
0 - no temporal smoothing.
Range: from 0 to 127

int  show = 0
To instead spots removing, show a motion map and noise that would of been eliminated, use parameter:
  • 0 - not show,
  • 1 - to highlight the noise instead of removing it
  • 2 - show a motion map and noise
If show=2, the luma is changed as follows:
  • 255 (White): Noise that will be removed
  • 159: Noise that won't be remove because it might be motion
  • 95: Motion map for the current image

int  mark_v = 255
Where mark_v is the luma value to highlight the noise with.
The color (pink, green or grey) of noise spot now is depend from parity of mark_v.
Motion map is also shown.
Range: from 0 to 255

bool  show_chroma = false
Use to show clip color data on motion map.

int  motpn = true
Define motion detecting method.
  • false - detect motion from previous to current and from current to next frame (old method used in all versions before 3.0)
  • true - detect motion from previous to next frame (new method since version 3.0)

int  seg = 2
Control spots segments removing method.
  • 0 - remove only spots pixels which has no overlap with motion zones (old method used in all versions before 3.0, most strong removing);
  • 1 - remove only spots line segments which has no any overlap with motion zones;
  • 2 - remove only whole spots which has no any overlap with motion zones (most safe).

bool  color = false
Control color correction at place of removed spots .
  • true - change color of pixels at places of removed spots to mean value previous, current and next frames,
  • false - not change color of pixels at places of detected spots.

int  mscene = 40
Set percent of pixels in motion for scenechange detection and disabling of frame spot removal.
Range: from 0 to 100

int  minpts = 0
Set lower limit of points (pixels) per every spot.
Range: from 0 to 10000000, default=0 - no limit

clip  extmask = none
Optional external mask clip. It will be binarized with threshold 127 and logically added (by "OR" operation) to internal motion mask. It can be used for additional protection of good objects (if you have some reliable mask).

bool  planar = false
Old hack, do not use. Read included docs if you are curious.

string  outfile = ""
Nname of a generated file containing the detected spot locations. The file is in the .ASS subtitle file format. Spots are located with their bounding boxes drawn as magenta rectangles (dilated by 2 pixels in each direction relative to the actual bounding boxes, for clarity). The default Outline style can be later changed to Mask in an ASS editor (like Aegisub) to produce a mask made of rectangles filled with white. The file is overwritten at each filter run, so make a copy before editing it!

bool  mc = false
Uses a 3-fold interleaved stream to allow motion-compensated analysis. Only the second frame every three frames is processed and returned. The input stream should be in the form: Interleave (forward, original, backward), where forward and backward are the frames N-1 and N+1 reconstructed with motion compensation. See the MVTools2 plug-in for more information.

int  spotmax1 = 12
When using outfile, sets a first limit on the number of spots. If it is greater than the parameter, locations are checked. If the spots look “packed”, it is likely a detection error and all spots are discareded (from the outfile file only, they are still processed).

int  spotmax2 = 20
Hard limit on the number of spots per frame to send to the outfile. If greater, all spots from the frame are discarded.

[edit] Parameters for spots removing and median modes

  • Parameters for DeSpot in spots removing mode (median=false) are any of the following:
p1, p2, pwidth, pheight, ranked, sign, maxpts, minpts, p1percent, dilate, fitluma, blur, tsmooth, motpn, seg, color, mscene, extmask

  • Parameters of DeSpot for both spots removing and median modes are:
mthres, mwidth, mheight, merode, interlaced, show, mark_v, show_chroma, outfile, mc, spotmax1, spotmax2

[edit] Tuning The Parameters

In order for the filter to work right the various parameters MUST be set correctly. There is no good default values.

  • The first parameter that needs to be set is interlaced, set it to true if your video is interlaced, false otherwise.
  • Than pwidth and pheight need to be set. Set these to be slightly larger than the specks you want to eliminate. If your video is interlaced than height represents the height of an individual field. Thus, it will essentially be doubled.
  • Than p1, p2, and mthres need to be set. In general, p1 > mthres > p2. If these are set too low than you may lose detail as small pixel variations might be mistaken as specks, thus losing detail, and more importantly, real specks might not be recognized as the size of the filter thinks the spec is might be larger than pwidth by pheight. show=1 or 2 might be helpful in setting these parameters.
  • The mwidth, mheight parameters define the range of motion zones influence on noise (spots) zones. For decreasing of false spot detecting for fast motion scenes, you may increase these. After that, to cancel the influence of very small motion zones, you may increase the merode parameter (relative) .
  • Then sign may be set, if almost all spots are only white or only black. Correct tuning reduces number of false spot detection and artifacts.
  • I recommend to use new parameter ranked=true for stability of spots detection in noisy video.
  • Use parameter maxpts as another method (in addition to pwidth and pheight) to avoid cleaning too large objects - probably not spots.
  • Use p1percent to not clean weak (small contrast) spots with small relative fracture of strong points (with p1 threshold).
  • For better removing of partially damaged pixels near non-sharp spots edges, you may increase spots sizes by increasing of dilate parameter.
  • Enable brightness correction in spaces of deleted spots by parameter fitluma.
  • This correction is local (line segment based) in seg>0 mode and must be used with properly defined dilated spots to prevent false correction due to non-sharp spots edges.
  • To reduce noticeability of some borders in places of deleted spots some more, tune local spatial smoothing by parameter blur.
  • For denoising of almost static areas, try to use temporal smoothing, with tsmooth parameter about 4-8.
  • If spots have some color, try enable color parameter to correct spots color.
  • To prevent artifacts at scene change, decrease mscene parameter.
  • You also may try to use external mask clip (extmask parameter) in addition to (or instead of) internal motion mask to protect good objects. For example, it can be motion mask or inverted SAD mask from MVTools plugin.

[edit] How It Works

The filter works in Denoise mode as follows:

  • 1a) Find pixels that are different from its neighbors by at least p1.
    • If ranked parameter is true (new method from version 1.2), the 3 neighbors in previous frame (x-1, x, x+1) and same 3 neighbors in next frame are ranked (ordered by value), and those min and max are used for luma difference calculation for current pixel (x).
    • If ranked parameter is false (old method), the only 1 neighbor in previous frame (at same position x) and 1 neighbor in next frame are used for min and max calculation,
    • If sign parameter is not 0, the sign of difference is also taken into account.
    • These pixels are merged to horizontal line segments.
    • Stacked line segments are merged to spots.
  • 1b) Enlarge outliers based on difference p2<p1.
  • 2a) Determine the size of the specks and reject (will not clean) all those larger than pwidth x pheight.
    • If numpts parameter is set, the big spots are rejected also.
    • If p1percent parameter is set, then weak (by criterion p1) spots, which mostly consist of outliers (by criterion p2), are rejected also.
  • 2b) If Dilate mode set, than spots are dilated to cover its non-contrast edges and close small gaps between its, by applying a morphological dilate operation to noise (spots) map.
  • 3a) Find moving areas of an image by simply comparing each pixel to the another frame and considering all those which are greater than mthres.
    • If motpn=false, it is defined from previous to current frame,
    • if motpn=true, it is defined from previous to next frame.
  • 3b) Mark motion pixels without noise with weight 3 in the motion map.
    • If motpn=false, mark pixels determined both noise and motion as weight 1 in the motion map.
  • 4) Denoise the motion map by constrained erosion and then dilating (as a whole it is morphological opening operation).
    • During erode phase, the motion map is eroded with range mwidth/2 and mheight/2, and zones with small summary weight (less than 3*merode/100) are decreased or completely removed from motion map. Such zones correspond to small relative (in percent) numbers of motion neighbors within this range (or mostly noisy pixels -spots).
    • During dilate phase, remained motion zones are enlarged with same range. These are probably the most important steps (especially for motpn=false) .
  • 4a) If percent of pixels in motion is more than mscene parameter, the plugin detects scenechange, and whole motion map is set as motion.
  • 4b) Add optional external mask to motion mask.
  • 5) Only remove the specks in which there was no motion (in the current frame or next frame if motpn=false).
    • In pixel removing mode (seg = 0), test and reject all noise candidate pixels which has overlap with motion zones, rest candidates will be removed.
    • In segment removing mode (seg = 1), test and reject all noise candidate segments which has any overlap with motion zones, rest segments will be removed.
    • In segment removing mode (seg = 2), test and reject all noise candidate spots which has any overlap with motion zones, rest spots will be removed. It is the most safe mode, with minimum artifacts false removing
  • 6) Optional make luma correction in place of removed pixels and spatial smoothing near spot edges.
  • 7) Optional make temporal smoothing of static areas.
  • 8) Optional correction of color at place of spots.

The filter can also be configured to work as follows (Simple Median mode):

  • 1) Find moving areas of an image by simply comparing each pixel to the previous frame and considering all those which are greater than mthres.
  • 2) Denoise the motion map by erosion and then dilating (i.e. morphological opening). This is probably the most important step.
  • 3) Apply a simple temporal median filter on the non-moving areas of the image.

[edit] Examples

Very good results may be obtained with combined this filter with motion estimation and compensation: global motion with DePan plugin, or local motion with MVTools plugin.

In this case the pixels from previous and next frames are moved to best fit to current frame, therefore relative motion is decreased, false spots detection is decreased, and noise reduction is increased.

  • Example script with DePan (you may tune optional DePanEstimate and DepanInterleave parameters):
i = last
d = DePanEstimate(i, trust=3)
DePanInterleave(i, data=d)
DeSpot(p1=30, p2=15, pwidth=800, pheight=600, mthres=20, motpn=true, dilate=1, seg=1)

  • Example script with external mask from MVTools2 (you may tune optional MAnalyse parameters):
i = last
prefilt = i.DeGrainMedian() # prefiltered for better motion analysis

# analyse and compensate motion forward and backward (to current frame)
ml = 100     # mask scale
thscd1 = 400 # scene change

super=i.MSuper() # super clip
superprefilt = prefilt.MSuper() # super filtered clip

vf = superprefilt.MAnalyse(isb=false) # forward vectors 
cf = i.MFlow(super, vf, thscd1 = thscd1) # previous compensated forward
sadf = i.MMask(vf, ml=ml,kind=1,gamma=1, thscd1 = thscd1) # forward SAD mask
msadf = sadf.MT_Binarize(20, upper=true) # binary inverted forward SAD mask

vb = superprefilt.MAnalyse(isb=true)  # backward vectors 
cb = i.MFlow(super, vb, thscd1 = thscd1) # next compensated backward 
sadb = i.MMask(vb, ml=ml, gamma=1, kind=1, thscd1 = thscd1) # backward SAD mask
msadb = sadb.MT_Binarize(20, upper=true) # binary inverted backward SAD mask

msad = MT_Logic(msadf,msadb,"or") # combined inverted SAD mask
msad = msad.MT_Expand() # expanded inverted SAD mask
msadi = Interleave(msad, msad, msad) # interleaved 3-frame inverted SAD mask
# This mask is high (255) where at least one motion estimation is good, 
# so these areas will be protected

Interleave(cf,i,cb) # interleave forward compensated, source, and backward compensated

   sign=0,show=0,seg=0,color=true,motpn=true, extmask=msadi)

SelectEvery(3,1) # get filtered source

[edit] Changelog

Version (Aug  7, 2020):

    - Updated by Groucho2004
    - Bug fix: crashing on AVS+ 3.6.1
Version (June 3, 2020):

    - Updated by Groucho2004
    - Update to AviSynth 2.6 api
    - x64 binary

Version (June 3, 2020):

    - Updated by Groucho2004
    - Update to AviSynth 2.6 api
    - x64 binary

Version (October 8, 2013):

    - Added the mc, spotmax1 and spotmax2 parameters.
    - Mod by cretindesalpes

Version (August 19, 2011):

    - Added the outfile parameter.
    - Mod by cretindesalpes

Version (June 11, 2010):

    - Last release by Fizick, see included documentation for previous changes

[edit] Archived Downloads

Version Download Mirror
v3.6.3.1 (x86/x64) DeSpot3631.7z DeSpot3631.7z
v3.6.3.0 (x86/x64) DeSpot3630.7z
v3.6.1.1 (x86/x64) DeSpot3611.7z DeSpot3611.7z

[edit] External Links

Back to External Filters

Personal tools