README_rus.md

AutoOverlay AviSynth plugin

ENG | RUS

Требования

• AviSynth+ 3.7+: https://github.com/AviSynth/AviSynthPlus/releases/
• AvsFilterNet plugin https://github.com/Asd-g/AvsFilterNet (включено в поставку)
• SIMD Library https://github.com/ermig1979/Simd (включено в поставку)
• warp plugin v0.1b by wonkey_monkey https://forum.doom9.org/showthread.php?t=176031 (включено в поставку)
• Avsresize based on z.lib: https://codeberg.org/StvG/avsresize/releases (для ColorMatchChain, не включено в поставку)
• ResampleMT by jpsdr: https://github.com/jpsdr/ResampleMT/releases (для повышения производительности, не включено в поставку)
• MVTools https://github.com/pinterf/mvtools/releases (для aoInterpolate, не включено в поставку)
• RGTools https://github.com/pinterf/RgTools/releases (для aoInterpolate, не включено в поставку)
• .NET framework 4.8+
• Windows 7+
• Для редактирования и отладки скриптов рекомендуется использовать AvsPmod: https://github.com/gispos/AvsPmod

Установка

• Скопировать файлы из папок x86/x64 в папки с плагинами AviSynth.
• В свойствах DLL в проводнике Windows может потребоваться "Разблокировать" файлы.
• Рекомендуется использовать x64 версию для лучшей производительности

Описание

Плагин предназначен для оптимального наложения одного видеоклипа на другой. Выравнивание клипов относительно друг друга осуществляется фильтром OverlayEngine путем тестирования различных координат верхнего левого угла наложения, размеров изображений, соотношений сторон и углов вращения для того, чтобы найти оптимальные параметры наложения. Функция сравнения двух участков изображения двух клипов - среднеквадратическое отклонение, которое далее обозначается как diff. Задача автовыравнивания - найти минимальное значение diff. Для повышения производительности автовыравнивание разделено на несколько шагов масштабирования для тестирования различных параметров наложения, задаваемых фильтром OverlayConfig. На первом шаге тестируются все возможные комбинации наложения в низком разрешении. На каждом следующем шаге в более высоком разрешении тестируются комбинации на базе лучших с предыдущего шага. Конфигурации OverlayConfig могут объединяться в цепочки. Если определенная конфигурация дала хороший результат, тестирование следующих не выполняется для экономии времени. После автовыравнивания один клип может быть наложен на другой различными способами с помощью фильтра OverlayRender.

Подключение плагина

LoadPlugin("%plugin folder%\AvsFilterNet.dll")
LoadNetPlugin("%plugin folder %\AutoOverlay_netautoload.dll")

AviSynth+ поддерживает автоподключение плагинов, если имя файла плагина .NET содержит суффикс _netautoload, который по умолчанию есть.

Пример

portrait = ImageSource("Lenna.portrait.jpg")
landscape = ImageSource("Lenna.landscape.jpg")

OverlayEngine(portrait, landscape)
OverlayRender(portrait, landscape, colorAdjust = 1, preset = "fitscreenblur", width=500, height=500)

Portrait image + landscape image -> script output

Фильтры

OverlayConfig

OverlayConfig(string preset, float minOverlayArea, float minSourceArea, float aspectRatio1, float aspectRatio2, 
              float angle1, float angle2, float minAngleStep, float maxAngleStep, float angleStepCount, 
              clip warpPoints, int warpSteps, int warpOffset, int minSampleArea, int requiredSampleArea, 
              float maxSampleDiff, int subpixel, float scaleBase, int branches, float branchMaxDiff, 
              float acceptableDiff, float correction, float rotationCorrection, int minX, int maxX, 
              int minY, int maxY, int minArea, int maxArea, bool fixedAspectRatio, bool debug)

Фильтр описывает конфигурацию автовыравнивания для OverlayEngine. Он содержит граничные значения параметров наложения таких как: координаты верхнего левого угла накладываемого изображения относительно основного, ширину и высоту накладываемого изображения и угол вращения. Также конфигурация включает параметры работы OverlayEngine. Результат работы фильтра - фейковый кадр, в котором закодированы параметры, с помощью чего они могут быть считаны в OverlayEngine. Существует возможность объединять несколько конфигурация в цепочки с помошью обычного объединения клипов: OverlayConfig(…) + OverlayConfig(…). В этом случае OverlayEngine будет тестировать каждую конфигуарцию последовательно на каждом шаге пока не будет получен приемлемое (acceptable) значение diff.

Параметры

• preset (default medium) - пресет основных параметров. Пресеты low, medium, high, extreme регулируют качество и производительность. low - самый быстрый и наименее качественный, extreme - наоборот. Пресет fixed предназначен для случая, когда одно изображение четко вписано в другое по границам основного клипа.

Параметр / Пресет	Low	Medium	High	Extreme	Fixed
Subpixel	0	1	2	3	0
Branches	1	2	3	4	1
MinSampleArea	1000	1500	1500	2000	1500
RequiredSampleArea	1000	3000	4000	5000	3000
RequiredSampleArea	1000	3000	4000	5000	3000
RotationCorrection	0.5	0.5	1	1	0.5
FixedAspectRatio	false	false	false	false	true
MinOverlayArea	default	default	default	default	100

• minOverlayArea - минимальное отношение используемой части к общей площади накладываемого изображения в процентах. По умолчанию рассчитывается таким образом, чтобы накладываемый клип мог полностью перекрыть базовый (режим пансканирования). К примеру, если разрешение основного клипа 1920x1080, а накладываемого 1920x800, то значение параметра будет 800/1080=74%.
• minSourceArea - минимальное отношение используемой части к общей площади основного изображения в процентах. По умолчанию рассчитывается таким образом, чтобы основной клип мог полностью включить накладываемый (режим пансканирования). К примеру, если разрешение основного клипа 1920x1080, а накладываемого 1440x800, то значение параметра будет 1440/1920=75%.
• aspectRatio1 and aspectRatio2 - диапазон допустимых соотношений сторон накладываемого изображения. По умолчанию - соотношение сторон накладываемого клипа. Может быть задан в любом порядке: aspectRatio1=2.35, aspectRatio2=2.45 то же самое, что и aspectRatio1=2.45, aspectRatio2=2.35. По умолчанию равно соотношению сторон накладываемого клипа, если FixedAspectRatio = true, иначе к нему добавляется допуск в размере minDimension + (Correction + rotationShift) x 2) / minDimension - 1, где minDimension - меньшая из сторон накладываемого клипа, а rotationShift равен RotationCorrection, если углы не равны 0, иначе 0.
• angle1 и angle2 (default 0) - диапазон допустимых углов вращения накладываемого изображения. Может быть задан в любом порядке. Отрицательные значения – вращение по часовой стрелке, положительные – против.
• minAngleStep (default 0.05) - минимальный шаг поворота изображения в градусах.
• maxAngleStep (default 1) - максимальный шаг поворота изображения в градусах.
• angleStepCount (default 2) - количество шагов поворота изображения на каждом шаге подобора параметров наложения.
• warpPoints (default empty) – последовательность клипов типа Rect, описывающих исходные точки warp трансфорфмаций и возможных отклонения по осям X и Y, которые будут переданы в фильтр warp. Пример: Rect(0,0,3,3) + Rect(1920,800,3,3) + Rect(1920,0,3,3) + Rect(0,800,3,3) + Rect(960,400,3,3). Здесь описаны warp трансформации с максимальной дальностью 3 пикселя по углам и центру изображения размером 1920x800.
• warpSteps (default 3) – количество итераций warp трансформаций. Больше лучше, но медленнее.
• warpOffset (default 0) – величина свдига warp трансформаций от последнего шага к первому (в меньшем разрешении). Меньше лучше, но медленнее.
• minSampleArea (default 1500) – минимальная площадь в пикселях базового изображения на первом шаге. Чем меньше, тем быстрее, но выше риск некорректного результата. Рекомендованный диапазон: 500-3000.
• requiredSampleArea (default 3000) - максимальная площадь в пикселях базового изображения на первом шаге. Чем меньше, тем быстрее, но выше риск некорректного результата. Рекомендованный диапазон: 1000-5000.
• maxSampleDiff (default 5) – максимально допустимое значение diff уменьшенного базового изображения между шагами. Если превышает указанное значение, то предыдущий шаг выполнен не будет. Используется для выбора начального размера изображения между minSampleArea и requiredSampleArea и соответственно шага.
• subpixel (default 0) – величина наложения с субпиксельной точностью. 0 – точность один пиксель, 1 – половина пикселя, 2 – четверть и т.д. Ноль рекомендуется, если один клип имеет существенно более низкое разрешение, чем другой. 1-3 рекомендуется, если оба клипа имеют примерно одинаковое разрешение. Отрицательные значения тоже поддерживаются, в этом случае наложение будет выполнено с пониженной точностью, но быстрее.
• scaleBase (default 1.5) – основание для расчета уменьшающего коэффициента по формуле coef=scaleBase^(1 - (maxStep - currentStep)). Чем ниже, тем большее количество шагов.
• branches (default 1) - какое количество наилучших параметров наложения использовать с предыдущего шага для поиска на текущем. Больше - лучше, но дольше. По сути, глубина ветвления.
• branchMaxDiff (default 0.2) - максимальная разница на текущем шаге между значениями diff наилучших параметров поиска и прочих. Используется для отбрасывания бесперспективных ветвей поиска.
• acceptableDiff (default 5) – приемлемое значение diff, после которого не тестируются последующие конфигурации в цепочке OverlayConfig.
• correction (default 1) – величина коррекции некоторого показателя на текущем шаге с предыдущего. Чем выше, тем больше различных параметров тестируется, но это занимает больше времени.
• rotationCorrection (default 0.5) - дополнительная коррекция, если угол поворота изображения не равен 0.
• minX, maxX, minY, maxY - допустимые диапазоны координат левого верхнего угла наложения, по умолчанию не ограничены.
• minArea, maxArea - диапазон допустимой площади накладываемого изображения, в пикселях. По умолчанию не ограничен.
• fixedAspectRatio (default false) - режим точного соотношения сторон накладываемого клипа, только для случая, когда aspectRatio1=aspectRatio2.
• debug (default false) – отображение параметров конфигурации.

