MaskTools2
see also MaskTools
Abstract  

Author  pinterf, tp7, Manao, mg262, Kurosu 
Version  2.2.18 
Download 

Category  Support filters 
License  MIT but binaries are GPLv2 
Discussion  Doom9 Thread /// Updated thread 
Contents 
MaskTools2 v2.2.x
This is a fork of tp7's MaskTools2 plugin. It works for high bit depth under AviSynth+ (1016 bits, 32 bit float), supports RGB (planar) under Avisynth+, extends existing and add new features, contains a bugfix, and AVX and AVX2 optimizations for some filters. This branch will be called 2.2.x opposed to 2.0.* like the previous MaskTools2.
At the moment "mt_polish" functionality is not available on XP builds.
Difference to Masktools2 b1
 project moved to Visual Studio 2017
Requires Visual Studio redistributables (14.xx family)  add back "none" and "ignore" for values to "chroma" parameter (2.2.9)
 Fix: mt_merge at 8 bit clips: keep exact pixel values when mask is 0 or 255 (v2.2.7)
 Fix: mt_merge (and probably other multiclip filters) may result in corrupted results under specific circumstances, due to using video frame pointers which were already released from memory
 no special function names for high bit depth filters
 filters are auto registering their mt mode as MT_NICE_FILTER for Avisynth+
 Avisynth+ high bit depth support (incl. planar RGB, color spaces with alpha plane are supported from v2.2.7)
All filters are now supporting 10, 12, 14, 16 bits and 32 bit float. Note: From v2.2.15 the 32 bit float U and V chroma channels are 0 centered instead of 0.5, supporting the change in Avisynth+ in May 2018. This change affects lut functions and mt_diff. (The last Avisynth+ version that matches masktools 2.2.14 is Avs+ r2664, please use Avisynth+ r2724 or newer!) Threshold and sc_value parameters are scaled automatically to the current bit depth (v2.2.5) from a default 8bit value. Y,U,V,A (and parameters chroma/alpha) negative (memset) values are scaled automatically to the current bit depth (v2.2.7, chroma/alpha v.2.2.8) from a default 8bit value. Default range of such parameters can be overridden to 816 bits or float. Disable parameter scaling with paramscale="none"
 Supporting clips with alpha plane
 new parameter "A" (default 1: no process) similar to "Y", "U", and "V"
 new parameter aExpr for filters that can take yExpr, vExpr and uExpr
 new parameter "alpha" to override alpha plane mode, similar to "chroma"
 New plane mode: 6 (copy from fourth clip) for "Y", "U", "V" and "A" (2.2.7)
 New "chroma" and "alpha" plane mode override: "copy fourth" (2.2.7)
Use for mt_lutxyza which has four clips
 YV411 (8 bit 4:1:1) support
 mt_polish to recognize new constants and scaling operator, and some other operators introduced in earlier versions.
