docs ¶

def descale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Perform a regular descaling operation.

    :param clip:        Input clip.
    :param width:       Output width.
    :param height:      Output height.
    :param shift:       Shift clip during the operation.
                        Expects a tuple of (src_top, src_left).

    :return:            The descaled clip.
    """
    width, height = self._wh_norm(clip, width, height)
    return depth(
        core.descale.Debicubic(
            depth(clip, 32),
            width,
            height,
            b=self.b,
            c=self.c,
            src_top=shift[0],
            src_left=shift[1],
            **self.kwargs | kwargs,
        ),
        clip,
    )

@classmethod
def ensure_obj(cls, kernel: KernelLike | None = None, /, func_except: FuncExceptT | None = None) -> Self:
    """
    Ensure that the given kernel input is returned as a kernel instance.

    :param kernel:              Kernel name, class, or instance. Defaults to current class if None.
    :param func_except:         Function returned for custom error handling.

    :return:                    The resolved and instantiated kernel.
    """
    return _base_ensure_obj(cls, kernel, func_except)

@classmethod
def from_param(cls, kernel: KernelLike | None = None, /, func_except: FuncExceptT | None = None) -> type[Self]:
    """
    Resolve and return a kernel class from a string name, class type, or instance.

    :param kernel:              Kernel identifier as a string, class type, or instance. If None, defaults to the current class.
    :param func_except:         Function returned for custom error handling.

    :return:                    The resolved kernel class.
    :raises UnknownKernelError: If the kernel could not be identified.
    """
    return _base_from_param(cls, kernel, cls._err_class, func_except)

def get_descale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate and normalize argument dictionary for a descale operation.

    :param clip:    The source clip.
    :param shift:   Vertical and horizontal shift to apply.
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Additional arguments to pass to the descale function.

    :return:        Dictionary of keyword arguments for the descale function.
    """
    return dict(src_top=shift[0], src_left=shift[1]) | self.get_params_args(True, clip, width, height, **kwargs)

def get_params_args(
    self, is_descale: bool, clip: vs.VideoNode, width: int | None = None, height: int | None = None, **kwargs: Any
) -> dict[str, Any]:
    """
    Generate a base set of parameters to pass for scaling, descaling, or resampling.

    :param is_descale:  Whether this is for a descale operation.
    :param clip:        The source clip.
    :param width:       Target width.
    :param height:      Target height.
    :param kwargs:      Additional keyword arguments to include.

    :return:            Dictionary of combined parameters.
    """
    return dict(width=width, height=height) | self.kwargs | kwargs

