lvsfunc.deinterlace

Deinterlacing, IVTC, and post-deinterlacing functions and wrappers.

lvsfunc.deinterlace.check_patterns(clip[, tff])

Naïve function that iterates over a given clip and tries out every simple 3:2 IVTC pattern.

lvsfunc.deinterlace.deblend(clip[, start, ...])

Deblending function for blended AABBA patterns.

lvsfunc.deinterlace.decomb(clip[, tff, ...])

Perform relatively aggressive filtering to get rid of the combing on a interlaced/telecined source.

lvsfunc.deinterlace.descale_fields(clip[, ...])

Descale interwoven upscaled fields, also known as a cross conversion.

lvsfunc.deinterlace.fix_telecined_fades(clip)

Give a mathematically perfect solution to fades made after telecining (which made perfect IVTC impossible).

lvsfunc.deinterlace.pulldown_credits(clip, ...)

Deinterlacing function for interlaced credits (60i/30p) on top of telecined video (24p).

lvsfunc.deinterlace.seek_cycle(clip[, ...])

Purely visual tool to view telecining cycles.

lvsfunc.deinterlace.sivtc(clip[, pattern, ...])

Simplest form of a fieldmatching function.

lvsfunc.deinterlace.tivtc_vfr(clip[, ...])

Perform TFM and TDecimate on a clip that is supposed to be VFR.

lvsfunc.deinterlace.vinverse(clip[, sstr, ...])

Clean up residual combing after a deinterlacing pass.

lvsfunc.deinterlace.check_patterns(clip, tff=None)

Naïve function that iterates over a given clip and tries out every simple 3:2 IVTC pattern.

This function will return the best pattern value that didn’t result in any combing. If all of them resulted in combing, it will raise an error.

Note that the clip length may seem off because I grab every fourth frame of a clip. This should make processing faster, and it will still find combed frames.

This function should only be used for rudimentary testing. If I see it in any proper scripts, heads will roll.

Dependencies:

Parameters
  • clip (VideoNode) – Clip to process.

  • tff (Union[bool, int, None]) – Top-field-first. False sets it to Bottom-Field-First. If None, get the field order from the _FieldBased prop.

Return type

int

Returns

Integer representing the best pattern.

Raises
  • TopFieldFirstError – No automatic tff can be determined.

  • StopIteration – No pattern resulted in a clean match.

lvsfunc.deinterlace.deblend(clip, start=0, rep=None, decimate=True)

Deblending function for blended AABBA patterns.

Assuming there’s a constant pattern of frames (labeled A, B, C, CD, and DA in this function), blending can be fixed by calculating the D frame by getting halves of CD and DA, and using that to fix up CD. DA is then dropped because it’s a duplicated frame.

Doing this will result in some of the artifacting being added to the deblended frame, but we can mitigate that by repairing the frame with the non-blended frame before it.

For more information, please refer to this blogpost by torchlight.

Dependencies:

  • RGSF (optional: 32 bit clip)

Parameters
  • clip (VideoNode) – Clip to process.

  • start (int) – First frame of the pattern (Default: 0).

  • rep (Optional[int]) – Repair mode for the deblended frames, no repair if None (Default: None).

  • decimate (bool) – Decimate the video after deblending (Default: True).

Return type

VideoNode

Returns

Deblended clip.

lvsfunc.deinterlace.decomb(clip, tff=True, mode=1, decimate=True, vinv=False, rep=0, show_mask=False, tfm_args={}, tdec_args={}, vinv_args={}, qtgmc_args={})

Perform relatively aggressive filtering to get rid of the combing on a interlaced/telecined source.

Decimation can be disabled if the user wishes to decimate the clip themselves.

Enabling vinverse will result in more aggressive decombing at the cost of potential detail loss. A reference clip can be passed with ref, which will be used by TFM to create the output frames.

Original function written by Midlifecrisis, modified by LightArrowsEXE.

Dependencies:

Parameters
  • clip (VideoNode) – Clip to process.

  • tff (bool | int) – Top-Field-First.

  • mode (int) – Sets the matching mode or strategy to use for TFM.

  • decimate (bool) – Decimate the video after deinterlacing (Default: True).

  • vinv (bool) – Use vinverse to get rid of additional combing (Default: False).

  • rep (Union[int, Sequence[int]]) – Repair mode for repairing the decombed clip using the original clip (Default: None).

  • show_mask (bool) – Return combmask.

  • tfm_args (Dict[str, Any]) – Arguments to pass to TFM.

  • vinv_args (Dict[str, Any]) – Arguments to pass to vinverse.

  • qtgmc_args (Dict[str, Any]) – Arguments to pass to QTGMC.