Due to the stopped XP support of boost library mt_polish and mt_infix are not available on XP version.
 new: mt_lutxyza. Accepts four clips. 4th variable name is 'a' (besides x, y and z)
 new: mt_luts: weight expressions as an addon for then main expression(s) (martin53's idea)
 wexpr
 ywExpr, uwExpr, vwExpr, awExpr
If the relevant parameter strings exist, the weighting expression is evaluated for each source/neighborhood pixel values (lut or realtime, depending on the bit depth and the "realtime" parameter).
Then the usual lut result is premultiplied by this weight factor before it gets accumulated.
Weights are float values. Weight luts are x,y (2D) luts, similarly to the base working mode, where x is the base pixel, y is the current pixel from the neighbourhood, defined in "pixels".
When the weighting expression is "1", the result is the same as the basic weightless mode.
For modes "average" and "std" the weights are summed up. Result is: sum(value_i*weight_i)/sum(weight_i).
When all weights are equal to 1.0 then the expression will result in the average: sum(value_i)/n.
Same logic works for min/max/median/etc., the "old" lut values are premultiplied with the weights before accumulation.
mt_merge changes
 mt_merge accepts 4:2:2 clips when luma=true
 mt_merge accepts 4:1:1 clips when luma=true
 mt_merge new parameter hint when luma=true and clip is 4:2:0/4:2:2
 String 'cplace' (2.2.15). Possible values "mpeg1" or "mpeg2" (default)
 mt_merge to discard U and V automatically when input is greyscale
AVX and AVX2 support
 some filters got AVX (float) and AVX2 (integer) support when processor supports (Avisynth+ and Win7 SP1 or newer required):
 mt_merge: 816 bits and 32 bit float: AVX2
 mt_logic: 816 bit: AVX2, float:AVX
 mt_edge: 816 bit: AVX2, float: AVX
Expression syntax supporting bit depth independent expressions
 bitdepth aware scale operators
 operator scaleb scales from 8 bit to current bit depth using bitshifts. scaleb alternative: @B (see warning)
Use this for YUV. "235 scaleb" always results in max luma  operator scalef scales from 8 bit to current bit depth using full range stretch. scalef alternative: @F (see warning)
"255 scalef" results in maximum pixel value of current bit depth.
Calculation:
x/255*65535 for a 8>16 bit sample (rgb)
 operator scaleb scales from 8 bit to current bit depth using bitshifts. scaleb alternative: @B (see warning)
 Warning: please use scaleb or scalef instead of @B and @F, to match the syntax with Avisynth+'s Expr filter
 hints for non8 bit based constants:
Added configuration keywords i8, i10, i12, i14, i16 and f32 in order to tell the expression evaluator the bit depth of the values that are to scale by scaleb and scalef operators (see "sbitdepth"). By default scaleb and scalef scales from 8 bit to the bit depth of the clip.
 i8 .. i16 and f32 sets the default conversion base to 8..16 bits or float, respectively.
 When used with scale_inputs=true (v2.2.15), it specifies the internal working range (temporary scaling target)
 These keywords can appear anywhere in the expression, but only the last occurence will be effective for the whole expression.
 Examples
8 bit video, no modifier: "x y  256 scaleb *" evaluates as "x y  256 *" 10 bit video, no modifier: "x y  256 scaleb *" evaluates as "x y  1024 *" 10 bit video: "i16 x y  65536 scaleb *" evaluates as "x y  1024 *" 8 bit video: "i10 x y  512 scaleb *" evaluates as "x y  128 *"
 new predefined, bit depth aware constants
 bitdepth: automatic silent parameter of the lut expression
 sbitdepth: automatic silent parameter of the lut expression (bit depth of values to scale)
 range_half > autoscaled 128 or 0.5 for float luma/rgb, 0.0 for float chroma
 range_min > 0 for 816 bits and nonUV 32bit, or 0.5 for float UV chroma (new from 2.2.15)
 range_max > 255/1023/4095/16383/65535 or 1.0 for float luma or 0.5 for float chroma
 range_size > 256/1024...65536
 ymin, ymax, cmin, cmax > 16/235 and 16/240 autoscaled. For zero based float: (16128)/255.0 and (240128)/255.0
Example #1 (bit depth dependent, all constants are treated asis):
expr8_luma = "x 16  219 / 255 *" expr10_luma = "x 64  876 / 1023 *" expr16_luma = "x 4096  56064 / 65535 *"
Example #2 (new, with autoscale operators )
expr_luma = "x 16 scaleb  219 scaleb / 255 scalef *" expr_chroma = "x 16 scaleb  224 scaleb / 255 scalef *"
Example #3 (new, with constants)
expr_luma = "x ymin  ymax ymin  / range_max *" expr_chroma = "x cmin  cmax cmin  / range_max *"
 new option for Lut expressions:
 Parameter "clamp_float"
True: clamps 32 bit float to valid ranges, which is 0..1 for Luma or for RGB color space and 0.5..0.5 for YUV chroma UV channels Default false, ignored (treated as true) when scale_inputs scales float
 new option for Lut expressions:
 parameter "scale_inputs" (default "none")
 Autoscale any input (x,y,z,a) bit depths to 816 bit for internal expression use, the conversion method is either full range or limited YUV range. Extends and replaces clamp_f_i8, clamp_f_i10, clamp_f_i12, clamp_f_i14 or clamp_f_i16, clamp_f_f32 or clamp_f
 Feature is available from v2.2.15
 The primary reason of this feature is the "easy" usage of formerly written expressions optimized for 8 bits.
 Use
 "int" : scales limited range videos, only integer formats (816bits) to 8 (or bit depth specified by 'i8'..'i16')
 "intf": scales full range videos, only integer formats (816bits) to 8 (or bit depth specified by 'i8'..'i16')
 "float" or "floatf" : only scales 32 bit float format to 8 bit range (or bit depth specified by 'i8'..'i16')
 "all": scales videos to 8 (or bit depth specified by 'i8'..'i16')  conversion uses limited_range logic (mul/div by two's power)
 "allf": scales videos to 8 (or bit depth specified by 'i8'..'i16')  conversion uses full scale logic (stretch)
 "none": no magic
 Limited range is usually used for normal YUV videos, full scale is for RGB or knowntobefullscale YUV.
 By default the internal conversion target is 8 bits, so old expressions written for 8 bit videos will probably work. This internal working bitdepth can be overwritten by the i8, i10, i12, i14, i16 specifiers.
 When using autoscale mode, scaleb and scalef keywords are meaningless, because there is nothing to scale.
 How it works:
 This option scales (x,y,z,a) 832 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). The conversion is not a simple shiftright8 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 8bitvideoonly 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, floatdivision 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 16816 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).
 new expression syntax: auto scale modifiers for float clips (test, may change, use clamp_float and scale_inputs parameters instead since v2.2.16):
 Keyword at the beginning of the expression:
 deprecated clamp_f_i8, clamp_f_i10, clamp_f_i12, clamp_f_i14 or clamp_f_i16 for scaling and clamping
 deprecated clamp_f_f32 or clamp_f: for clamping the result to 0..1
 Input values 'x', 'y', 'z' and 'a' are autoscaled by 255.0, 1023.0, ... 65535.0 before the expression evaluation, so the working range is similar to native 8, 10, ... 16 bits. The predefined constants 'range_max', etc. will behave for 8, 10,..16 bits accordingly.
