Levels

Levels(clip input, int input_low, float gamma, int input_high, int output_low, int output_high [, bool coring] [, bool dither])

The Levels filter adjusts brightness, contrast, and gamma. This is done using the following transfer function is:

output = ((input-input_low)/(input_high-input_low))^(1/gamma)*(output_high-output_low) + output_low

The input_low and input_high parameters determine what input pixel values are treated as pure black and pure white. The output_low and output_high parameters determine what output values are treated as pure black and pure white. The gamma parameter controls the degree of non-linearity in the conversion.

This is one of those filters for which it would really be nice to have a GUI. Since we can't offer a GUI (though AvsP does), we at least make this filter compatible with VirtualDub's when the clip is RGB. In that case you should be able to take the numbers from VirtualDub's Levels dialog and pass them as parameters to the Levels filter and get the same results. Unlike VirtualDub's Levels filter however, the input and output parameters can be larger than 255.

When processing data in YUV mode, Levels only gamma-corrects the luma information, not the chroma. Gamma correction is really an RGB concept, and is only approximated here in YUV. If gamma = 1.0, the filter should have the same effect in RGB and YUV modes. For adjusting brightness or contrast it may be better (depending on the effect you are looking for) to use Tweak or ColorYUV, because Levels changes the chroma of the clip.

input_low

higher input_low darkens the output; smaller input values are clipped, that is, rounded up to input_low.

gamma

gamma can be used to undo and redo gamma (see examples).

input_high

lower input_high brightens the output; higher input values are clipped, that is, rounded down to input_high.

output_low

dark values brighten to gray as output_low becomes larger.

output_high

light values darken to gray as output_high becomes smaller.

coring

when true (the default), input luma is clamped to [16,235] and the chroma to [16,240]; this clamped input is scaled from [16,235] to [0,255], the conversion takes place according to the transfer function above, and then output is scaled back from [0,255] to [16,235]. When false, the conversion takes place according to the transfer function, without any scaling.

Coring was created for VirtualDub compatibility, and it it remains true by default for compatibility with scripts written for AviSynth prior to version 2.53. In the opinion of some, you should always use coring=false. if you are working directly with luma values (whether or not your input is [16,235]).

dither

when true, ordered dithering is applied to combat banding. Default is false.

Examples:

# does nothing on a [16,235] clip, but it clamps (or rounds) a [0,255] clip to [16,235]:
Levels(0, 1, 255, 0, 255)

# the input is scaled from [16,235] to [0,255], the conversion [0,255]->[16,235] takes place (accordingly to the formula),
# and the output is scaled back from [0,255] to [16,235]: (for example: the luma values in [0,16] are all converted to 30)
Levels(0, 1, 255, 16, 235)

# gamma-correct image for display in a brighter environment:
# example: luma of 16 stays 16, 59 is converted to 79, etc.
Levels(0, 1.3, 255, 0, 255)

# invert the image (make a photo-negative):
# example: luma of 16 is converted to 235
Levels(0, 1, 255, 255, 0)

# does nothing on a [0,255] clip; does nothing on a [16,235]:
Levels(0, 1, 255, 0, 255, coring=false)

# scales a [0,255] clip to [16,235]
Levels(0, 1, 255, 16, 235, coring=false)  # note both luma and chroma components are scaled by the same amount,
                                          # so it's not exactly the same as ColorYUV(levels="PC->TV")

# scales a [16,235] clip to [0,255]:
Levels(16, 1, 235, 0, 255, coring=false)  # note both luma and chroma components are scaled by the same amount,
                                          # so it's not exactly the same as ColorYUV(levels="TV->PC")

# makes a clip 100% black
Levels(0, 1.0, 255, 0, 0)

# apply fading on gamma corrected source (same holds for resizing and smoothing else well)
clip = ... 
gamma = 2.2
clip.Levels(0, gamma, 255, 0, 255) # undo gamma (also called gamma correction)
FadeOut(n)
Levels(0, 1.0/gamma, 255, 0, 255) # redo gamma

Changes

v2.53	added coring (true by default, which reflects the behaviour in older versions)
v2.60	added dither