OverlayEngine

OverlayEngine(clip source, clip overlay, clip sourceMask, clip overlayMask, string statFile, 
              string preset, int sceneBuffer, int shakeBuffer, bool stabilize, bool scan, bool correction,
              float frameDiffTolerance, float frameAreaTolerance, float sceneDiffTolerance, float sceneAreaTolerance,
              float frameDiffBias, float maxDiff, bool legacyMode, int backwardFrames, int forwardFrames, 
              float maxDiffIncrease, int scanDistance, float scanScale, float stickLevel, float stickDistance,
              clip configs, string presize, string resize, string rotate, bool editor, string mode,
              int colorAdjust, string sceneFile, clip[] sceneClips, bool SIMD, bool debug)

Фильтр принимает на вход два клипа: основной и накладываемый и выполняет процедуру автовыравнивания с помощью изменения размера, вращения и сдвига накладываемого клипа, чтобы найти наименьшее значение diff. Оптимальные параметры наложения кодируются в выходной кадр, чтобы они могли быть считаны другими фильтрами. Последовательность таких параметров наложения кадра за кадром (статистика) может накапливаться в оперативной памяти, либо в файле для повторного использования без необходимости повторно выполнять дорогостоящую процедуру автовыравнивания. Файл статистики может быть проанализирован и отредактирован во встроенном графическом редакторе. Статистика накапаливается при движении по клипу в любую сторону, главное чтобы он было последовательным, кадр за кадром, иначе не будут учитываться соседние кадры.

Параметры

• source (required) - первый, основной клип.
• overlay (required) - второй, накладываемый клип. Оба клипа должны быть в одном и том же типе цветового пространства (YUV или RGB) и глубине цвета.
• sourceMask, overlayMask (default empty) – маски для основного и накладываемого клипа. Если маска задана, то пиксели клипа, которым соответствует значение 0 в маске, игнорируются при расчете DIFF. Подходит, к примеру, для исключения логотипа из расчета diff. В RGB клипах каналы анализируются раздельно. В YUV анализируется только канал яркости. Маска должна быть в полном диапазоне (ColorYUV(levels="TV->PC")).
• statFile (default empty) – путь к файлу со статистикой параметров наложения. Если не задан, то статистика накапливается только в оперативной памяти в пределах одного сеанса. Рекомендуемый сценарий использования: для начального подбора параметров вручную не использовать файл статистики, а использовать для тестового прогона, чтобы собрать статистику, проанализировать и подправить в редакторе.
• preset (default medium) - пресет основных параметров фильтра, влияющих на соотношение качества и производительности.

Параметр / Пресет	Low	Medium	High
SceneBuffer	10	15	20
ShakeBuffer	1	2	3
FrameDiffTolerance	10	7	5
SceneDiffTolerance	75	50	25
MaxDiff	20	15	10

• sceneBuffer (default 15) - количество соседних предыдущих и последующих кадров (т.е. в сумме их будет x2), которые будут анализироваться на предмет включения в интервал.
• shakeBuffer (default 2) - количество соседних кадров, по которым будет выполнена изначальное определение параметров наложения для интервала.
• stabilize (default true) – попытка полной стабилизации параметра наложения соседних кадров. Если клипы не являются результатом кадрирования единого исходного мастеринга, то параметр следует выставить в false.
• scan (default true) – попытка определения сканирования между соседними кадрами, т.е. плавного изменения параметров наложения без выбросов. Применяется, если полная стабилизация не удалась. Рекомендуется отключать, если заведомо известно, что таких эпизодов в источниках нет. Если stabilize и scan отключены, то каждый кадр будет совмещаться с нуля - это ресурсозатратно и может породить выбросы.
• correction (default true) - попытка ретроспективно скорректировать параметры наложения ранее обработанных кадров после обработки очередных кадров.
• frameDiffTolerance (default 4) - допустимое отклонение diff в процентах при стабилизации кадра.
• frameAreaTolerance (default 0.2) - допустимое отклонение области пересечения в процентах при стабилизации кадра.
• sceneDiffTolerance (default 4) - допустимое отклонение diff в процентах между соседними кадрами.
• sceneAreaTolerance (default 0.5) - допустимое отклонение области пересечения в процентах между соседними кадрами.
• frameDiffBias (default 1.5) - величина, которая добавляется к diff, чтобы сгладить различия при их сравнении.
• maxDiff (default 5) – величина diff, при превышении которого кадр не может быть включен в сцену.
• legacyMode (default false) - если true, будет задействован старый алгоритм определения сцен с параметрами backwardFrames, forwardFrames, maxDiffIncrease, maxDeviation, scanDistance, scanScale вместо sceneBuffer, shakeBuffer и т.п.
• backwardFrames and forwardFrames (default 3) – количество анализируемых предыдущих и последующих кадров в одной сцене для стабилизации и ускорения поиска параметров наложения.
• maxDiffIncrease (default 1) – максимально допустимое превышение diff текущего кадра от среднего значения в последовательности (сцене).
• maxDeviation (default 1) – максимально допустимая разница в процентах между объединением и пересечением двух конфигураций выравнивания для обнаружения сцен. Более высокие значения могут привести к ошибочному объединению нескольких сцен в одну, но обеспечивают лучшую стабилизацию в пределах сцены.
• scanDistance (default 0) – максимально допустимый сдвиг накладываемого изображения между соседними кадрами в сцене. Используется, если источники не стабилизированы относительно друг друга.
• scanScale (default 3) – максимально допустимое изменения размера в промилле накладываемого изображения между соседними кадрами в сцене.
• stickLevel (default 0) - максимально допустимая разница между значениями DIFF для наилучших параметров наложения и тех, что приведут к приклеиванию накладываемого изображения к границам основного.
• stickDistance (default 1) - максимально допустимое расстояние между краями накладываемого изображения для наилучших параметров наложения и тех, что приведут к приклеиванию накладываемого изображения к границам основного.
• configs (по умолчанию OverlayConfig со значениями по умолчанию) – список конфигураций в виде клипа. Пример: configs=OverlayConfig(subpixel=1, acceptableDiff=10) + OverlayConfig(angle1=-1, angle2=1). Если в ходе автовыравнивания после прогона первой конфигурации будет получено значение diff менее 10, то следующая конфигурация с более "тяжелыми" параметрами (вращение) будет пропущена.
• presize (default BilinearResize) – функция изменения размера изображения для начальных шагов масштабирования.
• resize (default Spline36Resize или Spline36ResizeMT при наличии) – функция изменения размера изображения для финальных шагов масштабирования.
• rotate (default BilinearRotate) – функция вращения изображения. В настоящее время по умолчанию используется реализация из библиотеки AForge.NET.
• editor (default false). Если true, во время загрузки скрипта запустится визуальный редактор.
• mode (default "default") – режим работы со статистикой:
  DEFAULT – по умолчанию UPDATE – как предыдущий, но DIFF текущего кадра всегда перерассчитывается ENHANCE - уточнить параметры наложения каждого конкретного кадра, исходя из ранее собранной статистики с потерей стабилизации. ERASE – стереть статистику (используется для очистки информации об определенных кадрах совместно с функцией Trim) READONLY – использовать, но не пополнять файл статистики PROCESSED – включить только уже обработанные кадры UNPROCESSED – включить только необработанные кадры
