Decomb Plugin for Avisynth
(Version 5.1.1)
Tutorial

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)

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)

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)

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.

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()