# Decomb Plugin for Avisynth
(Version 5.1.0)
Tutorial

## by Donald A. Graft

## Table of Contents

- Introduction
- Telecide()

- Step 1. Determine and Set the Field Order
- Step 2. Set up Pattern Guidance If Appropriate
- Step 3. Set up Postprocessing

- Decimate()

- Step 4. Setting Up Decimation

- Refinements

## Introduction

This document is a tutorial for Decomb. It provides a cookbook procedure for applying Telecide() and Decimate() correctly to process a given clip. It doesn't cover FieldDeinterlace() as that is fairly easy to figure out from the Decomb Reference Manual.

Please refer to the accompanying Decomb Reference Manual for a detailed description of Decomb and it parameters.

## Telecide()

Telecide() recovers progressive frames (by finding and aligning matching fields). Do not use Telecide() on streams that do not contain telecined progressive frames, such as pure interlaced video.

### Step 1. Determine and Set the Field Order

It is essential to set the field order properly for correct rendering. The field order is set using the mandatory parameter order. Set order=1 for top field first; set order=0 for bottom field first. Because setting it correctly is so important, you are strongly encouraged not to make assumptions about the field order of a clip, but rather to verify the field order using the following procedure.

To determine the field order, make an Avisynth script that serves the raw clip without any processing. If it were an AVI, then just AviSource() would be used. For our examples, we'll use AviSource(). Add a script line to separate the fields using top field first, as follows:

    AviSource("your_clip.avi")
    AssumeTFF().SeparateFields()

Now serve the script into VirtualDub and find an area with motion. Single step forward through the motion. Note whether the motion progresses always forward as it should, or whether it jumps back and forth as it proceeds. For example, if the field order is wrong, an object moving steadily from left to right would move right, then jump back left a little, then move right again, etc. If the field order is correct, it moves steadily to the right.

If the motion is correct with AssumeTFF().SeparateFields(), then your field order is top field first and you must set order=1. If the motion is incorrect, then your field order is bottom field first and you must set order=0. If you are want to double check things, you can use AssumeBFF.SeparateFields() to check correct operation for bottom field first.

Let's assume we have a top field first clip in the following steps. You would of course use the correct field order for your clip. So far, then, our script is as follows:

    AviSource("your_clip.avi")
    Telecide(order=1)

### Step 2. Set up Pattern Guidance If Appropriate

Often you know from the nature of a clip what telecining pattern (if any) is used and therefore what the pattern of field matches should be. Telecide()'s pattern guidance feature uses that information to improve the field matching. Pattern guidance is controlled by the optional guide parameter. It has 4 possible values: guide=0 means disable pattern guidance; guide=1 means use 3:2 pulldown guidance (24fps->30fps); guide=2 means use 2:2 guidance (PAL); and guide=3 means use 3:2:3:2:2 guidance (25fps->30fps).

First decide if your source clip is PAL. If it is, and if it has progressive content, you can almost invariably set guide=2 to use PAL pattern guidance. Of course, if your clip does not have progressive content, it will not help you, and you shouldn't be using Telecide() at all! So for PAL, we can skip to Step 3 with our script looking this so far:

    AviSource("your_clip.avi")
    Telecide(order=1,guide=2)

If we have an NTSC 29.97fps or 30fps source clip, things are trickier. First we have to determine whether the clip contains 3:2 pulldown material. There are several tests we can apply. First, serve the clip raw (no Decomb or other processing) into VirtualDub. Then step through the frames in motion areas. If you see a repeating pattern of 3 clean frames followed by 2 interlaced frames, that is 3:2 pulldown. Typically, movies will use 3:2 pulldown.

Looking for the 3:2 pattern as described above is not foolproof, because for animations there are duplicate frames that can make it hard to see a clear 3:2 pattern.

Second, you can serve the following script into VirtualDub and see what Telecide() reports about it (remember to use the correct field order as you determined it above).

    AviSource("your_clip.avi")
    Telecide(order=1,guide=1,post=0,show=true)

Serve this into VirtualDub and step through several typical sections of your clip. If Telecide() reports "in-pattern", or "in-pattern*", then it is locking onto 3:2 pulldown. If it reports "out-of-pattern" or continuously jumps in and out of pattern lock, then it is not locking onto a consistent 3:2 pattern.

If you determine that your clip has a lot of 3:2 content, then you should go ahead and set guide=1. If there is not a lot of 3:2 content, or you have any doubts about the nature of the clip, then you should set guide=0. We will assume that we have a lot of 3:2 content for the next steps. Therefore, our script so far looks like this:

    AviSource("your_clip.avi")
    Telecide(order=1,guide=1)