The result is automatically scaled back to 0..1 _and_ is clamped to that range. When using clamp_f_f32 (or clamp_f) the scale factor is 1.0 (so there is no scaling), but the final clamping will be done anyway. No integer rounding occurs.
 Keyword at the beginning of the expression:
# obsolate examples, from v2.2.15 use scale_inputs and clamp_float parameter instead of clamp_f_xx keywords expr = "x y  range_half +" # good for 8..32 bits but float is not clamped expr = "clamp_f y  range_half +" # good for 8..32 bits and float clamped to 0..1 expr = "x y  128 + " # good for 8 bits expr = "clamp_f_i8 x y  128 +" # good for 8 bits and float, float will be clamped to 0..1 expr = "clamp_f_i8 x y  range_half +" # good for 8..32 bits, float will be clamped to 0..1
 parameter "paramscale" for filters working with thresholdlike 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
mt_binarize(threshold=80*256, paramscale="i16") # threshold is assumed in 16 bit range mt_binarize(threshold=80) # no param: threshold is assumed in 8 bit range thY1 = 0.1 thC1 = 0.1 thY2 = 0.1 thC2 = 0.1 paramscale="f32" mt_edge(mode="sobel",u=3,v=3,thY1=thY1,thY2=thY2,thC1=thC1,thC2=thC2,paramscale=paramscale) # f32: parameters assumed as float (0..1.0)
Other new parameters
 parameter "stacked" (default false) for filters with stacked format support
Stacked support is not intentional, but since tp7 did it, I did not remove the feature. Filters currently without stacked support will never have it.
 parameter "realtime" for luttype filters, slower but at least works on those bit depths where LUT tables would occupy too much memory.
 For bit depth limits where realtime = true is set as the default working mode, see table below.
