exprop ¶

def __call__(
    self,
    *clips: VideoNodeIterable,
    planes: Planes = None,
    format: HoldsVideoFormat | VideoFormatLike | None = None,
    opt: bool = False,
    boundary: bool = True,
    func: FuncExcept | None = None,
    split_planes: bool = False,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Apply the expression to one or more input clips.

    Args:
        clips: Input clip(s).
        planes: Plane to process, defaults to all.
        format: Output format, defaults to the first clip format.
        opt: Forces integer evaluation as much as possible.
        boundary: Specifies the default boundary condition for relative pixel accesses:

               - `True` (default): Mirrored edges.
               - `False`: Clamped edges.
        func: Function returned for custom error handling. This should only be set by VS package developers.
        split_planes: Splits the VideoNodes into their individual planes.
        kwargs: Additional keyword arguments passed to [norm_expr][vsexprtools.norm_expr].

    Returns:
        Evaluated clip.
    """
    from .funcs import norm_expr

    return norm_expr(clips, self, planes, format, opt, boundary, func, split_planes, **kwargs)

def append(self, *__object: SupportsString) -> None:
    for __obj in __object:
        super().append(__obj)

def to_str(self) -> str:
    return str(self)

def __call__(self, *pos_args: Any, **kwargs: Any) -> vs.VideoNode | str:
    """
    Combines multiple video clips using the selected expression operator or returns a formatted version
    of the [ExprOp][vsexprtools.ExprOp], using substitutions from pos_args and kwargs.

    Args:
        *pos_args: Positional arguments.
        **kwargs: Keywords arguments.

    Returns:
        A clip representing the combined result of applying the expression
        or formatted version of this [ExprOp][vsexprtools.ExprOp].
    """
    args = list(flatten(pos_args))

    if args and isinstance(args[0], vs.VideoNode):
        return self.combine(*args, **kwargs)

    while True:
        try:
            return self.format(*args, **kwargs)
        except KeyError as key:
            if not args:
                raise
            kwargs[key.args[0]] = args.pop(0)

@classmethod
def acos(cls, c: SupportsString = "", n: int = 10) -> ExprList:
    """
    Build an expression to approximate arccosine using an identity: `acos(x) = π/2 - asin(x)`

    Args:
        c: The input expression variable.
        n: Number of terms to use in the internal asin approximation.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the acos(x) expression.
    """
    return ExprList([c, "__acosvar!", cls.PI, 2, cls.DIV, cls.asin("__acosvar@", n), cls.SUB])

@classmethod
def asin(cls, c: SupportsString = "", n: int = 10) -> ExprList:
    """
    Build an expression to approximate arcsine using an identity: `asin(x) = atan(x / sqrt(1 - x²))`

    Args:
        c: The input expression variable.
        n: Number of terms to use in the internal atan approximation.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the asin(x) expression.
    """
    return cls.atan(ExprList([c, cls.DUP, cls.DUP, cls.MUL, 1, cls.SWAP, cls.SUB, cls.SQRT, cls.DIV]).to_str(), n)

@classmethod
def atan(cls, c: SupportsString = "", n: int = 10) -> ExprList:
    """
    Build an expression to compute arctangent (atan) using domain reduction.

    Args:
        c: The expression variable or string input.
        n: The number of terms to use in the Taylor series approximation.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the arctangent expression.
    """
    # Using domain reduction when |x| > 1
    expr = ExprList(
        [
            ExprList([c, cls.DUP, "__atanvar!", cls.ABS, 1, cls.GT]),
            ExprList(
                [
                    "__atanvar@",
                    cls.SGN.convert_extra(),
                    cls.PI,
                    cls.MUL,
                    2,
                    cls.DIV,
                    1,
                    "__atanvar@",
                    cls.DIV,
                    cls.atanf("", n),
                    cls.SUB,
                ]
            ),
            ExprList([cls.atanf("__atanvar@", n)]),
            cls.TERN,
        ]
    )

    return expr

@classmethod
def atanf(cls, c: SupportsString = "", n: int = 10) -> ExprList:
    """
    Approximate atan(x) using a Taylor series centered at 0.

    This is accurate for inputs in [-1, 1]. Use [ExprOp.atan][vsexprtools.ExprOp.atan] for full-range values.

    Args:
        c: The expression variable or string input.
        n: The number of terms in the Taylor series (min 2).

    Returns:
        An [ExprList][vsexprtools.ExprList] approximating atan(x).
    """
    # Approximation using Taylor series
    n = max(2, n)

    expr = ExprList([c, cls.DUP, "__atanfvar!"])

    for i in range(1, n):
        expr.append("__atanfvar@", 2 * i + 1, cls.POW, 2 * i + 1, cls.DIV, cls.SUB if i % 2 else cls.ADD)

    return expr

@classmethod
def clamp(
    cls, min: float | ExprToken = ExprToken.RangeMin, max: float | ExprToken = ExprToken.RangeMax, c: str = ""
) -> ExprList:
    """
    Create an expression to clamp a value between `min` and `max`.

    Args:
        min: The minimum value.
        max: The maximum value.
        c: Optional expression variable or prefix to clamp.

    Returns:
        An [ExprList][vsexprtools.ExprList] containing the clamping expression.
    """
    return ExprList([c, min, max, ExprOp.CLAMP])

def combine(
    self,
    *clips: VideoNodeIterable,
    suffix: SupportsString | Iterable[SupportsString] | None = None,
    prefix: SupportsString | Iterable[SupportsString] | None = None,
    expr_suffix: SupportsString | Iterable[SupportsString] | None = None,
    expr_prefix: SupportsString | Iterable[SupportsString] | None = None,
    planes: Planes = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Combines multiple video clips using the selected expression operator.

    Args:
        clips: Input clip(s).
        suffix: Optional suffix string(s) to append to each input variable in the expression.
        prefix: Optional prefix string(s) to prepend to each input variable in the expression.
        expr_suffix: Optional expression to append after the combined input expression.
        expr_prefix: Optional expression to prepend before the combined input expression.
        planes: Which planes to process. Defaults to all.
        **kwargs: Additional keyword arguments forwarded to [combine][vsexprtools.combine].

    Returns:
        A clip representing the combined result of applying the expression.
    """
    from .funcs import combine

    return combine(clips, self, suffix, prefix, expr_suffix, expr_prefix, planes, **kwargs)

def combine_expr(
    self,
    n: SupportsIndex | Sequence[SupportsString] | HoldsVideoFormat | VideoFormatLike,
    suffix: SupportsString | Iterable[SupportsString] | None = None,
    prefix: SupportsString | Iterable[SupportsString] | None = None,
    expr_suffix: SupportsString | Iterable[SupportsString] | None = None,
    expr_prefix: SupportsString | Iterable[SupportsString] | None = None,
) -> ExprList:
    """
    Combines multiple video clips using the selected expression operator.

    Args:
        n: Object from which to infer the variables.
        suffix: Optional suffix string(s) to append to each input variable in the expression.
        prefix: Optional prefix string(s) to prepend to each input variable in the expression.
        expr_suffix: Optional expression to append after the combined input expression.
        expr_prefix: Optional expression to prepend before the combined input expression.

    Returns:
        A clip representing the combined result of applying the expression.
    """
    from .funcs import combine_expr

    return combine_expr(n, self, suffix, prefix, expr_suffix, expr_prefix)

def convert_extra(  # type: ignore[misc]
    self: Literal[
        ExprOp.SGN,
        ExprOp.NEG,
        ExprOp.TAN,
        ExprOp.ATAN,
        ExprOp.ASIN,
        ExprOp.ACOS,
        ExprOp.CEIL,
        ExprOp.MMG,
        ExprOp.LERP,
        ExprOp.POLYVAL,
    ],  # pyright: ignore[reportGeneralTypeIssues]
    degree: int | None = None,
) -> str:
    """
    Converts an 'extra' operator into a valid `akarin.Expr` expression string.

    Args:
        degree: If calling from POLYVAL, the degree of the polynomial.

    Returns:
        A string representation of the equivalent expression.

    Raises:
        ValueError: If the operator is not marked as extra.
        NotImplementedError: If the extra operator has no defined conversion.
    """
    if not self.is_extra():
        raise CustomValueError

    match self:
        case ExprOp.SGN:
            return "dup 0 > swap 0 < -"
        case ExprOp.NEG:
            return "-1 *"
        case ExprOp.TAN:
            return "dup sin swap cos /"
        case ExprOp.ATAN:
            return self.atan().to_str()
        case ExprOp.ASIN:
            return self.asin().to_str()
        case ExprOp.ACOS:
            return self.acos().to_str()
        case ExprOp.CEIL:
            return "-1 * floor -1 *"
        case ExprOp.MMG:
            return self.masked_merge().to_str()
        case ExprOp.LERP:
            if bytes(self, "utf-8") in _get_akarin_expr_version()["expr_features"]:
                return str(self)
            return "dup 1 - swap2 * swap2 * -"
        case ExprOp.POLYVAL:
            assert degree is not None
            return self.polyval("", *[""] * (degree + 1)).to_str()
        case _:
            raise NotImplementedError

@classmethod
def convolution(
    cls,
    var: SupportsString | Collection[SupportsString],
    matrix: Iterable[SupportsSumNoDefaultT] | Iterable[Iterable[SupportsSumNoDefaultT]],
    bias: SupportsString | None = None,
    divisor: SupportsString | bool = True,
    saturate: bool = True,
    mode: ConvMode = ConvMode.SQUARE,
    premultiply: SupportsString | None = None,
    multiply: SupportsString | None = None,
    clamp: bool = False,
) -> TupleExprList:
    """
    Builds an expression that performs a weighted convolution-like operation.

    Args:
        var: The variable used as the central value
            or elements proportional to the radius if mode is `Literal[ConvMode.TEMPORAL]`.
        matrix: A flat or 2D iterable representing the convolution weights.
        bias: A constant value to add to the result after convolution (default: None).
        divisor: If True, normalizes by the sum of weights; if False, skips division;
            Otherwise, divides by this value.
        saturate: If False, applies `abs()` to avoid negatives.
        mode: The convolution shape.
        premultiply: Optional scalar to multiply the result before normalization.
        multiply: Optional scalar to multiply the result at the end.
        clamp: If True, clamps the final result to [RangeMin, RangeMax].

    Returns:
        A [TupleExprList][vsexprtools.TupleExprList] representing the expression-based convolution.

    Raises:
        CustomValueError: If matrix length is invalid or doesn't match the mode.
    """
    convolution = list[SupportsSumNoDefaultT](flatten(matrix))

    if not (conv_len := len(convolution)) % 2:
        raise CustomValueError("Convolution length must be odd!", cls.convolution, matrix)
    elif conv_len < 3:
        raise CustomValueError("You must pass at least 3 convolution items!", cls.convolution, matrix)
    elif mode == ConvMode.SQUARE and conv_len != isqrt(conv_len) ** 2:
        raise CustomValueError(
            "With square mode, convolution must represent a horizontal*vertical square (radius*radius n items)!",
            cls.convolution,
        )

    radius = conv_len // 2 if mode != ConvMode.SQUARE else isqrt(conv_len) // 2

    rel_pixels = cls.matrix(var, radius, mode)

    output = TupleExprList(
        [
            ExprList(
                [
                    rel_pix if weight == 1 else [rel_pix, weight, cls.MUL]
                    for rel_pix, weight in zip(rel_px, convolution)
                    if weight != 0
                ]
            )
            for rel_px in rel_pixels
        ]
    )

    for out in output:
        out.extend(cls.ADD * out.mlength)

        if premultiply is not None:
            out.append(premultiply, cls.MUL)

        if divisor is not False:
            div = sum(convolution) if divisor is True else divisor

            if div not in {0, 1}:
                out.append(str(div), cls.DIV)

        if bias is not None:
            out.append(bias, cls.ADD)

        if not saturate:
            out.append(cls.ABS)

        if multiply is not None and multiply != 1.0:
            out.append(multiply, cls.MUL)

        if clamp:
            out.append(cls.clamp(ExprToken.RangeMin, ExprToken.RangeMax))

    return output

@classmethod
def from_param(cls, value: Any, func_except: FuncExcept | None = None) -> Self:
    """
    Return the enum value from a parameter.

    Args:
        value: Value to instantiate the enum class.
        func_except: Exception function.

    Returns:
        Enum value.

    Raises:
        NotFoundEnumValue: Variable not found in the given enum.
    """
    func_except = func_except or cls.from_param

    try:
        return cls(value)
    except (ValueError, TypeError):
        pass

    if isinstance(func_except, tuple):
        func_name, var_name = func_except
    else:
        func_name, var_name = func_except, repr(cls)

    raise NotFoundEnumValueError(
        'The given value for "{var_name}" argument must be a valid {enum_name}, not "{value}"!\n'
        "Valid values are: [{readable_enum}].",
        func_name,
        var_name=var_name,
        enum_name=cls,
        value=value,
        readable_enum=(f"{name} ({value!r})" for name, value in cls.__members__.items()),
        reason=value,
    ) from None

@cache
def is_extra(self) -> bool:
    """
    Check if the operator is an 'extra' operator.

    Extra operators are not natively supported by VapourSynth's `std.Expr` or `akarin.Expr`
    and require conversion to a valid equivalent expression.

    Returns:
        True if the operator is considered extra and requires conversion.
    """
    return self.name in ExprOp._extra_op_names_

@classmethod
def mae(
    cls,
    planesa: ExprVars | HoldsVideoFormat | VideoFormatLike | SupportsIndex,
    planesb: ExprVars | HoldsVideoFormat | VideoFormatLike | SupportsIndex | None = None,
) -> ExprList:
    """
    Build an expression to compute the Mean Absolute Error (MAE) between two plane sets.

    Args:
        planesa: The first plane set or clip.
        planesb: The second plane set or clip. If None, uses same as `planesa`.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the MAE expression across all planes.
    """
    planesa, planesb = cls._parse_planes(planesa, planesb, cls.mae)
    expr = ExprList()

    for a, b in zip(planesa, planesb):
        expr.append([a, b, cls.SUB, cls.ABS])

    expr.append(cls.MAX * expr.mlength)

    return expr

@classmethod
def masked_merge(cls, c_a: SupportsString = "", c_b: SupportsString = "", mask: SupportsString = "") -> ExprList:
    """
    Build a masked merge expression from two inputs and a mask.

    Args:
        c_a: The first input expression variable.
        c_b: The second input expression variable.
        mask: The mask expression that determines how `c_a` and `c_b` are combined.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the MaskedMerge expression.
    """
    return ExprList([c_a, c_b, [mask, ExprToken.RangeMax, ExprToken.RangeMin, cls.SUB, cls.DIV], cls.LERP])

@classmethod
def matrix(
    cls,
    var: SupportsString | Collection[SupportsString],
    radius: int,
    mode: ConvMode,
    exclude: Iterable[tuple[int, int]] | None = None,
    include: Iterable[tuple[int, int]] | None = None,
) -> TupleExprList:
    """
    Generate a matrix expression layout for convolution-like operations.

    Args:
        var: The variable representing the central pixel
            or elements proportional to the radius if mode is `Literal[ConvMode.TEMPORAL]`.
        radius: The radius of the kernel in pixels (e.g., 1 for 3x3).
        mode: The convolution mode.
        exclude: Optional set of (x, y) coordinates to exclude from the matrix.
        include: Optional set of (x, y) coordinates to include in the matrix.

    Returns:
        A [TupleExprList][vsexprtools.TupleExprList] representing the matrix of expressions.

    Raises:
        CustomValueError: If the input variable is not sized correctly for temporal mode.
        NotImplementedError: If the convolution mode is unsupported.
    """
    match mode:
        case ConvMode.SQUARE:
            coordinates = [(x, y) for (y, x) in product(range(-radius, radius + 1), repeat=2)]
        case ConvMode.VERTICAL:
            coordinates = [(0, y) for y in range(-radius, radius + 1)]
        case ConvMode.HORIZONTAL:
            coordinates = [(x, 0) for x in range(-radius, radius + 1)]
        case ConvMode.HV:
            return TupleExprList(
                [
                    cls.matrix(var, radius, ConvMode.VERTICAL, exclude, include)[0],
                    cls.matrix(var, radius, ConvMode.HORIZONTAL, exclude, include)[0],
                ]
            )
        case ConvMode.TEMPORAL:
            assert isinstance(var, Collection)

            if len(var) != radius * 2 + 1:
                raise CustomValueError(
                    "`var` must have a number of elements proportional to the radius", cls.matrix, var
                )

            return TupleExprList([ExprList(v for v in var)])
        case _:
            raise NotImplementedError

    assert isinstance(var, SupportsString)

    exclude = list(exclude) if exclude else []
    include = list(include) if include else coordinates

    return TupleExprList(
        [
            ExprList(
                [
                    var if x == y == 0 else ExprOp.REL_PIX(var, x, y)
                    for (x, y) in coordinates
                    if (x, y) not in exclude and (x, y) in include
                ]
            )
        ]
    )

@classmethod
def polyval(cls, c: SupportsString, *coeffs: SupportsString) -> ExprList:
    """
    Build an expression to evaluate a polynomial at a given value using Horner's method.

    Args:
        c: The input expression variable at which the polynomial is evaluated (the 'x' value).
        *coeffs: Coefficients of the polynomial. Must provide at least one coefficient.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the polyval expression.

    Raises:
        CustomValueError: If fewer than one coefficient is provided.
    """
    if len(coeffs) < 1:
        raise CustomValueError("You must provide at least one coefficient.", cls.polyval, coeffs)

    if b"polyval" in _get_akarin_expr_version()["expr_features"]:
        return ExprList([*coeffs, c, ExprOp.POLYVAL(len(coeffs) - 1)])

    stack_len = len(coeffs) + 1

    expr = ExprList([*coeffs, c, 0])

    for i in range(stack_len, 1, -1):
        expr.append(ExprOp.DUPN(1), ExprOp.MUL, ExprOp.DUPN(i), ExprOp.ADD)

    expr.append(ExprOp.SWAPN(stack_len), ExprOp.DROPN(stack_len))

    return expr

@classmethod
def rmse(
    cls,
    planesa: ExprVars | HoldsVideoFormat | VideoFormatLike | SupportsIndex,
    planesb: ExprVars | HoldsVideoFormat | VideoFormatLike | SupportsIndex | None = None,
) -> ExprList:
    """
    Build an expression to compute the Root Mean Squared Error (RMSE) between two plane sets.

    Args:
        planesa: The first plane set or clip.
        planesb: The second plane set or clip. If None, uses same as `planesa`.

    Returns:
        An [ExprList][vsexprtools.ExprList] representing the RMSE expression across all planes.
    """
    planesa, planesb = cls._parse_planes(planesa, planesb, cls.rmse)

    expr = ExprList()

    for a, b in zip(planesa, planesb):
        expr.append([a, b, cls.SUB, cls.DUP, cls.MUL, cls.SQRT])

    expr.append(cls.MAX * expr.mlength)

    return expr

@enum_property
def value(self) -> str: ...

def __call__(self, *pos_args: Any, **kwargs: Any) -> vs.VideoNode | str:
    """
    Combines multiple video clips using the selected expression operator or returns a formatted version
    of the [ExprOp][vsexprtools.ExprOp], using substitutions from pos_args and kwargs.

    Args:
        *pos_args: Positional arguments.
        **kwargs: Keywords arguments.

    Returns:
        A clip representing the combined result of applying the expression
        or formatted version of this [ExprOp][vsexprtools.ExprOp].
    """
    args = list(flatten(pos_args))

    if args and isinstance(args[0], vs.VideoNode):
        return self.combine(*args, **kwargs)

    while True:
        try:
            return self.format(*args, **kwargs)
        except KeyError as key:
            if not args:
                raise
            kwargs[key.args[0]] = args.pop(0)