## Overlay (Sobreposição)

`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` sobrepõe dois clipes com um deslocamento de sobreposição opcional da imagem, usando diferentes métodos. Além disso a opacidade pode ser ajustada para sobrepor o clipe.
A entrada para a sobreposição pode ser qualquer colorspace, não importa se o clipe é diferente! Os clipes de entrada são convertidos internamente ao formato YUV geral (sem subamostragem de croma), assim é possível o filtro produzir outro colorspace da entrada. Também é possível introduzir vídeo em diferentes colorspaces, bem como convertidos sem problemas. Não é recomendado porém, usar overlay ''apenas'' para conversões de colorspace, porque é mais lento e tem qualidade ligeiramente pior.
Em geral todos os clipes são tratados com valores de 0->255. Isto significa que os números não serão cortados à gama CCIR 601. Depois use `Limiter` para esta tarefa.

Máscaras também devem ter valores de 0->255. Você pode usar `Histogram` em modo `Histogram`("levels") para ver as entradas de cor. Se sua máscara estiver na gama CCIR 601, use `ColorYUV`(levels="TV->PC") para re-escalar os níveis de cor.
Não é recomendado fazer sobreposição em material entrelaçado, a menos que você saiba como fazer.

#### Parâmetros:

clip
Este clipe será a base e a imagem de sobreposição que será colocada em cima dele.

overlay
Esta é a imagem que será colocada (sobreposta) em cima do clipe básico. O colorspace ou dimensões da imagem não têm que se igualar ao clipe básico.

x & y
Estas duas variáveis definem a colocação da imagem overlay (de sobreposição) no clipe básico em píxeis. A variável pode ser positiva ou negativa.
Os valores padrões são 0.

mask
Isto será usado como a máscara de transparência para a imagem de sobreposição. A máscara deve ter o mesmo tamanho do clipe de sobreposição. Por padrão, só os componentes cinzas (luma) da imagem são usados. Quanto mais escura é a imagem, mais transparente será a imagem de sobreposição.
Não há padrão, mas a não especificação é equivalente a ter um clipe 255.

opacity
Isto fixa a transparência da imagem. O valor vai de 0.0 a 1.0, onde 0.0 é transparente e 1.0 é completamente opaco (se nenhuma máscara é usada). Quando usado com máscara este valor é multiplicado pelo valor dela para formar a opacidade final.
O valor padrão é 1.0

mode
Mode define como seu clipe deve ser sobreposto em sua imagem.

Modo | Descrição
Blend | Este é o modo padrão. Quando a opacidade é 1.0 e não há máscara, a imagem de sobreposição será copiada sobre a original. Mistura transparente normal é usada em caso contrário.
Add | Isto incluirá o vídeo de sobreposição ao básico, tornando o vídeo mais brilhante. Para fazer comparável ao RGB, áreas de luma mais brilhante influenciam o croma e as deixam mais brancas.
Subtract | O oposto de Add. Isto tornará as áreas mais escuras.
Multiply | Isto também escurecerá a imagem, mas trabalha diferente de subtract.
Chroma | Isto sobreporá apenas a informação de cor do clipe de sobreposição à imagem básica.
Luma | Isto sobreporá só a informação de luminosidade do clipe de sobreposição à imagem básica.
Lighten | Isto copiará a informação de luminosidade do clipe de sobreposição ao clipe básico, mas só se ela for mais clara que a imagem básica.
Darken | Isto copiará a informação de luminosidade do clipe de sobreposição ao clipe básico, mas só se a sobreposição for mais escura que a imagem básica.
SoftLight | Isto vai clarear ou escurecer o clipe básico, baseado no nível de luminosidade do clipe de sobreposição. Se ela for mais escura que luma = 128, a imagem básica será mais escura. Se mais clara que luma=128, a imagem básica será mais clara. Isto é útil para acrescentar sombras a uma imagem. Pintando com preto ou branco puros produz uma área distintamente mais escura ou mais clara mas não resulta em puro preto ou branco.
HardLight | Isto vai clarear ou escurecer o clipe básico, baseado no nível de luminosidade do clipe de sobreposição Se ela for mais escura que luma = 128, a imagem básica será mais escura. Se for mais clara que luma=128, a imagem básica será mais clara. Isto é útil para acrescentar sombras a uma imagem. Pintando com preto ou branco puros, resulta em preto ou branco puros.
Difference | Isto exibirá a diferença entre o clipe e a sobreposição. Note que igual a Subtract nenhuma diferença é exibida como grey=127 (cinza). Se você quiser a diferença pura, use ColorYUV(off_y=-127).
Exclusion | Isto inverterá a imagem baseado na luminosidade da sobreposição da imagem. Misturando com branco inverte os valores de cores básicos; misturando com preto nada muda.

O valor padrão é Blend

greymask
Esta opção especifica se o croma da máscara deve ser usado para transparência de croma. Para propósito geral este modo não deve ser desativado. Filtros externos como mSharpen e Masktools podem exportar mapas de croma apropriados.
O padrão é true

output
É possível a sobreposição retornar outro colorspace. As saídas possíveis de colorspaces são " YUY2 ", YV12 ", RGB32 " e " RGB24 ".
O padrão é input colorspace

ignore_conditional
Isto fará Overlay ignorar qualquer variável condicional dada. Veja a seção "Variáveis Condicionais" para uma avaliação
O padrão é false

