vapoursynth-vivtc 2.0

Inverse telecine filter for VapourSynth

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).