## 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` накладывает один клип поверх другого с возможным смещением накладываемого клипа, используя различные способы наложения. Кроме того, возможна настройка прозрачности накладываемого клипа.
Исходные клипы могут быть представлены в любом цветовом формате, и также могут иметь различные цветовые форматы - совместимость клипов здесь не имеет значения ! Исходные клипы автоматически преобразуются к общему формату YUV (с непрореженной цветностью), что позволяет получать на выходе фильтра иной формат цвета, чем тот, который имеется на входе. Это также позволяет использовать клипы в разных цветовых форматах, они будут автоматически преобразованы. Тем не менее, не рекомендуется использовать Overlay только для преобразования цветового представления клипа. Во-первых, для этого есть специальные фильтры, а во-вторых, Overlay делает это медленнее и чуть менее качественно.
Как правило, предполагается что значения пикселов у клипов находятся в диапазоне от 0 до 255. То есть сигнал не будет автоматически ограничен диапазоном (16-235) стандарта CCIR 601. Для этого можно использовать фильтр `Limiter`, уже после применения фильтра Overlay.
Маска тоже должна содержать пикселы в диапазоне 0-255. Можно использовать `гистограмму` в виде `Histogram`("levels"), чтобы посмотреть, как в действительности распределены цвета в картинке. Если выяснится, что цвета у маски приведены к стандарту CCIR 601, используйте `ColorYUV`(levels="TV->PC") чтобы восстановить цветовую информацию.
Если вы точно не уверены в том, что вы делаете, не используйте наложение с чересстрочным (interlaced) видео

#### Параметры :

clip
Это базовый клип - тот на который будет наложено изображение.

overlay
Это оверлей - клип, который содержит накладываемое изображение. Его цветовой формат и размеры по горизонтали и вертикали могут не совпадать с таковыми у базового клипа.

x и y
Эти параметры задают положение накладываемого клипа относительно базового. Задаются в пикселах, и могут быть как положительными, так и отрицательными
По умолчанию равны 0.

mask
Это маска - клип, который будет играть роль маски прозрачности для накладываемого изображения. Маска должна иметь такой же размер, что и оверлей. По умолчанию используется только информация о яркости (luma) маски. Чем темнее маска, тем более прозрачным будет выглядеть накладываемое изображение.
Значения по умолчанию здесь нет, но если маска не задана, то считается что все ее пикселы имеют значение 255.

opacity
Задает прозрачность накладываемого клипа. Значение можно изменять в диапазоне от 0.0 до 1.0, где 0.0 означает полную прозрачность, а 1.0 - полную непрозрачность (если нет маски). Если маска используется, то указанное значение умножается на значение пиксела маски чтобы получить прозрачность данного пиксела.
По умолчанию 1.0

mode
Определяет способ наложения клипа.

Значение mode | Описание
Blend | Это способ по умолчанию. При opacity равной 1.0 и отсутствии маски, оверлей просто накладывается поверх базового клипа.
Add | Сложение значений двух клипов. Результат становится более ярким. Если яркость начинает зашкаливать за стандартные пределы, то изменяется цвет, и изображение становится более белым (как в RGB).
Subtract | Противоположность Add. Делает изображение темнее.
Multiply | Тоже затемняет изображение, но иначе, чем Subtract.
Chroma | Накладывает только цветовую составляющую оверлея на базовое изображение.
Luma | Накладывает только яркостную составляющую оверлея на базовое изображение.
Lighten | Накладывает информацию о яркости оверлея на базовый клип, но только в тех местах, где оверлей ярче, чем базовое изображение.
Darken | Накладывает информацию о яркости на базовый клип, но только в тех местах, где оверлей темнее, чем базовое изображение.
SoftLight | Осветляет или затемняет базовый клип, в зависимости от уровня яркости оверлея. Если оверлей темнее, чем клип с luma = 128, базовый клип будет затемнен. Если оверлей светлее, чем клип с luma = 128, базовый клип будет осветлен. Это полезно для добавления теней к картинке. Накладывание чисто черного (чисто белого) цветов приведет к существенному затемнению (осветлению) изображения, но в результате не получатся чистые черный или белый. Название режима переводится как "мягкий свет", так оно в действительности и выглядит.
HardLight | Осветляет или затемняет базовый клип, в зависимости от уровня яркости оверлея. Если оверлей темнее, чем клип с luma = 128, базовый клип будет затемнен. Если оверлей светлее, чем клип с luma = 128, базовый клип будет осветлен. Это полезно для добавления теней к картинке. Накладывание чисто черного (чисто белого) цветов приведет к тому, что на результирующем изображении в этих местах будет чистый черный (белый) цвет. Название режима переводится как "жесткий свет", так оно в действительности и выглядит.
Difference | Результат - разность между базовым клипом и оверлеем. Обратите внимание, что как и в фильтре Subtract отсутствие различий будет выражено как серый цвет, но с яркостью 128 вместо 126. Если вам нужна точная разность, используйте режим mode="Subract" или добавьте ColorYUV(off_y=-128).
Exclusion | Инвертирует (производит негативное изображение) изображения в зависимости от яркости оверлея. Если оверлей чисто белый, то в результате получается просто негатив, если оверлей черный, то ничего не меняется.

