Overlay

Puts clip overlay on top of clip base using different blend modes, and with optional x,y positioning, masking and opacity.

• Input clips (base, overlay and mask) are converted to YV24 internally. The output is re-converted to the input colorspace (or to the output colorspace, if specified).

• In general all clips are treated as 0–255 values. This means that numbers will not be clipped at CCIR-601 range; you may use Limiter for this task afterwards. If your mask is 16–235, convert it to 0–255 – for example, with ColorYUV(levels="TV->PC") – or the mask will never be fully opaque.

• It is not recommended to do overlays on interlaced material, unless you know what you are doing.

Syntax and Parameters

Overlay(clip clip, clip overlay [, int x, int y, clip mask, float opacity, string mode,
      bool greymask, string output, bool ignore_conditional, bool pc_range ] )

clip  clip = (required)

This clip will be the base, determining the size and all other video and audio properties of the result, and the overlay picture will be placed on top of this.

clip  overlay = (required)

This is the image that will be placed on top of the base clip. The colorspace or image dimensions do not have to match the base clip.

int  x, y = 0

Define the placement of the overlay image on the base clip, in pixels. Can be positive or negative.

clip  mask =

Optional transparency mask. Must be the same size as overlay. Where mask is darker, overlay will be more transparent. By default only the greyscale (luma) components are used, but this can be overridden with greymask=false.

There is no default, but not specifying is equivalent to supplying a 255 clip.

float  opacity = 1.0

Set overlay transparency. The value is from 0.0 to 1.0, where 0.0 is transparent and 1.0 is fully opaque. This value is multiplied by mask luminance to form the final opacity.

string  mode = "blend"

Defines how your overlay should be blended with your base image.

Mode	Description
Blend	The default mode: ordinary blending in proportion to opacity.
Add	Add the overlay video to the base video, making the video brighter. To make this as comparable to RGB, overbright luma areas are influencing chroma and making them more white.[clarification needed]
Subtract	The opposite of Add. Make the video darker.
Multiply	Darkens the image in proportion to overlay lightness.
Chroma	Overlay only the color information of the overlay clip on to the base image.
Luma	Overlay only the luminosity information of the overlay clip on to the base image.
Lighten	Use overlay only where it is lighter than the base image.
Darken	Use overlay only where it is darker than the base image.
SoftLight	Lighten or darken the base clip, based on overlay luma. Where overlay luma is darker than 128, the output will be darker. Where overlay luma is lighter than 128, the output will be lighter. This is useful for adding shadows to an image. Pure black or white in the overlay produces a distinctly darker or lighter area, but unlike HardLight, does not result in pure black or white output.
HardLight	Lighten or darken the base clip, based on overlay luma. Where overlay luma is darker than 128, the output will be darker. Where overlay luma is lighter than 128, the output will be lighter. Pure black or white in the overlay results in pure black or white in the output.
Difference	Display the difference between the clip and the overlay. Note that like Subtract, a difference of zero is displayed as grey, but with luma=128 instead of 126. If you want the pure difference, use mode="Subtract" or add ColorYUV(off_y=-128).
Exclusion	Invert the image based on the luminosity of the overlay image. Blending with white inverts the base color values; blending with black produces no change.

bool  greymask = true

Specifies whether chroma should be used for chroma transparency. Generally you want to leave this alone. External filters like mSharpen and Masktools are able to export proper chroma maps.

string  output = (input)

Set output colorspace. Possible values are "YV24", "YUY2", "YV12", "Y8", "RGB32" and "RGB24".

bool  ignore_conditional = false

Ignore any given conditional (runtime) variables. See the Conditional Variables section for more information.

bool  pc_range = false

When set to true, this will make all internal RGB→YUV →RGB conversions assume that luma range is 0–255 instead of default 16–235 range. It is only recommended to change this setting if you know what you are doing. See RGB considerations below.

RGB considerations

RGB inputs are accepted. However, as Overlay converts internally to YV24, this will lead to an RGB→YUV conversion. There are two modes for this conversion, toggled by the pc_range parameter. This parameter will extend the YUV range from 16–235 (this is the range used by all avisynth converters) to 0–255. There are some cases where enabling pc_range is a good idea:

• When overlaying an RGB clip using the add, subtract or multiply modes, the range of the overlay clip is better, if it is 0–255, since this will enable completely dark areas not to influence the result (instead of adding 16 to every value).
• When NOT doing a colorspace conversion on output. If the output colorspace (RGB vs. YUV) is different from the input, the scale will be wrong. If pc_range=true, and input is RGB, while output is YUY2, the YUY2 will have an invalid range, and not CCIR-601 range.

Outputting RGB

It might be a good idea to let Overlay output YV24, even if your input colorspace is RGB, as this avoids a colorspace conversion back to RGB from YUV. You should however be aware that your material might be "overscaled", as mentioned above, if you use pc_range=true. You can correct this by using ColorYUV(levels="pc->tv") to convert back to 16-235 range.

Inputting RGB for mask clip

An RGB mask clip may behave a bit oddly if it contains color information. If you use a greyscale mask, or if you leave greymask=true, you will get the result you would expect. Note that mask values are never scaled, so it will automatically be in 0–255 range, directly copied from the RGB values.

Using RGB32 alpha channel

Overlay will never use the alpha channel given in an RGB32 clip. If you want to extract the alpha channel from an RGB32 clip you can use the ShowAlpha command — for example, Overlay(kitten, mask=kitten.ShowAlpha). For maintaining maximum quality it is recommended to extract the alpha as RGB.