def get_resample_args(
    self,
    clip: vs.VideoNode,
    format: int | VideoFormatT | HoldsVideoFormatT,
    matrix: MatrixT | None,
    matrix_in: MatrixT | None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate and normalize argument dictionary for a resample operation.

    :param clip:        The source clip.
    :param format:      The target video format, which can either be:
                            - an integer format ID,
                            - a `vs.PresetVideoFormat` or `vs.VideoFormat`,
                            - or a source from which a valid `VideoFormat` can be extracted.
    :param matrix:      Target color matrix.
    :param matrix_in:   Source color matrix.
    :param kwargs:      Additional arguments to pass to the resample function.

    :return:            Dictionary of keyword arguments for the resample function.
    """
    return dict(
        format=get_video_format(format).id, matrix=Matrix.from_param(matrix), matrix_in=Matrix.from_param(matrix_in)
    ) | self.get_params_args(False, clip, **kwargs)

def get_rescale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate and normalize argument dictionary for a rescale operation.

    :param clip:    The source clip.
    :param shift:   Vertical and horizontal shift to apply.
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Additional arguments to pass to the rescale function.

    :return:        Dictionary of keyword arguments for the rescale function.
    """
    return dict(src_top=shift[0], src_left=shift[1]) | self.get_params_args(True, clip, width, height, **kwargs)

def get_scale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate and normalize argument dictionary for a scale operation.

    :param clip:    The source clip.
    :param shift:   Vertical and horizontal shift to apply.
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Additional arguments to pass to the scale function.

    :return:        Dictionary of keyword arguments for the scale function.
    """
    return dict(src_top=shift[0], src_left=shift[1]) | self.get_params_args(False, clip, width, height, **kwargs)

@cached_property
def kernel_radius(self) -> int:
    """
    Return the effective kernel radius for the scaler.

    :raises CustomNotImplementedError:  If no kernel radius is defined.
    :return:                            Kernel radius.
    """
    ...

@deprecated('The "multi" method is deprecated. Use "supersample" instead.', category=DeprecationWarning)
def multi(
    self, clip: VideoNodeT, multi: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Deprecated alias for `supersample`.

    :param clip:    The source clip.
    :param multi:   Supersampling factor.
    :param shift:   Subpixel shift (top, left) applied during scaling.
    :param kwargs:  Additional arguments forwarded to the scale function.
    :return:        The supersampled clip.
    """
    return self.supersample(clip, multi, shift, **kwargs)

@cached_property
def pretty_string(self) -> str:
    """
    Cached property returning a user-friendly string representation.

    :return: Pretty-printed string with arguments.
    """
    return self._pretty_string()

def resample(
    self,
    clip: vs.VideoNode,
    format: int | VideoFormatT | HoldsVideoFormatT,
    matrix: MatrixT | None = None,
    matrix_in: MatrixT | None = None,
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Perform a regular resampling operation.

    :param clip:        Input clip
    :param format:      Output format
    :param matrix:      Output matrix. If `None`, will take the matrix from the input clip's frameprops.
    :param matrix_in:   Input matrix. If `None`, will take the matrix from the input clip's frameprops.

    :return:            Resampled clip.
    """
    return core.resize2.Bicubic(
        clip,
        format=get_video_format(format).id,
        filter_param_a=self.b,
        filter_param_b=self.c,
        matrix=Matrix.from_param(matrix),
        matrix_in=Matrix.from_param(matrix_in),
        **self.kwargs | kwargs,
    )

def rescale(
    self,
    clip: vs.VideoNode,
    width: int | None,
    height: int | None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Rescale a clip to the given resolution from a previously descaled clip.

    Keyword arguments passed during initialization are automatically injected here,
    unless explicitly overridden by the arguments provided at call time.
    Only arguments that match named parameters in this method are injected.

    :param clip:    The source clip.
    :param width:   Target scaled width (defaults to clip width if None).
    :param height:  Target scaled height (defaults to clip height if None).
    :param shift:   Subpixel shift (top, left) applied during scaling.
    :return:        The scaled clip.
    """
    width, height = self._wh_norm(clip, width, height)
    check_correct_subsampling(clip, width, height)

    return self.rescale_function(
        clip, **_norm_props_enums(self.get_rescale_args(clip, shift, width, height, **kwargs))
    )

def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Perform a regular scaling operation.

    :param clip:        Input clip.
    :param width:       Output width.
    :param height:      Output height.
    :param shift:       Shift clip during the operation.
                        Expects a tuple of (src_top, src_left).

    :return:            The scaled clip.
    """
    width, height = self._wh_norm(clip, width, height)
    return core.resize2.Bicubic(
        clip,
        width,
        height,
        src_top=shift[0],
        src_left=shift[1],
        filter_param_a=self.b,
        filter_param_b=self.c,
        **self.kwargs | kwargs,
    )

def shift(
    self,
    clip: vs.VideoNode,
    shifts_or_top: float | tuple[float, float] | list[float],
    shift_left: float | list[float] | None = None,
    /,
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Apply a subpixel shift to the clip using the kernel's scaling logic.

    If a single float or tuple is provided, it is used uniformly.
    If a list is given, the shift is applied per plane.

    Keyword arguments passed during initialization are automatically injected here,
    unless explicitly overridden by the arguments provided at call time.
    Only arguments that match named parameters in this method are injected.

    :param clip:                    The source clip.
    :param shifts_or_top:           Either a single vertical shift, a (top, left) tuple, or a list of vertical shifts.
    :param shift_left:              Horizontal shift or list of horizontal shifts. Ignored if `shifts_or_top` is a tuple.
    :param kwargs:                  Additional arguments passed to the internal `scale` call.

    :return:                        A new clip with the applied shift.
    :raises VariableFormatError:    If the input clip has variable format.
    :raises CustomValueError:       If the input clip is GRAY but lists of shift has been passed.
    """
    assert check_variable_format(clip, self.shift)

    n_planes = clip.format.num_planes

    def _shift(src: vs.VideoNode, shift: tuple[TopShift, LeftShift] = (0, 0)) -> ConstantFormatVideoNode:
        return self.scale(src, shift=shift, **kwargs)  # type: ignore[return-value]

    if isinstance(shifts_or_top, tuple):
        return _shift(clip, shifts_or_top)

    if isinstance(shifts_or_top, (int, float)) and isinstance(shift_left, (int, float, NoneType)):
        return _shift(clip, (shifts_or_top, shift_left or 0))

    if shift_left is None:
        shift_left = 0.0

    shifts_top = normalize_seq(shifts_or_top, n_planes)
    shifts_left = normalize_seq(shift_left, n_planes)

    if n_planes == 1:
        if len(set(shifts_top)) > 1 or len(set(shifts_left)) > 1:
            raise CustomValueError(
                "Inconsistent shift values detected for a single plane. "
                "All shift values must be identical when passing a GRAY clip.",
                self.shift,
                (shifts_top, shifts_left),
            )

        return _shift(clip, (shifts_top[0], shifts_left[0]))

    shifted_planes = [
        plane if top == left == 0 else _shift(plane, (top, left))
        for plane, top, left in zip(split(clip), shifts_top, shifts_left)
    ]

    return core.std.ShufflePlanes(shifted_planes, [0, 0, 0], clip.format.color_family)

def supersample(
    self, clip: VideoNodeT, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Supersample a clip by a given scaling factor.

    :param clip:                The source clip.
    :param rfactor:             Scaling factor for supersampling.
    :param shift:               Subpixel shift (top, left) applied during scaling.
    :param kwargs:              Additional arguments forwarded to the scale function.
    :raises CustomValueError:   If resulting resolution is non-positive.
    :return:                    The supersampled clip.
    """
    assert check_variable_resolution(clip, self.supersample)

    dst_width, dst_height = ceil(clip.width * rfactor), ceil(clip.height * rfactor)

    if max(dst_width, dst_height) <= 0.0:
        raise CustomValueError(
            'Multiplying the resolution by "rfactor" must result in a positive resolution!',
            self.supersample,
            rfactor,
        )

    return self.scale(clip, dst_width, dst_height, shift, **kwargs)  # type: ignore[return-value]