VIVTC
=====

VIVTC is a set of filters that can be used for inverse telecine.
It is a rewrite of some of tritical's TIVTC filters.

.. function:: VFM(clip clip, int order[, int field=2, int mode=1, bint mchroma=1, int cthresh=9, int mi=80, bint chroma=1, int blockx=16, int blocky=16, int y0=16, int y1=16, float scthresh=12, int micmatch=1, bint micout=0, clip clip2])
   :module: vivtc

   VFM is a field matching filter that recovers the original progressive frames
   from a telecined stream. VFM's output will contain duplicated frames, which
   is why it must be further processed by a decimation filter, like VDecimate.

   Unlike TFM, VFM does not have any postprocessing capabilities.
   
   You can however script your own like this (make sure the deinterlacer and VFM reference field is the same to avoid jerkiness)::

      import vapoursynth as vs
      import functools

      input_clip = vs.core.std.BlankClip(format=vs.YUV420P8, length=1000, color=[255, 128, 128])

      def postprocess(n, f, clip, deinterlaced):
         if f.props['_Combed'] > 0:
            return deinterlaced
         else:
            return clip

      matched_clip = vs.core.vivtc.VFM(input_clip, 1)
      deinterlaced_clip = vs.core.eedi3.eedi3(matched_clip, field=1)
      postprocessed_clip = vs.core.std.FrameEval(matched_clip, functools.partial(postprocess, clip=matched_clip, deinterlaced=deinterlaced_clip), prop_src=matched_clip)
      decimated_clip = vs.core.vivtc.VDecimate(postprocessed_clip)
      decimated_clip.set_output()

   VFM adds the following properties to every frame it outputs:
      VFMMics
         Array of five integers.

         It will contain the mic values for the five possible matches
         (p/c/n/b/u). Some of them may be unset (-1), depending on *micout*
         and *micmatch*.

         These numbers represent the highest concentration of combed pixels
         found in any block in the frame.

      _Combed
         1 if VFM thinks the frame is combed, 0 if not.

      VFMMatch
         Match used for the frame.

         0 = p

         1 = c

         2 = n

         3 = b

         4 = u

      VFMSceneChange
         1 if VFM thinks the frame is a scene change, 0 if not.


   Parameters:
      clip
         Input clip. YUV420P8, YUV422P8, YUV440P8, YUV444P8, and GRAY8
         are supported. Must have constant format and dimensions.

      order
         Sets the field order of the clip. Normally the field order is
         obtained from the ``_FieldBased`` frame property. This parameter
         is only used for those frames where the ``_FieldBased`` property
         has an invalid value or doesn't exist.

         If the field order is wrong, VFM's output will be visibly wrong
         in mode 0.

         0 - bottom field first

         1 - top field first

      field
         Sets the field to match from. This is the field that VFM will take
         from the current frame in case of p or n matches. It is recommended
         to make this the same as the field order, unless you experience
         matching failures with that setting. In certain circumstances
         changing the field that is used to match from can have a large
         impact on matching performance.

         0 - bottom field

         1 - top field

         2 - same as the field order

         3 - opposite of the field order

         0 and 1 will disregard the ``_FieldBased`` frame property. 2 and 3
         will adapt to the field order obtained from the ``_FieldBased``
         property.

         Default: 2.

      mode
         Sets the matching mode or strategy to use. Plain 2-way matching
         (option 0) is the safest of all the options in the sense that it won't
         risk creating jerkiness due to duplicate frames when possible, but if
         there are bad edits or blended fields it will end up outputting combed
         frames when a good match might actually exist. 3-way matching + trying
         the 4th/5th matches if all 3 of the original matches are detected as
         combed (option 5) is the most risky in terms of creating jerkiness,
         but will almost always find a good frame if there is one. The other
         settings (options 1, 2, 3, and 4) are all somewhere in between options
         0 and 5 in terms of risking jerkiness and creating duplicate frames vs.
         finding good matches in sections with bad edits, orphaned fields,
         blended fields, etc.
         
         Note that the combed condition here is not the same as the ``_Combed``
         frame property. Instead it's a combination of relative and absolute
         threshold comparisons and can still lead to the match being changed
         even when the ``_Combed`` flag is not set on the original frame.

         0 = 2-way match (p/c)
         
         1 = 2-way match + 3rd match on combed (p/c + n)
         
         2 = 2-way match + 3rd match (same order) on combed (p/c + u)
         
         3 = 2-way match + 3rd match on combed + 4th/5th matches if still combed (p/c + n + u/b)
         
         4 = 3-way match (p/c/n)
         
         5 = 3-way match + 4th/5th matches on combed (p/c/n + u/b)

         The parantheses at the end indicate the matches that would be used
         for each mode assuming order=1 and field=1.

         Default: 1.

      mchroma
         Sets whether or not chroma is included during the match comparisons.
         In most cases it is recommended to leave this enabled. Only if your
         clip has bad chroma problems such as heavy rainbowing or other
         artifacts should you set this to false. Setting this to false could
         also be used to speed things up at the cost of some accuracy.

         Default: true.

      cthresh
         This is the area combing threshold used for combed frame detection.
         This essentially controls how "strong" or "visible" combing must be
         to be detected. Larger values mean combing must be more visible and
         smaller values mean combing can be less visible or strong and still
         be detected. Valid settings are from -1 (every pixel will be detected
         as combed) to 255 (no pixel will be detected as combed). This is
         basically a pixel difference value. A good range is between 8 to 12.

         Default: 9.

      mi
         The number of combed pixels inside any of the *blockx* by *blocky*
         size blocks on the frame for the frame to be detected as combed.
         While *cthresh* controls how "visible" the combing must be, this
         setting controls "how much" combing there must be in any localized
         area (a window defined by the *blockx* and *blocky* settings) on the
         frame. The minimum is 0, the maximum is *blocky* * *blockx* (at which
         point no frames will ever be detected as combed).

         Default: 80.

      chroma
         Sets whether or not chroma is considered in the combed frame decision.
         Only disable this if your source has chroma problems (rainbowing, etc)
         that are causing problems for the combed frame detection with *chroma*
         enabled. Actually, using chroma=false is usually more reliable, except
         in case there is chroma-only combing in the source.

         Default: true.

      blockx

      blocky
         Sets the size of the window used during combed frame detection. This
         has to do with the size of the area in which *mi* number of pixels are
         required to be detected as combed for a frame to be declared combed.
         See the *mi* parameter description for more info. Possible values are
         any power of 2 between 4 and 512.

         Defaults: 16, 16.

      y0

      y1
         The rows from *y0* to *y1* will be excluded from the field matching
         decision.
         This can be used to ignore subtitles, a logo, or other things that may
         interfere with the matching.
         Set *y0* equal to *y1* to disable.

         Defaults: 16, 16.

      scthresh
         Sets the scenechange threshold as a percentage of maximum change on the
         luma plane.
         Good values are in the 8 to 14 range.

         Default: 12.

      micmatch
         When micmatch is greater than 0, tfm will take into account the mic
         values of matches when deciding what match to use as the final match.
         Only matches that could be used within the current matching mode are
         considered. micmatch has 3 possible settings:

         0 - disabled. Modes 1, 2 and 3 effectively become identical to mode 0.
         Mode 5 becomes identical to mode 4.

         1 - micmatching will be used only around scene changes. See the
         *scthresh* parameter.

         2 - micmatching will be used everywhere.

         Default: 1.

      micout
         If true, VFM will calculate the mic values for all possible matches
         (p/c/n/b/u).
         Otherwise, only the mic values for the matches allowed by *mode* will
         be calculated.

         Default: false.

      clip2
         Clip that VFM will use to create the output frames. If *clip2* is used,
         VFM will perform all calculations based on *clip*, but will copy the
         chosen fields from *clip2*. This can be used to work around VFM's video
         format limitations. For example if you have a YUV444P16 input clip::

            yv12 = vs.core.resize.Bicubic(clip=original, format=vs.YUV420P8)
            fieldmatched = vs.core.vivtc.VFM(clip=yv12, order=1, chroma=False, clip2=original)

         .. note::
            In this example chroma is ignored because the used conversion to YUV420P8
            will not accurately preserve it.