Return type

VideoNode

Returns

Decombed and optionally decimated clip.

Raises

ModuleNotFoundError – Dependencies are missing.

lvsfunc.deinterlace.descale_fields(clip, tff=True, width=None, height=720, kernel=vskernels.Bicubic, src_top=0.0)

Descale interwoven upscaled fields, also known as a cross conversion.

This function also sets a frameprop with the kernel that was used.

The kernel is set using an py:class:vskernels.Kernel object. For more information, check the vskernels documentation.

src_top allows you to to shift the clip prior to descaling. This may be useful, as sometimes clips are shifted before or after the original upscaling.

Parameters
  • clip (vs.VideoNode) – Clip to process.

  • tff (bool) – Top-field-first. False sets it to Bottom-Field-First.

  • width (int | None) – Native width. Will be automatically determined if set to None.

  • height (int) – Native height. Will be divided by two internally.

  • kernel (Kernel | str) – py:class:vskernels.Kernel object used for the descaling. This can also be the string name of the kernel (Default: py:class:vskernels.Catrom).

  • src_top (float) – Shifts the clip vertically during the descaling.

Return type

vs.VideoNode

Returns

Descaled GRAY clip.

lvsfunc.deinterlace.fix_telecined_fades(clip, tff=None, thr=2.2)

Give a mathematically perfect solution to fades made after telecining (which made perfect IVTC impossible).

This is an improved version of the Fix-Telecined-Fades plugin that deals with overshoot/undershoot by adding a check.

Make sure to run this after IVTC/deinterlacing!

If the value surpases thr * original value, it will not affect any pixels in that frame to avoid it damaging frames it shouldn’t need to. This helps a lot with orphan fields as well, which would otherwise create massive swings in values, sometimes messing up the fade fixing.

Warning

If you pass your own float clip, you’ll want to make sure to properly dither it down after.
If you don’t do this, you’ll run into some serious issues!

Taken from this gist and modified by LightArrowsEXE. <https://gist.github.com/blackpilling/bf22846bfaa870a57ad77925c3524eb1>

Parameters
  • clip (VideoNode) – Clip to process.

  • tff (Union[bool, int, None]) – Top-field-first. False sets it to Bottom-Field-First. If None, get the field order from the _FieldBased prop.

  • thr (float) – Threshold for when a field should be adjusted. Default is 2.2, which appears to be a safe value that doesn’t cause it to do weird stuff with orphan fields.

Return type

VideoNode

Returns

Clip with only fades fixed.

Raises

TopFieldFirstError – No automatic tff can be determined.

lvsfunc.deinterlace.pulldown_credits(clip, frame_ref, tff=None, interlaced=True, dec=None, bob_clip=None, qtgmc_args={})

Deinterlacing function for interlaced credits (60i/30p) on top of telecined video (24p).

This is a combination of havsfunc’s dec_txt60mc, ivtc_txt30mc, and ivtc_txt60mc functions. The credits are interpolated and decimated to match the output clip.

The function assumes you’re passing a telecined clip (that’s native 24p). If your clip is already fieldmatched, decimation will automatically be enabled unless set it to False. Likewise, if your credits are 30p (as opposed to 60i), you should set interlaced to False.

The recommended way to use this filter is to trim out the area with interlaced credits, apply this function, and vsutil.insert_clip the clip back into a properly IVTC’d clip. Alternatively, use muvsfunc.VFRSplice to splice the clip back in if you’re dealing with a VFR clip.

Parameters
  • clip (vs.VideoNode) – Clip to process. Framerate must be 30000/1001.

  • frame_ref (int) – First frame in the pattern. Expected pattern is ABBCD, except for when dec is enabled, in which case it’s AABCD.

  • tff (bool | None) – Top-field-first. False sets it to Bottom-Field-First.

  • interlaced (bool) – 60i credits. Set to false for 30p credits.

  • dec (bool | None) – Decimate input clip as opposed to IVTC. Automatically enabled if certain fieldmatching props are found. Can be forcibly disabled by setting it to False.

  • bob_clip (vs.VideoNode | None) – Custom bobbed clip. If None, uses a QTGMC clip. Framerate must be 60000/1001.

  • qtgmc_args (Dict[str, Any]) – Arguments to pass on to QTGMC. Accepts any parameter except for FPSDivisor and TFF.

