help file - tdeint.txt

the De-interlace video processing developed with C++ enviroment in Motion adaptive in 3D and Bi-indi

                                                                                                      |
                                    TDeint for AviSynth v2.5.x                                        |
                                   v1.0 beta 4 (14 August 2005)                                       |
                                           by tritical                                                |
                                                                                                      |
                                            HELP FILE                                                 |
-------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------


INFO:


        TDeint is a bi-directionally, motion adaptive (sharp) deinterlacer.  It can also adaptively
   choose between using per-field and per-pixel motion adaptivity.  It can use cubic interpolation, 
   kernel interpolation (with temporal direction switching), or one of two forms of modified ELA 
   interpolation which help to reduce "jaggy" edges in moving areas where interpolation must be used.  
   TDeint also supports user overrides through an input file, and can act as a smart bobber or same 
   frame rate deinterlacer, as well as an IVTC post-processor. Currently only YV12 and YUY2 colorspaces 
   are supported.

   Syntax =>    TDeint(int mode, int order, int field, int mthreshL, int mthreshC, int map, string ovr, 
                       int ovrDefault, int type, bool debug, int mtnmode, bool sharp, bool hints, 
                       PClip clip2, bool full, int cthresh, bool chroma, int MI, bool tryWeave,
                       int link, bool denoise, int AP, int blockx, int blocky, int APType)