• colorAdjust - коррекция цвета клипов в процессе наложения для более точного наложения: 0 - в сторону основного клипа, 1 - в сторону накладываемого.
• sceneFile - путь к файлу с ключевыми кадрами для обособления сцен во время процесса автовыравнивания изображений и цветокоррекции
• sceneClips - массив произвольных клипов, по которым в разрезе каналов отбираются ключевые для цветокоррекции кадры сцены: кадры с минимальным и максимальным значениями пикселя, а также кадр с максимальным динамическим диапазоном. Параметр может работать только в паре с параметром sceneFile. Клипы в sceneClips должны быть легковесными, иначе заметно снизится производительность.
• simd (default true) - использование SIMD Library для повышения производительности в некоторых случаях
• debug (default false) - отображение параметров наложения, снижает производительность

Принцип работы

OverlayEngine ищет оптимальные параметры наложения: координаты верхнего левого угла накладываемого клипа относительного основного, угол вращения в градусах, ширина и высота накладываемого изображения, а также величины обрезки накладываемого изображения по краям для субпиксельного позиционирования.
Цепочка OverlayConfig в виде клипа описывает границы допустимых значений и алгоритм поиска оптимальных. Движок прогоняет каждую конфигурацию друг за другом пока не будут найдены параметры наложения с приемлемым diff. Процесс автовыравнивания для каждой конфигурации содержит несколько шагов. На первом шаге тестируются все возможные комбинации параметров наложения в низком разрешении. На следующий шаг передается некоторое количество наилучших комбинаций, задаваемых параметром OverlayConfig.branches. На каждом следующем шаге параметры наложения конкретизируются в более высоком разрешении, область поиска задается параметром correction. Масштабирование изображений выполняется функциями, заданными в параметрах presize and resize. Первый используется на предварительных шагах автовыравнивания, второй на финальных, когда работа ведется в полном разрешении. На финальных шагах рекомендуется использовать фильтр с хорошей интерполяцией. Функция масштабирования должно иметь следующую сигнарутуру: Resize(clip clip, int target_width, int target_height, float src_left, float src_top, float src_width, float src_height). Допускаются дополнительные параметры. Такая же сигнатура используется в стандартных функциях AviSynth. Крайне рекомендуется использовать плагин ResampleMT, который дает тот же результат, что и встроенные фильтры, но работает значительно быстрее за счет параллельных вычислений.

Визуальный редактор

Запускается, если OverlayEngine.editor=true.
Слева превью кадра. Внизу трекбар по количеству кадров и поле ввода текущего кадра. Справа таблица, отображающая кадры с одинаковыми параметрами наложения, объединенные в эпизоды. Между эпизодами можно переключаться. Под гридом панель управления.
Overlay settings - параметры наложения текущего эпизода.

Ниже секция Frame processing.

• Align - автоналожение "с нуля" без учета других кадров
• Adjust - коррекция каждого сцены относительно текущего кадра (или первого кадра сцены, если текущий кадр в сцену не входит) с учетом Distance (отклонение X и Y), Scale (отклонение произведения Width и Height) и Max deviation (отклонение площади пересечения от площади объединения кадров)
• Scan - режим последовательного сканирования относительно предыдущего кадра, начиная с первого кадра сцены с учетом Distance, Scale и Max deviation

Кнопки:

• Frame - обработка текущего кадра (в случае Align если сцена Fixed, изменятся параметры всей сцены)
• Single - обработка текущего кадра, если сцена Fixed и параметры наложения изменятся, кадр будет вынесен в отдельную сцену
• Scene - обработа текущей сцены (текущая строка в таблице)
• Clip - обработка всех сцен в таблице

Измененные и несохраненные эпизоды подсвечиваются желтым цветом в гриде. Кнопка save - сохранение изменений. Reset - сброс изменений и повторная загрузка данных. Reload - перезагрузка характеристик для текущего кадра, распространяющиеся на весь эпизод.
Separate - обособление кадра. Join prev - присоединить кадры предыдущего эпизода. Join next - присоединить кадры следующего эпизода. Join to - присоединить кадры до введенного включительно.

Hotkeys:

• Ctrl + S - save
• Ctrl + R - reload
• D - enable/disable difference
• P - enable/disable preview
• Ctrl + arrow keys - move overlay image
• Ctrl + add/subtract - scale overlay image
• A, Z - next/previous frame

OverlayRender

OverlayRender(clip engine, clip source, clip overlay, clip sourceMask, clip overlayMask, 
              clip sourceCrop, clip overlayCrop, string sourceChromaLocation, string overlayChromaLocation, 
              clip extraClips, string preset, clip innerBounds, clip outerBounds, 
              float overlayBalanceX, float overlayBalanceY, bool fixedSource, bool IgnoreAspectRatio, 
              int overlayOrder, float stabilizationDiffTolerance, float stabilizationAreaTolerance, 
              int stabilizationLength, string overlayMode, int width, int height, string pixelType, 
              int gradient, int noise, int borderControl, float borderMaxDeviation, clip borderOffset, 
              clip srcColorBorderOffset, rectangle overColorBorderOffset, bool maskMode, float opacity, 
              float colorAdjust, int colorBuckets, float colorDither, int colorExclude, 
              int colorFramesCount, float colorFramesDiff, float colorMaxDeviation, 
              float gradientColor, int[] colorFrames, clip colorMatchTarget, 
              string adjustChannels, string matrix, string sourceMatrix, string overlayMatrix,
              string upsize, string downsize, string chromaResize, string rotate, bool preview, 
              string sourceName, string overlayName, int legend,
              bool debug, bool invert, string background, clip backgroundClip, int blankColor, 
              float backBalance, int backBlur, bool fullScreen, string edgeGradient, int bitDepth)

Фильтр осуществляет рендеринг результата совмещения двух или более клипов с определенными настройками.

Параметры

• engine (required) - клип типа OverlayEngine, который предоставляет параметры наложения.
• source (required) - первый, основной клип.
• overlay (required) - второй клип, накладываемый на первый.
• sourceMask and overlayMask (default empty) - маски основного и накладываемого клипа. В отличие от OverlayEngine смысл этих масок такой же, как в обычном фильтре Overlay. Маски регулируют интенсивность наложения клипов относительно друга друга. Маски должны иметь ту же разрядность, что и соответствующий ей клип.
• sourceCrop and overlayCrop (default 0) - клипы типа Rect, позволяющие учесть разность в обрезке клипов между статистикой (OverlayEngine) и клипами source and overlay. Положительные значения - обрезка, отрицательные - наоборот.
• sourceChromaLocation and overlayChromaLocation - смещение UV каналов относительно канала яркости. Возможные значения: left, center, top_left, top, bottom, bottom_left. По умолчанию используется значение свойства кадра _ChromaLocation, иначе left. Для выходного клипа используется значение sourceChromaLocation.
• extraClips (default empty) - клип из склеенных клипов типа OverlayClip, описывающих дополнительные клипы для наложения.
• preset (default not set) - пресеты используются для пакетной предустановки других параметров (если они не заданы явно)

Параметр / Пресет	FitSource	FitScreen	FitScreenBlur	FitScreenMask	FullFrame	FullFrameBlur	FullFrameMask	Difference
FixedSource	true	false	false	false	false	false	false	true
OverlayBalance	-1	0	0	0	0	0	0	-1
InnerBounds	0	1	1	1	1	1	1	0
OuterBounds	0	0	0	0	1	1	1	0
Gradient	50	50	50	0	50	50	0	0
EdgeGradient	none	none	inside	none	none	inside	none	none
Background	blank	blank	blur	blank	blank	blur	blank	blank
MaskMode	false	false	false	true	false	false	true	false
OverlayMode	blend	blend	blend	blend	blend	blend	blend	difference
Debug	false	false	false	false	false	false	false	true

