## 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` sovrappone 2 clips con la possibilità di impostare la posizione dell'immagine che si sovrappone. In più si può impostare l'opacity del clip.
In input si può avere qualsiasi colorspace e non ha importanza se i colorspaces delle clips sono diversi. Le input clips sono convertite internamente in YUV ( no chroma subsampling) , sicché il filtro può generare un colorspace diverso da quello di input. E' anche possibile convertire video di input in colorspaces diversi. Tuttavia non si raccomanda di usare overlay ''solo'' per leconversioni di colorspace poichè il filtro oltre che essere lento non è di qualità eccelsa.
In generale tutte le clips sono trattate nel range 0->255 . Questo significa che i valori non sono tagliati secondo le spcifiche CCIR 601. Per ottenere ciò posporre il filtro `Limiter` .
Anche Masks dovrebbe avere valori 0->255. Usare `Histogram` in modalità `Histogram`("levels") per vedere le distribuzioni dei colori. Se la vostra Mask è nel range CCIR 601 , usare `ColorYUV`(levels="TV->PC") per aumentare i livelli dei colori.
Si consiglia di NON sovrapporre materiale interlacciato a meno che non si sappia ESATTAMENTE cosa si sta facendo.

#### Parametri:

clip
Clip di base, e la "overlay picture" le sarà sovrapposta.

overlay
Questa è l'immagine che sarà sovrapposta al clip. Sia colorspace che dimensioni possono differire da quelle di base clip.

x & y
Queste 2 variabili definiscono in pixels la disposizione dell' overlay image eispetto al base clip. Le variabili possono essere sia positive che negative.
Default = 0.

mask
Questa sarà usata come transparency mask per l'overlay image. Mask deve avere le stesse dimensioni dell' overlay clip. Di default sono usati solamente componenti greyscale (luma). Più l'immagine è scura, più trasparente sarà l'overlay image.
Non c'è valore di default, ma non specificarlo equivale a fornire un clip con valore 255.

opacity
Questo definisce quanto l'immagine sarà trasparente. Il valore va da 0.0 a 1.0, dove 0.0 è transparente ed 1.0 è completamente opaco (se non si usa mask). Usato insieme a mask, questo valore è moltiplicato dal valore di mask.
Default è 1.0

mode
Mode definisce come il clip deve essere ricoperta dall'immagine.

Mode | Descrizione
Blend | Default mode. Quando opacity è 1.0 e non c'è mask l' overlay image sarà copiata sull'originale. In caso contrario si usa un normale transparent blending.
Add | Questo aggiunge l'overlay video al base video rendendolo più luminoso. Facendo un paragone con RGB, rendendo più luminose le aree, si influenza anche il chroma rendendolo più white.
Subtract | L'opposto di Add. Scurisce le aree.
Multiply | Anche questo scurisce l'immagine, ma in modo diverso risoetto a subtract.
Chroma | Questo sovrappone le informazioni di colore dell' overlay clip alla base image.
Luma | Questo sovrappone le informazioni di luminosità dell' overlay clip alla base image.
Lighten | Questo sovrappone le informazioni di luminosità dell' overlay clip alla base image, ma solo se l'overlay è più chiaro della base image.
Darken | Questo sovrappone le informazioni di luminosità dell' overlay clip alla base image, ma solo se l'overlay è più scuro della base image.
SoftLight | Questo schiarisce o scurisce il base clip, in funzione del livello di luminosità dell' overlay clip. Se l'overlay è più scuro di un luma = 128, la base image sarà più scura. Se l'overlay è più chiara di un luma=128, la base image sarà più chiara. Questo è utile per aggiungere ombre ad un'immagine. Colorare con un nero od un bianco puro produce un'area distintamente più scura o più chiara, ma non ne risulta un nero od un bianco puro.
HardLight | Questo schiarisce o scurisce il base clip, in funzione del livello di luminosità dell' overlay clip. Se l'overlay è più scuro di un luma = 128, la base image sarà più scura. Se l'overlay è più chiara di un luma=128, la base image sarà più chiara. Questo è utile per aggiungere ombre ad un'immagine. Colorare con un nero od un bianco puro produce un'area distintamente più scura o più chiara, ma non ne risulta un nero od un bianco puro.
Difference | Questo mostra le differenze tra il e l'overlay. Notare che in modo analogo a Subtract nessuna differenze è mostrata nel caso in cui grey=127. Se si vogliono le differenze pure, usare ColorYUV(off_y=-127).
Exclusion | Questo inverte l'immagine sulla base della luminosità dell' overlay image. Mescolando col bianco si invertono i valori dei colori di base; mescolando col nero non produce effetti.

