helpers ¶

def as_var(self) -> ComputedVar:
    """
    Converts the expression variable to a ComputedVar.

    Returns:
        A ComputedVar.
    """
    if isinstance(self, ComputedVar):
        return self
    return ComputedVar(self)

def to_str(self, **kwargs: Any) -> str:
    """
    Returns the string representation of the expression variable.

    Args:
        **kwargs: Additional keywords arguments.

    Returns:
        The string representation of the expression variable.
    """
    return str(self)

def as_var(self) -> ComputedVar:
    """
    Converts the expression variable to a ComputedVar.

    Returns:
        A ComputedVar.
    """
    if isinstance(self, ComputedVar):
        return self
    return ComputedVar(self)

def to_str(self, *, plane: int = 0, **kwargs: Any) -> str:
    """
    Returns a string representation of the expression in RPN format for the selected plane.

    Args:
        plane: Optional plane index to select which expression to stringify.
        **kwargs: Additional keyword arguments passed to each expression's to_str method.

    Returns:
        String representation of the expression in RPN format for the selected plane.
    """

    return " ".join(x.to_str(**kwargs) for x in self._operations_per_plane[plane])

def to_str_per_plane(self, num_planes: int = 3) -> list[str]:
    """
    Returns string representations of the expression in RPN format for each plane.

    Args:
        num_planes: Optional number of planes to include (defaults to 3).

    Returns:
        A list of strings, one for each plane.
    """
    return [" ".join(p.to_str(plane=i) for p in x) for x, i in zip(self._operations_per_plane, range(num_planes))]

def as_var(self) -> ComputedVar:
    """
    Converts the expression variable to a ComputedVar.

    Returns:
        A ComputedVar.
    """
    if isinstance(self, ComputedVar):
        return self
    return ComputedVar(self)

def to_str(self, **kwargs: Any) -> str:
    """
    Returns the string representation of the expression variable.

    Args:
        **kwargs: Additional keywords arguments.

    Returns:
        The string representation of the expression variable.
    """
    return str(self)

def as_var(self) -> ComputedVar:
    """
    Converts the expression variable to a ComputedVar.

    Returns:
        A ComputedVar.
    """
    if isinstance(self, ComputedVar):
        return self
    return ComputedVar(self)

def to_str(self, **kwargs: Any) -> str:
    """
    Returns the string representation of the expression variable.

    Args:
        **kwargs: Additional keywords arguments.

    Returns:
        The string representation of the expression variable.
    """
    return str(self)

def __call__(self) -> Self:
    """
    Returns itself.

    Returns:
        Returns itself.
    """
    return self

def abs(self, x: ExprVarLike) -> ComputedVar:
    """Absolute value of x."""
    return ComputedVar([x, ExprOp.ABS])

def abs_pix(self, char: SupportsString, x: int, y: int) -> ComputedVar:
    """Absolute pixel access."""
    return ComputedVar(ExprOp.ABS_PIX.format(char=char, x=x, y=y))

def acos(self, x: ExprVarLike) -> ComputedVar:
    """Arccosine (inverse cosine) of x."""
    return ComputedVar([x, ExprOp.ACOS])