• innerBounds (default 0) - клип типа Rect, ограничивающий длину пустот внутри объединения клипов. Значения в диапазоне от 0 до 1 интерпретируются как коэффициент, а свыше 1 как абсолютное значение в пикселях от объединенной области.
• outerBounds (default 0) - клип типа Rect, ограничивающий длину полей относительно результирующего клипа. Значения в диапазоне от 0 до 1 интерпретируются как коэффициент, а свыше 1 как абсолютное значение в пикселях.
• overlayBalanceX (default 0) - центрирование изображения по ширине относительно основного клипа (-1) или накладываемого (1) в диапазоне от -1 до 1.
• overlayBalanceY (default 0) - центрирование изображения по высоте относительно основного клипа (-1) или накладываемого (1) в диапазоне от -1 до 1.
• fixedSource (default false) - фиксированное центрирование результирующего клипа относительно основного.
• ignoreAspectRatio (default false) - растягивать во весь экран, игнориря соотношение сторон исходного клипа.
• overlayOrder (default 0) - номер слоя для накладываемого клипа. Позволяет наложить клип после дополнительных.
• stabilizationDiffTolerance (default 200) - допустимая разница diff между соседними кадрами при стабилизации рендеринга сцены.
• stabilizationAreaTolerance (default 1.5) - допустимая разница в процентах между областями пересечения соседних кадров при стабилизации рендеринга сцены.
• StabilizationLength (default 0, max 20) - количество соседних кадров с каждой стороны для стабилизация рендеринга сцены. По умолчанию стабилизация отключена. Имеет смысл включать, если innerBounds > 0 и клипы исходно не стабилизированы относительно друг друга, т.е. статистика собиралась с параметром stabilize = false). Включение приведет к небольшой обрезке выходного кадра, но при этом картинка будет стабилизирована. Также учитывается sceneFile из OverlayEngine.
• overlayMode (default blend) – режим наложения для встроенного фильтра Overlay. Для оценки результата наложения рекомендуется использовать difference.
• width и height - ширина и высота выходного изображения. По умолчанию соответствует основному клипу.
• pixelType - цветовое пространство результирующего клипа, должен соответствовать типу цветового пространства накладываемых клипов (YUV или RGB). По умолчанию используется цветовое пространство основного клипа.
• gradient (default 0) - длина прозрачного градиента в пикселях по краям накладываемой области. Делает переход между изображениями более плавным.
• noise (default 0) - добавление шума на границы пересечений, чтобы сделать переходы менее заметными. Если больше 0, то gradient применяется только по краям.
• borderControl (default 0) – количество соседних кадров в обе стороны для анализа какие стороны маски наложения должны быть включены для текущего кадра с учетом параметра borderOffset.
• borderMaxDeviation (default 0.5) – максимальное отклонение общей площади текущего и соседнего кадра для использования в последовательности кадров при создании маски наложения.
• borderOffset (default empty) - клип типа Rect для задания "пустых" границ изображения (left, top, right, bottom), которые будут проигнорированы при расчете градиентной маски.
• srcColorBorderOffset (default empty) - (не реализовано) клип типа Rect для определения "пустых" границ основного клипа (left, top, right, bottom), которые будут проигнорированы при цветокоррекции.
• overColorBorderOffset (default empty) - (не реализовано) клип типа Rect для определения "пустых" границ накладываемого клипа (left, top, right, bottom), которые будут проигнорированы при цветокоррекции.
• maskMode (defualt false) - если true, замещает все клипы белой маской.
• opacity (default 1) - степень непрозрачности накладываемого изображения от 0 до 1.
• colorAdjust (default -1, disabled) - вещественное значение между 0 и 1. 0 - стремление к цвету основного клипа. 1 - накладываемого клипа. 0.5 - усредненный цвет. С дополнительными клипами поддерживаются только значения -1, 0, 1. Цветокоррекция основана на сравнении гистограмм области пересечения.
• colorBuckets (default 1024) - см. ColorMatch.length
• colorDither (default 0.95) - см. ColorMatch.dither
• colorExclude (default 0) - см. ColorMatch.exclude
• colorFramesCount (default 0) - количество соседних кадров в обе стороны, информация о которых включается в построение карты соответствия цветов для цветокоррекции
• colorFramesDiff (default 1) - максимальное среднеквадратическое отклонение гистограмм разницы цветов сэмпла и образца от текущего кадра к соседним для цветокоррекции
• colorMaxDeviation (default 0.5) - максимальное отклонение общей площади текущего и соседнего кадра для использования в последовательности кадров при цветокоррекции
• gradientColor - см. ColorMatch.gradient
• colorFrames - см. ColorMatch.frames
• colorMatchTarget - используется для сложных сценариев цветокоррекции внутри фильтра ColorMatchChain
• adjustChannels (default empty) - в каких каналах регулировать цвет. Примеры: "yuv", "y", "rgb", "rg".
• matrix (default empty). Если параметр задан, YUV изображение конвертируется в RGB по указанной матрице на время обработки.
• sourceMatrix and overlayMatrix (default empty) - возможность переопределить матрицу для основного или накладываемого клипа, используются в связке с параметром matrix
• downsize и upsize (default Spline36Resize или Spline36ResizeMT при наличии) - функции для уменьшения и увеличения размера изображений. Если задан только один параметр, то второй заполняется тем же значением.
• chromaResize - функция ресемплинга UV каналов в том же формате, что и downsize и upsize, по умолчанию используется значение downsize.
• rotate (default BilinearRotate) - функция вращения накладываемого изображения.
• preview - вывод превью.
• sourceName и overlayName - названия основного и накладываемого клипов для легенды.
• legend (default disabled) - размер текста в пикселях, активирует легенду, если preview = true.
• debug - вывод параметров наложения и превью.
• invert - поменять местами основной и накладываемый клипы, "инвертировать" параметры наложения.
• background (default blank) - способ заполнения фона: blank (сплошная заливка), blur (растянутое изображение с заливкой), inpaint (не реализовано).
• backgroundClip (default empty) - если указан, клип используется в качестве фона, должен иметь то же разрешение, что и результирующий клип.
• blankColor (default 0x008080 для YUV и 0x000000 для RGB) - цвет в HEX формате для заполнения пустот.
• backBalance - вещественное значение в диапазоне от -1 до 1 для задания источника заблюренного фона, если background равен blur. -1 - основной клип, 1 - накладываемый клип.
• backBlur (default 15) - сила смазывания, если background равен blur.
• fullScreen (default false) - фоновое изображение заполняется на всю площадь изображения, а не только на область объединения изображений.
• edgeGradient (default none) - градиент на границах изображений. none - отключено, inside - только внутри объединенной области, full - везде.
• bitDepth (default unused) - глубина цвета выходного изображения

ColorMatch

ColorMatch(clip, clip reference, clip sample, clip sampleMask, clip referenceMask, bool greyMask, 
           float intensity, int length, float dither, string channels, 
           int frameBuffer, float frameDiff, bool limitedRange, 
           int exclude, float gradient, int[] frames, int seed, string plane, string cacheId)

Автокоррекция цвета с помощью сопоставления цветовых гистограмм. Входной клип, sample и reference клипы должны быть в одном типе цветового диапазона (YUV or RGB). Входной клип и sample клип должны иметь одинаковую глубину цвета. Глубина цвета входного клипа изменится на глубину цвета клипа reference. Фильтр дает хороший результат только если sample и reference клипы содержат схожее наполнение кадра. Фильтр используется внутри OverlayRender, обрезая sample и reference клипы с учетом параметров наложения, но может использоваться и независимо, например для преобразвания HDR->SDR или наоборот клипов, имеющих одинаковое кадрирование.

Параметры