pc_range
Quando fixado true, fará todas as conversões internas RGB - > YUV - > RGB assumirem a gama luma entre 0 e 255 em vez da gama padrão 16->235. Só é recomendado mudar esta colocação se você sabe como fazer. Veja a seção em "considerações RGB" abaixo.
O padrão é false

### Considerações RGB

Esta seção descreverá como Overlay se comporta quando lhe é dado uma ou mais fontes de RGB.
Um ou mais entradas de Overlay são permitidas para dados RGB. Porém, como Overlay está processando material no colorspace YUV, conduzirá a uma conversão de RGB para YUV. Há dois modos para esta conversão, reforçados pelo parâmetro "pc_range". Este parâmetro estenderá a faixa YUV de 16 a 235 (esta é a gama usada por todos os conversores do Avisynth) para 0 a 255. Há alguns casos em que habilitar pc_range é uma boa idéia:

- Ao sobrepor um clipe RGB com os modos "add", "subtract" ou "multiply", sua gama é melhor, se for de 0 a 255, desde que permita áreas completamente escuras a não influenciar o resultado (em vez de somar 16 a todo valor).

- Ao NÃO produzir uma conversão de colorspace. Se produzir colorspace (RGB vs YUV) diferente da entrada, a escala estará errada. Se pc_range for true e a entrada é RGB, quando a saída é YUY2, o YUY2 terá uma gama inválida e não a gama CCIR 601.

Produzindo RGB

Pode ser uma boa idéia deixar Overlay produzir YUY2, até mesmo se sua entrada colorspace for RGB, pois isto evita que uma conversão colorspace volte da YUV para RGB. Fique ciente que seu material pode ficar "re-escalado", como mencionado antes, se você usar pc_range = true. Você pode corrigir isso usando ''ColorYUV(levels ="pc->tv")'' para reconverter à gama de 16 a 235.

Entrando RGB para clipe de máscara

O clipe de máscara RGB pode se comportar um pouco diferente ao que poderia ser esperado. Se sempre usa uma máscara cinza e não desativa ''greymask'' você terá o resultado que espera. Note que os valores de clipe de máscara nunca são escalados, assim estará automaticamente na gama de 0->255, copiados diretamente dos valores de RGB.

Usando o canal alfa RGB32

Overlay nunca usará o canal alfa dado a um clipe RGB32. Se você quer extrair o canal alfa de um clipe RGB32 pode usar o comando `ShowAlpha` para extrair sua informação. Para manter a máxima qualidade é recomendado extrair o alfa como RGB.

### Variáveis Condicionais

As variáveis " globais OL_opacity_offset ", OL_x_offset " e " OL_y_offset " são lidas em cada quadro e aplicado. É possível modificar estas variáveis que com `FrameEvaluate`. Os valores destas variáveis serão acrescentados ao original em cada quadro. Assim se você especifica "x = 100" como um parâmetro de filtro e a "variável" global OL_x_offset é fixada a 50, a sobreposição será colocada em x = 150.
Se você está usando múltiplos filtros isto pode ser desativados com o parâmetro."ignore_conditional = true"

Há um exemplo de modificação condicional na página `ConditionalReader`.

### Exemplos

# Prepara algumas fontes.

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

# Isto sobreporá o texto em três versões diferentes.

    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)

# Isto sobreporá yuy2clip com rgbclip coma uma máscara yuy2 (note que a gama luma da máscara é [0-255]).

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

# que é igual a

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

# que é igual a

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

# Isto pega a média de dois clipes. Pode ser usado para combinar duas capturas de radiodifusões diferentes para reduzir ruído, por exemplo. Uma discussão desta idéia pode ser achada [aqui]. Um escrito de amostra (claro que você tem que assegurar que os quadros dos dois clipes sejam exatamente iguais, use DeleteFrame se necessário):

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

# Use um fundo azul (ou qualquer outra cor - blue.jpg é uma sobreposição de quadro azul com subtítulos num retângulo preto) como máscara. O retângulo preto que contém os subtítulos será visível no clipe fonte (que é ColorBars aqui):

    testcard = ColorBars()

    # pegue um clipe de máscara azul (o mesmo azul que é usado em ColorBars: R16 G16 B180)
    maskclip = BlankClip(clip=testcard, color=$0f0fb4)

    # Exemplo de arquivo de subtítulo com fundo azul como acima
    subs = ImageSource("F:\TestClips\blue.jpg").ConvertToRGB32

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

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

Uma tolerância de 60 é usada aqui porque o azul não é inteiramente uniforme. Próximo aos retângulos pretos o azul é determinado por R23 G22 B124. Provavelmente devido à compressão de blue.jpg.

# Mova um ponto vermelho (ou qualquer outra cor) em um clipe com ConditionalReader (dot.bmp é um vermelho em um fundo preto):

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

    #a2.GreyScale retorna um ponto cinzento em um fundo preto; Levels faz o ponto branco
    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)

Faça xoffset.txt que contêm as posições x e yoffset.txt que contêm as posições y do ponto móvel (veja ConditionalReader para mais info), e ponha na mesma pasta do seu escrito:

    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

assim o ponto se move deste jeito: (20,20) - > (250,350) - > (400,40). Nb, também é possível fazer isto com Anime.

### Log de Mudanças:

v2.54 | Lançamento Inicial

`$Date: 2006/03/26 18:11:19 $ Portuguese translation by RoLon`