## Overlay

`Overlay` (clip, clip overlay, int "x", int "y", clip "mask", float "opacity", string "mode", bool "greymask", string "output", bool "ignore_conditional", bool "pc_range")
`Overlay` は、さまざまなオーバーレイ*1手法を使って、オプションでオーバーレイする画像の座標をずらして 2 つのクリップを重ねます。さらに overlay クリップの不透明度を調整することも可能です。
入力は、どのような色空間でもかまいません。異なるクリップの色空間は問題にならないのです！入力クリップは、内部で一般的な YUV フォーマット（色差のサブサンプリングなし）に変換されます。このため、入力とは別の色空間で出力することも可能です。また、異なる色空間のビデオも、シームレスに変換されるため、入力が可能です。しかし、（`Convert` フィルタに比べて）遅くてわずかに品質も劣るため、色空間変換のため”だけ”に Overlay フィルタを使用することはおすすめできません。
通常、すべてのクリップは 0->255 の値を持っているものとして扱われます。要するに、数値は ITU-R BT.601 の範囲でクリッピングされません。このタスクを遂行するには、あとで `Limiter` を使用してください。
マスクも 0->255 の値を持つべきです。色の分布を見るには、`Histogram` を `Histogram`("levels") モードで使用することができます。もしマスクが ITU-R BT.601 の範囲にあるなら、色のレベルをアップスケールするために `ColorYUV`(levels="TV->PC") を使用してください。
何をやっているのか理解していない限り、インターレース素材にオーバーレイを実行することは推奨されません。

#### パラメータ:

clip
このクリップがベースになります。overlay 画像は、この上に配置されます。

overlay
こちらがベースクリップの上に配置される画像です。色空間や画像の大きさは、ベースクリップと一致する必要はありません。

x と y
これらの 2 つの変数は、ベースクリップ上の overlay 画像の位置をピクセル単位で定義します。正の数または負の数を指定することができます。
デフォルト値は 0 です。

mask
このクリップは、overlay 画像の透明度マスクとして使用されます。mask は、overlay クリップと同じ大きさでなければなりません。デフォルトでは、画像のグレースケール（輝度）成分のみが使用されます。この画像が暗ければ暗いほど、overlay 画像はより透明になります。
デフォルト値はありませんが、指定なしで 255 のクリップ*2を供給するのと同じになります。

opacity
このパラメータは、画像がどの程度透明になるかを設定します。値は 0.0 から 1.0 までで、0.0 なら透明、1.0 なら完全に不透明です（マスク不使用の場合）。マスクと併用した場合、この値にマスクの値が掛け合わされ、最終的な不透明度が決定されます。
デフォルト値は 1.0 です。

mode
mode（モード） は、クリップが画像の上にオーバーレイされる方法を定義します。

モード | 説明
--- | ---
Blend | これがデフォルトのモードです。opacity が 1.0 で、かつ mask がない場合、overlay 画像はオリジナルの上面にコピーされます。さもなければ、普通の透明ブレンドが使われます。
Add | overlay ビデオをベースビデオに付け足して、ビデオを明るくします。RGB と同等にするために、明るすぎる輝度領域は色差に影響を与えていて、より白っぽくしています。
Subtract | Add の反対。こちらは領域を暗くします。
Multiply | これも画像を暗くしますが、subtract とは異なる動作をします。
Chroma | overlay クリップの色情報のみをベース画像にオーバーレイします。
Luma | overlay クリップの輝度情報のみをベース画像にオーバーレイします。
Lighten | overlay がベース画像より明るい場合にのみ、明るさの情報を overlay クリップからベースクリップへコピーします。
Darken | overlay がベース画像より暗い場合にのみ、明るさの情報を overlay クリップからベースクリップへコピーします。
SoftLight | overlay クリップの明るさのレベルに基づいて、ベースクリップを明るくまたは暗くします。overlay が輝度 = 128 より暗いなら、ベース画像は暗くなります。overlay が輝度 = 128 より明るいなら、ベース画像は明るくなります。これは画像に影を付け足すのに役立ちます。純粋な黒または白で塗りつぶすと、はっきりと暗いまたは明るい領域が作られますが、純粋な黒または白にはなりません。
HardLight | overlay クリップの明るさのレベルに基づいて、ベースクリップを明るくまたは暗くします。overlay が輝度 = 128 より暗いなら、ベース画像は暗くなります。overlay が輝度 = 128 より明るいなら、ベース画像は明るくなります。これは画像に影を付け足すのに役立ちます。純粋な黒または白で塗りつぶすと、純粋な黒または白になります。
Difference | ベースクリップと overlay の差を表示します。Subtract のように、差が 0 の領域は灰色で表示されますが、輝度 = 126 ではなく 128 が使用されます。純粋な差を表示したいなら、mode="Subract" を使うか、ColorYUV(off_y=-128) を付け足してください。
Exclusion | overlay 画像の輝度に基づいて画像を反転します。白とブレンドするとベースの色の値を反転しますが、黒とブレンドすると何の変化も起こりません。

