Layer

Layer (aka overlay, blend, merge) two clips of possibly different sizes, but with the same color format.

For pixel-wise transparency information the alpha channel of an RGB32 overlay_clip is used as a mask.

Layer( clip base_clip, clip overlay_clip [, string op, int level, int x, int y, int threshold, bool use_chroma ] )

clip  base_clip =

The underlying clip, which determines the size and all other video and audio properties of the result.

clip  overlay_clip =

The clip which is merged onto clip.

string  op = "add"

The merge operation to be performed, which can be one of the following:

Op	Description
add	This is the default mode. Equivalent to Overlay(mode="blend"). overlay_clip will be copied on top of the original, in proportion to level, and subject to the alpha channel.
subtract	base_clip minus overlay_clip. If both clips are equal and level=128, a flat gray field is returned; compare to Subtract.
lighten	Copy overlay_clip over base_clip in areas where overlay_clip is lighter. Also known as lighter color.
darken	Copy overlay_clip over base_clip in areas where overlay_clip is darker. Also known as darker color.
fast	Like add, but without masking.
mul	base_clip multiplied by overlay_clip. This will generally make the output darker (see GIMP: Multiply).

int  level = (maximum)

The strength of the performed operation:

• 0 – no effect: base_clip is returned unchanged
• 257 (256 for YUY2) – maximum strength

int  x = 0

int  y = 0

offset position of overlay_clip

int  threshold = 0

Changes the transition point of op="darken" and op="lighten" as shown below.

bool  use_chroma = true

Use chroma of the overlay_clip. Default=true. When false, only luma is used.

Audio, FrameRate and FrameCount are taken from the first clip.

There are some differences in the behaviour and the allowed parameter depending on the color format and the operation; here are the details:

• There is no mask (alpha channel) in YUY2, so the alpha channel is assumed to be fully opaque (255) everywhere.

• In RGB32 the overlay_clip alpha channel is multiplied with level, so the resulting alpha = (alpha_mask * level + 1) / 256.
  This means for full strength of operation, alpha has to be 255 and level has to be 257.

• These operators behave equally for RGB32 or YUY2:

Op	Comment
fast	use_chroma must be true; level and threshold are not used. The result is simply the average of base_clip and overlay_clip.
add	threshold is not used. The difference between base_clip and overlay_clip is multiplied with alpha and added to base_clip. alpha=0    → only base_clip visible alpha=128 → base_clip and overlay_clip equally blended alpha=255 → only overlay_clip visible Formula used : RGB:   YUY2:
subtract	the same as add, but overlay_clip is inverted before adding.

• These operators work correctly only in YUY2:

Op	Comment
mul	threshold is not used. use_chroma may be true or false, depending on the desired effect. See examples below. alpha=0    → only base_clip visible. alpha=255 → approx. the same luminance as base_clip but with the colors of overlay_clip.

• These operators work correctly only in RGB32:

Op	Comment
lighten	use_chroma must be true. Performs the same operation as add, but only when overlay_clip is BRIGHTER than base_clip. With a higher threshold the operation is more likely, so with threshold=255 is the same as add; with threshold=0, base_clip is more likely passed unchanged, depending on the difference between base_clip and overlay_clip.
darken	the same as "lighten", but it is performed only when overlay_clip is DARKER than base_clip.

Examples

• Layer can be used to combine two captures of different broadcasts for reducing noise. A discussion of this idea can be found here. Of course you have to ensure that the frames of the two clips match exactly -- use Trim or DeleteFrame as necessary. A sample script:

clip1 = AviSource("capture-pass-1.avi").ConvertToYUY2
clip2 = AviSource("capture-pass-2.avi").ConvertToYUY2.Trim(101, 0)
return Layer(clip1, clip2, "fast")

• Demonstration of lighten, darken, and the effect of threshold:

lena=ImageSource("Lenna.png", pixel_type="RGB32").BicubicResize(256, 256)
grad=mt_lut(GraMaMa(lena.ConvertToYV12, 4, 0, 0, lena.Width), 
\    "x 0.5 * 64 +", u=-128, v=-128).ConvertToRGB32
\  .Subtitle("TEXT", size=32, text_color=$ebebeb, halo_color=$ff000000, align=5)
return StackVertical(
\   StackHorizontal(
\      lena.Subtitle("lena", size=14, align=2).AddBorders(2, 2, 2, 2)
\    , grad.Subtitle("grad", size=14, align=2).AddBorders(2, 2, 2, 2)
\   )
\ , StackHorizontal(
\       Layer(lena, grad, "lighten", threshold=0).AddBorders(2, 2, 2, 2) 
\         .Subtitle("""Layer(lena, grad, "lighten", threshold=0)""", size=14, align=2)
\     , Layer(lena, grad, "darken", threshold=0).AddBorders(2, 2, 2, 2) 
\         .Subtitle("""Layer(lena, grad, "darken", threshold=0)""", size=14, align=2)
\   )
\ , StackHorizontal(
\       Layer(lena, grad, "lighten", threshold=64).AddBorders(2, 2, 2, 2) 
\         .Subtitle("""Layer(lena, grad, "lighten", threshold=64)""", size=14, align=2)
\     , Layer(lena, grad, "darken", threshold=64).AddBorders(2, 2, 2, 2) 
\         .Subtitle("""Layer(lena, grad, "darken", threshold=64)""", size=14, align=2)
\  

• Demonstration of mul with use_chroma:

lena=ImageSource("Lenna.png", pixel_type="RGB32").BicubicResize(256, 256)
grad=GraMaMa(lena.ConvertToYV12, 3, 0, 0, Round(1.3*lena.Width))
\  .ConvertToYUY2
\  .Subtitle("TEXT\n", size=32, text_color=$ff000000, halo_color=$ebebeb, align=5, lsp=0, font_angle=180.0)
\  .Subtitle("TEXT\n", size=32, text_color=$ff000000, halo_color=$404040, align=5, lsp=0)
\  .Invert
\  .ColorYUV(off_u=-60, off_v=-60)
return StackVertical(
\   StackHorizontal(
\      lena.Subtitle("lena", size=14, align=2).AddBorders(2, 2, 2, 2)
\    , grad.Subtitle("grad", size=14, align=2).AddBorders(2, 2, 2, 2)
\   )
\ , StackHorizontal(
\       Layer(lena, grad, "mul", level=128, use_chroma=true).AddBorders(2, 2, 2, 2) 
\         .Subtitle("""Layer(lena, grad, "mul", level=128, use_chroma=true)""", size=10, align=2)
\     , Layer(lena, grad, "mul", level=128, use_chroma=false).AddBorders(2, 2, 2, 2) 
\         .Subtitle("""Layer(lena, grad, "mul", level=128, use_chroma=false)""", size=10, align=2)
\   )
\ )

Applies a defined alpha-mask to a clip, by converting RGB32-only mask_clip to greyscale and copying that greyscale information to the alpha channel of RGB32-only clip. In the alpha channel, "black" means transparent and "white" means opaque. For those of you who familiar with Photoshop masks, the concept is the same. In fact you can create a black and white photo in Photoshop, load it in your script and use it as a mask.

Mask(clip clip, clip mask_clip)

Examples

Suppose "ss.jpg" is a snapshot from a video clip, which served as a guideline to create the mask using Paint. We use ImageSource to load the image in the script and Mask to apply it.

bg  = AviSource("01gray.avi").ConvertToRGB32      # here is the background clip
mk  = ImageSource("ss.jpg").ConvertToRGB32        # load the image
top = AviSource("k3.avi").ConvertToRGB32.Mask(mk) # load the top layer clip and apply the mask to it
Layer(bg, top)                                    # layer the background and the top layer with mask

Applies an opaque (white) alpha channel to a clip. The alpha channel of an RGB32 clip is not always well-defined, depending on the source (it may contain random data); this filter is a fast way to apply an all-white mask.

ResetMask(clip clip)

Clears pixels in the alpha channel by comparing to a transparent color (default black).

Each pixel with a color differing less than (tolB,tolR,tolG) (default 10) is set to transparent (black); otherwise it is left unchanged – note, it is NOT set to opaque (white). That's why you might need ResetMask before applying this filter. This behaviour allows an aggregate mask to be constructed with multiple calls to ColorKeyMask.

When tolR or tolG are not set, they get the value of tolB by default. Normally you start with a ResetMask, then chain a few calls to ColorKeyMask to cause transparent holes where each color of interest occurs. See Overlay for examples.

ColorKeyMask(clip clip, int color [, int tolB, int tolG, int tolR])

clip  clip =

Source clip.

int  color = black

Transparent color. Default black.

int  tolB = 10

int  tolG = (tolB)

int  tolR = (tolB)

Color tolerance. See description above.