По умолчанию предполагается Blend

greymask
Этот параметр определяет, будет ли цветность маски учитываться при расчете прозрачности. Обычно это так и требуется делать. Внешние фильтры, такие как mSharpen или Masktools способны выдавать нужные маски.
По умолчанию true - включено

output
Дает возможность задать формат цвета для результирующего клипа. Допустимые значения таковы : "YUY2", "YV12", "RGB32" и "RGB24".
По умолчанию формат цвета результата совпадает с форматом цвета исходного (базового) клипа

ignore_conditional
Заставляет Overlay игнорировать условные вычисления См. раздел "Условные переменные" руководства.
По умолчанию false - использовать условные вычисления

pc_range
Если установить этот параметр в true, все внутренние преобразования из RGB в YUV и обратно в RGB будут предполагать что яркость (luma) изменяется от 0 до 255, а не от 16 до 235. Используйте этот параметр только если вы точно уверены что это вам нужно. Прочтите раздел "Рассуждения о RGB" ниже.
По умолчанию false - использовать телевизионный диапазон яркости

### Рассуждения о RGB

Этот раздел содержит информацию о том, почему фильтр Overlay работает именно так, а не иначе, когда дело касается клипов в формате RGB
Исходные клипы для Overlay могут быть в формате RGB. Но, поскольку вся внутренняя обработка в Overlay производится в формате YUV, исходный материал конвертируется. Существует два способа сделать это, и задавая параметр "pc_range", можно выбрать один из них. Если задать его равным true, то диапазон YUV будет расширен с 16-235 (как во всех встроенных конвертерах) до 0-255. В следующих случаях это может быть полезно :

- При накладывании RGB-клипа с использованием режимов "add", "subtract" и "multiply", результат будет лучше, поскольку совершенно черные области оверлея не будут влиять на результат вовсе (в противном случае совершенно черных областей просто не будет - к ним везде добавится 16).

- Если преобразование цветового формата не производится. В противном случае, например если на входе имеем RGB, а на выходе YUY2, а pc_range=true, то диапазон результирующего YUY2 будет неправильным, не соответствующим CCIR 601.

Результат в формате RGB

Возможно, наилучшим решением будет оставить результат работы фильтра Overlay в формате YUY2, даже если на входе - RGB, поскольку таким образом можно избежать проблем с преобразованиями формата. Тем не менее, как отмечено выше, при использовании pc_range = true, возможно получение несовместимого со стандартом изображения. Поправить положение можно применением ''ColorYUV(levels="pc->tv")'', что приведет клип в соответствие со стандартом.

Маска в формате RGB

При использовании маски в формате RGB возможны несколько неожиданные результаты. Однако если маска только серая (не цветная), и параметр greymask = true, то проблем не будет. Надо заметить, что значения пикселов маски не преобразуются к формату CCIR 601, и автоматически будут в диапазоне 0->255 range, в точности соответствуя значениям RGB.

Использование альфа-канала RGB32

Фильтр Overlay не использует альфа-канал. Если вам нужно именно это, выделите его из клипа, используя `ShowAlpha`. Для получения максимально возможного качества, выделите его в формате RGB.

### Условные переменные

Глобальные переменные "OL_opacity_offset", "OL_x_offset" и "OL_y_offset" вычисляются при обработке каждого кадра. Их значения можно изменить, используя `FrameEvaluate`. Значения этих переменных прибавляются к оригиналу в процессе вычисления каждого кадра. Так, если задать "x = 100", а глобальную переменную "OL_x_offset" равной 50, то оверлей будет наложен со смещением 150.
Если используются несколько фильтров Overlay в одном скрипте, то использование условных переменных может быть запрещено установкой параметра "ignore_conditional = true".

Пример условных вычислений можно найти в документации на фильтр the `ConditionalReader`.

### Примеры использования

# Приготовим исходники.

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

# Наложим текст тремя разными способами.

    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)

# Наложение на yuy2clip клипа rgbclip с использованием маски в yuy2 (обратите внимание что яркость маски лежит в диапазоне [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)

# Получим среднее арифметическое двух клипов. Например, так можно слить одно и то же видео, захваченное два раза, с целью уменьшения шума. Обсуждение этого метода читайте : [здесь]. Пример использования (разумеется, надо убедиться, что два клипа действительно одинаковы, кадр в кадр, в противном случае можно использовать 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(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)

Допуск в 60 нужен потому, что синий цвет в jpg файле не везде одинаковый. Например, рядом с границей черного прямоугольника он имеет значения 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)

Сделайте файлы xoffset.txt, содержащий x-координаты и yoffset.txt, содержащий y-координаты движущейся точки (см. ConditionalReader для справки ), и положите в тот же каталог, где лежит сам скрипт:

    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). NB, можно достичь того же эффекта, используя фильтр Animate.

### Изменения:

v2.54 | Первоначальный вариант

`$English Date: 2006/12/15 19:29:25 $
Русский перевод 25.05.2005 Alexander Nickolsky (anickol@yahoo.com)
Редакция 27.09.2006 Fizick avisynth.org.ru`