デフォルト値は Blend です。

greymask
このオプションは、色差の透明度のために mask の色差を使用するかどうかを指定します。一般的な目的のためには、このモードは無効化されるべきではありません。mSharpen や Masktools のような外部フィルタは、適切な色差のマップをエクスポートすることができます。
デフォルト値は、true です。

output
Overlay フィルタに別の色空間を返すことを可能にします。可能な出力色空間は、"YUY2"、"YV12"、"RGB32" と "RGB24" です。
デフォルトは、入力（ベースクリップ）のカラーフォーマットです。

ignore_conditional
与えられた条件変数を Overlay に無視させます。条件変数の概要については「条件変数」の項を参照してください。
デフォルトは false です。

pc_range
true に設定すると、内部の RGB -> YUV -> RGB 変換はすべて、輝度の範囲がデフォルトの 16->235 ではなく 0 から 255 までと仮定されます。何を行っているのか理解している場合にのみ、この設定を変更することをおすすめします。下記の「RGB で考慮すべき事柄」の項を参照。
デフォルトは false です。

### RGB で考慮すべき事柄

この節では、1 つ以上の RGB ソースを与えられたときに Overlay が取る挙動に関する説明を行います。
Overlay に対する 1 つ以上の入力は、RGB データであることを許可されています。しかしながら、Overlay は YUV 色空間で素材を処理しているため、RGB から YUV への変換が生じます。この変換には「pc_range」パラメータによって有効/無効が切り替えられる 2 つのモードがあります。このパラメータは、YUV の範囲を 16-235 （これはすべての AviSynth 変換で使われている範囲です）から 0-255 に伸張します。pc_range を有効化した方がいいケースがいくつかあります:

- "add" モード、"subtract" モード、または "multiply" モードを使って RGB クリップをオーバーレイするとき、真っ暗な領域が（すべての値に 16 を足す代わりに）結果に影響を与えられなくするために、overlay クリップの範囲は 0-255 の方が好ましいです。

- 出力時に色空間変換を行わないとき。出力色空間（RGB 対 YUV）が入力と異なるなら、スケールが間違っています。pc_range が true で、かつ、入力が RGB、出力が YUY2 なら、YUY2 は無効な範囲（ITU-R BT.601 の範囲ではない）を含みます。

RGB 出力

たとえ入力色空間が RGB であっても、YUV から RGB への色空間の再変換を回避するために、Overlay に YUY2 で出力させた方がいいかもしれません。しかし、pc_range = true を使用している場合、上述のように、素材が「オーバースケールされている」かもしれないということを知っておくべきです。16-235 の範囲に変換し戻すために、「ColorYUV(levels="pc->tv")」を使ってこれを補正することができます。

mask クリップに対する RGB 入力

RGB の mask クリップは、予想されるのとは少し異なった反応を示します。もしつねにグレースケールのマスクを使用しているのなら、「greymask」を無効にしないでください。そうすれば、期待通りの結果が得られるでしょう。mask クリップの値は伸張されないということに注意すべきです。RGB 値から直接コピーされ、自動的に 0->255 の範囲になります。

RGB32 のアルファチャンネルの使用

Overlay は、RGB32 クリップで与えられるアルファチャンネルを使用しません。RGB32 クリップのアルファチャンネルを抽出したいのなら、アルファ情報を抽出するために `ShowAlpha` コマンドを使用することができます。最高品質を維持するには、RGB としてアルファを抽出することをおすすめします。