• clip (required) - входной клип, цвет которого будет откорректирован
• reference (required) - клип-образец с тем же наполнением, что и sample
• sample - клип, сравнивающийся с клипом-образцом. Если не задан, будет использован входной клип без обрезки.
• sampleMask and referenceMask (default empty) - маски для включения в обработку только пикселей с максимальным значением в заданной глубине цвета, т.е. 255, 1023 и т.п.
• greyMask (default true) - маска только по яркости или по всем каналам (используется только для YUV)
• intensity (default 1) - интенсивность цветокоррекции
• length (default 1024, max 1000000) - длина гистограммы, чем больше - тем качественнее, но медленнее. Фактическая длина ограничена глубиной цвета (256 для 8 bit, 1024 для 10 bit и т.п.).
• dither (default 0.95) - уровень дизеринга 0 (disable) to 1 (aggressive). Применяется только если фактическая длина гистгораммы равна глубине цвета. Добавляет упорядоченный шум, если один исходный цвет должен разбиться на несколько цветов, учитывая их веса.
• channels (default yuv or rgb) - плоскости или каналы для обработки. Допустимы любые комбинации y,u,v или r,g,b (пример: y, uv, r, br).
• frameBuffer (default 0) - количество соседних кадров в обе стороны, информация о которых включается в построение карты соответствия цветов
• frameDiff (default 1) - максимальное среднеквадратическое отклонение гистограмм разницы цветов сэмпла и образца от текущего кадра к соседним
• limitedRange (default false) - ТВ диапазон. Как правило нет смысла включать даже если исходные клипы в ТВ диапазоне.
• exclude (default 0, max 100) - минимальное количество пикселей одного цвета, используемых при цветокоррекции. Позволяет избежать случайных выбросов. Не применяется в режиме дизеринга.
• gradient (default 0, max 1000000) - если больше нуля, активирует режим градиентной цветокоррекция, когда по каждому кадру формируется не одна, а четыре гистограммы, с акцентами на разные углы изображения. Это позволяет скорреактировать цвет неравномерно по всему изображению. Подходит прежде всего для клипов, имеющих разный оригинальный мастеринг. Чем выше значение - тем сильнее эффект.
• frames (default empty) - рассчитать усредленный LUT по определенным кадрам, а не текущему, и применить ко всем кадрам входного клипа.
• seed (default is constant) - seed для дизеринга, если фильтр используется многократно для рендеринга одного кадра. Как правило, менять нет смысла.
• plane и cacheId - используются внутри OverlayRender

ColorMatchChain

ColorMatchChain(clip, clip reference, string sampleSpace, string referenceSpace, clip chain, 
                string preset, clip sample, clip sampleMask, clip referenceMask, bool greyMask, 
                clip engine, clip sourceCrop, clip overlayCrop, bool invert, int iterations, 
                string space, string format, string resize, int length, float dither, 
                float gradient, int frameBuffer, float frameDiff, float frameMaxDeviation, 
                int exclude, int[] frames, bool matrixConversionHQ,
                string inputChromaLocation, string outputChromaLocation)

Многошаговая автоматическая коррекция цвета с поддержкой статистики из OverlayEngine. Позволяет гибко скорректировать цвет клипов до их совмещения через OverlayRender. Например, для YUV клипов сначала преобразовать их цветовое пространство RGB HDR, скорректировать цвет, затем преобразовать в YUV HDR и снова скорректировать цвет. Преобразование цветовых пространств возможно как с использованием встроенных фильтров AviSynth, так и с помощью z.lib. Последняя может использоваться для преобразования SDR 709 -> HDR 2020 и наоборот. Цепочка преобразований задается с помощью склеенных фильтров ColorMatchStep (см. ниже). Встроенные пресеты генерируют готовую цепочку.

Параметры

• clip (required) - входной клип, цвет которого будет откорректирован
• reference (required) - клип-образец. Если параметр engine не определен, то должен быть с тем же наполнением, что и sample, иначе с тем же наполнением, что и в OverlayEngine.
• sampleSpace и referenceSpace (required) - цветовые пространства (матрицы) исходника и образца соответственно в терминах z.lib или avisynth, например: 2020ncl:st2084:2020:f или PC.2020.
• chain (required) - скленные клипы типа ColorMatchStep, определяющие цепочку преобразований.
• preset - пресет основных параметров фильтра для осуществления основных типов преобразований: HdrConversion - одношаговая конвертация SDR 709 -> HDR PQ 2020 или наоборот в зависимости от глубины цвета входных клипов с промежуточным преобразованием в RGB 32 bit. HdrConversionHQ - двушаговая конвертация SDR 709 -> HDR PQ 2020 или наоборот в зависимости от глубины цвета входных клипов с промежуточным преобразованием в RGB 32 bit, а затем в YUV 32 bit. RgbYuv32 - двушаговая конвертация клипов в произвольном цветовом пространстве сначала в RGB 32 bit, затем в YUV 32 bit. YuvRgb32 - двушаговая конвертация клипов в произвольном цветовом пространстве сначала в YUV 32 bit, затем в RGB 32 bit. RgbYuv10 - двушаговая конвертация клипов в произвольном цветовом пространстве сначала в RGB 10 bit, затем в YUV 10 bit. YuvRgb10 - двушаговая конвертация клипов в произвольном цветовом пространстве сначала в YUV 10 bit, затем в RGB 10 bit.
• sample - клип, сравнивающийся с клипом-образцом. Если не задан, будет использован входной клип без обрезки. При использовании engine, должен быть тем же клипом, что использовался для сбора статистики в качестве основы.
• sampleMask and referenceMask (default empty) - маски для включения в обработку только пикселей с максимальным значением в заданной глубине цвета, т.е. 255, 1023 и т.п.
• greyMask (default true) - маска только по яркости или по всем каналам (используется только для YUV)
• engine - клип типа OverlayEngine, в котором накладываемый клип соответствует reference клипу. Для инверсии необходимо использовать параметр invert=true.
• sourceCrop and overlayCrop - см. OverlayRender.sourceCrop and OverlayRender.overlayCrop
• iterations (default 1) - количество повторений цепочки преобразваний. Большее количество может давать лучший результат, но снижает производительность.
• space - цветовое пространство результирующего клипа, например: 2020ncl:st2084:2020:f или PC.2020. По умолчанию используется последнее цветовое пространство из цепочки преобразований.
• format - формат результирующего клипа, например: YUV420P10. По умолчанию используется последний формат из цепочки преобразований.
• resize (default BilinearResize) - фильтр для изменения размера изображений при использовании параметра engine, высокое качество не требуется. Если задан, также используется для ресемплинга uv каналов, иначе spline16.
• length (default 1024) - см. ColorMatch.length
• dither (default 0.95) - см. ColorMatch.dither
• gradient (default 0) - см. ColorMatch.gradient
• frameBuffer (default 0) - см. ColorMatch.frameBuffer
• frameDiff (default 1) - см. ColorMatch.frameDiff
• frameMaxDeviation (default 0.5) - см. OverlayRender.colorMaxDeviation
• exclude (default 0) - см. ColorMatch.exclude
• frames - см. ColorMatch.frames
• matrixConversionHQ (default false) - повышенное качество изменения цветовой матрицы в YUV пространстве с конвертацией в 32 bit
• inputChromaLocation and outputChromaLocation - смещение UV каналов относительно канала яркости входного и выходного клипов. Возможные значения: left, center, top_left, top, bottom, bottom_left. По умолчанию используется значение свойства кадра _ChromaLocation, иначе left.

ColorMatchStep

ColorMatchStep(string sample, string reference, string space, float intensity, clip merge, 
               float weight, float chromaWeight, string channels, int length, float dither, 
               loat gradient, int frameBuffer, float frameDiff, int exclude, bool debug)

Вспомогательный фильтр для определения цепочки преобразований внутри ColorMatchChain.

Параметры

• sample - целевой формат корректируемого клипа, например YV12
• reference - целевой формат клипа-образца
• space - целевое цветовое пространство в формате z.lib или матрица AviSynth
• intensity - переопределение ColorMatchChain.intensity
• merge - дочерний ColorMatchStep. Если определен, результат конвертации будет смешан с весами из параметров weight и chromaWeight
• channels - см. ColorMatch.channels
• length - переопределение ColorMatchChain.length
• dither - переопределение ColorMatchChain.dither
• gradient - переопределение ColorMatchChain.gradient
• frameBuffer - переопределение ColorMatchChain.frameBuffer
• frameDiff - переопределение ColorMatchChain.frameDiff
• exclude - переопределение ColorMatchChain.exclude

ComplexityOverlay

ComplexityOverlay(clip source, clip overlay, string channels, int steps, float preference, 
                  bool mask, float smooth, bool invert, int threads, bool debug)

Независимый фильтр для совмещения наиболее сложных участков двух клипов. Подходит для совмещения двух источников низкого качества. Клипы должны иметь одинаковые кадрирование, цвет, разрешения и цветовые пространства.

Parameters