### Step 3. Set up Postprocessing

Postprocessing is the process by which frames that come out of the field matching process still combed can be detected and deinterlaced. The postprocessing modes are controlled by the post parameter: post=0 means disable postprocessing; post=1 means calculate the metrics but don't deinterlace; post=2 means calculate the metrics and deinterlace accordingly; and post=3 means calculate the metrics, deinterlace accordingly, and show a deinterlacing motion map for frames that are detected as combed. There are two more advanced modes as well; please refer to the reference manual for details.

We will adopt a standard procedure for setting up postprocessing. First, we will enable the metrics and show them as follows (note we are carrying forward previously determined settings -- you would use the ones you earlier determined for order and guide):

    AviSource("your_clip.avi")
    Telecide(order=1,guide=1,post=3,vthresh=25,show=true)

Serve this into VirtualDub and play through the clip while examining frames and the displayed vmetric values. The value that applies to the frame as matched is the one in brackets that starts with "chosen=", e.g., "[chosen=27]". Let's just call that the vmetric value. Any vmetric value greater than vthresh defines the frame as interlaced. You want to find the vthresh value that correctly distinguishes combed frames from non-combed frames for your clip. You'll easily be able to identify the frames thought to be combed because a) the vmetric value will be greater than vthresh, b) the progressive/interlaced indicator will say interlaced, and c) the frame will have a white deinterlacing motion map overlayed on it. There's no way you'll miss them!

Your chosen vthresh may not be perfect and if it is not you should err on the side of caution. It's better to catch some progressive frames than to miss some combed ones.

Let's suppose that our vthresh value that distinguishes combed from non-combed frames is 30. Now create the following script with post=2 (carry over your determined previous settings, as always):

    AviSource("your_clip.avi")
    Telecide(order=1,guide=1,post=2,vthresh=30,show=true)

Serve this and play it into VirtualDub. As you step through you should see the progressive frames passing through untouched while the combed ones ones are deinterlaced.

If you are not happy with the deinterlacing of the combed frames and want them "hit a little harder", you can reduce the dthresh parameter. Also, if you prefer interpolation to blending for the combed areas, you can change the blend parameter. Refer to the reference manual for the proper use of these parameters.

Our script so far then is:

    AviSource("your_clip.avi")
    Telecide(order=1,guide=1,post=2,vthresh=30)

There are two more important things to say about postprocessing before we move on. First, there is a subtle difference between post=2 and post=4 which might affect you. The reference manual describes the differences in detail. Setting post=2 will often avoid making gross frame blends at scene changes, but it can make deinterlaced video sequences jerky. Setting post=4 retains the smoothness of deinterlaced sequences, but may make frame blends at scene changes.

Second, you may find that you need different vthresh values for different parts of your clip. If so, use Telecide's manual override capability to specify values for different frame ranges as needed. Refer to the reference manual for details.

## Decimate()

As a side effect of performing field matching for 3:2 pulldown, Telecide() emits duplicate frames and leaves the clip at its original frame rate. Decimate() detects and removes these duplicates and sets the frame rate down appropriately.

### Step 4. Set up Decimation

If your clip is PAL, you do not require decimation and you are finished!

If your clip has 3:2 pulldown, you will need to decimate the clip. Simply add a call to Decimate(). Our final script then looks like this:

    AviSource("your_clip.avi")
    Telecide(order=1,guide=1,post=2,vthresh=30)
    Decimate()

One thing to be aware of is that you may not always want to decimate 30fps material. For example, if your clip is a hybrid of 3:2 progressive and normal interlaced video, if you decimate it you'll make the video portions jerky. Often with such clips it is better to leave them at their original frame rate by omitting Decimate().

## Refinements

This manual has described only the basic parameters and procedures required to quickly master Decomb. There are many more parameters that you can use to adapt to unusual and difficult situations. Please refer to the Decomb Reference manual to begin exploring this additional functionality.

Here is one example of a refinement so you'll understand what I am talking about: Suppose you have a noisy off-air capture and you are experiencing matching failures. You can add some extra noise tolerance to Telecide() by increasing the value of the nt parameter. You will find many such little gems in the Reference Manual. It makes great bathtub reading.

Copyright © 2003, Donald A. Graft, All Rights Reserved.

For updates and other filters/tools, visit my web site:
http://shelob.mordor.net/dgraft/