OverlayPlus

Revision as of 06:06, 23 September 2021

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 (line #298).

Requirements

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

Required Plugins

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

• MaskTools2

Syntax and Parameters

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

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.

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 = true

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.

string  cplace = "mpeg2"

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

Only applicable when mask_first_plane=true and for YUV420 or YUV422 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.
• "topleft" : also known as "chromaloc type 2"; used on UHD formats and only available for YUV 4:2:0 colorspaces.

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)

Changelog

Version      Date            Changes

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

External Links

Back to External Filters ←