### 条件変数

グローバル変数の「OL_opacity_offset」、「OL_x_offset」、「OL_y_offset」は、フレームごとに読み込まれ、適用されます。`FrameEvaluate` を使って、これらの変数を修正することが可能です。これらの変数の値は、各フレームのオリジナルの値に足されます。もしフィルタパラメータとして「x = 100」と指定し、かつ、グローバル変数「OL_x_offset」が 50 に設定されたなら、overlay クリップは x = 150 に配置されます。
もし複数のフィルタを使用しているのなら、「ignore_conditional = true」パラメータを使って、これを無効化することも可能です。

`ConditionalReader` のページには、条件修正の使用例があります。

### 使用例

# いくつかのソースを用意してください。

    bg = colorbars(512,384).converttoyuy2()
    text = blankclip(bg).subtitle("Colorbars", size=92, text_color=$ffffff).coloryuv(levels="tv->pc")

# 3 つの異なるバージョンでテキストをオーバーレイする。

    overlay(bg, text, x=50, y=20, mode="subtract", opacity=0.25)
    overlay(text, x=50, y=120, mode="add", opacity=0.5)
    overlay(text, x=50, y=240, mode="blend", opacity=0.7)

# yuy2 マスクを使って yuy2clip を rgbclip にオーバーレイする（マスクの輝度の範囲は [0-255] です）。

    Overlay(yuy2clip, rgbclip, mask = rgbclip.ShowAlpha("yuy2"))

# 下に同じ

    mask = rgbclip.ShowAlpha("rgb").ConvertToYUY2.ColorYUV(levels="TV->PC")
    Overlay(yuy2clip, rgbclip, mask)

# 下に同じ

    mask = rgbclip.ShowAlpha("rgb")
    Overlay(yuy2clip, rgbclip, mask)

# 2 つのクリップの平均をとる。例えばノイズ低減のために 2 つの異なる放送のキャプチャを合成するために使用することができる。このアイデアに関する議論は [こちらにある。サンプルスクリプト（もちろん 2 つのクリップのフレームが正確に一致することを確保しなければならない。必要なら DeleteFrame を使用すること）:

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

# 青色（または他の色）の背景（blue.jpg は黒色の長方形の中に字幕をオーバーレイした青色のフレーム）をマスクとして使用。字幕を含む黒色の長方形はソースクリップ（ここでは ColorBars）の上に見える:

    testcard = ColorBars()

    # 青色のマスククリップを取得（ColorBars と同じ青色を使用: R16 G16 B180）
    maskclip = BlankClip(clip=testcard, color=$0f0fb4)

    # 上述のとおり青色の背景付きの字幕ファイルの例
    subs = ImageSource("F:\TestClips\blue.jpg").ConvertToRGB32

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

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

青色が完全に均一ではないため、tolerance*3 = 60 が使用されています。黒い長方形の近くでは、青色は R23 G22 B124 になっています。おそらく blue.jpg の圧縮によるものでしょう。

# ConditionalReader を使ってクリップ上の赤色（または他の色）の点を移動させる（dot.bmp は黒色の背景の上に赤色の点がある）:

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

    # a2.GreyScale は黒色の背景の上にある灰色の点を返し、Levels はそのドットを白にする
    mask_clip = Mask(a2, a2.GreyScale.Levels(0, 1, 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)

以下のように、移動する点の x 座標を含む xoffset.txt と y 座標を含む yoffset.txt を作成してください（詳しくは ConditionalReader を参照）。そして、それらのテキストファイルを AviSynth スクリプトと同じフォルダに置いてください:

    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

点は、次のように移動します: (20,20) -> (250,350) -> (400,40)。Animate を使って同様のことを行うことも可能です。

### 更新履歴:

v2.54 | 初版

`原文 Date: 2007/12/03 22:56:04`
`日本語訳 $Date: 2008/06/28 00:58:31 $`

- 訳者註:
  - *1 参考: オーバーレイ (情報工学) - Wikipedia
  - *2 完全に白色のクリップに相当します。つまり、overlay 画像は完全に不透明になります。
  - *3 ColorKeyMask の tolerance パラメータ。Layer の ColorKeyMask の節を参照。