Reel.Deal: add documentation (v2.2.24)

2020-07-27T20:23:34Z

add documentation (v2.2.24)

New page

{{FilterCat4|External_filters|Plugin_functions|Other_filters|Support_filters}}
== Description ==
mt_lut applies an expression to all the pixels of a mask / video.

 

== [[Script variables|Syntax and Parameters]] ==
<div style="max-width:70em" >
:{{Template:FuncDef|mt_lut (clip, string "expr", string "yExpr", string "uExpr", string "vExpr", float "Y ", float "U", float "V", string "chroma", int "offX", int "offY", int "w", int "h", bool "sse2", bool "sse3", bool "ssse3", bool "sse4", bool "avx", bool "avx2", float "A", string "alpha", string "paramscale", bool "stacked", bool "realtime", string "aExpr", string "scale_inputs", bool "clamp_float", int "use_expr", bool "clamp_float_UV")
}}
 
::{{Par2| |clip| }}
:::Input clip one.
 
::{{Par2|expr|string|"x"}}
::{{Par2|yExpr|string|"x"}}
::{{Par2|uExpr|string|"x"}}
::{{Par2|vExpr|string|"x"}}
:::Expression written is reverse polish notation.
:::If yexpr, uexpr or vexpr is noy defined, expr is used instead.
 
::{{Par2|Y|float|3}}
::{{Par2|U|float|2}}
::{{Par2|V|float|2}}
:::These values describe the actual processing mode that is to be used on each plane / channel. Here is how the modes are coded :
::::*x = -255...0 : all the pixels of the plane will be set to -x. (-255..0 range can of course differ when non-8 bit video formats are used)
::::*x = 1 : the plane will not be processed. That means the content of the plane after the filter is pure garbage.
::::*x = 2 : the plane of the first input clip will be copied.
::::*x = 3 : the plane will be processed with the processing the filter is designed to do.
:::U, V and A are defaulted to 2 (that way, the resulting clip contains the chroma (alpha) of clip1, and looks right).
 
::{{Par2|chroma|string|""}}
:::When defined, the value contained in this string will overwrite the u & v processing modes.
:::This is a nice addition proposed by mg262 that makes the filter more user friendly. Allowed values for chroma are:
::::*"process" : set u = v = 3.
::::*"copy" or "copy first" : set u = v = 2.
::::*"xxx", where xxx is a number : set u = v = -xxx.
 
::{{Par2|offX|int|0}}
::{{Par2|offY|int|0}}
:::{{Template:FuncDef3|offX}} and {{Template:FuncDef3|offY}} are the top left coordinates of the box where the actual processing shall occur. Everything outside that box will be garbage.
 
::{{Par2|w|int|-1}}
::{{Par2|h|int|-1}}
:::{{Template:FuncDef3|w}} and {{Template:FuncDef3|h}} are the width and height of the processed box. -1 means that the box extends to the lower right corner of the video. That also means that default settings are meant to process the whole picture.
 
::{{Par2|sse2|bool|true}}
::{{Par2|ssse3|bool|true}}
::{{Par2|sse4|bool|true}}
::{{Par2|avx|bool|true}}
::{{Par2|avx2|bool|true}}
:::CPU optimizations; for debugging only.
 
::{{Par2|Y|float|1}}
:::Same as the Y,U,V parameters but for the alpha channel, if applicable.
 
::{{Par2|alpha|string|""}}
:::Same as the chroma parameter but for the alpha channel, if applicable.
 
::{{Par2|paramscale|string|"i8"}}
:::Same as the chroma parameter but for the alpha channel, if applicable.
:::Parameter "paramscale" for filters working with threshold-like parameters (v2.2.5-)
:::Filters: mt_binarize, mt_edge, mt_inpand, mt_expand, mt_inflate, mt_deflate, mt_motion, mt_logic, mt_clamp
:::paramscale can be "i8" (default), "i10", "i10", "i12", "i14", "i16", "f32" or "none" or ""
:::Using "paramscale" tells the filter that parameters are given at what bit depth range.
:::By default paramscale is "i8", so existing scripts with parameters in the 0..255 range are working at any bit depths
 