• source and overlay - входные клипы
• channels (default yuv or rgb) - плоскости или каналы для обработки. Допустимы любые комбинации y,u,v или r,g,b (пример: y, uv, r, br).
• steps (default 1) - количество шагов формирования маски совмещения.
• preference (default 0) - если больше ноля 0 второй клип будет более предпочтителен, иначе первый клип. Рекомендуется: -1 to 1.
• mask (default false) - выводить маску наложения вместо совмещения.
• smooth (default 0) - смазать маску наложения для снижения резкости.
• invert (default false) - инверсия маски, т.е. предпочтение наименее сложных участков изображений
• threads (.NET default) - максимальное число потоков

ComplexityOverlayMany

ComplexityOverlayMany(clip source, clip[] overlays, string channels, int steps, bool invert, int threads, bool debug)

Аналогичен ComplexityOverlay, но позволяет объединить произвольное количество клипов.

OverlayCompare

OverlayCompare(clip engine, clip source, clip overlay, string sourceText, string overlayText, int sourceColor, 
               int overlayColor, int borderSize, float opacity, int width, int height, bool debug)

Фильтр позволяет визуализировать совмещение двух клипов.

Parameters

• engine (required) - OverlayEngine clip.
• source (required) - first, base clip.
• overlay (required) - second, overlaid clip.
• sourceText (default "Source") - source clip name.
• overlayText (default "Source") - overlay clip name.
• sourceColor (default 0x0000FF) - source clip border color.
• overlayColor (default 0x00FF00) - overlay clip border color.
• borderSize (default 2) - border size.
• opacity (default 0.51) - opacity of overlay clip.
• width (source clip width by default) - output width.
• height (source clip height by default) - output height.
• debug (default false) - print align settings.

StaticOverlayRender

StaticOverlayRender(clip source, clip overlay, float x, float y, float angle, float overlayWidth, float overlayHeight, 
                    string warpPoints, float diff, clip sourceMask, clip overlayMask, clip sourceCrop, clip overlayCrop,
                    string sourceChromaLocation, string overlayChromaLocation, clip extraClips, string preset, 
                    clip innerBounds, clip outerBounds, space overlayBalance, bool fixedSource, bool ignoreAspectRatio, 
                    string overlayMode, int width, int height, string pixelType, int gradient, int noise, clip borderOffset,
                    clip srcColorBorderOffset, clip overColorBorderOffset, bool maskMode, float opacity, 
                    float colorAdjust, int colorBuckets, float colorDither, int colorExclude, int colorFramesCount, 
                    float colorFramesDiff, bool colorBufferedExtrapolation, string adjustChannels, float gradientColor, 
                    string matrix, string sourceMatrix, string overlayMatrix, string upsize, string downsize, 
                    string chromaResize, string rotate, bool preview, bool debug, bool invert, string background, 
                    clip backgroundClip, int blankColor, float backBalance, int backBlur, bool fullScreen, 
                    string edgeGradient, int bitDepth)

Аналогичен OverlayRender, но без OverlayEngine, параметры совмещения клипов задаются вручную.

CustomOverlayRender

CustomOverlayRender(clip engine, clip source, clip overlay, string function, int width, int height, bool debug)

Фильтр позволяет визуализировать результат наложения с помощью пользовательский функции с параметрами clip engine, clip source, clip overlay, int x, int y, float angle, int overlayWidth, int overlayHeight, float diff)

Parameters

• engine (required) - OverlayEngine clip.
• source (required) - first, base clip.
• overlay (required) - second, overlaid clip.
• function (required) - user function name. The function must have the following parameters:
• width (source clip width by default) - output clip width.
• height (source clip height by default) - output clip height.
• debug (default false) - debug mode.

OverlayClip

OverlayClip(clip clip, clip mask, clip crop, float opacity, string matrix, bool minor, int color, string name, bool debug)

Вспомогательный фильтр, позволяющий указать дополнительный клип, маску и уровень прозрачности для OverlayRender.

Rect

Rect(float left, float top, float right, float bottom, bool debug)

Вспомогательный фильтр, позволяющий указать параметры для левой, верхней, правой и нижней части изображения соответственно. Если указан только left, то его значение распространяется на все. Если left и top, то right и bottom будут равны им же соответственно.

ColorRangeMask

ColorRangeMask(clip, int low, int high, bool greyMask)

Support filter which provides mask clip by color range: white if pixel value is between low and high arguments. For YUV clips only luma channel is used. For RGB clips all channels are proccessed independently. Output is the clip in the same color space. Limited range is not supported.

Parameters

• input (required) - input clip.
• low (default 0) - lower bound of color range.
• high (default 0) - higher bound of color range.
• greyMask (default true) - маска только по яркости или по всем каналам

BilinearRotate

BilinearRotate(clip, float)

Support filter for rotation by angle with bilinear interpolation.

Parameters

• input (required) - input clip.
• angle (required) - rotation angle.

OverlayMask

OverlayMask(clip template, int width, int height, 
            int left, int top, int right, int bottom, 
            bool noise, bool gradient, int seed)

Support filter which provides mask clip for overlay with gradient or noise at borders.

Parameters

• template (default empty) - if specified width, height and color space will be used from template clip for output.
• width - output clip width if template is not specified.
• height - output clip height if template is not specified.
• left, top, right, bottom - border size.
• noise - noise generation on borders.
• gradient - gradient borders.
• seed - seed for noise generation.

ExtractScenes

ExtractScenes(string statFile, string sceneFile, int sceneMinLength, float maxDiffIncrease)

Filter to extract and save scene key frames to text file based on stat file of aligning target clip to the target.Trim(1,0) clip.

Parameters

• statFile - stat file path
• sceneFile - scene file path
• sceneMinLength (default 10) - scene minimal length
• maxDiffIncrease (default 15) - scene detection DIFF value

User functions

В дополнение к перечисленным выше фильтрам в файле OverlayUtils.avsi определены пользовательские функции. Они предназначены для облегчения процесса синхронизиации двух клипов и подготовки исходников для автовыравнивания.

aoShift

aoShift(clip clp, int pivot, int length)

Сдвигает кадры, начиная с номера 'pivot', с удалением предыдущих или вставки пустых в зависимости от направления. Положительное значение 'length' - сдвиг вправо со вставкой пустых кадров перед 'pivot'. Отрицаительное значение 'length' - сдвиг влево с удалением кадров перед 'pivot'.

aoDelay

aoDelay(clip clp, int length)

Частый случай 'aoShift' для вставки или удаления кадров в начале клипа. Положительное значение 'length' - сколько пустых кадров вставить. Отрицаительное значение 'length' - сколько кадров выкинуть.

aoDelete

aoDelete(clip clp, int start, int end)

Удаление последовательности кадров от 'start' до 'end' включительно.

aoReplace

aoReplace(clip clp, clip replace, int start, int "end")

Замена последовательноси кадров аналогичной из другого (синхронизированного) клипа. Параметр 'end' равен параметру 'start' по умолчанию, удобно для замены только одного кадра. Явно указанный ноль в параметре 'end' заменяется на последний кадр.

aoOverwrite

aoOverwrite(clip clp, clip scene, int frame)

Вставка другого клипа 'scene', начиная с кадра 'frame' текущего с перезаписью.

aoInsert

aoInsert(clip clp, clip insert, int start, int "end")

Вставка без перезаписи фрагмента из другого клипа, начиная с позиции 'start' в обоих клипах, заканчивая кадром 'end' во вставляемом клипе. Параметр 'end' равен 'start' по умолчанию (вставка одного кадра). Явно указанный ноль в параметре 'end' заменяется на последний кадр.

aoTransition

aoTransition(clip prev, clip next, int transitionStart, int transitionEnd, 
             int "reverseTransitionStart", int "reverseTransitionEnd")

Плавный переход между синхронизированными клипами. transitionStart - начальный кадр перехода, включительно Положительное значение 'transitionEnd' - последний кадр перехода, включительно Отрицательное значение 'transitionEnd' - продолжительность перехода в кадрах, включительно reverseTransitionStart - начальный кадр обратного перехода, по умолчанию обратный переход отсутствует reverseTransitionEnd - последний кадр или длина обратного перехода, по умолчанию длина обратного перехода равна длине прямого

aoTransitionScene

aoTransitionScene(clip prev, clip next, int start, int end, int "length")

Плавный переход указанной длины 'length' между синхронизированными клипами от 'start' до 'end' для замены фрагмента в исходном клипе, частный случай aoTransition.