PARAMETERS:


   mode:
  
      Sets the mode of operation.  Modes -2 and -1 require progressive input.

         -2 - double height using modified ELA
         -1 - double height using modified ELA-2
          0 - same rate output
          1 - double rate output (bobbing)

      default -  0  (int)


   order:

      Sets the field order of the video.

        -1 - use parity from AviSynth
         0 - bottom field first (bff)
         1 - top field first (tff)
     
      default -  -1  (int)


   field:

      When in mode 0, this sets the field to be interpolated (i.e. the other field is kept as 
      is and this field will be constructed).  When in mode 1 this setting does nothing.

        -1 - will set field to 1 if hints = false or 0 if hints is set to true
         0 - interpolate top field (keep bottom field)
         1 - interpolate bottom field (keep top field)
  
      default -  -1  (int)


   mthreshL/mthreshC:

      The motion thresholds for luma and chroma (mthreshL for luma, mthreshC for chroma). If
      the difference between two pixels is less then this value they are declared static.
      Smaller values will reduce residual combing, larger values will decrease flicker and
      increase the accuracy of field construction in static areas.  The spatially corresponding
      parts of the luma and chroma planes are linked (if link != 0), so mthreshC and mthreshL 
      may be somewhat interconnected.  Setting both values to 0 or below will disable motion 
      adaptation (i.e. every pixel will be declared moving) allowing for a dumb bob.

      default - mthreshL - 6  (int)
                mthreshC - 6


   map:

      Displays an output map instead of the deinterlaced frame.  There are three possible
      options.  **Note: the maps will not be displayed if the current frame is not being 
      deinterlaced due to overrides, hints, full=false, or tryWeave=true.

      **AP post-processing is currently not taken into account when using map = 1 or 2.

         0 - no map
         1 - value (binary) map.  This will output a frame in which all the pixels
             have one of the following values (indicating how the frame is to be
             constructed):
                 0   (use pixel from current frame)
                 51  (use pixel from previous frame)
                 102 (use pixel from next frame)
                 153 (use average of curr/next)
                 204 (use average of curr/prev)
                 255 (interpolate pixel)
         2 - merged map.  This will output a frame in which all the static parts of the 
             frame (values 0, 51, 102, 153, and 204 from map=1) have been constructed 
             as they would appear in the deinterlaced frame, and the pixels that are to be 
             interpolated are marked in white.

      default - 0  (int)


   ovr:

      Sets the name and path to an overrides file.  When mode=0, an overrides file can be 
      used to control the values of mthreshL, mthreshC, field, order, and type for single
      frames or for ranges of frames, as well as control which frames are deinterlaced.
      When mode=1, an overrides file can be used to control the values of mthreshL,
      mthreshC, and type for specific frames or ranges of frames.

        Overrides file specifiers:

            + = mark frame to be deinterlaced (only useful if ovrDefault = 1)
            - = mark frame to not be deinterlaced
            f = field
            o = order
            l = mthreshL
            c = mthreshC
            t = type

            *The c,f,o,l,t specifiers also require a change value to be specified when 
             they are used (look at the overrides syntax to see how this is done)

        Override syntax:

                [] = not required for +,- specifiers

            single frame override:

               frame_number specifier [change_value]

               examples:
 
                   245 f 1
                   345 +
                   400 -
                   450 c -1

            override for range of frames:

               start_frame_number,end_frame_number specifier [change_value]

               examples:

                   100,200 +
                   346,352 f 0
                   900,1200 l 5

                * the range is inclusive, meaning the end frame and start frame are
                  both included

               pattern based frame range overrides (only for +,- specifiers):

                   examples

                      100,300 +-+++--+++
                      400,456 ---+---++

                   * will use the given pattern over the specified frame range

        Things to remember (key points/rules):
 
             1.) Ranges are inclusive
             2.) When mode = 1 (bobbing) all overrides except for mthreshL/mthreshC, and type
                 overrides are ignored. Also, frame #'s correspond to the input clip not the 
                 output clip, thus one frame will be two frames in the output.
             3.) The changed value is always set back to what it was originally set to 
                 after the override goes out of the specified range. (i.e. if you specify an 
                 mthresh override for frame 600 to 700 after frame 700 mthresh is set back to 
                 its original value automatically, you don't need to set it back in the 
                 overrides file!  The original value is what it is set to on load (i.e. either 
                 the default or what you set it to in your avisynth script).
             4.) Frame numbers must be within range for the file.
             5.) Frame numbers for specific specifiers must be ascending (if they are not, the 
                 last entry in the file takes precedence ex. if you specify 300,400 c 10 then 
                 later do 350,450 c 12 frames 350 to 400 will use 12 not 10)
             6.) Frames numbers for the (+, -) specifiers cannot overlap (i.e. don't do 
                 300,400 - and then later in the file write 350,500 + or strange things will 
                 happen.  The other specifiers don't have to meet this requirement as they all 
                 effect different things.
             7.) +, - specifiers require no change value.
             8.) The spacing is important! Just look at the examples.
             9.) Only +, - specifiers can be used in pattern specifications.
            10.) You can change multiple specifiers over the same frame range as long as you follow 
                 the rules above (+,- ascending frame numbers for example).
            11.) You can comment out a line (i.e. it will be ignored) by adding a '#' or ';' to
                 the beginning of the line.
            12.) Entering 0 as the end_frame for a range of frames is taken as meaning the last
                 frame of the video.

         Example overrides file:         
      
              Syntax example => TDeint(order=1,ovr="c:\path\myoverridesfile.txt")

                       100,300 o 0
                       100,300 f 1
                       90,250 c 3
                       40,500 -
                       505 -
                       300,700 l -1
                       #700,3000 f 1   <- commented out, will be ignored
                       800,1000 -++-
                       500,1000 c 13

      default - ""  (string)


   ovrDefault:

      When using an overrides file in mode 0, this specifies the default action for all frames
      in the video.  Using ovrDefault=1 makes it easy to deinterlace only a few specific frames 
      in a video.  When mode = 1 this setting does nothing.

         0 - all frames not specified as '-' in the overrides file are deinterlaced
         1 - all frames not specified as '+' in the overrides file are not 
             deinterlaced and simply returned as is

      default - 0  (int)


   type:

      Sets the type of interpolation to use.  Cubic is the fastest, modified ELA and ELA2 will give
      smoother, less "jaggy", edges and are the slowest (ELA2 is faster), and kernel interpolation 
      will cause significantly less flickering then cubic or ela when interpolation gets used in 
      almost static areas.  Modified ELA/ELA2 works best with anime/cartoon type material... it is not
      that great with real life sources (sometimes it is, test for yourself).

         0 - cubic interpolation
         1 - modified ELA interpolation
         2 - kernel interpolation (can be normal or sharp, controlled by the sharp setting)
         3 - modified ELA-2 interpolation

      default - 2  (int)


   debug:

      Will enable debug output, which for each frame will list the values of order, field, 
      mthreshL, mthreshC, and type if the frame is being deinterlaced.  If the frame is
      not being deinterlaced (due to user overrides, hints, or full=false) it will simply 
      say the frame is not being deinterlaced and list the specific reason. If the output
      frame is weaved, then debug output will report which field the current field was
      weaved with (PREV or NEXT).

      default - false  (bool)


   mtnmode:

      Controls whether a 4 field motion check or a 5 field motion check is used.  5 field 
      will prevent more artifacts and can deal with duplicate interlaced frames, however
      it is quite a bit slower then the 4 field motion check.  Modes 2 and 3 are like 0 and
      1 except that in areas where an average of the prev and next field would have been
      used in mode 0 or 1, the pixel value from the most similar field (computed via field 
      differencing) is used instead (i.e. no averages are used).

         0 - 4 field check
         1 - 5 field check
         2 - 4 field check (no averages, replace with most similar field)
         3 - 5 field check (no averages, replace with most similar field)

      default - 1  (int)


   sharp:

      Controls whether the sharp or normal kernel is used when using kernel interpolation (type
      = 2).  The sharp kernel includes more pixels and produces a sharper result, but is
      slightly slower.
 
         true - use sharp kernel
         false - use normal kernel

      default - true  (bool)


   hints:

      Read hints from telecide or tfm indicating which frames are interlaced and which are not if
      hints are present in the video stream.  To make this work you need to set post=1 in telecide 
      or PP=1 in tfm and put TDeint immediately afterwards.  TDeint will not effect the hints (as long 
      as your video has a width of at least 64 pixels) in case any filters later on need to 
      read them.  If hints is set to true, but no hints from telecide or tfm are detected in the
      video stream, then all frames will be deinterlaced (TDeint will operate as if hints=false).