MaskTools2/Mt merge

Description

It's the backbone of the framework. It merges two clips according to the mask. The bigger the mask value, the more the second clip will be taken into account.

For 8 bits the actual formula is:
y = ((256 - m) * x1 + m * x2 + 128) / 256

Since v2.2.7: keep original pixels from clip1/2 when mask is exactly 0 or 255:
y = (m == 0) ? x1 : (m == 255) ? x2 : ((256 - m) * x1 + m * x2 + 128) / 256

For 10-12-14-16 bits the minimum value is 0, maximum value is 1023, 4095, 16383, 65535 accordingly.
y = (m == minvalue) ? x1 : (m == maxvalue) ? x2 : ((2^bitdepth - m) * x1 + m * x2 + 2^(bitdepth-1)) / (2^bitdepth)

For 32 bit float the actual formula is:
y = (1.0 - m) * x1 + m * x2

Syntax and Parameters

mt_merge (clip, clip, clip, bool "luma", int "Y", int "U", int "V", string "chroma", int "offX", int "offY", int "w", int "h")

or since v2.2.15

mt_merge (clip, clip, clip, bool "luma", float "Y", float "U", float "V", string "chroma", int "offX", int "offY", int "w", int "h", float "A", string "cplace")

clip   =

Input clip one.

clip   =

Input clip two.

clip   =

Mask input clip.

bool  luma = false

luma is a special mode, where only the the first plane (luma or red plane) of the mask is used to process all three channels.

Note: when luma=true, it forces chroma processing (chroma="process" or u=3, v=3).

int  Y = 3

int  U = 2

int  V = 2

int  A = 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.
• x = 4 : the plane of the second input clip will be copied.

U, V and A are defaulted to 2 (that way, the resulting clip contains the chroma (alpha) of clip1, and looks right).

Note: when luma=true, the u and v parameters are overridden and set to u=3, v=3 internally.

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.
• "xxx", where xxx is a number : set u = v = -xxx.

Note: when luma=true, the chroma parameter is overridden and set to chroma="process" internally.

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.

string  cplace = "mpeg2"

Parameter defines chroma placement hint for 4:2:0 and 4:2:2 formats. Introduced in v2.2.15.

• "mpeg1" : Simple block averaging (e.g. average 2x2 pixels to a single YV12 chroma mask)
• "mpeg2" : default
• "topleft" : only for 4:2:0 videos. (added in v2.2.27)

Examples

mt_merge with default settings: (TO DO)

clip1 = original
clip2 = processed
mask  = mask

mt_merge(clip1, clip2, mask, Y=3, U=2, V=2, chroma="", w=-1, h=-1)

---

Back to MaskTools2 ←

---