aoBorders

aoBorders(clip clp, int left, int top, int "right", int "bottom", 
          int "refLength", int "segments", float "blur", float "dither")

Исправление цветового уровня около границ кадра с использованием фильтра ColorMatch. Параметры left, top, right, bottom определяют сколько пикселей от границ необходимо обработать. Параметры right и bottom по умолчанию равны left и top соответственно. refLength (default 1) задает ширину/высоту области в непосредственной близости от корректируемой, которая будет использоваться как образец цвета. segments (default 1) позволяет разбить границы на сегменты и обработать каждый из них отдельно с плавными переходами, чтобы избежать ошибок цветокоррекции на большей площади кадра, особенно если кадр содержит много объектов. blur (default 0, max 1.5) смазывает ближайшие к границам пиксели для уменьшения шума dither - уровень дизеринга для фильтра ColorMatch

aoInvertBorders

aoInvertBorders(clip clp, int left, int top, int "right", int "bottom")

Инвертирует цвета по границам кадра, подходит для создания масок. В YUV клипе обрабатывается только яркость. Параметры right и bottom по умолчанию равны left и top соответственно.

aoInterpolate

aoInterpolate(clip clp, int length, int "start", int "end", int "removeGrain")

Интерполирует последовательность кадров клипа от 'start' до 'end' включительно, уменьшая или увеличивая их количество с помощью плагина MVTools.

aoInterpolateScene

aoInterpolateScene(clip clp, int inStart, int inEnd, int outStart, int outEnd, int "removeGrain")

Интерполирует последовательность кадров клипа от 'inStart' до 'inEnd' включительно, перезаписывая результатом кадры от 'outStart' до 'outEnd' с помощью плагина MVTools.

aoInterpolateOne

aoInterpolateOne(clip clp, int frame, bool "insert", int "removeGrain")

Вставляет (по умолчанию) или заменяет один кадр интерполируемым из соседних с помощью плагина MVTools.

aoDebug

aoDebug(clip clp)

Функция для дебага остальных функций пакета. Для функции aoReplace будут удалены все кадры кроме заменяемых.

aoExpand

aoExpand(clip mask, int pixels, string mode, float "blur")

Expand the black mask (mode=darken) or white mask (mode=lighten)

Варианты использования

Подготовка клипов

1. Перед выполнением любых действий с двумя клипами по их совмещению или цветокоррекции, их необходимо покадрово синхронизировать. Для этого подходит встроенный в AviSynth функционал: Trim, DeleteFrame, DuplicateFrame и т.п. Дополнительно можно использовать функции aoShift, aoDelay, aoDelete, aoReplace, aoOverwrite, aoInsert.
2. Если у видео есть поля, их необходимо обрезать с помощью функции Crop.
3. Клипы должны быть в одном типе цветового пространства - YUV или RGB, рекомендуется YUV.
4. Если по границам есть засветы или затемнение, можно попробовать восстановить яркость с помощью aoBorders.
5. Подготавливать клипы можно в отдельных файлах avs, которые затем надо импортировать в основной скрипт через функции Import.
6. Если исходные видео подвергаются тяжелой фильтрации, сильно влияющей производительность, их рекомендуется закодировать в lossless перед обработкой в OverlayEngine.

Совмещение клипов с автовыравниванием

1. Для начала нужно решить какой клип взять за основу. Обычно это исходник с бОльшим наполнением кадра.
2. Для автоматического совмещения оба клипа должны быть одной глубины цвета, т.е. например 8 бит или 10 бит. Если один из источников в HDR, а другой в SDR, то рекомендуется HDR клип сконвертировать в SDR. Особенно это удобно если HDR клипу уже имеется альтернатива с таким же кадрированием, но в SDR, тогда можно использовать фильтр ColorMatchChain с пресетом HdrConversion.
3. Далее необходимо подготовить болванку скрипта для совмещения с включенным режимом отладки, чтобы оценить результат и скорректировать параметры выравнивания:

   OM=Import("OM.avs")
   WS=Import("WS.avs")
   WStest = WS.ColorMatchChain(Import("WS_SDR.avs"), preset = "HdrConversion") # Пример предварительной цветокоррекции с изменением глубины цвета для использования в OverlayEngine вместо клипа WS
   config = OverlayConfig() # добавить нужные параметры по мере необходимости, например aspectRatio1, aspectRatio2, preset и т.п.
   engine = OverlayEngine(OM, WS, configs = config)
   engine.OverlayRender(OM, WS, debug = true, preset = "difference")
   
   

4. В AvsPmod посмотреть результат. Область пересечения должны быть как можно более монотонно серой без котуров. При ненобходимости нужно скорректировать параметры OverlayConfig и OverlayEngine.
5. После подбора оптимальных параметров, нужно указать файл статистики и запустить тестовый прогон для сбора статистики. В AvsPmod: Video/Tools/Run analysis pass. OverlayRender при этом лучше временно закомментировать - это повысит производительность:

   config = OverlayConfig(preset = "high", aspectRatio1 = 2.38, aspectRatio2 = 2.42) # подобранные параметры
   engine = OverlayEngine(OM, WS, configs = config, statFile = "WS.stat")
   engine#.OverlayRender(OM, WS, debug = true, preset = "difference") # OverlayRender закомментирован с помощью #
   

6. После тестового прогона, можно проверить и отредактировать результат с помощью редактора, добавив в OverlayEngine параметр editor=true.
7. Теперь можно подготовить итоговое видео, расскомментировав OverlayRender и добавив нужные параметры:

   engine.OverlayRender(OM, WS, debug = false, preset = "FullFrame", colorAdjust = 0) # Максимизация содержимого кадра с цветокоррекций по основному клипу
   

8. Если накладываемый клип худшего качества, чем основной, то в OverlayRender необходимо сделать его прозрачным, т.е. opacity=0.

Совмещение источников с одинаковым наполнением кадра для получения результата лучшего качества

Для этого необходимо использовать фильтр ComplexityOverlay или ComplexityOverlayMany, если фильтров несколько:

ComplexityOverlay(clip1, clip2, steps = 2, smooth = 0.5)

ComplexityOverlay целесообразно использовать до применения к источникам фильтров, которые глобально влияют на изображение, например ColorMatch. Если есть потребность в фильтрации, то сначала надо создать маску наложения в режиме mask=true, затем применить фильтры, а потом наложить клипы один на другой по маске:

mask = ComplexityOverlay(clip1, clip2, steps = 2, smooth = 0.5, mask = true)
clip2 = clip2.ColorMatch(clip1)
clip1.Overlay(clip2, mask = mask)

Автоматическая цветокоррекция

1. Для этого предусмотрены фильтры ColorMatch и ColorMatchChain.

2. Если клипы кадрированы по-разному в динамике, то предварительно надо их выровнять с помощью OverlayEngine.

3. Если исходные клипы в одном цветовом пространстве, а цвет подвергался лишь линейным преобразованиям, то достаточно использовать ColorMatch или OverlayRender:

   target.ColorMatch(reference)

4. Для сложной многошаговой цветокоррекции необходимо использовать ColorMatchChain:

   target.ColorMatchChain(reference, preset = "RgbYuv32")

Конвертация HDR <-> SDR

Для этого нужно использовать ColorMatchChain с престом HdrConversion или HdrConversionHQ. Если кадрирование динамическое, нужно подготовить OverlayEngine и указать его в параметре engine.

Удаление логотипа

1. Если на видео есть логотип, необходимо подготовить клип-маску, где логотип имеет строго черный (нулевой) цвет.
2. По краям его целесообразно заблюрить, чтобы обеспечить плавные переходы при наложении в OverlayRender. При этом заблюренные границы должны быть уже за рамками логотипа: mask = ImageSource("logo.png", end = 0, pixel_type = "Y8") # статичная маска из одного кадра mask = mask.aoExpand(3, "darken", 1.5) # опциональное расширение маски с блюром
3. Клип-маска может быть динамическим и иметь ту же длину, что и основной клип.
4. После создании маски, ее необходимо использовать во всех фильтрах, где она поддерживается для основного или накладываемого клипа: OverlayEngine, ColorMatch, OverlayRender и т.п.

Сравнение клипов

1. Если требуется покадрово проверить, что два клипа имеют одинаковое кадрирование/полностью синхронизированы/не содержат битые кадры, можно использовать OverlayEngine, приведя оба клипа к единому разрешению:

   clip1 = clip1.BilinearResize(clip2.width, clip2.height)
   OverlayEngine(clip1, clip2, maxDiff = 1024, sceneDiffTolerance = 10000, statFile = "diff.stat")
   

