MaskTools2

Revision as of 18:09, 20 November 2016

see also MaskTools

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.

• No MMX-optimized versions. MMX is too old to support and is always slower than SSE2.

• 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 (5-o9k times).

• all filters: faster modes 2, 4 and 5 (copy), negative (memset) modes.

• mt_hysteresis: 3-4 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 asm-optimized filters: same performance on any resolution up to mod-1. Original MaskTools2 used unoptimized version for any non-mod8 clips.

All filters were tested on a Core i7 860. Performance might be a bit different on other CPUs.

Download

MaskTools b1 comes in three variations:

• masktools2-25-x86.zip - compatible with AviSynth 2.5.8

• masktools2-x86.zip**** - compatible with AviSynth 2.6.0 and AviSynth+ (x86)

• masktools2-x64.zip**** - compatible with AviSynth+ (x64)

Runtime dependencies:

• Microsoft Visual C++ 2012 Redistributable Package (x86 / x64)

**** vcredist_x86.exe is required for MaskTools2-x86

**** vcredist_x64.exe is required for MaskTools2-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!).

Here is an exhaustive list of the filters contained in MaskTools2 (see developer's page here for more information)

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.

int  Y = 3

int  U = 1

int  V = 1

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 : all the pixels of the plane will be set to -x.
• 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.

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:

• "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.
• "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.

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".

• Making the assumption that a positive float is "true", and a negative one is "false", we can also define boolean operators : "&", "|", "&!" (and not), "?°" (xor).

• We can create boolean values with the following comparison operators : "<", ">", "<=", ">=", "!=", "==", "=".

• The variable "x" and "y" (when applicable) contains the value of the pixel. It's an integer that ranges from 0 to 255.

• The constant "pi" can be used.

• Finally, there's a ternary operator : "?", which acts like a "if .. then .. else .."

• All the computations are made in floats, and the final result is rounded to the nearest integer, in the range [0..255].

• Throughout the whole documentation, you'll be able to find plenty of examples.

Changelog

See the GitHub commit log for newer changes; see this page for older changes.

Exernal Links

• GitHub - Source code repository.
• Doom9 Forum - Original MaskTools2 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 ←