convolution

convolution(
  input: Clip,
  #{
    matrix: Array<Int | Float>,
    bias?: Int | Float,
    divisor?: Int | Float,
    planes?: Array<Int>,
    saturate?: Bool,
    mode?: String,
  }
)

Performs spatial convolution on selected planes using a user-supplied kernel.

The input must be one fixed-format planar Gray, YUV, or planar RGB clip. All sample types (u8, u16, f32) are supported.

The kernel is supplied as a flat row-major array. Square mode ("s", the default) requires exactly 9 values (3x3) or 25 values (5x5). Horizontal, vertical, and separable modes accept any odd length from 3 through 25.

Edge pixels use periodic reflection. Border coordinates are mirrored without repeating the edge sample, so the filter always evaluates a full neighborhood even at image borders, on single-pixel-wide planes, and when the kernel is larger than the plane.

Matrix coefficients must be finite and within -1023..=1023. For integer sample formats, f64 coefficient values are rounded to the nearest i16 before use. For float sample formats, coefficients are cast to f32.

When divisor is omitted or set to 0, the effective divisor is the sum of the runtime coefficients. If that sum is near zero (absolute value below f32::EPSILON), the divisor defaults to 1. An explicit non-zero divisor must have a finite f32 reciprocal.

Integer output uses f32 division and bias, rounds ties to even, and clamps to the declared bit-depth code range. Float output is not clamped.

When saturate is true (the default), float output preserves signed values and integer output clamps negative results to 0 through the normal output clamp. When saturate is false, the absolute value of the result is taken before any clamping.

If planes is omitted or set to (), every plane is processed. If planes is provided, only the listed zero-based plane indexes are processed; all other planes are preserved without modification and share their input storage. An empty array processes no planes and the input frames are returned unchanged.

Examples

Gaussian-like 3x3 blur with default divisor (coefficient sum = 16):

output = source("input.mkv").std.convolution(#{
  matrix: [1, 2, 1, 2, 4, 2, 1, 2, 1],
})

Horizontal Sobel edge detection on the luma plane only, with absolute output:

output = source("input.mkv").std.convolution(#{
  matrix: [-1, 0, 1],
  mode: "h",
  divisor: 1,
  saturate: false,
  planes: [0],
})

Input

One fixed-format planar Gray, YUV, or planar RGB clip.

Output

A clip with the same format, resolution, timing, and metadata, with selected planes replaced by the convolution result.

Options

• matrix (Array<Int | Float>) – Flat row-major kernel coefficients. Square mode requires 9 or 25 values. One-dimensional modes require an odd length from 3 through 25. Values must be finite and within -1023..=1023.
• bias (Int | Float, default: 0) – Additive value applied to the output sample after division.
• divisor (Int | Float, default: 0) – Divides the accumulated sum before bias is added. A value of 0 selects the coefficient sum as the divisor; if the sum is near zero, the divisor becomes 1.
• planes (Array<Int>, default: all planes) – Zero-based plane indexes to process. Unlisted planes are preserved without modification. An empty array processes no planes.
• saturate (Bool, default: true) – When true, float output preserves signed values and integer output clamps negative results to 0. When false, the absolute value of the result is taken.
• mode (String, default: "s") – Kernel arrangement. "s" for square (3x3 or 5x5), "h" for horizontal, "v" for vertical, "hv" or "vh" for separable (vertical pass then horizontal pass, each finalized independently). Case-insensitive.