.. function:: VDecimate(clip clip[, int cycle=5, bint chroma=1, float dupthresh=1.1, float scthresh=15, int blockx=32, int blocky=32, clip clip2, string ovr="", bint dryrun=0])
   :module: vivtc

   VDecimate is a decimation filter. It drops one in every *cycle* frames -- the
   one that is most likely to be a duplicate (mode 0 in TDecimate).

   Parameters:
      clip
         Input clip. Must have constant format and dimensions, known length,
         integer sample type, and bit depth between 8 and 16 bits per sample.

      cycle
         Size of a cycle, in frames. One in every *cycle* frames will be
         decimated.

         Default: 5.

      chroma
         Controls whether the chroma is considered when calculating frame
         difference metrics.

         Default: true when the input clip has chroma.

      dupthresh
         This sets the threshold for duplicate detection. If the difference
         metric for a frame is less than or equal to this value then it is
         declared a duplicate. This value is a percentage of maximum change
         for a block defined by the *blockx* and *blocky* values, so 1.1 means
         1.1% of maximum possible change.

         Default: 1.1.

      scthresh
         Sets the threshold for detecting scene changes. This value is a
         percentage of maximum change for the luma plane. Good values are
         between 10 and 15.

         Default: 15.

      blockx

      blocky
         Sets the size of the blocks used for metric calculations. Larger blocks
         give better noise suppression, but also give worse detection of small
         movements. Possible values are any power of 2 between 4 and 512.

         Defaults: 32, 32.

      clip2
         This has the same purpose as VFM's *clip2* parameter.

      ovr
         Text file containing overrides. This can be used to manually choose
         what frames get dropped. Lines starting with # are ignored.

         Drop a specific frame::

            314 -
            
         Drop every fourth frame, starting at frame 1001, up to frame 5403::
         
            1001,5403 +++-+

         The frame numbers apply to the undecimated input clip, of course.

         The decimation pattern must contain *cycle* characters.

         If the overrides mark more than one frame per cycle, the first frame
         marked for decimation in the cycle will be dropped.

      dryrun
         If true, VDecimate will not drop any frames. Instead, it will attach
         the following properties to every frame:
         
            VDecimateDrop
               1 if VDecimate would normally drop the frame, 0 otherwise.

            VDecimateMaxBlockDiff
               This is the highest absolute difference between the current
               frame and the previous frame found in any *blockx*\ \*\ *blocky*
               block. It is known in Yatta as "DMetric".

            VDecimateTotalDiff
               This is the absolute difference between the current frame and
               the previous frame.

         Default: false.


Large parts of this document were copied from "TFM - READ ME.txt" and
"TDecimate - READ ME.txt", written by Kevin Stone (aka tritical).
