From f11cdea882b8024e0465ad48c9ea0044458042f9 Mon Sep 17 00:00:00 2001 From: Fredrik Mellbin Date: Thu, 9 Sep 2021 15:34:06 +0200 Subject: [PATCH] Add documentation --- .gitignore | 32 +++++ README.rst | 338 ++++++++++++++++++++++++++++++++++++++++++++++++++++ src/vivtc.c | 6 +- 3 files changed, 373 insertions(+), 3 deletions(-) create mode 100644 .gitignore create mode 100644 README.rst diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..259148f --- /dev/null +++ b/.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 diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..5db18d7 --- /dev/null +++ b/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). diff --git a/src/vivtc.c b/src/vivtc.c index 0381917..d2c1c30 100644 --- a/src/vivtc.c +++ b/src/vivtc.c @@ -29,9 +29,9 @@ #ifdef _WIN32 #include #endif -#include "VapourSynth4.h" -#include "VSHelper4.h" -#include "VSConstants4.h" +#include +#include +#include // Shared