Limiter

The standard known as Rec.601 or CCIR-601 (Studio Encoding Parameters of Digital Television...) defines standard quantization levels: for luminance, black is 16 and peak white is 235. For chrominance, the range is 16 to 240, or 128±112. "The signal may occasionally excurse beyond" this range according to Rec.601.^{BT.601-7 (Annex 1, Table 3)}

Luminance or chrominance values outside this range are known to cause problems with some TV sets, so Limiter was created to clip them (or clamp them - both terms are used) to the ranges [min_luma, max_luma] and [min_chroma, max_chroma], which you may specify, but by default are the Rec.601 values listed above.

Limiter can also colorize out-of-range pixels (with show) to warn of a potential problem. See the example images below. Naturally, this option should not be enabled for final output.

Syntax and Parameters

Limiter(clip clip [, int min_luma, int max_luma, int min_chroma, int max_chroma, string show ] )

clip  clip = (required)

Source clip. YUV only.

int  min_luma = 16

Y (luma) lower clamping limit.

int  max_luma = 235

Y (luma) upper clamping limit.

int  min_chroma = 16

U & V (chroma) lower clamping limit.

int  max_chroma = 240

U & V (chroma) upper clamping limit.

string  show = (empty)

Colorizes the pixels outside the specified [min_X, max_X] range.

If set, show must take one of the following values:

show	Effect
"luma"	colorizes out of bound luma
"luma_grey"	colorizes out of bound luma, and makes the remaining pixels grey
"chroma"	colorizes out of bound chroma
"chroma_grey"	colorizes out of bound chroma, and makes the remaining pixels grey

The colorizing is done as follows:

• YUY2: j,k=1,2 (chroma shared between two horizontal pixels p1 and p2: Y1UY2V)
• YV24: j,k=1 (no chroma shared)
• YV12: j,k=11,12,21,22 (chroma shared between 2x2 pixels Y11UY12V: Y21UY22V)

Pixel Condition	Colorization
	show="luma"	show="luma_grey"
Yj < min_luma	red (pj)	red (pj)
Yj > max_luma	green (pj)	green (pj)
Yj < min_luma and Yk > max_luma	yellow (pj and pk)	puke (pj), olive (pk)
	show="chroma"	show="chroma_grey"
U < min_chroma	yellow	yellow
U > max_chroma	yellow	blue
V < min_chroma	yellow	cyan
V > max_chroma	yellow	red
U < min_chroma and V < min_chroma	yellow	green
U > max_chroma and V < min_chroma	yellow	teal
U < min_chroma and V > max_chroma	yellow	orange
U > max_chroma and V > max_chroma	yellow	magenta

Examples

# 1. Original image FFmpegSource2("sintel.mp4") Trim(4685, 4685) ColorYUV(analyze=true)

# 2. Exaggerated luma and chroma range [...] Levels(16, 1.0, 255-16, 0, 255, coring=false) Tweak(sat=2.0, coring=false) ColorYUV(analyze=true)

# 3. Limiter("luma") [...] Limiter(16, 235, 16, 240, "luma") ColorYUV(analyze=true)

# 4. Limiter("luma_grey") [...] Limiter(16, 235, 16, 240, "luma_grey") ColorYUV(analyze=true)

# 5. Limiter("chroma") [...] Limiter(16, 235, 16, 240, "chroma") ColorYUV(analyze=true)

# 6. Limiter("chroma_grey") [...] Limiter(16, 235, 16, 240, "chroma_grey") ColorYUV(analyze=true)

Changes

v2.60	Added support for YV24.
v2.56	Added show to show out of bound luma/chroma.