# QTGMC

## Abstract

A very high quality deinterlacer with a range of features for both quality and convenience. These include a simple presets system, extensive noise processing capabilities, support for repair of progressive material, precision source matching, shutter speed simulation, etc. Originally based on TempGaussMC_beta2 by Didée

Author: Vit
Version: 3.32
Date: 2011-05-05
Requirements: YV12 or YUY2 colorspace, required plugins list

## Contents

1. Latest Changes
2. Usage
   1. Requirements
   2. Getting Started
   3. Multi-threading
3. Features / Settings
   1. Core Settings
   2. Motion Analysis
   3. Interpolation
   4. Sharpness
   5. Source Match / Lossless
   6. Noise Bypass / Denoising
   7. Progressive Input
   8. Shutter Speed Motion Blur / Frame Rate
   9. Miscellaneous Settings
4. External Linkage
   1. Accessing QTGMC Motion Vectors
   2. Multiple QTGMC Calls
5. TempGaussMC Notes
6. Acknowledgments
7. Version History

## Latest Changes

v3.32

- Bugfix with shutter blur and ChromaMotion
- Tweaked vector recalculation for shutter motion blur
- Changed defaults for TR2 when using source-match
- Minor bugfix with SLMode/SLRad on pass-through settings

Jump to Version History

## Usage

### Requirements

Requires the following plugins, either in the avisynth plugin autoload folder or loaded from the calling script:

#### Core plugins

- MVTools2 (2.5.11.2 or above)
- MaskTools v2 (recommend 2.0a45 or above)
- NNEDI3 (recommend 0.9.2 or above)
- RemoveGrain + Repair (extract only the SSE2 versions, some SSE3 versions have a bug and give no real benefit)
- SSE2Tools for YUY2 support (take only SSE2Tools.dll from this zip - do not take the SSE3 version nor the RemoveGrain or Repair dlls)

#### Additional plugins

