### [yv12][yuy2][rgb32][rgb24]

# 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: klip, który zostanie nałożony na klip zadany parametrem clip; rozmiar i przestrzeń kolorów może inna niż podstawowego klipu
x, y: te dwie zmienne (wyrażone w pikselach) określają położenie obrazu nakładanego na klip. Mogą przyjmować wartości dodatnie i ujemne (domyślnie x=y=0)
mask: klip ten zostanie użyty jako maska przezroczystości dla nakładanego obrazu. Rozmiar maski musi być taki sam jak klipu zadanego parametrem overlay. Domyślnie tylko sygnał lumy jest używany jako maska. Im maska będzie ciemniejsza, tym nakładany obraz będzie bardziej przezroczysty (parametr ten nie ma wartości domyślnej, lecz gdy nie jest podany, to maska będzie klipem o luminancji równej 255)
opacity: określa poziom przezroczystości obrazu. Przyjmuje on wartości z przedziału [0.0, 1.0]. Przy opacity=0 obraz jest w pełni przezroczysty, a przy opacity=1.0 jest całkowicie nieprzezroczysty (jeżeli nie została użyta maska). Gdy jest on używany łącznie z maską to jego wartość jest przemnażana przez wartości mask i w ten sposób uzyskiwana jest końcowa przezroczystość

mode: określa sposób, którym klip będzie nakładany na obraz (dokładny opis przyjmowanych wartości jest umieszczony w tabelce na końcu dokumentu); domyślnie mode="blend"
greymask: określa czy sygnał chromy z maski zostanie użyty dla przezroczystości chromy. Do zastosowań powszechnych zaleca się wyłączenie (greymask=false) tej opcji. Zewnętrzne filtry takie jak mSharpen i Masktools są w stanie prawidłowo dostarczyć mapy chrominacji; domyślnie greymask=true

output: parametr ten umożliwia zwrócenie klipu w innej przestrzeni kolorów. Dostępne przestrzenie to "YUY2", "YV12", "RGB24" i "RGB32". Domyślnie przestrzeń wyjściowa jest równa przestrzeni zadanej parametrem clip
ignore_conditional: gdy jego wartość jest równa true to filtr ignoruje zmienne warunkowe. W celu zapoznania się ze zmiennymi warunkowymi zajrzyj do części "Zmienne warunkowe" (poniżej); domyślnie ignore_conditional=false

pc_range: gdy równy jest true, to umożliwi wewnętrzną konwersję RGB -> YUV -> RGB przy założeniu, że wartości lumy są z zakresu [0, 255], a nie jak domyślnie [16, 235]. Zmiana tego ustawienia na true jest zalecana tylko pod warunkiem świadomego działania (zobacz "Uwagi dotyczące przestrzeni RGB"); domyślnie pc_range=false

Overlay nakłada na siebie dwa klipy używając do tego różnych metod nakładania. Nakładany obraz może być także przemieszczony. Możliwe jest także ustalenie parametru przezroczystości dla nakładanego klipu.
Nakładany klip może być w dowolnej przestrzeni kolorów, co więcej przestrzenie dwóch klipów mogą się różnić. Klipy wejściowe są wewnętrznie konwertowane do formatu YUV, co umożliwia filtrowi wygenerowanie klipu w innej przestrzeni niż wejściowa. Możliwe jest użycie różnych przestrzeni dla każdego z klipów, ponieważ i tak zostaną one przekonwertowane do YUV. Jednakże nie powinno się używać Overlay tylko jako filtru służącego do zmiany przestrzeni kolorów, ponieważ taka zmiana jest wolna i daje w wyniku niewielkie straty na jakości.
Na ogół we wszystkich klipach sygnały lumy i chromy są traktowane jako wartości z przedziału [0, 255]. Oznacza to, że nie zostaną one ograniczone do wartości obowiązujących dla standardu CCIR 601. Jeżeli chcesz ograniczyć sygnały lumy i chromy to po Overlay użyj filtru Limiter. W celu obejrzenia rozkładu kolorów możesz użyć filtru Histogram w trybie Histogram("levels"). Jeżeli w klipie zadanym parametrem mask wartości kolorów mieszczą się w zakresie [16, 235] (standard CCIR 601), to wtedy możesz skorzystać z ColorYUV(levels="TV->PC"), by poszerzyć przedział wartości kolorów do zakresu [0, 255].
Nie zaleca się stosowania nakładek na materiale z przeplotem, chyba, że jest to wykonywane świadomie.
UWAGI DOTYCZĄCE PRZESTRZENI RGB:
W tej części opisu zostanie wyjaśnione zachowanie się filtru, gdy jeden lub więcej klipów jest w przestrzeni RGB.
Jeden lub więcej klipów wejściowych może być w przestrzeni RGB. Aczkolwiek w trakcie obróbki materiału w przestrzeni YUV konieczna będzie konwersja RGB -> YUV. Konwersja ta może być wykonana na dwa sposoby w zależności od parametru pc_range. Gdy pc_range=true to zostanie wykonana konwersja z zachowaniem pełnego zakresu tj. [0, 255] dla sygnałów lumy i chromy. W niektórych przypadkach może to być dobrym rozwiązaniem:

- Gdy nakładany jest klip w przestrzeni RGB przy użyciu trybów: "add", "subtract" lub "multiply", wtedy zakres nakładanego klipu jest lepszy (wartości 0-255), ponieważ umożliwi on uzyskanie całkowicie ciemnych obszarów, które nie będą miały wpływu na wynik końcowy. W ten sposób do każdej wartości nie będzie dodawana wartość 16.

- Gdy nie jest wykonywana konwersja przestrzeni kolorów na klipie wyjściowym. Jeżeli przestrzeń klipu wyjściowego (RGB) jest inna niż klipu wejściowego (YUV) wtedy skala sygnałów lumy i chromy będzie nieprawidłowa. Gdy pc_range=true, a klip wejściowy będzie w przestrzeni RGB, a wyjściowy w YUY2, to wtedy wartości sygnałów będą spoza przedziału [16, 235], tym samym nie będą spełniać założeń standardu CCIR 601.

Sposób postępowania przy materiale wejściowym w przestrzeni RGB
Dobrym pomysłem może być pozwolenie, aby Overlay na wyjściu dał przestrzeń YUY2 pomimo, że na wejściu klip był w przestrzeni RGB. Pozwala to uniknąć konwersji YUV -> RGB. Należy być jednak świadomym tego, że materiał wyjściowy może zostać "przeskalowany", jak wspomniano wcześniej (gdy zostanie użyty parametr pc_range=true). "Przeskalowanie" można skorygować do przedziału [16, 235] poprzez użycie ColorYUV(levels="PC->TV").
Używanie klipu RGB jako maski
Klip w przestrzeni RGB dla parametru mask może zachowywać się w inny sposób niż powinien. Jeżeli zawsze używałeś maski w odcieniach szarości, to pozostawiając parametr greymask=true (wartość domyślna) otrzymasz oczekiwany rezultat. Musisz wiedzieć, że dla klipu danego parametrem mask wartości nie są nigdy skalowane, tak więc automatycznie będą z zakresu [0, 255].
Używanie kanału alfa (przestrzeń RGB32)
Overlay nigdy nie użyje kanału alfa zawartego w klipie RGB32. Jeżeli chcesz wydzielić kanał alfa z klipu RGB32 to możesz użyć filtru ShowAlpha. W celu zachowania maksymalnej jakości zaleca się wydzielenie kanału alfa jako RGB.
Zmienne warunkowe
Zmienne globalne ol_opacity_offset, ol_x_offset i ol_y_offset są odczytywane co jedną klatkę, a następnie wykorzystywane. Zmienne te można modyfikować za pomocą FrameEvaluate. Wartości w ten sposób uzyskane zostaną dodane do zmiennych oryginalnych dla każdej klatki. Jeżeli ustawisz wartość parametru x=100 i zmienna globalna ol_x_offset będzie równa 50 to klip zostanie nałożony w pozycji x=150.
Jeżeli używasz wielu filtrów to modyfikację parametrów x, y i opacity można wyłączyć poprzez ustawienie parametru ignore_conditional na true. Przykład warunkowej modyfikacji został umieszczony przy opisie filtru ConditionalReader.

Wartości, które przyjmuje argument mode:

Blend (mieszanie) | Gdy opacity=1.0 i nie ma maski, klip zostanie skopiowany na klip będący podstawą. W innym przypadku klipy zostaną ze sobą zmieszane w stopniu danym przez opacity
Add (dodawanie) | W tym trybie nakładany klip zostanie dodany do klipu podstawowego zwiększając tym samym jego jasność. Używając analogii do przestrzeni RGB, obszary o zwiększonej luminancji wpływają na chrominację czyniąc te obszary jeszcze bardziej białymi
Subtract (odejmowanie) | Ten tryb daje odwrotny efekt niż Add, tzn. obszary klipu video zostaną przyciemnione
Multiply (mnożenie) | W tym trybie obraz także zostanie przyciemniony lecz w inny sposób niż dla trybu Subtract
Chroma | Ten tryb umożliwi nałożenie tylko informacji o kolorze klipu nakładanego na klip podstawowy
Luma | Ten tryb umożliwi nałożenie tylko informacji o jasności klipu nakładanego na klip podstawowy
Lighten (rozjaśnianie) | W tym trybie informacja o jasności z klipu nakładanego zostanie skopiowana do klipu podstawowego tylko wtedy, gdy klip nakładany jest jaśniejszy niż klip podstawowy
Darken (zaciemnianie) | W tym trybie informacja o jasności z klipu nakładanego zostanie skopiowana do klipu podstawowego tylko wtedy, gdy klip nakładany jest ciemniejszy niż klip podstawowy
SoftLight | Ten tryb rozjaśni lub przyciemni podstawowy klip w zależności od jasności nakładanego klipu. Gdy nakładany klip jest ciemniejszy niż luma=128 to klip podstawowy będzie ciemniejszy. Natomiast, gdy klip nakładany będzie jaśniejszy od luma=128 to klip podstawowy będzie jaśniejszy. Tryb ten może zostać użyty do dodania cieni do obrazu. Nakładnie z zupełną bielą lub czernią spowoduje wytworzenie się wyraźnego ściemniania lub rozjaśnienia obrazy, jednakże w rezultacie nie będzie on dokładnie czarny lub biały
HardLight | Ten tryb rozjaśni lub przyciemni podstawowy klip w zależności od jasności nakładanego klipu. Gdy klip nakładany jest ciemniejszy niż luma=128 to klip podstawowy będzie ciemniejszy. Natomiast gdy klip nakładany będzie jaśniejszy od luma=128 to klip podstawowy będzie jaśniejszy. Tryb ten może zostać użyty do dodania cieni do obrazu. Nakładnie z zupełną bielą lub czernią spowoduje wytworzenie się całkowicie czarnego lub białego obrazu
Difference (różnica) | Ten tryb umożliwia wyświetlenie różnicy pomiędzy klipem podstawowym a nakładanym. Podobnie jak w przypadku filtru Subtract, różnica jest wyświetlana na szarym tle (grey=127). Jeżeli chcesz wyświetlić tylko samą różnicę to musisz użyć ColorYUV(off_y=-127)
Exclusion (wykluczenie) | W tym trybie obraz podstawowy zostanie odwrócony w zależności od jasności nakładanego klipu. Mieszanie obrazu podstawowego z białym kolorem spowoduje odwrócenie kolorów klipu podstawowego; mieszanie z kolorem czarnym nie spowoduje zmiany kolorów

Przykłady:

bg = colorbars(512,384).converttoyuy2() text = blankclip(bg).subtitle("Colorbars", size=92, text_color=$ffffff).coloryuv(levels="tv->pc") | # | przygotowanie klipów
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) | # | nakładanie się tekstu na trzy różne sposoby
Overlay(yuy2clip, rgbclip, mask = rgbclip.ShowAlpha("yuy2")) | # | nałożenie klipu rgbclip na klip yuy2clip z maską yuy2 (zwróć uwagę, że przedział luminancji maski to [0, 255])
mask = rgbclip.ShowAlpha("rgb").ConvertToYUY2.ColorYUV(levels="TV->PC") Overlay(yuy2clip, rgbclip, mask) | # | ten sam efekt co wyżej
mask = rgbclip.ShowAlpha("rgb") Overlay(yuy2clip, rgbclip, mask) | # | ten sam efekt co wyżej

### translated by Dj_AnT