Return type

vs.VideoNode

Returns

IVTC’d/decimated clip with credits pulled down to 24p.

Raises
  • ModuleNotFoundError – Dependencies are missing.

  • ValueError – Clip does not have a framerate of 30000/1001 (29.97).

  • TopFieldFirstError – No automatic tff can be determined.

  • InvalidFramerateError – Bobbed clip does not have a framerate of 60000/1001 (59.94)

lvsfunc.deinterlace.seek_cycle(clip, write_props=True, scale=- 1)

Purely visual tool to view telecining cycles.

Warning

This is purely a visual tool and has no matching parameters!
Just use Wobbly instead if you need that.

Displays the current frame, two previous and future frames, and whether they are combed or not.

P indicates a progressive frame, and C a combed frame.

Dependencies:

Parameters
  • clip (VideoNode) – Clip to process.

  • write_props (bool) – Write props on frames. Disabling this will also speed up the function.

  • scale (int) – Integer scaling of all clips. Must be to the power of 2.

Return type

VideoNode

Returns

Viewing UI for standard telecining cycles.

Raises

ValueErrorscale is a value that is not to the power of 2.

lvsfunc.deinterlace.sivtc(clip, pattern=0, tff=True, decimate=True)

Simplest form of a fieldmatching function.

This is essentially a stripped-down JIVTC offering JUST the basic fieldmatching and decimation part. As such, you may need to combine multiple instances if patterns change throughout the clip.

Parameters
  • clip (VideoNode) – Clip to process.

  • pattern (int) – First frame of any clean-combed-combed-clean-clean sequence.

  • tff (bool) – Top-Field-First.

  • decimate (bool) – Drop a frame every 5 frames to get down to 24000/1001.

Return type

VideoNode

Returns

IVTC’d clip.

lvsfunc.deinterlace.tivtc_vfr(clip, tfm_in='.ivtc/{yourScriptName}_matches.txt', tdec_in='.ivtc/{yourScriptName}_metrics.txt', timecodes_out='.ivtc/{yourScriptName}_timecodes.txt', decimate=True, tfm_args={}, tdecimate_args={})

Perform TFM and TDecimate on a clip that is supposed to be VFR.

Includes automatic generation of a metrics/matches/timecodes txt file.

This function took heavy inspiration from atomchtools.TIVTC_VFR,
and is basically an improved rewrite on the concept.

Warning

When calculating the matches and metrics for the first time, your previewer may error out!
To fix this, simply refresh your previewer. If it still doesn’t work, open the .ivtc directory
and check if the files are 0kb. If they are, delete them and run the function again.
You may need to restart your previewer entirely for it to work!

Dependencies:

Parameters
  • clip (VideoNode) – Clip to process.

  • tfmIn – File location for TFM’s matches analysis. By default it will be written to .ivtc/{yourScriptName}_matches.txt.

  • tdecIn – File location for TDecimate’s metrics analysis. By default it will be written to .ivtc/{yourScriptName}_metrics.txt.

  • timecodes_out (Path | str) – File location for TDecimate’s timecodes analysis. By default it will be written to .ivtc/{yourScriptName}_timecodes.txt.

  • decimate (int | bool) – Perform TDecimate on the clip if true, else returns TFM’d clip only. Set to -1 to use TDecimate without TFM.

  • tfm_args (Dict[str, Any]) – Additional arguments to pass to TFM.

  • tdecimate_args (Dict[str, Any]) – Additional arguments to pass to TDecimate.

Return type

VideoNode

Returns

IVTC’d VFR clip with external timecode/matches/metrics txt files.

Raises

TypeError – Invalid decimate argument is passed.

lvsfunc.deinterlace.vinverse(clip, sstr=2.0, amount=128, scale=1.5)

Clean up residual combing after a deinterlacing pass.

This is Setsugen no ao’s implementation, adopted into lvsfunc.

Parameters
  • clip (VideoNode) – Clip to process.

  • sstr (float) – Contrasharpening strength. Increase this if you find the decombing blurs the image a bit too much.

  • amount (int) – Maximum difference allowed between the original pixels and adjusted pixels. Scaled to input clip’s depth. Set to 255 to effectively disable this.

  • scale (float) – Scale amount for vertical sharp * vertical blur.

Return type

VideoNode

Returns

Clip with residual combing largely removed.

Raises

ValueErroramount is set above 255.