- NNEDI2, NNEDI, EEDI3, EEDI2, TDeint - if selected directly or via a source-match preset
- Yadif - for `Preset="Ultra Fast"` or if selected directly (this plugin cannot be autoloaded, it must beloaded in the calling script)
- VerticalCleaner - for `SVThin` or `Lossless` modes
- AddGrainC (or here) - if `NoiseDeint="Generate"` selected for noise processing
- FFT3DFilter - if selected for noise processing
- dfttest - if selected for noise processing
  - For FFT3DFilter and ddftest you also need the FFTW3 library (main page / windows zips). On Windows the file needed for both is libfftw3f-3.dll. However for FFT3DFilter, it needs to be called FFTW3.dll, so you will need two copies and rename one. On Windows put the files in your System32 or SysWow64 folder (which depends on your OS and the version of AviSynth that you're running)

### Getting Started

Install AviSynth and ensure you have at least the core plugins listed in the requirements section. Then to use QTGMC, write a script like this:

    YourSource( "yourfile" )  # DGDecode_mpeg2source, FFVideoSource, AviSource, whatever your source requires
    QTGMC( Preset="Slow" )
    SelectEven();  # Add this line to keep original frame rate, leave it out for smoother doubled frame rate

Save this script with an ".avs" extension. You can now use it as an AVI source for encoding.

The "Preset" used selects sensible settings for a given encoding speed. Choose a preset from:
`"Placebo", "Very Slow", "Slower", "Slow", "Medium", "Fast", "Faster", "Very Fast", "Super Fast", "Ultra Fast", "Draft"`
The default preset is `"Slower"`. Don't be obsessed with using slower settings, the differences can be small. In particular HD material benefits less from extreme settings (and will be slow)

There are many settings for tweaking this script, full details are provided in this documentation. The settings have been divided into categories, which each having key points, a detailed description, settings specifications/defaults, and several examples. The key points and examples should get you going. You can display settings currently being used with `ShowSettings`:

    QTGMC( Preset="Slow", ShowSettings=true )

### Multi-threading

QTGMC is very demanding on your system. For best performance try using it multi-threaded. You need an "MT" version of avisynth, find the links to these versions on the AviSynth Wiki. Below is a template multi-threading script, read and follow the comments carefully (you cannot use this script as it is):

    SetMemoryMax(M)  # Optional line. Leave it out at first. See below for value M
    SetMTMode(5, X)  # See below for value X
    YourSource( "yourfile" )  # DGDecode_mpeg2source, FFVideoSource, AviSource, whatever your source requires
    SetMTMode(2)
    QTGMC( Preset="Slow", EdiThreads=Y ) # Choose preset based on overall speed/quality you want. See below for value Y
    Distributor()    # This line may or may not be necessary, try removing it and see if you get more speed

#### Setting X

- Start at the number of logical cores in your machine (note: with HyperThreading enabled, logical cores = 2x physical cores)
- If it crashes, decrease 1 at a time
- Otherwise increase 1 at a time until CPU usage just about reaches 100%, don't go too far or it will slow down

#### Setting Y

- Start at about half number of cores and tweak upwards or downwards
- Reducing this value might allow you to increase X for an overall speedup

#### Setting M

- First try without the SetMemoryMax line
- However, selecting a good SetMemoryMax value might better utilise memory and increase stability. Particularly important for slower settings
- Try values 400,600,800,1000 etc. Sometimes reducing this value can allow you to increase X for a speedup

Each machine is different, the above guidelines are simply a good starting point. Experiment for best results. Note that you can only use QTGMC with SetMTMode(...), do not use MT(...). There are occasional instabilities with multi-threading, because AviSynth is not quite thread-safe. These instabilities affect different users in different ways: some report no issues, others can barely get multi-threading to work at all

## Features / Settings

### Core Settings

Key Points: For basic usage, select a preset and leave the core settings alone. Most useful setting is TR2, which controls smoothing of output

The core algorithm is this:
0. Bob the source clip. Temporally smooth the bob to remove shimmer then analyse its motion
1. More accurately interpolate the source clip (e.g. NNEDI3). Use the motion analysis from previous step to temporally smooth this interpolate with motion compensation. This removes shimmer whilst retaining detail. Resharpen the result to counteract any blurring
2. A final light temporal smooth to clean the result

Stages 0 & 1 use a binomial smooth (similar to a Gaussian) to remove deinterlacing shimmer. Stage 2 uses a simple linear smoothing. So each stage involves a temporal smooth with the radius (number of frames involved) given in the settings TR0, TR1 and TR2. The binomial smooths are critical for the algorithm so TR0 and TR1 should be at least 1. TR0 only affects the motion analysis and is only indirectly visible, increasing it to 2 will generally give a better motion match. Increasing TR1 and TR2 will create a smoother and more stable output and more strongly denoise. The downside is that you will get more blurring and may lose detail. The blur is counteracted by the sharpening settings described below. Also note that increased TR1 & TR2 can cause/strengthen halos where the motion analysis is inaccurate

The deinterlacer primarily tries to reduce "bob shimmer": horizontal lines of shimmer created when interpolating an interlaced stream. Consequently any changes made to the initial interpolation (e.g. NNEDI3) are expected to be horizontal lines of change only. The repair stages Rep0, Rep1 and Rep2 occur after each temporal smooth. They only allow such horizontal lines of change - shimmer fixes, discarding other changes. This prevents the motion blur
that temporal smoothing could generate. The repX settings control the size of areas to allow through. See the QTGMC_KeepOnlyBobShimmerFixes function comments

Settings |  |
TR0 | (0,1,2) | Temporal binomial smoothing radius used to create motion search clip. In general 2=quality, 1=speed, 0=don't use
TR1 | (0,1,2) | Temporal binomial smoothing radius used on interpolated clip for inital output. In general 2=quality, 1=speed, 0=don't use
TR2 | (0,1,2,3) | Temporal linear smoothing radius used for final stablization / denoising. Increase for smoother output
Rep0 | (0...) | Repair motion search clip (0 = off): repair unwanted blur after temporal smooth TR0 (see QTGMC_KeepOnlyBobShimmerFixes function in script for details)
Rep1 | (0...) | Repair initial output clip (0 = off): repair unwanted blur after temporal smooth TR1
Rep2 | (0...) | Repair final output clip (0 = off): unwanted blur after temporal smooth TR2 (will also repair TR1 blur if Rep1 not used)
RepChroma | (bool) | Whether the repair modes affect chroma
Defaults determined by preset for all these settings (see table in script or use ShowSettings), except RepChroma which defaults to true

Examples

    QTGMC( Preset="Slow", TR2=3 )  # Strong final smooth (e.g. noisy / shimmery source)

### Motion Analysis

Key Points: The presets make sensible choices for motion analysis. Some sources or requirements may require tweaks, but read these and MVTools2 docs first.

The bobbed source clip is sent to the MVTools2 plugin to perform motion analysis. Almost all these settings are used directly in MVTools2 functions. Read the MVTools2 documentation for more details on their purpose. Some settings can be altered for a speed / accuracy tradeoff. Less accurate motion search can result in blurring and/or oversharpening (in different circumstances) as well as slight distortions of visual elements. The faster presets gain speed by simplifying the motion search parameters, use the "ShowSettings" parameter or look at the table a short way into the script to see how.

Settings |  |
SrchClipPP | (0,1,2,3) | Pre-filtering for motion search clip, 0 = none, 1 = simple blur, 2 = Gauss blur, 3 = Gauss blur + edge soften
SubPel | (1,2,4) | Sub-pixel accuracy for motion analysis (1 = 1 pixel, 2 = 1/2 pixel, 4 = 1/4 pixel)
SubPelInterp | (0,1,2) | Interpolation used for sub-pixel motion analysis: 0 = bilinear (soft), 1 = bicubic (sharper), 2 = Weiner (sharpest)
Blocksize | (4,8,16,32) | Size of blocks that are matched during motion analysis
Overlap | (< Blocksize/2) | How much to overlap motion analysis blocks (requires more blocks, but essential to smooth block edges in motion compenstion)
Search | (0...5) | Search method used for matching motion blocks - see MVTools2 documentation for available algorithms
SearchParam | (0...) | Parameter for search method chosen. For default search method (hexagon search) it is the search range
PelSearch | (0...) | Search parameter (as above) for the finest sub-pixel level (see SubPel)
ChromaMotion | (bool) | Whether to consider chroma when analyzing motion. Setting to false gives good speed-up, but may very occasionally make incorrect motion decision.
TrueMotion | (bool) | Whether to use the 'truemotion' defaults from MAnalyse (see MVTools2 documentation)
Lambda | (0...) | Motion vector field coherence - how much the motion analysis favors similar motion vectors for neighboring blocks. Should be scaled by BlockSize*BlockSize/64
LSAD | (0...) | How much to reduce need for vector coherence (i.e. Lambda above) if prediction of motion vector from neighbors is poor, typically in areas of complex motion. This value is scaled in MVTools (unlike Lambda)
PNew | (0...) | Penalty for choosing a new motion vector for a block over an existing one - avoids chosing new vectors for minor gain
PLevel | (0,1,2) | Mode for scaling lambda across different sub-pixel levels - see MVTools2 documentation for choices
GlobalMotion | (bool) | Whether to estimate camera motion to assist in selecting block motion vectors
DCT | (0...10) | Modes to use DCT (frequency analysis) or SATD as part of the block matching process - see MVTools2 documentation for choices
ThSAD1 | (0...) | SAD threshold for block match on shimmer-removing temporal smooth (TR1). Increase to reduce bob-shimmer more (may smear/blur)
ThSAD2 | (0...) | SAD threshold for block match on final denoising temporal smooth (TR2). Increase to strengthen final smooth (may smear/blur)
ThSCD1 | (0...) | Scene change detection parameter 1 - see MVTools documentation
ThSCD2 | (0...) | Scene change detection parameter 2 - see MVTools documentation
Defaults: For some settings defaults are determined by preset (see table in script or use ShowSettings). Some other defaults are: SubPelInterp=2, TrueMotion = false, GlobalMotion=true, DCT=0, ThSAD1=640, ThSAD2=256, ThSCD1=180, ThSCD2=98 The remaining defaults depend on TrueMotion:
TrueMotion=false (the default):
Lambda = (1000 * BlockSize2)/64, LSAD=400, PNew=25, PLevel=0
TrueMotion=true:
Lambda = (100 * BlockSize2)/64, LSAD=1200, PNew=50, PLevel=1

### Interpolation

Key Points: Interpolation affects quality and speed. The presets can be relied on to provide sensible defaults mostly using NNEDI3.

The first step to create the deinterlaced output is to spatially interpolate a single half-height field into a full-height frame. A variety of interpolators are supported, with various settings to control the quality/speed of the output.

Settings |  |
EdiMode | (string) | Interpolation method, from "NNEDI3", "NNEDI2", "NNEDI", "EEDI3+NNEDI3" (EEDI3 with sclip from NNEDI3), "EEDI3", "EEDI2", "Yadif", "TDeint" or "RepYadif" ("repaired" Yadif), anything else uses "Bob"
ChromaEdi | (string) | Interpolation method used for chroma. Set to "" to use EdiMode above (default). Otherwise choose from "NNEDI3", "Yadif" or "Bob" - all high speed variants. This can give a minor speed-up if using a very slow EdiMode (i.e. one of the EEDIx modes)
NNSize | (0...6) | Area around each pixel used as predictor for NNEDI3. A larger area is slower with better quality, read the NNEDI3 docs to see the area choices. Note: area sizes are not in increasing order (i.e. increased value doesn't always mean increased quality)
NNeurons | (0...4) | Controls number of neurons in NNEDI2 (0-2) & NNEDI3 (0-4), larger = slower and better quality but improvements are small
EdiQual | (1,2,3) | Quality setting for NNEDI2 (1,2,3) & NNEDI3 (1,2 only). Higher values for better quality - but improvements are marginal
EdiMaxD | (1...) | Spatial search distance for finding connecting edges in EEDI2 and EEDI3
EdiThreads | (0...) | Number of threads to use in EEDI3 & NNEDI2/3, 0 = default = number of logical processors on system. Also affects source-match interpolations. Source-match can add 2 further interpolations per frame, adjusting this setting can help balance system load
EdiExt | (clip) | Provide externally created interpolated clip rather than use one of the above modes
Defaults: Determined by presets for NNEDIx and EEDIx (see table in script or use ShowSettings). Other defaults are ChromaEdi="", EdiThreads=0, EdiExt=undefined

Examples

    QTGMC( Preset="Slow", EdiMode="EEDI3", EdiMaxD=16 ) # Use EEDI3 with an explicit search radius
    QTGMC( Preset="Very Slow", EdiThreads=2 )           # Specify number of threads (with default NNEDI3) useful to tweak if using SetMTMode or source-match

### Sharpness

Key Points: Always consider adjusting the Sharpness setting to taste. The default 1.0 is fairly sharp. If using source-match the default is 0.2

The core of the algorithm involves a binomial smooth to remove shimmer. So the result needs to be resharpened to counteract this blur. The main setting Sharpness defaults to 1.0, which is a level designed to retain the sharpness of stable areas. However, this level can cause moving areas to be oversharpened so you may wish to reduce the value depending on source. Sharpness when using source-match behaves differently, see that section. The sharpness processing for a given setting is tweaked to remain roughly similar regardless of other settings. However, there will be minor differences, so always consider adjusting sharpness if you tweak other major settings.

Oversharpening is limited either spatially (SLMode = 1,3) or temporally (SLMode = 2,4). Temporal limiting is more "correct" but also more aggressive in preventing sharpening. It's also slower. You can set a small value in the overshoot setting (SOvs) to give the temporal limiting a bit of "headroom". You can also perform sharpness limiting later in the algorithm (SLMode = 3,4) for more sharpness, but with the potential for minor artefacts.

Settings |  |
Sharpness | (0.0...) | How much to resharpen the temporally blurred clip (default is always 1.0 unlike original TGMC)
SMode | (0,1,2) | Resharpening mode: 0 = none, 1 = difference from 3x3 blur kernel, 2 = vertical max/min average + 3x3 kernel
SLMode | (0,1,2,3,4) | Sharpness limiting: 0 = off, [1 = spatial, 2 = temporal] : before final temporal smooth, [3 = spatial, 4 = temporal] : after final temporal smooth
SLRad | (0...) | Temporal or spatial radius used with sharpness limiting (depends on SLMode). Temporal radius can only be 0,1 or 3
SOvs | (0...255) | Amount of overshoot allowed with temporal sharpness limiting (SLMode = 2,4), i.e. allow some oversharpening
SVThin | (0.0...) | How much to thin down 1-pixel wide lines that have been widened due to interpolation into neighboring field lines
Sbb | (0,1,2,3) | Back blend (blurred) difference between pre & post sharpened clip (minor fidelity improvement): 0 = Off, 1 = before (1st) sharpness limiting, 2 = after (1st) sharpness limiting, 3 = both
Defaults are determined by preset for SMode, SLMode, SLRad and Sbb (see table in script or use ShowSettings). Other defaults are: SOvs=0, SVThin=0.0, Sbb=0

Examples

    QTGMC( Preset="Slow", Sharpness=0.4 )           # Reduce oversharpening
    QTGMC( Preset="Slow", Sharpness=1.2, SLMode=1 ) # Increase sharpness, use spatial sharpness limiting (which typically allows more sharpening)

### Source Match / Lossless

`Very detailed section for new feature [documentation likely to be thinned as feature matures]`
`Note: the effects of this feature are both subtle and precise, intended only for exacting detail. Make sure you can see exacting detail first.`

Key Points: Source-match creates higher fidelity output with extra processing. Enable with SourceMatch = 1,2 or 3. Higher values are slower and more accurate. Can combine with Lossless setting (especially Lossless=2) for more detail again. Tweak speed with MatchPreset (like Preset). Will honor artefacts in source, so best used with quality sources. By default Sharpness becomes 0.2 & sharpness limiting (SLMode) is switched off, so adjust sharpness carefully.

Quickstart: The templates below increase in both quality and slowness. Choose a preset as required, the very fastest presets are not suitable though. The default Sharpness=0.2 but you may wish to increase it slightly. Set TR2=1 for clean source, set TR2=2 or TR2=3 (slower) if more denoising required or use noise processing

    QTGMC( Preset=XXXX, SourceMatch=1, Sharpness=XXX, TR2=X )             # Basic mode, fastest
    QTGMC( Preset=XXXX, SourceMatch=1, Lossless=2, Sharpness=XXX, TR2=X ) # Good quality, efficient, minor residual combing
    QTGMC( Preset=XXXX, SourceMatch=2, Sharpness=XXX, TR2=X )             # Good quality, slower, no combing
    QTGMC( Preset=XXXX, SourceMatch=3, Lossless=2, Sharpness=XXX, TR2=X ) # Best quality, slowest, very minor residual combing

Intuitively, a deinterlacer should just inject new fields into the source, leaving the original pixels untouched. The temporal blur/resharpen in this script means that doesn't happen - the source pixels are changed in the output. The (optional) source-match steps attempt to fix this and make the result closer to the source. They work by looking at the difference between output and source at different points in the algorithm and correcting for that difference.

Matching to the source will capture more source detail and reduce oversharpening / haloing. Caveat: the default algorithm temporally smooths but with source-matching much less so (by necessity / design). Source-matching may faithfully recreate artefacts in the source (e.g blocking, banding & some noise) so it's better for quality sources. The SourceMatch setting sets the mode: 0=off (standard [Q]TGMC algorithm), 1,2,3 for progressively more accurate but slower processing. Modes 2 & 3 restore almost exact source detail but are sensitive to noise & introduce occasional aliasing (mode 3 is less affected). Mode 1 is a more conservative halfway stage that rarely introduces artefacts.

Since source-matching recovers sharpness, the Sharpness default is reduced to 0.2. Source-matching may initially appear less sharp than standard processing because it will not oversharpen. However, be careful if raising the sharpness, because sharpness limiting is switched off by default. This is because sharpness limiting reduces the the accuracy of these modes. Use the MatchEnhance setting to exaggerate additional detail found by modes 2 & 3. This gives a sharpening / detail enhancing effect and works well at sensible levels - but it's a slight cheat that should be used with care as it can easily enhance noise. Since source-match is sensitive to source noise you may want to set TR2 to 2 or 3 and/or use some noise processing (see below).

The additional Lossless modes are designed to take source-match to its logical conclusion: Lossless mode 1 restores the *exact* pixels of the source into the output (provided NoiseRestore=0). This recovers a liitle more source detail but can introduce shimmering, minor combing, noise etc. Note the Sharpness and MatchEnhance settings have little effect in lossless mode 1. Lossless mode 2 makes the clip lossless before the sharpening & final temporal smooth. This removes most of the lossless artefacts and also allows sharpness control. This mode will not give an exactly lossless output but it will gain a little more detail.

The source-match settings introduce further processing. SourceMatch mode 1 requires a second interpolation (e.g. NNEDI3), but it can use a lower quality settings than the main stage. SourceMatch mode 2 requires yet another interpolation, but works effectively with just a bob (but using a better interpolator can reduce occasional aliasing). Mode 3 adds just a little more processing and is usually worth it as it reduces artefacts. There is no exact control over the interpolations used (too many settings required), instead there are MatchPresets that work in a similar way to the main Preset. The extra processing suggests much slower speeds, but actually using higher speed presets (both MatchPreset and Preset) with source-matching can give results comparable to slower presets without it. Having said that, the extra detail from source-matching is too subtle to significantly affect very high speed main presets.

Settings |  |
SourceMatch | (0,1,2,3) | 0 = Source-matching off (standard algorithm), 1 = basic source-match, 2 = refined match, 3 = twice refined match
SourceMatch=1,2,3 |  |
MatchPreset | (string) | Speed/quality for basic source-match processing, select from "Placebo", "Very Slow", "Slower", "Slow", "Medium", "Fast", "Faster", "Very Fast", "Super Fast", "Ultra Fast" ("Draft" is not supported). Ideal choice is the same as main preset, but can choose a faster setting (but not a slower setting). Default is 3 steps faster than main Preset.
MatchEdi | (string) | Override default interpolation method for basic source-match. Default method is same as main EdiMode setting (usually NNEDI3). Only need to override if using slow method for main interpolation (e.g. EEDI3) and want a faster method for source-match
SourceMatch=2,3 |  |
MatchPreset2 | (string) | Speed/quality for refined source-match processing, select from "Placebo", "Very Slow", "Slower", "Slow", "Medium", "Fast", "Faster", "Very Fast", "Super Fast", "Ultra Fast" ("Draft" is not supported). Default is 2 steps faster than MatchPreset. Faster settings are usually sufficient but can use slower settings if you get extra aliasing in this mode
MatchEdi2 | (string) | Override interpolation method for refined source-match. Can be a good idea to pick MatchEdi2="Bob" for speed
MatchTR2 | (0,1,2) | Temporal radius for refined source-matching. 2=smoothness, 1=speed/sharper, 0=not recommended. Differences are very marginal. Basic source-match doesn't need this setting as its temporal radius must match TR1 core setting (i.e. there is no MatchTR1)
MatchEnhance | (0.0...) | Enhance the detail found by source-match modes 2 & 3. A slight cheat - will enhance noise if set too strong. Best set < 1.0
Optional Extras |  |
Lossless | (0,1,2) | Puts exact source fields into result & cleans any artefacts. 0=off, 1=after final temporal smooth, 2=before resharpening. Adds some extra detail but: mode 1 gets shimmer / minor combing, mode 2 is more stable/tweakable but not exactly lossless
Defaults: SourceMatch=0, MatchPreset=[3 settings quicker than main Preset], MatchPreset2=[2 settings quicker than MatchPreset] MatchEdi = same as EdiMode, except if MatchPreset="Ultra Fast" when it is "Yadif" MatchEdi2 = "NNEDI3", except if MatchPreset="Super Fast" when it is "TDeint", or if MatchPreset="Ultra Fast" when it is "Bob"
MatchTR2=1, MatchEnhance=0.5, Lossless=0

Examples

    QTGMC( Preset="Slow", SourceMatch=1 )                # Enable basic source-match. Result somewhat closer to source.
    QTGMC( Preset="Slow", SourceMatch=1, Sharpness=0.4 ) # Basic source-match but sharper (up from 0.2). Be careful as sharpness limiting defaults to off
    QTGMC( Preset="Slow", SourceMatch=1, Lossless=2 )    # Basic source-match with "fake" lossless. Efficient setting for quality, may bring minor combing

    QTGMC( Preset="Medium", SourceMatch=2, TR2=2 )       # Refined source-match, closer to source with no combing, slower. Increased TR2 reduces noise

    QTGMC( Preset="Slower", SourceMatch=3 )              # Twice refined source-match, higher quality than mode 2, but a little bit slower again
    QTGMC( Preset="Slower", SourceMatch=3, Lossless=2 )  # Twice refined source-match with fake lossless. Almost perfect fidelity mode with few artefacts
    QTGMC( Preset="Slower", SourceMatch=3, Lossless=1 )  # Twice refined source-match with true lossless. Exact detail, but likely combing and shimmer

    QTGMC( Preset="Slow", SourceMatch=3, Lossless=2, MatchEnhance=0.75 ) # Further enhance detail found by refined match, a little sharper, may be noisier
    QTGMC( Preset="Slow", SourceMatch=3, Lossless=2, MatchEnhance=0.75, NoiseProcess=1, NoiseRestore=0.7, Sigma=1.5 ) # As above, denoise a little to help

    QTGMC( Preset="Slower", MatchPreset="Very Fast", SourceMatch=1 ) # Faster basic source-match preset (defaults to 3 steps faster than main Preset)
    QTGMC( Preset="Slower", MatchPreset="Faster", MatchPreset2="Ultra Fast", SourceMatch=3 ) # Faster refined source-match preset as well
                                                                                             # (defaults to 2 steps faster than basic match Preset)
    QTGMC( Preset="Slower", MatchPreset="Slow", MatchPreset2="Slow", SourceMatch=3 ) # Or use slower source-match presets (usually unnecessary)

### Noise Bypass / Denoising

Key Points: QTGMC can remove, retain or strengthen noise and very fine detail. Has automatic "EZ" settings for simple operation. Refer to examples below

The use of multiple temporal smooths means that this script denoises by default. QTGMC can extract some noise/grain from the source at the start, then optionally restore some of it back in again at the end. This allows either denoising, or for the grain/noise from the source to be retained. For simplest operation use one of the two automatic "EZ" modes, EZDenoise or EZKeepGrain (can only use one at once) and select a NoisePreset. For manual operation there are two modes: NoiseProcess=1 actually denoises at the start, whereas NoiseProcess=2 just identifies the noise in the source without removing it. NoiseProcess=1 is typically used for stronger denoising of the output, and NoiseProcess=2 is used to retain grain or for a very light denoise.

Manual operation: after selecting a mode, set a Sigma value to estimate the level of source noise. Use the ShowNoise setting to help in this choice. Then decide how much of that noise to restore after the deinterlace. There are two restore points called GrainRestore/NoiseRestore, the amount of noise restored depends on their sum. For full denoising set them both to 0. For grain retention, a good starting point is 0.7/0.3 for NoiseProcess=1, and 0.3/0.1 for NoiseProcess=2. GrainRestore restores more stable "grain-like" detail. NoiseRestore restores finer more fluctuating noise. Usually best if GrainRestore is greater than NoiseRestore unless you want a very noisy look. Too high restoral values will give grain exaggeration and even luma changes.

Important: You must use a non-zero value in one of EZDenoise, EZKeepGrain or NoiseProcess or no noise processing will occur

Quick Settings |  |
EZDenoise | (0.0...) | Automatic setting to denoise source. Set > 0.0 to enable. Higher values denoise more. Can use ShowNoise to help choose value
EZKeepGrain | (0.0...) | Automatic setting to retain source grain/detail. Set > 0.0 to enable. Higher values retain more grain. A good starting point = 1.0
NoisePreset | (string) | Automatic setting for quality of noise processing. Choices: "Slower", "Slow", "Medium", "Fast", and "Faster", Default is "Fast"
Full Settings |  |
NoiseProcess | (0,1,2) | Bypass mode: 0 = disable, 1 = denoise source & optionally restore some noise back at end of script [use for stronger denoising], 2 = identify noise only & optionally restore some after QTGMC smoothing [for grain retention / light denoising]
ChromaNoise | (bool) | When processing noise (NoiseProcess > 0), whether to process chroma noise or not (luma noise is always processed)
Removing Noise |  |
Denoiser | (string) | Select denoiser to use for noise bypass / denoising. Select from "dfttest" or "fft3dfilter". dfttest is better, but slower. Unknown value selects "fft3dfilter"
DftThreads | (0...) | Number of threads to use if using "dfttest" for Denoiser, 0 = number of logical processors on system. Default = EdiThreads
DenoiseMC | (bool) | Whether to provide a motion-compensated clip to the denoiser for better noise vs detail detection (will be a little slower)
NoiseTR | (0,1,2) | Temporal radius used when analyzing clip for noise extraction. Higher values better identify noise vs detail but are slower
Sigma | (0.0...) | Amount of noise known to be in the source, sensible values vary by source and denoiser, so experiment. Use ShowNoise to help
ShowNoise | (bool / 0.0...) | Display extracted and "deinterlaced" noise rather than normal output. Set to true or false, or set a value (around 4 to 16) to specify contrast for displayed noise. Visualising noise helps to determine suitable value for Sigma or EZDenoise - want to see noise and noisy detail, but not too much clean structure or edges - fairly subjective. Pause the video when checking this
Restoring Noise |  |
GrainRestore | (0.0...1.0...) | How much removed noise/grain to restore before final temporal smooth. Retain "stable" grain and some detail (effect depends on TR2)
NoiseRestore | (0.0...1.0...) | How much removed noise/grain to restore after final temporal smooth. Retains any kind of noise
NoiseDeint | (string) | When noise is taken from interlaced source, how to 'deinterlace' it before restoring. "Bob" & "DoubleWeave" are fast but with minor issues: "Bob" is coarse and "Doubleweave" lags by one frame. "Generate" is a high quality mode that generates fresh noise lines, but it is slower. Unknown value selects "DoubleWeave"
StabilizeNoise | (bool) | Use motion compensation to limit shimmering and strengthen detail within the restored noise. Recommended for "Generate" mode
For most presets the defaults are: NoiseProcess=0, Sigma=2.0, NoiseRestore/GrainRestore=0.0, ChromaNoise=false, DftThreads=EdiThreads, ShowNoise=false In "Placebo", "Very Slow" some defaults change: NoiseProcess=2, GrainRestore=0.3, NoiseRestore=0.1 EZDenoise and EZKeepGrain set automatic values for NoiseProcess, NoiseRestore/GrainRestore and Sigma
Denoiser, DenoiseMC, NoiseTR, NoiseDeint and StabilizeNoise settings are determined by NoisePreset
If using manual settings be sure to override *all* the values you are interested in

Examples

    # Automatic Settings
    QTGMC( Preset="Slower", EZDenoise=2.5,   NoisePreset="Slow"   ) # Automatic denoising, value is denoising strength, preset is quality/speed tradeoff
    QTGMC( Preset="Slower", EZKeepGrain=1.0, NoisePreset="Faster" ) # Automatic grain retention - retain all source grain

    # Denoising
    QTGMC( Preset="Slower", NoiseProcess=1, NoiseRestore=0.0, Sigma=4.0 ) # Fully denoise, strength of denoising depends on Sigma setting
    QTGMC( Preset="Slower", NoiseProcess=1, NoiseRestore=0.0, Denoiser="dfttest", DenoiseMC=true, NoiseTR=2, Sigma=4.0 ) # More "accurate" denoising (slower)

    # Retain Noise / Grain
    QTGMC( Preset="Slower", NoiseProcess=1, NoiseRestore=1.0, Sigma=2.0 ) # Retain *all* the noise / fine detail of a less noisy source
    QTGMC( Preset="Slower", NoiseProcess=1, GrainRestore=1.0, Sigma=2.0 ) # Similar to above but only keep the more "stable" noise elements (depends on TR2)

    # Strong Detail / Grain
    QTGMC( Preset="Slower", NoiseProcess=2, GrainRestore=0.5, NoiseRestore=0.1, Sigma=2.5 ) # Using stronger mode 2, retains noise and sharpens slightly
    QTGMC( Preset="Slower", NoiseProcess=2, GrainRestore=0.4, NoiseRestore=0.2, Sigma=1.8, \
           NoiseDeint="Generate", StabilizeNoise=true )  # As above with better quality, more stable detail and grain

### Progressive Input

Key Points: Can remove horizontal shimmering effects from progressive sources. Experiment with InputType=1, 2 or 3 for best results. FPS will not be doubled

This script is designed for deinterlacing and so by default expects an interlaced clip. However, much of its operation concerns the reduction of horizontal shimmering. It is possible to use the script to remove similar shimmer from a progressive clip by using the InputType setting. InputType=1 is used for general progressive material that contains less severe problems. InputType=2,3 are designed for badly deinterlaced material with considerable horizontal artefacts. These modes drop half the fields and recreate an interlaced stream from the others, which is then treated in the normal way. Mode 3 differs from mode 2 only in that it complements field parity of the input. Generally mode 1 will retain more detail, but repair less artefacts than modes 2,3. You may consider setting TR2 to a higher value (e.g. 2 or 3) when repairing progressive material.

SourceMatch and Lossless modes are supported for progressive material. It works well for InputType=2,3, where the input is converted to an interlaced stream, and helps in detail retention. Source-match is much less useful for InputType=1

Settings |  |
InputType | (0,1,2,3) | Default = 0 for interlaced input. Settings 1,2 & 3 accept progressive input for deshimmer or repair. Frame rate of progressive source is not doubled. Mode 1 is for general progressive material. Modes 2 & 3 are designed for badly deinterlaced material
ProgSADMask | (0.0...) | Only applies to InputType=2,3. If ProgSADMask > 0.0 then blend InputType modes 1 and 2/3 based on block motion SAD. Higher values help recover more detail, but repair less artefacts. Reasonable range about 2.0 to 20.0, or 0.0 for no blending
Defaults: InputType=0, ProgSADMask = 10.0 (slower presets) or 0.0 (faster presets)

Examples

    QTGMC( Preset="Slower", InputType=1 )                   # Process progressive source, it will be temporally smoothed / deshimmered
    QTGMC( Preset="Slower", InputType=2, ProgSADMask=12.0 ) # Process progressive source with major artefacts, slightly favoring detail over repairs

### Shutter Speed Motion Blur / Frame Rate

Key Points: Can output video at single or double-frame rate. For smoother playback of single-rate output there are settings to add light motion blur to simulate different shutter angles (shutter speeds)

By default QTGMC outputs video at "double-rate", twice the frame rate of the source. This is because there are two separate images (fields) in every frame, which the deinterlacing process restores in full. By setting FPSDivisor to 2, every second frame is dropped and the output frame rate is the same as the source ("single-rate")

Single-rate output may look a little stuttery, depending on how the source was filmed/created. Adding motion blur to each frame can help with this, smoothing the feel of the slower rate playback. This is done by setting ShutterBlur to 1,2 or 3, then specifying the shutter angle that you wish the output to simulate. However, as there may be some motion blur already in the source you also need to specify/estimate the shutter angle used in the source. Shutter angles range from 0 to 360, with 0 being perfectly sharp and 360 being fully blurred from one frame to next (artificial output shutter angles > 360 are supported to a very limited degree). Motion-blur can also be applied to double-rate output, but the effect is less noticable.

As motion analysis is block-based, motion blur of an object can "bleed" into surrounding, more static areas. This can be reduced using the slower ShutterBlur modes or by increasing the SBlurLimit setting (which is enabled and set to 4 by default). Both repair methods may reduce the level of motion blur a little though. In situations of complex motion the motion analysis can be incorrect, which can lead to inappropriate blurring.

Settings |  |
FPSDivisor | (1,2...) | 1 = Double-rate output, 2 = Single-rate output. Higher values can be used too (e.g. 60fps & FPSDivisor=3 gives 20fps output). Important: You do not need `SelectEven()` in the calling script if you use FPSDivisor=2
ShutterBlur | (0,1,2,3) | 0 = Off, 1 = Enable, 2,3 = Higher precisions (slower). Higher precisions reduce blur "bleeding" into static areas a little
ShutterAngleSrc | (0...360) | Shutter angle used in source. If necessary, estimate from motion blur seen in a single frame: 0=pin-sharp, 360=fully blurred from frame to frame
ShutterAngleOut | (0...360) | Shutter angle to simulate in output. Extreme values may be rejected (depends on other settings). Cannot reduce motion blur already in the source
SBlurLimit | (0...) | Limit motion blur where motion lower than given value. Increase to reduce blur "bleeding". 0=Off. Sensible range around 2-12
Defaults: FPSDivisor=1, ShutterBlur=0, ShutterAngleSrc=180, ShutterAngleOut=180, SBlurLimit=4

Examples

    QTGMC( Preset="Slower", FPSDivisor=2, ShutterBlur=1, ShutterAngleSrc=30,  ShutterAngleOut=180 ) # Smooth single-rate output, when input has little blur
    QTGMC( Preset="Slower", FPSDivisor=2, ShutterBlur=1, ShutterAngleSrc=180, ShutterAngleOut=180 ) # Keep "film" look on single-rate output, "film" input
    QTGMC( Preset="Slower", FPSDivisor=2, ShutterBlur=2, ShutterAngleSrc=180, ShutterAngleOut=180, SBlurLimit=8 ) # Same but srongly reduce blur "bleeding"
    QTGMC( Preset="Slower", FPSDivisor=1, ShutterBlur=1, ShutterAngleSrc=0,   ShutterAngleOut=720 ) # Blur some high shutter-speed footage, keep double rate
                                                                                                    # [Use of artificially high shutter angles is limited]

### Miscellaneous Settings

Settings not covered above. Note that Border is false by default, which differs from TempGaussMC

Settings |  |
Border | (bool) | Pad a little vertically while processing (doesn't affect output size) - set true you see flickering on the very top or bottom line of the output. If you have wider edge effects than that, you should crop afterwards instead. Be wary of this setting if reusing QTGMC motion vectors in the calling script.
Precise | (bool) | Set to false to use faster algorithms with *very* slight imprecision in places
Preset | (string) | Sets a range of defaults for different encoding speeds. Select from "Placebo", "Very Slow", "Slower", "Slow", "Medium", "Fast", "Faster", "Very Fast", "Super Fast", "Ultra Fast" & "Draft"
Tuning | (string) | Tweaks the defaults for different source types. Choose from "None", "DV-SD", "DV-HD". Default is "None". [An idea for development based on the x264 approach, but as I don't work with many source types it has seen little development]
ShowSettings | (bool) | Display all the current parameter values - useful to find preset defaults
GlobalNames | (string) | The name used to expose intermediate clips to calling script. See External Linkage section. Defaults to "QTGMC".
PrevGlobals | (string) | What to do with global variables from earlier QTGMC call that match above name. Either "Replace", or "Reuse" (for a speed-up)
ForceTR | (0,1,2,3) | Ensure globally exposed motion vectors are calculated to this radius even if not needed by QTGMC. 0 = disabled (default)
Defaults: Border=false, Preset="Slower", Tuning="None", ShowSettings=false, GlobalNames="QTGMC", PrevGlobals=undefined, ForceTR=0. Default for Precise depends on Preset

## External Linkage

### Accessing QTGMC Motion Vectors

QTGMC now exposes its motion vectors and other intermediate clips to the calling script through global variables. These globals are uniquely named. By default they begin with the prefix "QTGMC_". The available clips are:
Backward motion vectors | bVec1, bVec2, bVec3 (temporal radius 1 to 3)
Forward motion vectors | fVec1, fVec2, fVec3
Filtered clip used for motion analysis | srchClip
MVTools "super" clip for filtered clip | srchSuper
Not all these clips are necessarily created - it depends on your QTGMC settings. To ensure motion vector creation to radius X, set ForceTR=X

An example:

    QTGMC( Preset="Medium", ForceTR=2, SubPel=2 )  # Ensure we get temporal radius of at least 2, read note below regarding SubPel
    super = MSuper( pel=2, levels=1 )              # Faster to use levels=1, don't usually need more levels once you have the vectors
    MDegrain2( super, QTGMC_bVec1,QTGMC_fVec1, QTGMC_bVec2,QTGMC_fVec2 )  # Use QTGMC-created motion vectors

#### Important Notes

- The SubPel setting to QTGMC must match the pel setting in MVTools or you will get visual errors or crashes. Default SubPel in QTGMC varies depending on Preset, "Medium" and quicker settings get SubPel=1, slower settings get SubPel=2. Default pel in MVTools is 2
- Do not use Border=true if using motion vectors in this way, or the clips exposed will have an 8 pixel border top and bottom (i.e. they won't match your source)

### Multiple QTGMC Calls

The section above showed how global variables are used to expose the workings of QTGMC. However, if there are multiple calls to QTGMC in your script then you should consider whether they should work together with their exposed globals. By default the globals for each call to QTGMC will overwrite the globals from previous calls. However there are actually three options in this case:

- Use the setting GlobalNames to make unique global names for each call. E.g. if you set `GlobalNames="TestA"` you will receive a global called TestA_bVec1.
- Set PrevGlobals="Reuse" to reuse existing similar named globals for this run & not recalculate motion vectors etc. This will improve performance.
- Set PrevGlobals="Replace" to overwrite similar named globals from a previous run. This is the default and easiest option for most use cases.

Here's an artifical example of multiple calls in a script to show the options:

    q1 = c.QTGMC( Preset="Medium" )  # QTGMC_bVec1 and similar variables are created
    q2 = c.QTGMC( Preset="Medium" )  # Recalculates and replaces variables QTGMC_bVec1 and similar with new values (same as setting PrevGlobals="Replace")
    q3 = c.QTGMC( Preset="Medium", PrevGlobals="Reuse"   )  # Reuses QTGMC_bVec1 motion vectors from q2 above. Doesn't recalculate, improving performance
    q4 = c.QTGMC( Preset="Medium", GlobalNames="TestA"   )  # Creates new variables called TestA_bVec1...
    q5 = c.QTGMC( Preset="Medium", GlobalNames="TestA", PrevGlobals="Reuse" ) # Reuses the TestA_bVec1 motion vectors

Here's a realistic example. This simple script repairs progressive material with very bad deinterlacing artefacts. It needs two calls to QTGMC:

    t = QTGMC( Preset="Slower", InputType=2 )
    b = QTGMC( Preset="Slower", InputType=3, PrevGlobals="Reuse" ) # Reuse motion vectors from first call for a good speed-up
    Repair( t, b, 1 )

## TempGaussMC Notes

In its default setup this script is very similar in operation to TempGaussMC_beta2. The call QTGMC() is very similar to:

    TempGaussMC_beta2( 2,2,1, Border=false, SVthin=0.0 )

There are a few key differences:

- QTGMC typically uses "NNEDI3" for interpolation (TempGaussMC_beta2 uses "EEDI2" by default)
- Sharpness default in QTGMC is always 1.0 (or 0.2 if using source-match) - adjusted internally to give very roughly the same sharpness across settings / presets
- In QTGMC, SVThin defaults to 0, Border defaults to false
- Lossless and Draft modes are supported but in a different way
- The parameter order is the same up to EdiMode, a couple of 'lesser' parameters have had name changes for consistency

## Acknowledgements

Thanks go to Didée for the script from where this began.
Also thanks to the plugin coders: Manao, Fizick, Tritical, Kassandro, Tsp, SEt, Tom Barry, Foxyshadis, TSchniede, Kurosu, mg262 and any others...
And to the many people who have given feedback, reported bugs and offered suggestions to help improve the script

## Version History

v3.32
Bugfix with shutter blur and ChromaMotion
Tweaked vector recalculation for shutter motion blur
Changed defaults for TR2 when using source-match
Minor bugfix with SLMode/SLRad on pass-through settings
v3.31
Small bug-fix with new ChromaMotion setting
v3.30
Added ChromaMotion setting - can ignore chroma when analyzing motion (a speed-up with few ill-effects)
Added ChromaEdi setting - allow faster interpolation for chroma than luma (mainly useful for EEDI2/3)
New fast pre-filter (SrchClipPP) mode 1, previous modes 1 & 2 are now modes 2 & 3. Presets all updated with new modes
EdiMode "TDIYadif" changed to "RepYadif" = Yadif+Repair giving less artefacts & more speed. Is default mode for "Ultra Fast"
Preset is now the first setting, allowing a simpler form: QTGMC("Slow"). Old TGMC style will no longer work
Workaround for padding bug in MVTools that crashed faster modes. Removes need for SafeMode setting, which has been removed
v3.25
Added YUY2 support
NoiseBypass renamed to NoiseProcess
PrevGlobals now defaults to "Replace" for simplicity
Tweaked "Very Fast" preset for quality and consistency with other preset speeds
v3.20
Motion vectors made available to calling script (see External Linkage section in documentation), added related GlobalNames, PrevGlobals & ForceTR settings
Added simplified noise processing settings: EZDenoise, EZKeepGrain and NoisePreset
Support for dfttest as denoiser for noise processing - added settings Denoiser and DftThreads
Added ChromaNoise setting to optionally enable chroma noise processing
Added DenoiseMC setting to use motion-compensated clip for denoising, improves detection of noise vs detail
Replaced fft3dfilter-specific BT setting with NoiseTR setting to set temporal radius for denoiser.
Added StabilizeNoise setting to "stabilize" & "deshimmer" noise restored in noise bypass (was part of "Generate" mode)
Dropped NoiseRemove setting, now always removes all noise specified by given Sigma (enough controls already!)
MotionBlur renamed to ShutterBlur, MBlurLimit renamed to SBlurLimit, DetailRestore renamed to GrainRestore (old names gave wrong impression)
Bug fixes: stabilization of "Generate" noise mode, manually enabling SLMode with SourceMatch
Documentation converted to HTML
v3.11
Exposed ThSAD1, ThSAD2, ThSCD1 and ThSCD2 to allow tweaks to temporal smoothing and scene change detection
Fixed bug introduced in v3.05, which skipped part of core algorithm(!)
v3.10
Explicit conditions to ensure unused filters are not constructed to reduce memory use
FPSDivisor works even if not using motion blur
v3.05
Motion blur support, added settings FPSDivisor, MotionBlur, ShutterAngleSrc, ShutterAngleOut, SBlurLimit
Bug fixes: Some Sbb modes with source match, MatchEdi setting (again)
v3.01
Support for lossless modes on InputType=2,3 - improves detail retention
Enabling ShowNoise automatically switches on NoiseBypass
Bug fixes: "Draft" mode, noise extraction with InputType=1, MatchEdi setting
v3.0
Introduced source-match modes and settings for higher fidelity output - supported for interlaced and progressive input
Most lossless settings removed - superseded by source-match, only Lossless integer remains
Added ProgSADMask setting for progressive repair modes (InputType=2,3) to help recover stable detail
Added RepChroma setting to allow disabling of chroma processing in repair stages (rep0,1,2)
Added DetailRestore setting for NoiseBypass - allowing denoising with some fine detail retention
Noise bypass with NoiseDeint="Generate" is now motion-compensated for better grain/detail restoral, NoiseDeint="Copy" removed
Corrected minor luma shift when using NoiseBypass (FFT3DFilter noise center is 128.5 not 128)
Added ShowNoise setting to display extracted noise, helps in determining Sigma
TDeint added as interpolator (suitable for source-match)
YadifPath no longer global
EdiMode for "Ultra Fast" changed from "TDIYadif" to "Yadif" (otherwise slower than "Super Fast" for non-threaded)
Bug fixes in Sbb and InputType=3
Complete rewrite of documentation and some script tidying
v2.51
Changed default interpolator to "NNEDI3" for presets up to "Super Fast" and (new) lossless presets up to "Faster"
Range of preset tweaks including higher quality output from "Super Fast" & "Ultra Fast" but with a little speed loss
Support for EdiMode="EEDI3+NNEDI3": EEDI3 with sclip taken from NNEDI3
Added LosslessPreset and EdiThreads parameters
Tidied up output from ShowSettings and small bug fix
Fixed serious bug when using lossless modes on the higher speed presets
v2.47
Fixed bug with default overlap when an explicit blocksize was given
v2.46
Replaced mt_average with merge - was causing exceptions in certain MT situations
v2.45
Tweaked use of Yadif: explicit loading is now optional, see YadifPath variable
v2.41
Removed explicit Yadif plugin load
v2.40
Support for lossless output with added parameters: Lossless, LosslessTR, LosslessEdi
Support for EdiMode("NNEDI3", "EEDI3")
Paramters NNeurons added & NNSize reworked for new -EDI3 versions
Minor preset tweaks for better quality/speed spread
v2.30
Added EdiExt (edeint in original TGMC)
Improved progressive input modes
v2.20
All rep values, SVThin and motion search settings supported
Better matching of Sbb
"Draft" preset. Default preset changed from "Slow" to "Slower"
Support for progressive input (InputType)
Sharpness values/defaults normalized
v2.10
Supported most of the remaining core TGMC features: EdiMode("NNEDI", "Yadif"), TR2(3), SLmode(3,4), SLRad, Sbb(2,3)
Added noise bypass (removal / restoration)
Added ShowSettings
v2.00
First fully featured version
Supported majority of core TGMC features
Additional speed tweaks: NNSize, SrchClipPP, SubPel, Precise
Added Presets system and beginnings of Tunings
v1.00
First draft - high speed basic TGMC algorithm only