enum ¶

def __call__(self, taps: int | None = None, **kwargs: Any) -> Any:
    """
    Generate the blur kernel based on the enum variant.

    Args:
        taps: Size of the kernel in each direction.
        sigma: [GAUSS only] Standard deviation of the Gaussian kernel.
        mode: Convolution mode. Default depends on kernel.

    Returns:
        A `BlurMatrixBase` instance representing the kernel.
    """
    kernel: BlurMatrixBase[Any]

    match self:
        case BlurMatrix.MEAN_NO_CENTER:
            taps = fallback(taps, 1)
            mode = kwargs.pop("mode", ConvMode.SQUARE)

            matrix = [1 for _ in range(((2 * taps + 1) ** (2 if mode == ConvMode.SQUARE else 1)) - 1)]
            matrix.insert(len(matrix) // 2, 0)

            return self.custom(matrix, mode)

        case BlurMatrix.MEAN:
            taps = fallback(taps, 1)
            mode = kwargs.pop("mode", ConvMode.SQUARE)

            kernel = self.custom((1 for _ in range((2 * taps + 1))), mode)

        case BlurMatrix.BINOMIAL:
            taps = fallback(taps, 1)
            mode = kwargs.pop("mode", ConvMode.HV)

            c = 1
            n = taps * 2 + 1

            matrix = list[int]()

            for i in range(1, taps + 2):
                matrix.append(c)
                c = c * (n - i) // i

            kernel = self.custom(matrix[:-1] + matrix[::-1], mode)

        case BlurMatrix.GAUSS:
            taps = fallback(taps, 1)
            sigma = kwargs.pop("sigma", 0.5)
            mode = kwargs.pop("mode", ConvMode.HV)
            scale_value = kwargs.pop("scale_value", 1023)

            if mode == ConvMode.SQUARE:
                scale_value = sqrt(scale_value)

            taps = self.get_taps(sigma, taps)

            if taps < 0:
                raise CustomValueError("Taps must be >= 0!")

            if sigma > 0.0:
                half_pisqrt = 1.0 / sqrt(2.0 * pi) * sigma
                doub_qsigma = 2 * sigma**2

                high, *mat = [half_pisqrt * exp(-(x**2) / doub_qsigma) for x in range(taps + 1)]

                mat = [x * scale_value / high for x in mat]
                mat = [*mat[::-1], scale_value, *mat]
            else:
                mat = [scale_value]

            kernel = self.custom(mat, mode)

        case _:
            raise CustomNotImplementedError("Unsupported blur matrix enum!", self, self)

    if mode == ConvMode.SQUARE:
        kernel = kernel.outer()

    return kernel

@classmethod
def custom(cls, values: Iterable[_Nb], mode: ConvMode = ConvMode.SQUARE) -> BlurMatrixBase[_Nb]:
    """
    Create a custom BlurMatrixBase kernel with explicit values and mode.

    Args:
        values: The kernel coefficients.
        mode: Convolution mode to use.

    Returns:
        A BlurMatrixBase instance.
    """
    return BlurMatrixBase(values, mode=mode)

def from_radius(self: Literal[BlurMatrix.GAUSS], radius: int) -> BlurMatrixBase[float]:  # type: ignore[misc]
    """
    Generate a Gaussian blur kernel from an intuitive radius.

    This is a shortcut that converts a blur radius to a corresponding sigma value.

    Args:
        radius: Blur radius.

    Returns:
        Gaussian blur matrix.
    """
    assert self is BlurMatrix.GAUSS

    return BlurMatrix.GAUSS(None, sigma=(radius + 1.0) / 3)

def get_taps(self: Literal[BlurMatrix.GAUSS], sigma: float, taps: int | None = None) -> int:  # type: ignore[misc]
    """
    Compute the number of taps required for a given sigma value.

    Args:
        sigma: Gaussian sigma value.
        taps: Optional manual override; if not provided, it's computed from sigma.

    Returns:
        Number of taps.
    """
    assert self is BlurMatrix.GAUSS

    if taps is None:
        taps = ceil(abs(sigma) * 8 + 1) // 2

    return taps

def __call__(
    self,
    clip: vs.VideoNode | Iterable[vs.VideoNode],
    planes: PlanesT = None,
    bias: float | None = None,
    divisor: float | None = None,
    saturate: bool = True,
    passes: int = 1,
    func: FuncExceptT | None = None,
    expr_kwargs: KwargsT | None = None,
    **conv_kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Apply the blur kernel to the given clip via spatial or temporal convolution.

    Chooses the appropriate backend (`std.Convolution`, `std.AverageFrames`, or `ExprOp.convolution`)
    depending on kernel size, mode, format, and other constraints.

    Args:
        clip: Source clip.
        planes: Planes to process. Defaults to all.
        bias: Value added to result before clamping.
        divisor: Divides the result of the convolution (before adding bias). Defaults to sum of kernel values.
        saturate: If True, negative values are clamped to zero. If False, absolute values are returned.
        passes: Number of convolution passes to apply.
        func: Function returned for custom error handling. This should only be set by VS package developers.
        expr_kwargs: Extra kwargs passed to ExprOp.convolution when used.
        **conv_kwargs: Any other args passed to the underlying VapourSynth function.

    Returns:
        Processed (blurred) video clip.
    """
    clip = to_arr(clip)

    func = func or self

    assert check_variable_format(clip, func)

    if len(self) <= 1:
        return clip[0]

    expr_kwargs = expr_kwargs or {}

    fp16 = clip[0].format.sample_type == vs.FLOAT and clip[0].format.bits_per_sample == 16

    # Spatial mode
    if self.mode.is_spatial:
        if len(clip) > 1:
            raise CustomValueError("You can't pass multiple clips when using a spatial mode.", func)

        # TODO: https://github.com/vapoursynth/vapoursynth/issues/1101
        if all([not fp16, len(self) <= 25, all(-1023 <= x <= 1023 for x in self), self.mode != ConvMode.SQUARE]):
            return iterate(clip[0], core.std.Convolution, passes, self, bias, divisor, planes, saturate, self.mode)

        return iterate(
            clip[0],
            ExprOp.convolution("x", self, bias, fallback(divisor, True), saturate, self.mode, **expr_kwargs),
            passes,
            planes=planes,
            **conv_kwargs,
        )

    # Temporal mode
    use_std = all(
        [
            not fp16,
            len(self) <= 31,
            all(-1023 <= x <= 1023 for x in self),
            not bias,
            saturate,
        ]
    )

    if len(clip) > 1:
        if passes != 1:
            raise CustomValueError(
                "`passes` are not supported when passing multiple clips in temporal mode", func, passes
            )

        if use_std:
            return core.std.AverageFrames(clip, self, divisor, planes=planes)

        return ExprOp.convolution(
            ExprVars(len(clip)), self, bias, fallback(divisor, True), saturate, self.mode, **expr_kwargs
        )(clip, planes=planes, **conv_kwargs)

    # std.AverageFrames doesn't support premultiply, multiply and clamp from ExprOp.convolution
    if use_std and conv_kwargs.keys() <= {"scenechange"}:
        return iterate(clip[0], core.std.AverageFrames, passes, self, divisor, planes=planes, **conv_kwargs)

    return self._averageframes_akarin(clip[0], planes, bias, divisor, saturate, passes, expr_kwargs, **conv_kwargs)

def outer(self) -> Self:
    """
    Convert a 1D kernel into a 2D square kernel by computing the outer product.

    Returns:
        New `BlurMatrixBase` instance with 2D kernel and same mode.
    """
    from numpy import outer

    return self.__class__(list[_Nb](outer(self, self).flatten()), self.mode)  # pyright: ignore[reportArgumentType]