2. После тестового прогона уменьшить maxDiff до минимального уровня и посмотреть какие кадры выходят за его пределы в редакторе (чекбокс Defective only):

   OverlayEngine(clip1, clip2, maxDiff = 5, statFile = "diff.stat", editor = true)

История изменений

23.11.2025 v0.7.12

1. OverlayEngine: обновлен UI редактора: табы, масштабирование при просмотре, переопределение свойств конфигурации.
2. OverlayRender: новый параметр ignoreAspectRatio для растягивания изображения во весь экран, игнорируя оригинальное соотношение сторон.
3. OverlayRender: исправлена цветокоррекция при использовании нескольких масок.

12.05.2025 v0.7.11

1. OverlayRender и ColorMatchChain: исправлена деградация производительности при использовании colorAdjust в простом режиме.

11.05.2025 v0.7.10

1. ComplexityOverlay и ComplexityOverlayMany: цветовые пространства I420 и YV12 теперь могут использоваться одновременно.
2. OverlayRender: исправлена работа с OverlayEngine в режимах PROCESSED и UNPROCESSED.
3. OverlayRender: новые параметры legend, sourceName, overlayName и OverlayClip.name для отображения легенды в режиме preview.
4. OverlayRender: исправлена поддержка параметров overlayBalanceX и overlayBalanceY.

07.05.2025 v0.7.9

1. OverlayEngine: улучшено автовыравнивание в субпиксельном режиме.
2. OverlayEngine: исправлено автовыравнивание при более чем двукратной разнице в разрешении клипов.
3. OverlayEngine: для повышения производительности для ресайзинга масок используется фильтр из параметра presize, либо его многопоточный аналог, если установлен.
4. OverlayRender: из-за нестабильной работы служебный фильтр CombinePlanesMT теперь не используется по умолчанию. Включается при наличии в окружении (скрипте) переменной AO_MT_RENDER = true.
5. Исправлена поддержка interleaved цветовых пространств.

03.05.2025 v0.7.8

1. OverlayEngine: новый параметр sceneClips, позволяющий в паре с параметром sceneFile автоматически отобрать ключевые кадры в сцене для более точной цветокоррекции.
2. ColorMatchChain: контроль свойства клипа _ColorRange на выходе.
3. ColorMatch и ColorMatchChain: параметр frame переименован во frames и теперь позволяет указать несколько кадров, на основе которых будет применена усредненная LUT ко всему выходному клипу.
4. Параметр bufferedExtrapolation упразднен во всех фильтрах, где он присутствовал из-за плохо предсказуемого результата применения.
5. OverlayRender: новый параметр colorFrames - аналог параметр ColorMatch.frames.
6. OverlayRender: новый служебный фильтр CombinePlanesMT - многопоточный аналог системного CombinePlanes. Не требует явного использования, задействован внутри OverlayRender для повышения производительности.

21.04.2025 v0.7.7

1. OverlayEngine: исправлено автовыравнивание, если разрешение исходников сильно различается.
2. Параметр exclude для коррекции цвета сделан целочисленным и теперь задает минимальное количество пикселей одного цвета вместо их доли во всем изображении, т.к. работа этого параметра не должна зависеть от разрешения.

17.04.2025 v0.7.6

1. Восстановлена корректная работа ComplexityOverlay и ComplexityOverlayMany

16.04.2025 v0.7.5

1. OverlayEngine: улучшено автовыравнивание в субпиксельном режиме.
2. OverlayRender: параметр chromaResize для явного выбора алгоритма ресемплинга UV каналов, по умолчанию равен значению параметра downsize.
3. OverlayRender: параметры sourceChromaLocation, overlayChromaLocation и OverlayClip.chromaLocation для явного указания смещения UV каналов относительно канала яркости. Допустимые значения: left, center, top_left, top, bottom_left, bottom. По умолчанию используется свойство кадра _ChromaLocation, либо left.
4. ColorMatchChain: параметры inputChromaLocation и outputChromaLocation для явного указания смещения UV каналов относительно канала яркости. По умолчанию используется свойство кадра _ChromaLocation, либо left.
5. ColorMatchChain: для ресемплинга UV каналов используется тот же алгоритм, что указан в параметре resize, либо spline16 по умолчанию.
6. Фильтры теперь по возможности пробрасывают свойства кадра входного клипа.
7. Обновлена версия библиотеки AvsFilterNet.

06.04.2025 v0.7.4

1. ColorMatchChain: улучшена экстраполяция цвета.
2. OverlayEngine: исправлено предсказание при наличии sceneFile.
3. OverlayEngine: исправлена работа параметра colorAdjust в некоторых случаях.

04.04.2025 v0.7.3

1. OverlayEngine: увеличены значения по умолчанию параметра frameDiffTolerance.
2. OverlayEngine: улучшение стабилизации сцен.
3. OverlayRender: исправлена стабилизация цветокоррекции при использовании параметра colorFramesCount.
4. OverlayRender: параметр noise снова сделан целочисленным и теперь применяется внутри кадра вместо gradient, если задан, а gradient в этом случае применяется только по краям.
5. OverlayRender: исправлено наложения градиента по краям кадра.
6. OverlayRender: доработана поддержка некоторые цветовых пространств.
7. OverlayRender: исправлена работа параметра overlayCrop.
8. OverlayRender: исправлена работа с масками.
9. ColorMatch: повышение производительности при использовании параметра frameBuffer.

25.03.2025 v0.7.2

1. OverlayEngine: исправлено предсказание в режиме сканирования
2. Общее повышение производительности.

24.03.2025 v0.7.1

1. OverlayEngine: исправлена баги в автовыравнивании и предсказании

15.03.2025 v0.7

1. Все функции фильтра ColorAdjust перенесены в фильтр ColorMatch. Фильтр ColorAdjust упразднен.
2. OverlayEngine: новый алгоритм предсказания и стабилизации с пресетами.
3. OverlayRender: новый алгоритм наложения с помощью вспомогательного фильтра LayerMask.
4. OverlayRender: параметры StabilizationDiffTolerance, StabilizationAreaTolerance, StabilizationLength для стабилизации изображения
5. OverlayConfig: пресеты
6. OverlayConfig: дополнительные параметры поворота изображения
7. ComplexityOverlay и ComplexityOverlayMany - поддержка HDR и параметры маски инверсии наложения.
8. Значительно улучшена производительность в большинстве фильтров.
9. Новые фильтры ColorMatchChain и ColorMatchStep для многошаговой коррекции цвета.
10. OverlayRender: параметры для коррекции кроппинга клипов уже после применения OverlayEngine.
11. OverlayEditor: доработан UI, учтены последние изменения в фильтрах.
12. Упразднена библиотека simd.dll, которая теперь встроена в AutoOverlayNative.dll.
13. Поддержка RGBP и 32 bit HDR в большинстве фильтров.

13.05.2024 v0.6.2

1. ColorMatch: новый фильтр для сопоставления цветов с поддержкой 32-битного цвета
2. OverlayEngine, OverlayRender, OverlayMask: улучшенная поддержка HDR и RGB
3. OverlayRender: параметр BitDepth, чтобы явно указать глубину цвета результирующего клипа
4. OverlayRender: пресеты
5. OverlayRender: устранены артефакты на границах изображения при наличии цветовой субдискретизации
6. OverlayRender: используется фильтр ColorMatch вместо ColorAdjust для глубины цвета 32 бита
7. MathNet.Numerics обновлена до версии 5.0.0
8. Исправлено высвобождение ресурсов

02.12.2023 v0.6.1

1. OverlayEngine: warp and colorAdjust bugfix

01.12.2023 v0.6

1. OverlayRender: упразднен параметр mode
2. OverlayRender: добавлены параметры extraClips, innerBounds, outerBounds, overlayBalanceX, overlayBalanceY, fixedSource, overlayOrder, maskMode, colorInterpolation, colorExclude, backgroundClip, backBalance, fullScreen, edgeGradient.
3. OverlayRender: параметр background заменен на backBalance, а назначение background изменено.
4. OverlayRender: добавлена поддержка наложения произвольного количества клипов.
5. OverlayEngine: параметры panScanDistance и panScanScale переименованы в scanDistance и scanScale.
6. Добавлен фильтр ComplexityOverlayMany.