Repeated overlays on RGB base clip

When doing repeated partial overlays on an RGB base clip, the unchanged parts of the base clip will undergo a RGB→YV24→RGB conversion for each call to Overlay, producing a progressive loss of color accuracy. In these situations, it is better to convert the base clip to YV24 before doing the overlays and convert back to RGB afterwards.

Conditional Variables

The global variables OL_opacity_offset, OL_x_offset and OL_y_offset are evaluated for each frame. The values may be set using FrameEvaluate, or they may be read from a file using ConditionalReader – see example below.

These values, after evaluation, will be added to the relevant filter parameters — for example, if you specify x=100 as a filter parameter, and ol_x_offset=50, the overlay clip will be positioned at x=150. This behaviour can be disabled by using ignore_conditional=true.

There is an example of conditional modification at the ConditionalReader page.

Examples

# Prepares some sources.
bg = ColorBars(512,384).ConvertToYUY2
text = BlankClip(bg).Subtitle("Colorbars", size=92, 
\          text_color=$ffffff).ColorYUV(levels="tv->pc")

# Overlay the text in three different versions.
return Overlay(bg, text, x=50, y=20, mode="subtract", opacity=0.25)
return Overlay(text, x=50, y=120, mode="add", opacity=0.5)
return Overlay(text, x=50, y=240, mode="blend", opacity=0.7)

# Overlay yuy2 clip with rgb clip using a yuy2 mask
# (note that the luma range of the mask is [0-255]). 
return Overlay(yuy2clip, rgbclip, mask=rgbclip.ShowAlpha("yuy2"))

# ...which is the same as 
mask = rgbclip.ShowAlpha("rgb").ConvertToYUY2
\             .ColorYUV(levels="TV->PC")
return Overlay(yuy2clip, rgbclip, mask=mask)

# ...which is the same as 
mask = rgbclip.ShowAlpha("rgb")
return Overlay(yuy2clip, rgbclip, mask=mask)

This will take the average of two clips. It can be used for example to combine two captures of different broadcast captures for reducing noise. A discussion of this idea can be found here. A sample script (of course you have to ensure that the frames of the two clips matches exactly, using Trim as needed):

clip1 = AviSource("F:\shakira-underneath_your_clothes.avi")
clip2 = AviSource("F:\shakira-underneath_your_clothes2.avi")
Overlay(clip1, clip2, mode="blend", opacity=0.5)

Another use is to detect an altered video using Video Error Level Analysis (VELA), where clip2 is clip1 resaved using an h.263 Codec (e.g. XVID). This method is effective when the suspected altered video (clip1) has not been resaved multiple times. Levels is used to exaggerate contrast for view-ability:

clip1 = AviSource("SuspectVideo.avi")
clip2 = AviSource("SuspectVideo_resaved.avi")
result= Overlay(clip1,clip2,mode="Subtract").Levels(0, 5.0, 100, 0, 255)

Use a blue (or any other color) background (blue.jpg is a blue frame with subtitles in a black rectangle) as mask. The black rectangle containing the subtitles will be visible on the source clip (which is ColorBars here):

testcard = ColorBars

# get a blue mask clip (the same blue as in ColorBars is used: R16 G16 B180)
maskclip = BlankClip(testcard, color=$0f0fb4)

# Example subtitle file with blue backgroud as above
subs = ImageSource("F:\TestClips\blue.jpg").ConvertToRGB32

maskclip = ColorKeyMask(subs, $0f0fb4, 60)

Overlay(testcard, subs, mask=maskclip.ShowAlpha, mode="blend", opacity=1)

maskclip	overlay

A tolerance of 60 is used here because the blue is not entirely uniform. Near the black rectangles the blue is given by R23 G22 B124 – probably due to the compression artifacts of blue.jpg.

Move a red (or any other color) dot on a clip using ConditionalReader (dot.bmp is a red dot on a black background):

a1 = ColorBars.Trim(0,399)
a2 = ImageSource("F:\TestClips\dot.bmp").ConvertToRGB32

# a2.Greyscale returns a grey dot on a black background;
# Levels makes the dot white
mask_clip = Mask(a2, a2.GreyScale.Levels(0, 1.0, 75, 0, 255))
Overlay(a1, a2, mask=ShowAlpha(mask_clip), y=0, x=0,
\                              mode="blend", opacity=1)

ConditionalReader("xoffset.txt", "ol_x_offset", false)
ConditionalReader("yoffset.txt", "ol_y_offset", false)

Make xoffset.txt containing the x-positions and yoffset.txt containing the y-positions of the moving dot (see ConditionalReader for more info), and put it in the same folder as your script:

xoffset.txt:

Type int
Default -50

R 0 100 20
I 100 200 20 250
R 200 300 250
I 300 400 250 400

yoffset.txt:

Type int
Default -50
 
R 0 100 20
I 100 200 20 350
R 200 300 350
I 300 400 350 40

The figures:

dot.bmp over black	dot.bmp over color bars

thus the dot moves in the following way: (20,20)→(250,350)→(400,40). It's also possible to do this using script variables in place of text files, with Animate.

Changelog

v2.6	Added output="Y8", "YV24"; input: "Y8", "YV16" and "YV24".
v2.55	mode="Multiply" functionality has changed, so it works as it supposed to do.
v2.54	Initial Release.