realtime=true can be overridden, one can experiment and force realtime=false even for a 16 bit lutxy (8GBytes lut table!, x64 only) or for 8 bit lutxzya (4 GBytes lut table)
See also: 'use_expr' which can pass the expressions for realtime calculation to Avisynth+ Expr filter!
 parameter "use_expr" integer (default 0) for 'lut', 'lutxy', 'lutxyz', 'lutxyza' filters (from v2.2.15)
 Use it when realtime calculation (interpreted pixelbypixel expression calculation) is slow and an appropriate Avisynth+ version (>r2712) is available.
 By sending the expression to Avisynth+, lut filters can utilize a realtime JITcompiled fast expression calculation.
 use_expr>0 will pass the expressions, scale_inputs and clamp_float parameter to the "Expr" filter in Avisynth+
 Possible values:
 0: uses lut and internal realtime calculation
 1: Expr, when bit depth>=10 or lutxyza
 2: When masktools would use realtime calc
 3: Expr, always passed (from 2.2.17)
 For modes 1, 2 and 3: passes the expression strings, scale_inputs and clamp_float parameters to the "Expr" filter in Avisynth+
 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.
Other new operators
 new: "swap" keyword in expressions (v2.2.5)
swaps the last two results during RPN evaluation. Not compatible with mt_infix()
expr="x 2 /" expr="2 x swap /"
 new: "dup" keyword in expressions (v2.2.5)
duplicates the last result and put on the top of RPN evaluation stack. Not compatible with mt_infix()
expr="x 3 / x 3 / +" expr="x 3 / dup +"
Note: While Expr in Avisynth+ supports dup1, dup2, .... swap1, swap2..., masktools2 version is able to duplicate / swap only the top of the execution stack
Feature matrix
8 bit  1016 bit  float  stacked  realtime  use_expr mt_invert X X X  mt_binarize X X X X mt_inflate X X X X mt_deflate X X X X mt_inpand X X X X mt_expand X X X X mt_lut X X X X when float yes mt_lutxy X X X  when bits>=14 yes mt_lutxyz X X X  when bits>=10 yes mt_lutxyza X X X  always yes mt_luts X X X  when bits>=14 no mt_lutf X X X  when bits>=14 no mt_lutsx X X X  when bits>=10 no mt_lutspa X X X  mt_merge X X X X mt_logic X X X X mt_convolution X X X  mt_mappedblur X X X  mt_gradient X X X  mt_makediff X X X X mt_average X X X X mt_adddiff X X X X mt_clamp X X X X mt_motion X X X  mt_edge X X X  mt_hysteresis X X X  mt_infix/mt_polish: available only on nonXP builds
MaskTools2 b1
This is a fork of Manao's MaskTools2 plugin. It mostly contains performance improvements, bugfixes and some little things that make the plugin more "mature". This branch will be called b* as opposed to a* like the original MaskTools2.
Difference to MaskTools2 a48
 Works correctly with AviSynth 2.6 Alpha 4/5 and RC 1 (including MT). Doesn't work with previous alphas.
 Much cleaner and easy to understand codebase, also the source code is now licensed under MIT.
 all luts: faster LUT calculation, faster startup, reduced memory footprint if the same LUT is used for multiple planes or some planes aren't processed. For example mt_lutxyz(c1, c2, c3, "x y + z ") will use only 16MBs of memory instead of 48MBs.
 mt_lutspa: does not depend on source clip performance as it doesn't get requested at all (unless mode 2 is used). Always much faster (5o9k times).
 all filters: faster modes 2, 4 and 5 (copy), negative (memset) modes.
 mt_hysteresis: 34 times better performance.
 all luts: performance in mode 3 with an empty LUT is now identical to mode 2. Thus mt_lut(chroma="128") is a bit faster than Grayscale() instead of being much slower.
 mt_merge: luma=true now supports YV24.
 mt_luts: correct value is used as x. More info here.
 sobel/roberts/laplace modes of mt_edge: better performance when SSSE3 is available.
 mt_edge("cartoon"): 10 times faster when SSE2 is available.
 all asmoptimized filters: same performance on any resolution up to mod1. Original MaskTools2 used unoptimized version for any nonmod8 clips.
All filters were tested on a Core i7 860. Performance might be a bit different on other CPUs.
Download
Latest revision of MaskTools2 v2.2.x (x86/x64)
 MaskTools2 v2.2.x release page  compatible with AviSynth 2.6.0 (x86) and AviSynth+ (x86/x64)
