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. This is the normal luminance range. For chrominance, the range is 16 to 240, or 128±112. "The signal may occasionally excurse beyond" these ranges according to Rec.601.^{BT.601-7 (Annex 1, Table 3)}

Luminance or chrominance values outside their ranges 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.

AVS+ By default all parameters are non-autoscaling – they must be scaled to the target bit depth.
By using parameter paramscale the range parameters are treated to be of 8 bits range and will be scaled to the current bit depth automatically

Syntax and Parameters

Limiter(clip clip [, int min_luma, int max_luma, int min_chroma, int max_chroma, string show ] )
AVS+ Limiter(clip clip [, float min_luma, float max_luma, float min_chroma, float max_chroma, string show, bool paramscale ] )

clip  clip = (required)

Source clip. YUV only.

AVS+ also supports YUVA.

int  min_luma = 16_d

Y (luma) lower bound.

int  max_luma = 235_d

Y (luma) upper bound.

int  min_chroma = 16

U & V (chroma) lower bound.

int  max_chroma = 240_d

U & V (chroma) upper bound.

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		♦ blue
V < min_chroma		♦ cyan
V > max_chroma		♦ red
U < min_chroma and V < min_chroma		♦ green
U > max_chroma and V < min_chroma		♦ teal
U < min_chroma and V > max_chroma		♦ orange
U > max_chroma and V > max_chroma		♦ magenta

AVS+ bool  paramscale = false

If set, minimum/maximum luma/chroma values are treated as they were in 8 bit range (but non-integer values are allowed), limiter will autoscale them to the current bit depth of the clip.

Conversion uses the bit-shift method for integer bit depth conversion (from 8 to 8-16 bits). For 32 bit float clips the conversion is value/255.0 for Y (luma) channel and (value-128)/255.0 for U/V chroma channels. Do not use paramscale when you want to limit 32 bit float chroma exactly to +/-0.5, give the parameters directly instead.

Default: does not scale at all, parameters are used as-is. Parameters now are of float type to handle 32 bit float values..

Examples

# 1. Original image FFmpegSource2("sintel.mp4") Trim(4685, 4685) # 2. Exaggerated luma and chroma range Levels(16, 1.0, 255-16, 0, 255, coring=false) Tweak(sat=2.0, coring=false) # (insert Limiter here) 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)

# 7. Putting it all together [...] StackHorizontal( \ Last \ , StackVertical( \ Histogram("levels", 0.5).Crop(Width, 0, 256, 256).AddBorders(0, 0, 0, Height/2-256) \ , Histogram("color2" ).Crop(Width, 0, 256, 256).AddBorders(0, 0, 0, Height/2-256) \ ) \ , StackVertical( \ BicubicResize(Width/2, Height/2).Limiter(16, 235, 16, 240, "luma_grey") \ , BicubicResize(Width/2, Height/2).Limiter(16, 235, 16, 240, "chroma_grey") \ ) \ )

Changes

AVS+ r2724	Added support for float. Added paramscale
AVS+	Added support for 8-16bit color spaces.
v2.60	Added support for YV24.
v2.56	Added show to show out of bound luma/chroma.