Add documentation

.gitignore

@@ -0,0 +1,32 @@
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app

README.rst

@@ -0,0 +1,338 @@
+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).

src/vivtc.c

@@ -29,9 +29,9 @@
 #ifdef _WIN32
 #include <windows.h>
 #endif
-#include "VapourSynth4.h"
-#include "VSHelper4.h"
-#include "VSConstants4.h"
+#include <VapourSynth4.h>
+#include <VSHelper4.h>
+#include <VSConstants4.h>
 
 // Shared