def add(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs addition of two elements (x + y)."""
    return ComputedVar([x, y, ExprOp.ADD])

def and_(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs a logical AND."""
    return ComputedVar([x, y, ExprOp.AND])

def asin(self, x: ExprVarLike) -> ComputedVar:
    """Arcsine (inverse sine) of x."""
    return ComputedVar([x, ExprOp.ASIN])

def atan(self, x: ExprVarLike) -> ComputedVar:
    """Arctangent of x"""
    return ComputedVar([x, ExprOp.ATAN])

def bitand(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs a bitwise AND."""
    return ComputedVar([x, y, ExprOp.BITAND])

def bitnot(self, x: ExprVarLike) -> ComputedVar:
    """Performs a bitwise NOT."""
    return ComputedVar([x, ExprOp.BITNOT])

def bitor(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs a bitwise OR."""
    return ComputedVar([x, y, ExprOp.BITOR])

def bitxor(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs a bitwise XOR."""
    return ComputedVar([x, y, ExprOp.BITXOR])

def ceil(self, x: ExprVarLike) -> ComputedVar:
    """Round up x to nearest integer."""
    return ComputedVar([x, ExprOp.CEIL])

def clamp(self, x: ExprVarLike, min: ExprVarLike, max: ExprVarLike) -> ComputedVar:
    """Clamps a value between a min and a max."""
    return ComputedVar([x, min, max, ExprOp.CLAMP])

def convolution(
    self,
    var: SupportsString | Collection[SupportsString],
    matrix: Iterable[ExprVarLike] | Iterable[Iterable[ExprVarLike]],
    bias: ExprVarLike | None = None,
    divisor: ExprVarLike | bool = True,
    saturate: bool = True,
    mode: OnePassConvMode = ConvMode.SQUARE,
    premultiply: ExprVarLike | None = None,
    multiply: ExprVarLike | None = None,
    clamp: bool = False,
) -> ComputedVar:
    """
    Convenience method wrapping [ExprOp.convolution][vsexprtools.ExprOp.convolution].

    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 `ComputedVar` representing the expression-based convolution.
    """
    convo, *_ = ExprOp.convolution(
        var, flatten(matrix), bias, divisor, saturate, mode, premultiply, multiply, clamp
    )
    return ComputedVar(convo.to_str())

def cos(self, x: ExprVarLike) -> ComputedVar:
    """Cosine (radians) of x."""
    return ComputedVar([x, ExprOp.COS])

def div(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs division of two elements (x / y)."""
    return ComputedVar([x, y, ExprOp.DIV])

def eq(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x == y."""
    return ComputedVar([x, y, ExprOp.EQ])

def exp(self, x: ExprVarLike) -> ComputedVar:
    """Exponential function (e^x)."""
    return ComputedVar([x, ExprOp.EXP])

def floor(self, x: ExprVarLike) -> ComputedVar:
    """Round down x to nearest integer."""
    return ComputedVar([x, ExprOp.FLOOR])

def gt(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x > y."""
    return ComputedVar([x, y, ExprOp.GT])

def gte(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x >= y."""
    return ComputedVar([x, y, ExprOp.GTE])

def lerp(self, x: ExprVarLike, y: ExprVarLike, t: ExprVarLike) -> ComputedVar:
    """Performs a linear interpolation of t between x and y."""
    return ComputedVar([x, y, t, ExprOp.LERP])

def log(self, x: ExprVarLike) -> ComputedVar:
    """Natural logarithm of x."""
    return ComputedVar([x, ExprOp.LOG])

def lt(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x < y."""
    return ComputedVar([x, y, ExprOp.LT])

def lte(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x <= y."""
    return ComputedVar([x, y, ExprOp.LTE])

def matrix(
    self,
    char: SupportsString | Collection[SupportsString],
    radius: int,
    mode: Literal[ConvMode.SQUARE, ConvMode.HORIZONTAL, ConvMode.VERTICAL, ConvMode.TEMPORAL],
    exclude: Iterable[tuple[int, int]] | None = None,
    include: Iterable[tuple[int, int]] | None = None,
) -> list[LiteralVar]:
    """
    Convenience method wrapping [ExprOp.matrix][vsexprtools.ExprOp.matrix].

    Args:
        char: The variable representing the central pixel(s).
        radius: The radius of the kernel in pixels (e.g., 1 for 3x3).
        mode: The convolution mode. `HV` is not supported.
        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 list of [LiteralVar][vsexprtools.inline.helpers.LiteralVar] instances
        representing the matrix of expressions.
    """
    matrix, *_ = ExprOp.matrix(char, radius, mode, exclude, include)

    return [LiteralVar(str(m)) for m in matrix]

def max(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Calculates the maximum of x and y."""
    return ComputedVar([x, y, ExprOp.MAX])

def min(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Calculates the minimum of x and y."""
    return ComputedVar([x, y, ExprOp.MIN])

def mod(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x % y."""
    return ComputedVar([x, y, ExprOp.MOD])

def mul(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs multiplication of two elements (x * y)."""
    return ComputedVar([x, y, ExprOp.MUL])

def neg(self, x: ExprVarLike) -> ComputedVar:
    """Negation (multiply by -1) of x."""
    return ComputedVar([x, ExprOp.NEG])

def not_(self, x: ExprVarLike) -> ComputedVar:
    """Logical NOT of x."""
    return ComputedVar([x, ExprOp.NOT])

def or_(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs a logical OR."""
    return ComputedVar([x, y, ExprOp.OR])

def polyval(self, x: ExprVarLike, *coeffs: ExprVarLike) -> ComputedVar:
    """Evaluates a polynomial at x using Horner's method."""
    return ComputedVar(ExprOp.polyval(x, *coeffs).to_str())

def pow(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs x to the power of y (x ** y)."""
    return ComputedVar([x, y, ExprOp.POW])

def rel_pix(self, char: SupportsString, x: int, y: int) -> ComputedVar:
    """Relative pixel access."""
    return ComputedVar(ExprOp.REL_PIX.format(char=char, x=x, y=y))

def round(self, x: ExprVarLike) -> ComputedVar:
    """Round x to nearest integer."""
    return ComputedVar([x, ExprOp.ROUND])

def sgn(self, x: ExprVarLike) -> ComputedVar:
    """Sign function (-1, 0, or 1) of x."""
    return ComputedVar([x, ExprOp.SGN])

def sin(self, x: ExprVarLike) -> ComputedVar:
    """Sine (radians) of x."""
    return ComputedVar([x, ExprOp.SIN])

def sqrt(self, x: ExprVarLike) -> ComputedVar:
    """Square root of x."""
    return ComputedVar([x, ExprOp.SQRT])

def sub(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs subtraction of two elements (x - y)."""
    return ComputedVar([x, y, ExprOp.SUB])

def tan(self, x: ExprVarLike) -> ComputedVar:
    """Tangent (radians) of x."""
    return ComputedVar([x, ExprOp.TAN])

def tern(self, cond: ExprVarLike, if_true: ExprVarLike, if_false: ExprVarLike) -> ComputedVar:
    """Ternary operator (if cond then if_true else if_false)."""
    return ComputedVar([cond, if_true, if_false, ExprOp.TERN])

def trunc(self, x: ExprVarLike) -> ComputedVar:
    """Truncate x to integer (toward zero)."""
    return ComputedVar([x, ExprOp.TRUNC])

def xor(self, x: ExprVarLike, y: ExprVarLike) -> ComputedVar:
    """Performs a logical XOR."""
    return ComputedVar([x, y, ExprOp.XOR])

def __call__(self, var: ClipVar) -> ComputedVar:
    """
    Returns a version of the token specific to a clip variable.

    Args:
        var: The ClipVar to use.

    Returns:
        A ComputedVar with a var suffix for use in inline expressions.
    """
    return ComputedVar(f"{self.value}_{var.char}")

def as_var(self) -> ComputedVar:
    """
    Converts the expression variable to a ComputedVar.

    Returns:
        A ComputedVar.
    """
    if isinstance(self, ComputedVar):
        return self
    return ComputedVar(self)

def to_str(self, **kwargs: Any) -> str:
    """
    Returns the string representation of the expression variable.

    Args:
        **kwargs: Additional keywords arguments.

    Returns:
        The string representation of the expression variable.
    """
    return str(self)