MaskTools2

Revision as of 03:09, 26 October 2013

Introduction

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 these 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 mean that a single video will always be considered by the filters as 3 independant 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. They all work only in YV12 (though with Avisynth 2.6, support for all planar formats will be available).

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 "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. That also means that default settings are meant to process the whole picture.

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

Filters

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

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 expresion 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 unmistakenly 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 on 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 found plenty of examples.

Changelog

See the latest version of the Masktools2 changelog.

Links

MaskTools2 Homepage

The latest version can always be downloaded from manao4.free.fr or its Doom9 thread.