OverlayPlus

Latest revision as of 15:37, 27 October 2022

[edit] Description

OverlayPlus is a layering scrip similar to AviSynth's internal Overlay. It features:

• 33 blend modes.
• RGB colorspaces are processed without converting to YUV.
• YUV420/YUV422 colorspaces are processed without converting to YUV444.
• OverlayPlus in RGB produces results that are consistent with Photoshop and Gimp.

OverlayPlus is mainly a port of VapourSynth's Overlay script by HolyWu with some additional blending modes from Overlay_MTools. Blending mode "multiply128" was taken from FFmpeg.

[edit] Requirements

• [x86] / [x64]: AviSynth+
• Supported color formats: all planar and interleaved colorspaces are supported except YV411.

[edit] Required Plugins

Latest version of the following plugins are recommended unless stated otherwise.

• MaskTools2

[edit] Syntax and Parameters

OverlayPlus (clip base, clip overlay, clip "mask", string "mode", float "opacity", int "x", int "y", bool "chroma", bool "mask_first_plane", string "cplace", string "chromaresample")

clip   =

Base clip; all planar and interleaved colorspaces are supported except YV411. Output will always be planar YUV or RGB.

Properties such as dimensions, framerate, and length of the output clip will be the same as the base clip.

Alpha channel is copied from the base clip (if applicable).

• Note: OverlayPlus accepts mismatched colorspaces provided that they are in the same color family and bit depth.
  For example the base clip can be RGB32 and the overlay clip RGBP8/RGBAP8 or vice versa.
  Or in YUV the base clip can be YUVA420P16 and the overlay clip can be YUV420P16.

clip   =

Overlay clip must be the same colorspace as the base clip or can be mismatched as stated in the note.

Overlay clip does not have to be the same dimensions as the base clip.

• If the dimensions of the overlay clip are smaller, it will be top left aligned and padded accordingly.
• If the dimensions of the overlay clip are greater, it will be cropped at the bottom and right sides accordingly.

clip  mask = undefined

Optional transparency mask to use for the overlay clip.

Mask clip must be in full range (for example, 0-255 for 8 bit, 0-65535 for 16bit, 0.0-1.0 for 32bit float).

The darker the pixel, the more transparent the overlay clip will be; black (0) pixel means full transparency.

Mask clip must be the same colorspace as the base clip or can be mismatched as stated in the note.

Mask clip must have the same dimensions as the overlay clip.

If mask_first_plane=true, then the mask clip can be any colorspace but needs to have the same bitdepth as the base clip.

If the base clip is RGB or YUV444, an RGB or YUV444 mask can be used interchangeably, provided they are the same bitdepth.

string  mode = "blend"

Blend mode.

GROUP	BLEND MODE
Simple	average, blend (normal)
Darken	burn (colorburn), darken, linearburn, multiply, multiply128
Lighten	add (lineardodge), dodge (colordodge), lighten, linearadd (hypot), screen
Mix	hardlight, hardmix, interpolation, linearlight, overlay, pinlight, softburn, softdodge, softlight, softlight2, vividlight
Difference	difference, divide, exclusion, extremity, grainextract, grainmerge, linearsubtract, negation, phoenix, subtract
Names in parenthesis are aliases that can also be used.

float  opacity = 1.0

Blend transparency; the range is from 0.0 to 1.0, where 0.0 is transparent and 1.0 is fully opaque.

int  x = 0

int  y = 0

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

For subsampled colorspaces such as YUV420 both x and y must be mod2. For YUV422 only x must be mod2.

x=0, y=0 equals alignment at the top left corner of the frame.

bool  chroma = false

YUV chroma processing:

• True : process chroma planes
• False : copy chroma planes from base clip

For RGB all planes are always processed.

bool  mask_first_plane = true

When set to true, the first plane of the the mask clip will be used as a mask for all channels.

In other words, the luma (Y) channel on YUV or the red channel on RGB will be used as a mask.

This parameter is ignored when the mask clip is not defined.

string  cplace = "mpeg2"

Chroma location placement to use on the mask when resizing the chroma channels.

Only applicable when mask clip is defined, mask_first_plane=true and for YUV420 colorspaces only.

• "mpeg1" : also known as "center", "jpeg" and "chromaloc type 1" chroma placement.
• "mpeg2" : also known as "left" and "chromaloc type 0" chroma placement, most consumer SD/HD formats use this.
• "top_left" : also known as "chromaloc type 2"; used on UHD formats.

string  chromaresample = "bicubic"

Resizer to use on the mask chroma planes.

Only applicable when mask clip is defined, mask_first_plane=true and for YUV420/422 colorspaces only.

Available options: "point", "bilinear", "bicubic", "lanczos", "lanczos4", "blackman", "spline16", "spline36", "spline64", "gauss" and "sinc"

Default: "bicubic"

[edit] Examples

base    = Blankclip(color=$FFFFFF, pixel_type="RGBP8")
overlay = Colorbars(pixel_type="RGBP8")
mask    = Blankclip(color=$000000, pixel_type="RGBP8").Subtitle("AviSynth", size=150, align=5)

OverlayPlus(base, overlay, mask, mode="blend", opacity=1)

[edit] Changelog

Version      Date            Changes

1.3.0        2022/10/24      - Fix green stripe bug on subsampled colorspaces due to padding in the mask
                             - Added "chromaresample" parameter

1.2.0        2021/09/27      - mask_first_plane is ignored if the mask clip is a Y grayscale clip
                             - The chroma parameter now defaults to false for YUV clips
                             - Padding and cropping stage is bypassed when not needed
                             - A single frame mask is used when mask clip is undefined
                             - Correct output when all the following conditions are true: 
                              * mask is not defined, opacity=1.0, x=0, y=0, and overlay clip is a smaller dimension than the base clip
                             - If the base clip is RGB or YUV444, the mask clip can be either YUV444 or RGB

v1.1.0       2021/09/10      - Add support for all interleaved colorspaces (RBG24/32/48/64 and YUY2)
                             - Copy alpha channel from base clip when available
                             - Fix wrong output when opacity=1.0 and mask was not used and x or y > 0 
                             - Add "cplace" parameter
                             - Cosmetics and other minor improvements

v1.0.0       2021/09/02      - Public release

[edit] External Links

Back to External Filters ←