Runtime dependencies:
This 2017 version supersedes VS2015 redist update 3: Microsoft Visual C++ 2015 Redistributable Update 3 (x86/x64)
Filters
MaskTools2 contain a set of filters designed to create, manipulate and use masks. Masks, in video processing, are a way to give a relative importance to each pixel. You can, for example, create a mask that selects only the green parts of the video, and then replace those parts with another video. To give the most control over the handling of masks, the filters will use the fact that each luma and chroma planes can be uncorrelated. That means that a single video will always be considered by the filters as 3 independent planes. That applies for masks as well, which means that a mask clip will in fact contain 3 masks, one for each plane.
The filters have a set of common parameters, that mainly concern what processing to do on each plane. All filters only work with planar colorspaces (Y8, YV12, YV16, and YV24 (AviSynth 2.5.8 only supports YV12!).
Beginning with v2.2.4 YUV and planar RGB 1016 bit and 32 bit float color spaces are supported when using AviSynth+ (r2294).
Here is an exhaustive list of the filters contained in MaskTools2 (see developer's page here for more information)
Filter  Description  Color format 

Masks creation  
Mt_edge 
Creates edge masks. 
Y8, YV12, YV16, YV24 
Mt_motion 
Creates motion masks. 
Y8, YV12, YV16, YV24 
Masks operation  
Mt_invert 
Inverses masks. 
Y8, YV12, YV16, YV24 
mt_binarize 
Transforms soft masks into hard masks. 
Y8, YV12, YV16, YV24 
mt_logic 
Combines masks using logic operators. 
Y8, YV12, YV16, YV24 
mt_hysteresis 
Combines masks making the first one to grow into the second. 
Y8, YV12, YV16, YV24 
Masks merging  
Mt_merge 
Merges two clips according to a mask. 
Y8, YV12, YV16, YV24 
Morphologic operators  
mt_expand 
Expands the mask / the video. 
Y8, YV12, YV16, YV24 
mt_inpand 
Inpands the mask / the video. 
Y8, YV12, YV16, YV24 
mt_inflate 
Inflates the mask / the video. 
Y8, YV12, YV16, YV24 
mt_deflate 
Deflates the mask / the video. 
Y8, YV12, YV16, YV24 
LUT operators  
mt_lut 
Applies an expression to all the pixels of a mask / video. 
Y8, YV12, YV16, YV24 
mt_lutxy 
Applies an expression to all the pixels of two masks / videos. 
Y8, YV12, YV16, YV24 
mt_lutxyz 
Applies an expression to all the pixels of three masks / videos. 
Y8, YV12, YV16, YV24 
mt_lutxyza 
Applies an expression to all the pixels of four masks / videos. (v2.2.4) 
Y8, YV12, YV16, YV24 (+high bit depth) 
mt_lutf 
Creates a uniform picture from the collection of computation on pixels of two clips. 
Y8, YV12, YV16, YV24 
mt_luts 
Applies an expression taking neighbouring pixels into. 
Y8, YV12, YV16, YV24 
mt_lutsx 
Applies an expression taking neighbouring pixels into, in a different way. 
Y8, YV12, YV16, YV24 
mt_lutspa 
Computes the value of a pixel according to its spatial position. 
Y8, YV12, YV16, YV24 
Support operators  
mt_makediff 
Substracts two clips. 
Y8, YV12, YV16, YV24 
mt_adddiff 
Adds back a difference of two clips. 
Y8, YV12, YV16, YV24 
mt_clamp 
Clamps a clip between two other clips. 
Y8, YV12, YV16, YV24 
mt_average 
Averages two clips. 
Y8, YV12, YV16, YV24 
Convolutions  
mt_convolution 
Applies a separable convolution on the picture. 
Y8, YV12, YV16, YV24 
mt_mappedblur 
Applies a special 3x3 convolution on the picture. 
Y8, YV12, YV16, YV24 
Helpers  
mt_square 
Creates a string describing a square. 
Y8, YV12, YV16, YV24 
mt_rectangle 
Creates a string describing a rectangle. 
Y8, YV12, YV16, YV24 
mt_freerectangle 
Creates a string describing a rectangle. 
Y8, YV12, YV16, YV24 
mt_diamond 
Creates a string describing a diamond. 
Y8, YV12, YV16, YV24 
mt_losange 
Creates a string describing a lozenge. 
Y8, YV12, YV16, YV24 
mt_freelosange 
Creates a string describing a lozenge. 
Y8, YV12, YV16, YV24 
mt_circle 
Creates a string describing a circle. 
Y8, YV12, YV16, YV24 
mt_ellipse 
Creates a string describing an ellipse. 
Y8, YV12, YV16, YV24 
mt_freeellipse 
Creates a string describing an ellipse. 
Y8, YV12, YV16, YV24 
mt_polish 
Creates a reverse polish expression from an infix one. 
 
mt_infix 
Creates an infix expression from a reverse polish one. 
 
Common parameters
As said previously, all the filters  except the helpers  share a common set of parameters. These parameters are used to tell what processing to do on each plane / channel, and what area of the video to process.
 float Y = 3
or int Y = 3
 float U = 1
or int U = 1
 float V = 1
or int V = 1
 Parameter types are float since v2.2.7 to allow setting 32 bit float type memset values, e.g. 0.5
 These three 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, or 1.0..0.0 (any negative or zero value): all the pixels of the plane will be set to x. From v.2.2.7 Default: 8 bit range autoscaled. Use "paramscale" to change the autoscale mode
 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.
 x = 4 (when applicable) : the plane of the second input clip will be copied.
 x = 5 (when applicable) : the plane of the third input clip will be copied.
 x = 6 (when applicable) : the plane of the fourth input clip will be copied. Since v2.2.7
 As you can see, defaults parameters are chosen to only process the luma, and not to care about the chroma. It's because most video processing doesn't touch the chroma when handling 4:2:0.
 string chroma = ""
 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:
 "none" or "ignore" : set u = v = 1. Since 2.2.9
 "process" : set u = v = 3.
 "copy" or "copy first" : set u = v = 2.
 "copy second" : set u = v = 4.
 "copy third" : set u = v = 5.
 "copy fourth" : set u = v = 6. Since v2.2.7
 "xxx", where xxx is a number : set u = v = xxx.
 int offX = 0
 int offY = 0
 offx and offy are the top left coordinates of the box where the actual processing shall occur. Everything outside that box will be garbage.
 int w = 1
 int h = 1
 w and h are the width and height of the processed box. 1 means that the box extends to the lower right corner of the video.
 This also means that default settings are meant to process the whole picture.
 float A = 1
or int A = 1
 Since 2.2.7
 Describe the actual processing mode that is to be used on "A" plane
 see Y, U and V description
 string alpha = ""
 Since v2.2.7
 When defined, the value contained in this string will overwrite the A processing modes.
 Allowed values for alpha are:
 "none" or "ignore" : set u = v = 1. Since 2.2.9
 "process" : set a = 3.
 "copy" or "copy first" : set a = 2.
 "copy second" : set a = 4.
 "copy third" : set a = 5.
 "copy fourth" : set a = 6.
 "xxx", where xxx is a number : set a = xxx.
 string paramscale = ""
 Since v2.2.7
 When not defined, all thresholdlike and Y, U, V, A parameter values are treated as 8 bit values and will be autoscaled accordingly to match the clip bit depths.
 Allowed values for paramscale are:
 "i8" : Default, parameters are recognized as 8 bit integer constants. (existing 8 bit scripts will work in any bit depths)
 "i10" : Parameters are treated as in 10 bit range (0..1023). Autoscale base will be this bit depth.
 "i12" : Parameters are treated as in 12 bit range (0..4095).
 "i14" : Parameters are treated as in 14 bit range (0..16383).
 "i16" : Parameters are treated as in 16 bit range (0..65535).
 "f32" : Parameters are treated as in 32 bit float (0.0..1.0).
 "none" : Parameters are treated as is. No scaling happens at all.
 Scaling method is "stretch" for RGB, and bit shifts for YUV colorspaces. Note that the maximum pixel value is always mapped to the max mixel value of the target bit depth. E.g. 255 will be 65535 and not 255 lshift 8
Reverse polish notation
A lot of filters accept custom functions defined by an expression written in reverse polish notation. You may not be accustomed to this notation, so here are a few pointers :
 The basic concept behind the notation is to write the operator / function after the arguments. Hence, "x + y" in infix notation becomes in reverse polish "x y +". "(3 + 5) * x" would become "3 5 + x *".
 As you noticed in the last example, the great asset of the notation is that it doesn't need parenthesis. The expression that would have been enclosed in parenthesis ( "3 + 5" ) is correctly computed, because we read the expression from left to right, and because when the "+" is encountered, its two operands are unmistakeably known.
 The supported operators are : "+", "", "*", "/", "%" (modulo) and "^" (power)
 The supported functions are : "sin", "cos", "tan", "asin", "acos", "atan", "exp", "log", "abs", "round", "clip", "min", "max", "ceil", "floor", "trunc".
 Making the assumption that a positive float is "true", and a negative one is "false", we can also define boolean operators : "&", "", "&!" (and not), "°" (xor), "@" (xor).
 We can create boolean values with the following comparison operators : "<", ">", "<=", ">=", "!=", "==", "=" (same as "==").
 Binary operators. Since internally all intermediate values are double, the parameters are first converted to 64 bit integer (unsigned or signed), and after the bit operation is done, the result will be converted back to double. So working with binary data is not fast, nor has real 64 bit integer precision.
 Unsigned: "&u" (and), "u" (or), "°u" (xor), "@u" (xor), "~u" (negate), "<<" or "<<s" (shift left), ">>" or ">>u" (shift right).
 Signed: "&s" (and), "s" (or), "°s" (xor), "@s" (xor), "~s" (negate), "<<s" (shift left), ">>s" (shift right).
 autoscale operators (v2.2.4)
 scale from sbitdepth to bitdepth using bitshift method: "@B" or "scaleb" (#B until v2.2.4)
 scale from sbitdepth to bitdepth using full scale stretch method: "@F" or "scalef" (#F until v2.2.4)
 The variable "x", "y", "z" and "a" (when applicable) contains the value of the pixel. It's an integer 0 to (2^bitdepth)1 (e.g. 0..255 for 8 bits). For float the range is generally 0..1.0
 The constant "pi" can be used.
 The constant "bitdepth" (816, 32) for the input bitdepth (v2.2.4)
 The constant "sbitdepth" (816, 32) as the bitdepth of constants to scale (v2.2.4)
 Other predefined constants for bitdepth dependent values (v2.2.4)
 "range_half": 128 for 8 bits, 2^(bitdepth1) in general, 0.5 for 32 bit float
 "range_max": 255 for 8 bits, (2^bitdepth)1 in general, 1.0 for 32 bit float
 "range_size": 256 for 8 bits, (2^bitdepth) in general, 1.0 for 32 bit float
 "ymin", "ymax": luma min and max value. 16 and 235 for 8 bits, shifted left by (bitdepth8) in general
 "cmin", "cmax": chroma min and max value. 16 and 240 for 8 bits, shifted left by (bitdepth8) in general
 Finally, there's a ternary operator : "?", which acts like a "if .. then .. else .."
 All the computations are made in 64 bit doubles, and the final result is rounded to the nearest integer, in the range [0..255], [0..1023], .. [0..1.0] etc. depending on the clip's bitdepth.
 Throughout the whole documentation, you'll be able to find plenty of examples.
Changelog
See the Github repository for v2.2.x, or MaskTools2 b1 GitHub commit log for tp7's changes; see this page for older changes.
Exernal Links
 GitHub  Source code repository for MaskTools2 2.2.x.
 GitHub  Source code repository for MaskTools2 b1.
 Doom9 Forum  Original MaskTools2 discussion thread.
 Doom9 Forum  v2.2.x discussion thread
Guides:
 Excellent MaskTools guide by tp7 [1]
 Another guide by tp7 in Russian
 MaskTools guide in Chinese by 06_taro [2]
Back to External Filters ←