::{{Par2|stacked|bool|false}}
:::[[Stack16]] format; not recommended, MaskTools2 supports native high bit-depth with AviSynth+.
 
::{{Par2|realtime|bool|false}}
:::Parameter "realtime" for lut-type filters to override default behaviour.
:::Slower but at least works on those bit depths where LUT tables would occupy too much memory.
 
::{{Par2|aExpr|string|"x"}}
:::Same as the expr, yExpr, uExpr, vExpr parameters but for the alpha channel, if applicable.
 
::{{Par2|scale_inputs|string|"none"}}
:::Autoscale any input (x,y,z,a) bit depths to 8-16 bit for internal expression use, the conversion method is either full range or limited YUV range. (Replaces clamp_f_i8, clamp_f_i10, clamp_f_i12, clamp_f_i14 or clamp_f_i16, clamp_f_f32 or clamp_f keywords)

:::The primary reason of this feature is the "easy" usage of formerly written expressions optimized for 8 bits.

:::Use:

:::*<code>"int"</code> : scales limited range videos, only integer formats (8-16bits) to 8 (or bit depth specified by 'i8'..'i16')
:::*<code>"intf"</code> : scales full range videos, only integer formats (8-16bits) to 8 (or bit depth specified by 'i8'..'i16')
:::*<code>"float"</code> or <code>"floatf"</code> : only scales 32 bit float format to 8 bit range (or bit depth specified by 'i8'..'i16')
:::*<code>"floatUV"</code> : affects the chroma plane expressions of 32 bit float formats. Shifts the input up by 0.5 before processing it in the expression, thus values from -0.5..0.5 (zero centered) range are converted to the 0..1 (0.5 centered) one. Since the expression result internally has 0..1.0 range, this then is shifted back to the original -0.5..0.5 range. (since 2.2.20) Note: predefined constants such as cmin, cmax, range_min, range_max and range_half will be shifted as well, e.g. the expression will see range_half = 0.5
:::*<code>"all"</code> : scales videos to 8 (or bit depth specified by 'i8'..'i16') - conversion uses limited_range logic (mul/div by two's power)
:::*<code>"allf"</code> : scales videos to 8 (or bit depth specified by 'i8'..'i16') - conversion uses full scale logic (stretch)
:::*<code>"none"</code> : no magic

:::Usually limited range is for normal YUV videos, full scale is for RGB or known-to-be-fullscale YUV.

:::By default the internal conversion target is 8 bits, so old expressions written for 8 bit videos will probably work. This internal working bit-depth can be overwritten by the i8, i10, i12, i14, i16 specifiers.

:::When using autoscale mode, scaleb, scalef, yscaleb and yscalef keywords are meaningless for 8-16 bits, because there is nothing to scale. 32 bit (float) values will be scaled however when "float", "floatUV", "all", "allf" is specified.

:::How it works:

:::*This option scales (x,y,z,a) 8-32 bit inputs to a common bit depth value, which bit depth is 8 by default and can be set to 10, 12, 14 and 16 bits by the 'i10'..'i16' keywords For example: scale_inputs="all" converts any inputs to 8 bit range. No truncation occurs however (no precision loss), because even a 16 bit data is converted to 8 bit in floating point precision, using division by 256.0 (2^16/2^8). So the conversion is not a simple shift-right-8 in the integer domain, which would lose precision.

:::*Calculates expression

:::*Scales the result back to the output video bit depth. Clamping (clipping to valid range) and converting to integer occurs here.

:::The predefined constants such as 'range_max', etc. will behave according to the internal working bit depth.

:::Warning#1 This feature was created for easy porting earlier 8-bit-video-only expressions. You have to understand how it works internally.

:::Let's see a 16bit input in "all" and "allf" mode (target is the default 8 bits)

:::Limited range 16->8 bits conversion has a factor of 1/256.0 (Instead of shift right 8 in integer domain, float-division is used or else it would lose presision) Full range 16->8 bits conversion has a factor of 255.0/65535

:::Using bit shifts (really it's division and multiplication by 2^8=256.0): result = calculate_lut_value(input / 256.0) * 256.0 Full scale 16-8-16 bit mode ('intf', 'allf') result = calculate_lut_value(input / 65535.0 * 255.0 ) / 255.0 * 65535.0

:::Use scale_inputs = "all" ("int", "float") for YUV videos with 'limited' range e.g. in 8 bits: Y=16..235, UV=16..240). Use scale_inputs = "allf" (intf, floatf) for RGB or YUV videos with 'full' range e.g. in 8 bits: channels 0..255.

:::When input is 32bit float, the 0..1.0 (luma) and -0.5..0.5 (chroma) channel is scaled to 0..255 (8 bits), 0..1023 (i10 mode), 0..4095 (i12 mode), 0..16383(i14 mode), 0..65535(i16 mode) then back.

:::Warning#2 One cannot specify different conversion methods for converting before and after the expression. Neither can you specify different methods for different input clips (e.g. x is full, y is limited is not supported).
 
::{{Par2|clamp_float|bool|false}}
:::32 bit float video is always a bit different, as usually no clamping is applied to valid ranges
:::This parameter along with clamp_float_UV changes this behaviour.

:::*<code>false</code> : no clamp
:::*<code>true</code> : standard clamp which is 0..1 for Luma or for RGB color space and -0.5..0.5 for YUV chroma UV chroma clamping can be set to 0..1 by using clamp_float_UV.
 
::{{Par2|use_expr|int|0}}
::: Use it when realtime calculation (interpreted pixel-by-pixel expression calculation) is slow and an appropriate AviSynth+ version (>r2712) is available.

:::By sending the expression to the [[Expr]] filter in AviSynth+, lut filters can utilize a realtime JIT-compiled fast expression calculation.

:::Possible values:
:::*0 : Uses lut and internal realtime calculation
:::*1 : Expr, when bit depth>=10 or lutxyza
:::*2 : When masktools would use realtime calc, passes the expressions and parameters to the "Expr" filter in AviSynth+
:::*3 : Expr, always passed (from 2.2.17)

:::For modes 1, 2 and 3: Passes the expressions, "scale_inputs", "clamp_float" and "clamp_float_UV" parameter to the "Expr" filter in AviSynth+
:::Note: clamp_float_UV is valid parameter only from AviSynth+ 3.5, and for compatibility reasons is passed only when it's true, so when it differs from the default value.

:::Note #1: AviSynth+ internal precision is 32bit float, masktools2 is double (usually no difference can be seen)
:::Note #2: Some keywords (e.g. bit shift) are not available on AviSynth+
:::Note #3: Since "Expr" can work only on full sized clips, offX, offY, w and h parameters are ignored.
 
::{{Par2|clamp_float_UV|bool|false}}
:::*<code>false</code> : standard clamp which is 0..1 for Luma or for RGB color space and -0.5..0.5 for YUV chroma UV
:::*<code>true</code> : chroma UV clamp same as luma 0..1, used in conjunction with expressions written for integer (positive only) U/V values in mind.
 
== Examples ==
Very similar to [[Histogram]]("Luma")[https://forum.doom9.org/showthread.php?t=181511]:
mt_lut(expr="x 16 &u 17 x 15 &u - 1 x 15 &u + ? 14 *", u=-128, v=-128)

or for high bit depth:
mt_lut (expr="x 16 &u 17 x 15 &u - 1 x 15 &u + ? 14 *", u=-128, v=-128, scale_inputs="allf")
 
 
-----------------------------------------------
'''Back to [[MaskTools2#Filters|MaskTools2]] ←'''
-----------------------------------------------

MaskTools2/mt lut - Revision history

Reel.Deal: add documentation (v2.2.24)