Overlay

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
m (bad link)
(Update for Avisynth+)
 
(9 intermediate revisions by one user not shown)
Line 1: Line 1:
<div style="max-width:62em" >
+
<div style="max-width:82em; min-width:42em;" >
 +
{{AvsStarFilter}}<div style="max-width:62em" >
 
Puts clip {{FuncArg|overlay}} on top of clip {{FuncArg|base}} using different blend {{FuncArg|modes}}, and with optional {{FuncArg|x}},{{FuncArg|y}} positioning, {{FuncArg|mask}}ing and {{FuncArg|opacity}}.
 
Puts clip {{FuncArg|overlay}} on top of clip {{FuncArg|base}} using different blend {{FuncArg|modes}}, and with optional {{FuncArg|x}},{{FuncArg|y}} positioning, {{FuncArg|mask}}ing and {{FuncArg|opacity}}.
 +
</div>
 +
<div style="max-width:62em" >
 +
*Input clips ({{FuncArg|base}}, {{FuncArg|overlay}} and {{FuncArg|mask}}) are converted to [[YV24]] internally. The output is re-converted to the input colorspace (or to the {{FuncArg|output}} colorspace, if specified).
 +
<div {{ListItemContinue}} >
 +
{{AvsPluscon}} works a little differently, no 4:4:4 conversion occurs for "blend", "luma" and "chroma" modes; see [[#use444|{{FuncArg|use444}}]], below.</div>
  
*Input clips ({{FuncArg|base}}, {{FuncArg|overlay}} and {{FuncArg|mask}}) are converted to [[YV24]] internally. The output is re-converted to the input colorspace (or to the {{FuncArg|output}} colorspace, if specified).
+
*In general all clips are treated as full-range values. This means that numbers will not be clipped at TV range; you may use [[Limiter]] for this task afterwards. If your {{FuncArg|mask}} is TV-range, you should convert it to full-range,or the mask will never be fully opaque.
 
+
*In general all clips are treated as 0&ndash;255 values. This means that numbers will not be clipped at CCIR-601 range; you may use [[Limiter]] for this task afterwards. If your {{FuncArg|mask}} is 16&ndash;235, convert it to 0&ndash;255 &ndash; for example, with [[ColorYUV]](levels="TV->PC") &ndash; or the mask will never be fully opaque.
+
  
 
*It is not recommended to do overlays on [[Interlaced_fieldbased|interlaced]] material, unless you know what you are doing.  
 
*It is not recommended to do overlays on [[Interlaced_fieldbased|interlaced]] material, unless you know what you are doing.  
Line 16: Line 20:
 
{{Template:FuncDef
 
{{Template:FuncDef
 
|Overlay(clip ''clip'', clip ''overlay'' [, int ''x'', int ''y'', clip ''mask'', float ''opacity'', string ''mode'',<br>
 
|Overlay(clip ''clip'', clip ''overlay'' [, int ''x'', int ''y'', clip ''mask'', float ''opacity'', string ''mode'',<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool ''greymask'', string ''output'', bool ''ignore_conditional'', bool ''pc_range'' ] )
+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool ''greymask'', string ''output'', bool ''ignore_conditional'', bool ''pc_range'' ] )
 +
}}
 +
 
 +
{{Template:FuncDef
 +
|Overlay(clip ''clip'', clip ''overlay'' [, int ''x'', int ''y'', clip ''mask'', float ''opacity'', string ''mode'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool ''greymask'', string ''output'', bool ''ignore_conditional'', bool ''pc_range'', bool ''use444'' ] ) {{AvsPluscon}}
 
}}
 
}}
  
Line 29: Line 38:
 
::Define the placement of the overlay image on the base clip, in pixels. Can be positive or negative.
 
::Define the placement of the overlay image on the base clip, in pixels. Can be positive or negative.
  
:{{Par2|mask|clip|}}
+
:{{Par2|mask|clip|(full opacity)}}
::Optional transparency mask. Must be the same size as {{FuncArg|overlay}}. Where {{FuncArg|mask}} is darker, {{FuncArg|overlay}} will be more transparent. By default only the greyscale (luma) components are used, but this can be overridden with {{FuncArg|greymask}}=true.
+
::Optional ''transparency mask''. Must be the same size as {{FuncArg|overlay}}. Where {{FuncArg|mask}} is darker, {{FuncArg|overlay}} will be more transparent. Must be 0-255 range (in general: 0 - 2^N-1 range for N bits format). By default only the greyscale (luma) components are used, but this can be overridden with {{FuncArg|greymask}}=false.
::''There is no default, but not specifying is equivalent to supplying a 255 clip.''
+
  
 
:{{Par2|opacity|float|1.0}}
 
:{{Par2|opacity|float|1.0}}
::Set {{FuncArg|overlay}} transparency. The value is from 0.0 to 1.0, where 0.0 is transparent and 1.0 is fully opaque (if no mask is used). This value is multiplied by {{FuncArg|mask}} luminance to form the final opacity.
+
::Set {{FuncArg|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 {{FuncArg|mask}} luminance to form the final opacity.
  
 
:{{Par2|mode|string|"blend"}}
 
:{{Par2|mode|string|"blend"}}
::Defines how your clip should be overlaid on your image.
+
::Defines how your {{FuncArg|overlay}} should be blended with your base image.
::{| class="wikitable" style="max-width:60em!important"
+
<div style="max-width:56em;margin:0 0 0 3.5em" >
 +
{| class="wikitable" style="max-width:60em!important"
 +
! Mode
 +
! Example
 +
! Description
 
|-  
 
|-  
| '''Mode'''
+
|style="vertical-align:top"| Blend
| '''Description'''
+
|[[File:Layer-base-Lena.png]] [[File:Layer-over-grad.png]]
 +
 
 +
[[File:Overlay-example-blend.png]]
 +
|style="vertical-align:top"| The default mode: ordinary blending in proportion to {{FuncArg|opacity}}.
 
|-  
 
|-  
| Blend
+
|style="vertical-align:top"| Add
| The default mode. When opacity is 1.0 and there is no mask the overlay image will be copied on top of the original. Ordinary transparent blending is used otherwise.
+
|style="vertical-align:top"| [[File:Overlay-example-add.png]]
 +
|style="vertical-align:top"| 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.{{Clarify}}
 
|-  
 
|-  
| Add
+
|style="vertical-align:top"| Subtract
| 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.{{Clarify}}
+
|style="vertical-align:top"| [[File:Overlay-example-subtract.png]]
 +
|style="vertical-align:top"| The opposite of ''Add''. Make the video darker.
 
|-  
 
|-  
| Subtract
+
|style="vertical-align:top"| Multiply
| The opposite of Add. Make the video darker.
+
|style="vertical-align:top"| [[File:Overlay-example-multiply.png]]
 +
|style="vertical-align:top"| Darkens the image in proportion to {{FuncArg|overlay}} lightness.
 
|-  
 
|-  
| Multiply
+
|style="vertical-align:top"| Chroma
| Darkens the image in proportion to {{FuncArg|overlay}} lightness.
+
|style="vertical-align:top"| [[File:Overlay-example-chroma.png]]
 +
|style="vertical-align:top"| Overlay only the color information of the overlay clip on to the base image.
 
|-  
 
|-  
| Chroma
+
|style="vertical-align:top"| Luma
| Overlay only the color information of the overlay clip on to the base image.
+
|style="vertical-align:top"| [[File:Overlay-example-luma.png]]
 +
|style="vertical-align:top"| Overlay only the luminosity information of the overlay clip on to the base image.
 
|-  
 
|-  
| Luma
+
|style="vertical-align:top"| Lighten
| Overlay only the luminosity information of the overlay clip on to the base image.
+
|style="vertical-align:top"| [[File:Overlay-example-lighten.png]]
 +
|style="vertical-align:top"| Use {{FuncArg|overlay}} only where it is lighter than the base image.
 
|-  
 
|-  
| Lighten
+
|style="vertical-align:top"| Darken
| Use {{FuncArg|overlay}} only where it is lighter than the base image.
+
|style="vertical-align:top"| [[File:Overlay-example-darken.png]]
 +
|style="vertical-align:top"| Use {{FuncArg|overlay}} only where it is darker than the base image.
 
|-  
 
|-  
| Darken
+
|style="vertical-align:top"| SoftLight
| Use {{FuncArg|overlay}} only where it is darker than the base image.
+
|style="vertical-align:top"| [[File:Overlay-example-softlight.png]]
 +
|style="vertical-align:top"| Lighten or darken the base clip, based on {{FuncArg|overlay}} luma. Where {{FuncArg|overlay}} luma is darker than 128, the output will be darker. Where {{FuncArg|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 {{FuncArg|overlay}} produces a distinctly darker or lighter area, but unlike ''HardLight'', does not result in pure black or white output.
 
|-  
 
|-  
| SoftLight
+
|style="vertical-align:top"| HardLight
| Lighten or darken the base clip, based on the light level of the overlay clip. If the overlay luma is darker than 128, the base image will be darker. If the overlay luma is lighter than 128, the base image will be lighter. This is useful for adding shadows to an image. Painting with pure black or white produces a distinctly darker or lighter area, but (unlike ''HardLight'') does not result in pure black or white.
+
|style="vertical-align:top"| [[File:Overlay-example-hardlight.png]]
 +
|style="vertical-align:top"| Lighten or darken the base clip, based on {{FuncArg|overlay}} luma. Where {{FuncArg|overlay}} luma is darker than 128, the output will be darker. Where {{FuncArg|overlay}} luma is lighter than 128, the output will be lighter. Pure black or white in the {{FuncArg|overlay}} results in pure black or white in the output.
 
|-  
 
|-  
| HardLight
+
|style="vertical-align:top"| Difference
| Lighten or darken the base clip, based on the light level of the overlay clip. If the overlay luma is darker than 128, the base image will be darker. If the overlay luma is lighter than 128, the base image will be lighter. This is useful for adding shadows to an image. Painting with pure black or white results in pure black or white.
+
|style="vertical-align:top"| [[File:Overlay-example-difference.png]]
 +
|style="vertical-align:top"| 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).
 
|-  
 
|-  
| Difference
+
|style="vertical-align:top"| Exclusion
| 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).
+
|style="vertical-align:top"| [[File:Overlay-example-exclusion.png]]
|-  
+
|style="vertical-align:top"| 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.
| 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.
+
 
|}
 
|}
  
 
:{{Par2|greymask|bool|true}}
 
:{{Par2|greymask|bool|true}}
::Specifies whether {{FuncArg|}} chroma should be used for chroma transparency. Not generally recommended. External filters like [[mSharpen]] and [[Masktools]] are able to export proper chroma maps.
+
::Specifies whether {{FuncArg|}} 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.
  
 
:{{Par2|output|string|(input)}}
 
:{{Par2|output|string|(input)}}
 
::Set output colorspace. Possible values are "YV24", "YUY2", "YV12", "Y8", "RGB32" and "RGB24".
 
::Set output colorspace. Possible values are "YV24", "YUY2", "YV12", "Y8", "RGB32" and "RGB24".
 +
::{{AvsPluscon}} All 8-16 bits colorspaces e.g. "YUV420P14" and "RGB64"
  
 
:{{Par2|ignore_conditional|bool|false}}
 
:{{Par2|ignore_conditional|bool|false}}
::Ignore any given conditional (frame-by-frame) variables. See the [[#Conditional Variables]] section for more information.
+
::Ignore any given ''conditional'' ([[Runtime_environment|runtime]]) variables. See the [[#Conditional Variables|Conditional Variables]] section for more information.
  
 
:{{Par2|pc_range|bool|false}}
 
:{{Par2|pc_range|bool|false}}
::When set to true, this will make all internal RGB&rarr;YUV &rarr;RGB conversions assume that luma range is 0&ndash;255 instead of default 16&ndash;235 range. It is only recommended to change this setting if you know what you are doing. See [[#RGB considerations]] below.
+
::When set to true, this will make all internal RGB&rarr;YUV &rarr;RGB conversions assume that YUV sources are full-range instead of the default TV range. It is only recommended to change this setting if you know what you are doing. See [[#RGB considerations|RGB considerations]] below.
 +
 
 +
{{HiddenAnchor|use444}}
 +
:{{Par2|use444|bool|true}}
 +
::{{AvsPluscon}} If set to false, '''Overlay''' uses conversionless mode where possible instead of going through YUV 4:4:4. However, for Luma and Chroma {{FuncArg|mode}}s, RGB ''must'' be converted to YUV 4:4:4.
 +
:: default value is adaptive:
 +
:: false when mode="blend" and format is RGB
 +
:: false when mode="blend", "luma" or "chroma and format is YUV420/YUV422 (YV12/YV16). Original format is kept throughout the whole process, no 4:4:4 conversion occurs.
 +
:: true for all other cases (input is converted internally to 4:4:4)
 
</div>
 
</div>
  
Line 96: Line 128:
 
== RGB considerations ==
 
== RGB considerations ==
 
<div style="max-width:62em" >
 
<div style="max-width:62em" >
This may give you an explanation of why '''Overlay''' behaves like it does when it is given one or more RGB sources.
+
[[RGB]] inputs are accepted. However, as '''Overlay''' converts internally to [[YV24]] (see AVS+ exceptions), this will lead to an RGB&rarr;YUV conversion. There are two modes for this conversion, toggled by the {{FuncArg|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 {{FuncArg|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).
[[RGB]] inputs are accepted. However, as '''Overlay''' converts internally to [[YV24]], this will lead to an RGB&rarr;YUV conversion. There are two modes for this conversion, toggled by the {{FuncArg|pc_range}} parameter. This parameter will extend the YUV range from 16&ndash;235 (this is the range used by all avisynth converters) to 0&ndash;255. There are some cases where enabling {{FuncArg|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&ndash;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 {{FuncArg|pc_range}}=true, and input is RGB, while output is YUY2, the YUY2 will have an invalid range, and not CCIR-601 range.
 
* 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 {{FuncArg|pc_range}}=true, and input is RGB, while output is YUY2, the YUY2 will have an invalid range, and not CCIR-601 range.
 +
* {{AvsPluscon}} planar RGB formats are also supported besides 8 bit packed RGB formats and RGB48/RGB64.
 +
* {{AvsPluscon}} "blend" mode keeps original RGB format, no YUV intermediate conversion is used.
  
 
===== ''Outputting RGB'' =====
 
===== ''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 {{FuncArg|pc_range}}=true.  You can correct this by using <code>[[ColorYUV]](levels="pc->tv")</code> to convert back to 16-235 range.
+
:It might be a good idea to let '''Overlay''' output YV24 (or YUV444P10-16 in AVS+), 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 {{FuncArg|pc_range}}=true.  You can correct this by using <code>[[ColorYUV]](levels="pc->tv")</code> to convert back to 16-235 range (or equivalent ranges to 10+ bits).
  
 
===== ''Inputting RGB for mask clip'' =====
 
===== ''Inputting RGB for mask clip'' =====
:An RGB {{FuncArg|mask}} clip may behave a bit oddly if it contains color information. If you use a greyscale mask, or if you leave {{FuncArg|greymask}}=true, you will get the result you would expect. Note that {{FuncArg|mask}} values are never scaled, so it will automatically be in 0&ndash;255 range, directly copied from the RGB values.
+
:An RGB {{FuncArg|mask}} clip may behave a bit oddly if it contains color information. If you use a greyscale mask, or if you leave {{FuncArg|greymask}}=true, you will get the result you would expect. Note that {{FuncArg|mask}} values are never scaled, so it will automatically be in full-range, directly copied from the RGB values.
  
===== ''Using RGB32 alpha channel'' =====
+
===== ''Using RGB32, {{AvsPluscon}} RGB64 or planar RGBA 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 &mdash; for example, <code>Overlay(kitten, mask=kitten.ShowAlpha)</code>. For maintaining maximum quality it is recommended to extract the alpha as RGB.
+
:'''Overlay''' ignores the ''alpha'' (transparency) channel in an [[RGB32]] clip. If you want the alpha, you can use something like <code>Overlay(kitten, mask=kitten.[[ShowAlpha]]("RGB32"))</code>. For maximum quality, it is recommended to extract the alpha as RGB.
  
 
===== ''Repeated overlays on RGB base clip'' =====
 
===== ''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&rarr;YV24&rarr;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.
+
:When doing repeated partial overlays on an RGB base clip, the unchanged parts of the base clip will undergo a RGB&rarr;YV24&rarr;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 4:4:4 format (e.g. YV24) before doing the overlays and convert back to RGB afterwards.
 
</div>
 
</div>
  
Line 118: Line 150:
 
== Conditional Variables ==
 
== Conditional Variables ==
 
<div style="max-width:62em" >
 
<div style="max-width:62em" >
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]] &ndash; see example [[#ConditionalReader|below]].  
+
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]] &ndash; see example [[#ConditionalReader|below]].  
  
 
These values, after evaluation, will be added to the relevant filter parameters &mdash; for example, if you specify {{FuncArg|x}}=100 as a filter parameter, and '''ol_x_offset'''=50, the {{FuncArg|overlay}} clip will be positioned at x=150. This behaviour can be disabled by using {{FuncArg|ignore_conditional}}=true.
 
These values, after evaluation, will be added to the relevant filter parameters &mdash; for example, if you specify {{FuncArg|x}}=100 as a filter parameter, and '''ol_x_offset'''=50, the {{FuncArg|overlay}} clip will be positioned at x=150. This behaviour can be disabled by using {{FuncArg|ignore_conditional}}=true.
Line 194: Line 226:
 
|}
 
|}
  
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 &ndash; probably due to the compression artifacts of '''blue.jpg'''.
+
A tolerance of 60 is used here because the blue is not entirely uniform. Near the black rectangles the blue is given by R=23,G=22,B=124 &ndash; probably due to the compression artifacts of '''blue.jpg'''.
  
  
Line 249: Line 281:
  
 
thus the dot moves in the following way: (20,20)&rarr;(250,350)&rarr;(400,40). It's also possible to do this using script variables in place of text files, with [[Animate]].
 
thus the dot moves in the following way: (20,20)&rarr;(250,350)&rarr;(400,40). It's also possible to do this using script variables in place of text files, with [[Animate]].
 +
</div>
 +
 +
 +
== See also ==
 +
<div style="max-width:62em" >
 +
* [[Merge]], [[MergeChroma]] and [[MergeLuma]] &ndash; simple blending in any colorspace.
 +
<div {{ListItemContinue}} >
 +
Base and overlay colorspaces must match.
 +
</div>
 +
* [[Layer]], which supports YUY2 and RGB32 without internal conversion. Supports RGB32 alpha-channel masking.
 +
<div {{ListItemContinue}} >
 +
Base and overlay colorspaces must match.
 +
</div>
 +
* [[Uu_mt_blend|uu_mt_blend]], which does not support masking, but supports YV12, RGB24 and RGB32 blending without internal conversion.
 +
<div {{ListItemContinue}} >
 +
Base and overlay colorspaces must match. Wide selection of blend modes. Most blend modes work best in RGB.
 +
</div>
 +
* [[Fusion]], which uses image pyramids to blend clips together; most often used in the creation of [[Wikipedia:High-dynamic-range_imaging|HDR]] images and image stitching.
 +
 +
* and more &ndash; see [[External_filters#Averaging.2FLayering.2FMasking|External Filters: Averaging/Layering/Masking]]
 
</div>
 
</div>
  
Line 254: Line 306:
 
== Changelog ==
 
== Changelog ==
 
{| border="1"
 
{| border="1"
 +
|-
 +
| {{AvsPluscon}}
 +
| Added 10-16 bit formats, incl. Planar RGB.
 +
| Added 32 bit float support for "blend"
 +
| Added 4:4:4 conversionless mode for "blend"
 
|-  
 
|-  
 
| v2.6
 
| v2.6
Line 264: Line 321:
 
| Initial Release.
 
| Initial Release.
 
|}
 
|}
 
+
</div>
  
 
[[Category:Internal filters]]
 
[[Category:Internal filters]]
 
[[Category:Layering]]
 
[[Category:Layering]]

Latest revision as of 11:11, 13 December 2018

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).
AVS+ works a little differently, no 4:4:4 conversion occurs for "blend", "luma" and "chroma" modes; see use444, below.
  • In general all clips are treated as full-range values. This means that numbers will not be clipped at TV range; you may use Limiter for this task afterwards. If your mask is TV-range, you should convert it to full-range,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.


Contents


[edit] 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 ] )

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, bool use444 ] ) AVS+


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 = (full opacity)
Optional transparency mask. Must be the same size as overlay. Where mask is darker, overlay will be more transparent. Must be 0-255 range (in general: 0 - 2^N-1 range for N bits format). By default only the greyscale (luma) components are used, but this can be overridden with greymask=false.
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 Example Description
Blend Layer-base-Lena.png Layer-over-grad.png

Overlay-example-blend.png

The default mode: ordinary blending in proportion to opacity.
Add Overlay-example-add.png 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 Overlay-example-subtract.png The opposite of Add. Make the video darker.
Multiply Overlay-example-multiply.png Darkens the image in proportion to overlay lightness.
Chroma Overlay-example-chroma.png Overlay only the color information of the overlay clip on to the base image.
Luma Overlay-example-luma.png Overlay only the luminosity information of the overlay clip on to the base image.
Lighten Overlay-example-lighten.png Use overlay only where it is lighter than the base image.
Darken Overlay-example-darken.png Use overlay only where it is darker than the base image.
SoftLight Overlay-example-softlight.png 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 Overlay-example-hardlight.png 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 Overlay-example-difference.png 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 Overlay-example-exclusion.png 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".
AVS+ All 8-16 bits colorspaces e.g. "YUV420P14" and "RGB64"
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 YUV sources are full-range instead of the default TV range. It is only recommended to change this setting if you know what you are doing. See RGB considerations below.
bool  use444 = true
AVS+ If set to false, Overlay uses conversionless mode where possible instead of going through YUV 4:4:4. However, for Luma and Chroma modes, RGB must be converted to YUV 4:4:4.
default value is adaptive:
false when mode="blend" and format is RGB
false when mode="blend", "luma" or "chroma and format is YUV420/YUV422 (YV12/YV16). Original format is kept throughout the whole process, no 4:4:4 conversion occurs.
true for all other cases (input is converted internally to 4:4:4)


[edit] RGB considerations

RGB inputs are accepted. However, as Overlay converts internally to YV24 (see AVS+ exceptions), 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.
  • AVS+ planar RGB formats are also supported besides 8 bit packed RGB formats and RGB48/RGB64.
  • AVS+ "blend" mode keeps original RGB format, no YUV intermediate conversion is used.
[edit] Outputting RGB
It might be a good idea to let Overlay output YV24 (or YUV444P10-16 in AVS+), 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 (or equivalent ranges to 10+ bits).
[edit] 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 full-range, directly copied from the RGB values.
[edit] Using RGB32, AVS+ RGB64 or planar RGBA alpha channel
Overlay ignores the alpha (transparency) channel in an RGB32 clip. If you want the alpha, you can use something like Overlay(kitten, mask=kitten.ShowAlpha("RGB32")). For maximum quality, it is recommended to extract the alpha as RGB.
[edit] 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 4:4:4 format (e.g. YV24) before doing the overlays and convert back to RGB afterwards.


[edit] 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.


[edit] 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)
 Overlay blue.jpg   Overlay subs.png 
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 R=23,G=22,B=124 – 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:

 Overlay dot.png   Overlay dot2.png 
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.


[edit] See also

Base and overlay colorspaces must match.

  • Layer, which supports YUY2 and RGB32 without internal conversion. Supports RGB32 alpha-channel masking.

Base and overlay colorspaces must match.

  • uu_mt_blend, which does not support masking, but supports YV12, RGB24 and RGB32 blending without internal conversion.

Base and overlay colorspaces must match. Wide selection of blend modes. Most blend modes work best in RGB.

  • Fusion, which uses image pyramids to blend clips together; most often used in the creation of HDR images and image stitching.


[edit] Changelog

AVS+ Added 10-16 bit formats, incl. Planar RGB. Added 32 bit float support for "blend" Added 4:4:4 conversionless mode for "blend"
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.
Personal tools