TimeLapseDF filter for Avisynth 2.5

Version 1.0

The most recent version of this document is available at http://www.zhitenev.com/avisynth/TimeLapseDF/

General information

The TimeLapseDF filter is designed to remove luminosity flicker occurred in Time Lapse photography. This filter is designed to work only within one scene. It does not detect the scene changes. If your video contains more than one scene, each scene must be processed separately.

At the moment the filter supports YUY2 & YV12 formats only.

Syntax

TimeLapseDF(clip clip [, string mode] [, string area] [, string base] [, bool gradient] [, int lmin] [, int lmax] [, float lpf] [, bool info] [, bool showarea])

Parameters

mode="AVG"|"CDF"|"MFR" - Mode defines how luminosity should be metered and compared. Default mode is MFR.

Available values:

Mode	Description
AVG	Average luminosity for full frame (or defined area) is metered and compared. This is a standard way used by most of the filters. The difference between luminosity of the base frame and all other frames will be compensated accordingly.
CDF	Cumulative distribution function[1] is calculated for luminosity values and CDF (Histogram) matching[2] algorithm will be used to compensate luminosity difference. See original paper[3], for detailed explanation.
MFR	This is "two-pass" mode, so some delay will take place before start. In this mode the filter use average luminosity to determine 'anchor' frames and calculate smooth luminosity transition between these frames. It is the default and most recommended mode for all users.

area="%i,%i,%i,%i" - Mode: AVG, CDF. Defines rectangular area (x, y, width, height) for luminosity metering. If undefined (default) full frame is used for metering.

Example:

The scene contains a large area of clear sky from the first frame till the last frame. In this case the best result might be achieved by using "AVG" mode and defining the metering rect inside this area e.g. TimeLapseDF(mode="AVG",gradient=true,area="10,10,500,200")

base="%i[,%i]" - Mode: AVG, CDF. Defines base frame(s) for metering. You can define first and (if gradient compensation is used) last base frames. If undefined (default) clip's first frame and last frame will be used. If negative value is specified as last base frame, the resulting last base frame will be clip's num_frames - specified value.

Example 1:

The original clip contains 100 frames. If gradient=true, base="10" specified, frames 10 and 100 will be used for the gradient compensation calculation.

Example 2:

The original clip contains 100 frames. If gradient=true, base="10,-10" specified, frames 10 and 90 will be used for the gradient compensation calculation.

gradient=true|false - Mode: AVG, CDF. Default: false. This option specifies whether gradient compensation should be used. When enabled, the filter will determine the luminosity difference between first and last base frames and calculate the coefficient of variation. The coefficient of luminosity variation will be used to adjust the base luminosity value while comparing to other frames.

Example 1 (base not specified - use first and last clip's frames as base):

Frame	1	2	3	4	5	6	7	8	9	10	11
Original frame luminosity	100	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	110
Final luminosity (gradient=false)	100	100	100	100	100	100	100	100	100	100	100
Final luminosity (gradient=true)	100	101	102	103	104	105	106	107	108	109	110

Example 2 (base="4,-4" - use frames 4 and 8 as base frames):

Frame	1	2	3	4	5	6	7	8	9	10	11
Original frame luminosity	n/a	n/a	n/a	100	n/a	n/a	n/a	110	n/a	n/a	n/a
Final luminosity (gradient=false)	100	100	100	100	100	100	100	100	100	100	100
Final luminosity (gradient=true)	100	101	102	103	104	105	106	107	108	109	110

lmin=%i - Mode: AVG. Defines minimum luminosity value allowed

lmax=%i - Mode: AVG. Defines maximum luminosity value allowed

lpf=%f - Mode: CDF, MFR. Defines low-pass filter^[4] 'alpha' value for smoothing the luminosity distribution (using exponential moving average) during CDF calculations. This is experimental (and disputable) feature and should not be used. Default: 0 (lpf is disabled). Starting point for experiments is '0.3'.

info=true|false - Enables debug information embedded into clip. Clip must be more then 640 pixels width to accommodate debug info in CDF mode.

showarea=true|false - Show the border around metering area if area is defined.

Demonstrations

Demonstration 1: (Moon and light clouds)

Parameters	Video URL	Comments
Original video clip	MOV (mpeg4, 2.5 MB) MKV (H.264, 2.6 MB)	The situation in this clip might be considered as "easy" at first glance; however the light moving clouds can add some problems.
TimeLapseDF(mode="MFR")	MOV (mpeg4, 2.7 MB) MKV (H.264, 2.6 MB)	The flicker is eliminated almost completely.
TimeLapseDF(mode="AVG",gradient=false)	MOV (mpeg4, 2.7 MB) MKV (H.264, 2.6 MB)	The intensity of original flicker is reduced
TimeLapseDF(mode="AVG",gradient=true)	MOV (mpeg4, 2.6 MB) MKV (H.264, 2.6 MB)	The intensity of original flicker is reduced and the original luminosity shift is preserved
TimeLapseDF(mode="CDF",gradient=false)	MOV (mpeg4, 3.0 MB) MKV (H.264, 2.7 MB)	The original flicker is eliminated completely, but small 'pixelization' is occurred at the end.
TimeLapseDF(mode="CDF",gradient=true)	MOV (mpeg4, 2.7 MB) MKV (H.264, 2.6 MB)	The original flicker is eliminated completely, but tiny 'pixelization' is occurred at the middle of the clip.

Demonstration 2 (Moving clouds):

Parameters	Video URL	Comments
Original video clip	MOV (mpeg4, 4.9 MB) MKV (H.264, 3.3 MB)	This clip is a hard case. In spite of the fact that the scene is constant, the clouds are continuously changes.
TimeLapseDF(mode="MFR")	MOV (mpeg4, 4.9 MB) MKV (H.264, 3.3 MB)	The flicker is eliminated, but hardly noticable and smooth luminosity variation is exist.
TimeLapseDF(mode="AVG",gradient=false)	MOV (mpeg4, 4.9 MB) MKV (H.264, 3.3 MB)	Average luminosity metering is working for this clip, but small flicker still remains.
TimeLapseDF(mode="AVG",gradient=true)	MOV (mpeg4, 4.9 MB) MKV (H.264, 3.3 MB)	With gradient compensation the average luminosity metering is working even better, but some flicker is still there.
TimeLapseDF(mode="CDF",gradient=false)	MOV (mpeg4, 7.4 MB) MKV (H.264, 3.5 MB)	The flicker is virtually disappeared, but heavy color degradation can be visible, especially at the end of the clip.
TimeLapseDF(mode="CDF",gradient=true)	MOV (mpeg4, 6.1 MB) MKV (H.264, 3.2 MB)	The flicker is virtually disappeared, but some degradation of colors can be visible in the middle of the clip.

References