Smart Decimate
Version 0.20 ALPHA
Copyright 2003 Kevin Atkinson under the GPL 2.0

This filter implements the Telecine Removal method described at 
http://kevin.atkinson.dhs.org/.

It requires my C API Plugin (version 0.12 or better) 
which can be found at 
http://kevin.atkinson.dhs.org/avisynth_c/.


BASIC USAGE

  loadplugin("...\avisynth_c.dll")
  loadCplugin("...\SmartDecimate.dll") # or loadcplugin("...\SmartDecimate-sse.dll")
  assumetff() # or assumebff()
  b = bob()
  separatefields()
  SmartDecimate(24,60,b)

Note that the second plugin is loadCplugin not loadplugin. (There is a
C after load)

IT IS VERY IMPORTANT THE THE FIELD ORDER IS CORRECT.

The "-sse" version is an MMX/SSE optimized version.


GUIDE TO USAGE

I will assume that you your material is 3:2 pulldown with some
possible video mixed in.

To use this filter, you must first determine the correct field order.
If the field order is wrong my filter will not work correctly.  To
determine field order:

  avisource(...)
  assumetff()
  bob()

Now preview the video and look for backwards motion.  If you don't see
any than you should use "assumetff()".  If you do see any try:

  avisource(...)
  assumebff()
  bob()

And once again look for backwards motion.  If you don't see any this
time than you should use "assumebff()".

Now its time to set up my filter:

  loadplugin("...\avisynth_c.dll")
  loadCplugin("...\smartdecimate.dll") # notice the C in loadCplugin
  avisource(...)
  assumetff() # or assumebff() as determined above
  b = bob()
  SmartDecimate(24, 60, b)

If you are happy with the result than that is all that is needed.  If
not read on.

If your material is anime with lots of repeated frames than you should
try:

  SmartDecimate(24, 60, b, tel=0.60)

This should avoid any bobbing on long sequences with no motion.

The "tel" value controls how aggressive the filter is when matching
fields.  The default value is 0.50.

If you have a mixed video with a large amount of true video than you
might want to lower "tel" as low as 0.25.  This will risk bobbing some
progressive frames but should weaving true video frames which will 
leave combing artifacts.

If you have a video with that is pure 3:2 pulldown with very little
true video frames than you might try raising "tel" as high as 0.75.
This will cause SmartDecimate to be really aggressive when matching
progressive fields.  However, it will likely end up leaving serious
combing artifacts behind if there is any pure video in your clip.

If you have a really noisy video than you might need to raise the
noise factor such as:

  SmartDecimate(24, 60, b, noise=0.80)

The default value is 0.50.  Leave it at the default unless you clip is
very noisy.  As higher values of noise will often leave behind more
combing artifacts for pure video frames.

If you have a really clean clip and you notice some combing artifacts
in pure video frames than you might want to lower the noise factor.
But be careful if it is too low SmartDecimate won't be able to match
the progressive fields and will thus bob them.

Finally, if you have a hybrid video (mixed 3:2 pulldown and true
video) you should consider replacing the dumb "bob()" with something
like DgBob or SmoothDeinterlace.  This will greatly improve the
quality of the pure video frames.  Note that the bob source only
effects how bobbed frames are rendered, it is not used to compare
fields or by any other part of SmartDecimate.


FILTER REFERENCE

The filter will work with either YUY2 or YV12 input provided the width
is a multiple of 8.

The usage is:

  SmartDecimate(numerator, denominator, bob_src, options)

The numerator and denominator are for decimation ratio (not output fps).

"bob_src" is the same clip, but bob deinterlaced.  For best results
use a smart bob such as DgBob are SmoothDeinterlace.  The bobbed source
is used when ever SmartDecimate determines that a field is not part of
a progressive frame.

The following options may be used to fine tune SmartDecimate:

tel - a number between 0 and 1 and controls how aggressive the filter
  is when matching fields.  0.50 (the default) will work well with
  most clips.  The higher the value the more risk there is to leaving
  combing artifacts in true interlaced material.  The lower the value
  the more risk there is to bobbing (or in the extreme case skipping or
  duplicating) Telecine frames.

  Currently "tel" toggles various internal options depending on what
  it is set to.  Currently there are switches at: 0.45, 0.55, 0.65
  and 0.72.

noise - The noise factor.  The default value, 0.50, should work in most
  cases.

t_max - An alternate method of setting the noise factor.  You need to
  understand how my filter works in order to use it.

The following options can be used to control the printing of useful
information:

  log_level - The verbosity of the information printed.  Default 2.
  log_file - If set all output will be appended to the filename
    specified
  console - If set to true than a console window will pop up and
    all output will be sent to it
  debug_print - If set than all output will be printed using the
    OutputDebugString system call.  You can view this output with
    a utility such as DebugView

The meaning of the information printed is as follows:

  "Reseting to NUM" means that the internal variables are reset and
    any patterns are reset.  This will happen when ever the video
    is accessed in a non-linear way.
  "FRAME 3(7) = [0, 1]" indicates how frame number 3 (for example)
    is being rendered.  Here 7 indicates the primary source field that is
    chosen.  If the frame is to be rendered by weaving two fields together, 
    the numbers in [] indicate which source fields are chosen and are 
    relative to the chosen source frame.  If the frame is to be bob
    deinterlaced that the [] will instead be "BOB".
  "Diff NUM: WHAT DIFF" indicates the difference between to source field
    NUM and NUM+1.  WHAT is the classification of the difference with
    0 meaning the same, 1 similar, and 2 different.  DIFF is the numerical
    difference.
  "Thres1 now X" indicates that thres1 or thres2 was modified and indicates
    the new value.

The following options may be used to tune internal parameters.  In
order to understand what they do you will need to look at the source.
They may be changed between releases.

  max_last_set - positive integer
  t1_def, t2_def, t1_max, t2_max - float between 0.0 and 1.0
  floor - float between 0.0 and 1.0
  floor_adj = float larger than 0.0
  sml_peak, lrg_peak - float larger than 1.0
  sml_tail_diff, lrg_tail_diff - float larger than 0.0


FINAL WORDS

Feedback more than appreciated.  Please send it to 
kevin.tel@atkinson.dhs.org.