Default è Blend

greymask
Questa opzione specifica se il chroma preso da mask debba essere usato per il chroma transparency. Per un uso generale questa modalità non dovrebbe essere disabilitata. Filtri esterni come mSharpen e Masktools sono in grado di esportare delle corrette chroma maps.
Default è true

output
E' possibile fare in modo che Overlay restituisca un diverso colorspace. Output possibili sono "YUY2", "YV12", "RGB32" e"RGB24".
Default è l'input colorpace

ignore_conditional
Questo fa ignorare da Overlay qualsiasi variabile conditionale usata. Per un approfondimento vedere la sezione delle "Conditional Variables" .
Default is false

pc_range
Quando impostato a true, farà in modo che ogni conversione interna RGB -> YUV -> RGB assuma che il luma range sia da 0 a 255 invece del default 16->235 . Si raccomanda di cambiare questa impostazione SOLO con cognizione di causa. Vedere la sezione "Considerationi su RGB" qui sotto.
Default è false

### Considerationi su RGB

Questa sezione fornisce alcune spiegazioni su come si comporta Overlay a fronte di una o più sorgenti RGB .
In Overlay è consentito avere una o più sorgenti RGB-data. Tuttavia, siccome Overlay elabora il materiale nel colorspace YUV la cosa implica una conversione da RGB a YUV . Ci sono 2 modalità per ottenere questa conversione gestiti dal parametro "pc_range". Questo parametro estende il range YUV da 16-235 (range usato da tutti i convertitori di avisynth) a 0-255. Ci sono alcuni casi in cui abilitare pc_range è una buona idea:

- Quando si sovrappone un RGB-clip usando i modi "add", "subtract" o"multiply", è meglio che il range del clip sovrapposto sia 0-255, poichè questo fa si che le aree completamente nere non influenzino il risultato (invece di aggiungere 16 ad ogni valore).

- Quando NON di deve fare una conversione di colorspace in output. Se l'output colorspace (RGB vs. YUV) è diverso dall'input, la scala sarà sbagliata. Se pc_range è true, e l'input è RGB con output in YUY2 - YUY2 avrà un range non valido, e non un range CCIR 601.

Output in RGB

Potrebbe essere una buona idea consentire ad Overlay un output YUY2 anche se il colorspace di input è RGB, visto che questo evita una riconversione di colorspace in RGB da YUV. Siate consapevoli che il vostro materiale potrebbe essere "overscaled", come visto sopra, se si usa pc_range = true. Questo si può correggere usando ''ColorYUV(levels="pc->tv")'' per riconvertire in un range 16-235.

Input RGB per il mask clip

Il mask clip in RGB si comporta in modo leggermente diverso da come ci si apetterebbe. Se si usa sempre una greyscale mask, e non si disabilita ''greymask'' i risultati sono quelli attesi. Si noti che i valore di mask clip non sono mai scalati sicché saranno automaticamente nel range 0->255, copiati direttamente dai valori RGB.

Uso di RGB32 alpha channel

Overlay non usa mai l'alpha channel presente in un clip RGB32. Se si vuole estrarre l' alpha channel da un clip RGB32 si può usare il comando `ShowAlpha` . Al fine di mantenere la qualità massima, si raccomanda di estrarre l' alpha come RGB.

### Variabili Conditionali

Le global variables "OL_opacity_offset", "OL_x_offset" e "OL_y_offset" sono lette per ogni each frame, quindi applicate. E' possibile modificare queste variabili usando `FrameEvaluate`. I valori di queste variabili saranno aggiunti ad ogni frame dell'originale. Se quindi si specifica "x = 100" come parametro del filtro, e la global variable "OL_x_offset" è impostata a 50, l' overlay sarà piazzato ad x = 150.
Nel caso si usino filtri multipli, questo può essere evitato usando il parametro "ignore_conditional = true" .

C'è un esempio alla pagina `ConditionalReader` .

### Esempi

# Prepara alcune sources.

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

# Questo sovrappone il testo in 3 modi diversi.

    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)

# Questo sovrapponeun clip yuy2 con un clip rgb usando una mask yuy2 (notare che il luma range di mask è [0-255]).

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

# che equivale a

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

# ed anche a

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

# Questo ottiene la media di 2 clips. Lo si può usare per combinare insieme 2 catture TV per ridurre il rumore. Una discussione relativa a questa idea la trovate [qui]. Uno script di esempio (naturalmente vi dovete assicurare che i frames dei 2 clips siano compatibili, usare DeleteFrame se necessario):

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

### Changelog:

v2.54 | Initial Release

`$Date: 2004/10/03 21:26:00 $`