custom ¶

def descale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: ShiftT = (0, 0),
    *,
    # `linear` and `sigmoid` parameters from LinearDescaler
    linear: bool | None = None,
    sigmoid: bool | tuple[Slope, Center] = False,
    # ComplexDescaler adds border_handling, sample_grid_model, field_based,  ignore_mask and blur
    border_handling: int | BorderHandling = BorderHandling.MIRROR,
    sample_grid_model: int | SampleGridModel = SampleGridModel.MATCH_EDGES,
    field_based: FieldBasedLike | None = None,
    ignore_mask: vs.VideoNode | None = None,
    blur: float | None = None,
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Descale a clip to the given resolution, with image borders handling and sampling grid alignment,
    optionally using linear light processing.

    Supports both progressive and interlaced sources. When interlaced, it will separate fields,
    perform per-field descaling, and weave them back.

    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.

    Args:
        clip: The source clip.
        width: Target descaled width (defaults to clip width if None).
        height: Target descaled height (defaults to clip height if None).
        shift: Subpixel shift (top, left) or per-field shifts.
        linear: Whether to linearize the input before descaling. If None, inferred from sigmoid.
        sigmoid: Whether to use sigmoid transfer curve. Can be True, False, or a tuple of (slope, center). `True`
            applies the defaults values (6.5, 0.75). Keep in mind sigmoid slope has to be in range 1.0-20.0
            (inclusive) and sigmoid center has to be in range 0.0-1.0 (inclusive).
        border_handling: Method for handling image borders during sampling.
        sample_grid_model: Model used to align sampling grid.
        field_based: Field-based processing mode (interlaced or progressive).
        ignore_mask: Optional mask specifying areas to ignore during descaling.
        blur: Amount of blur to apply during scaling.
        **kwargs: Additional arguments passed to `descale_function`.

    Returns:
        The descaled video node, optionally processed in linear light.
    """
    width, height = self._wh_norm(clip, width, height)
    check_correct_subsampling(clip, width, height)

    field_based = FieldBased.from_param_or_video(field_based, clip)

    clip, bits = expect_bits(clip, 32)

    de_base_args = (width, height // (1 + field_based.is_inter))
    kwargs.update(
        linear=linear,
        sigmoid=sigmoid,
        border_handling=BorderHandling.from_param(border_handling, self.descale),
        ignore_mask=ignore_mask,
        blur=blur,
    )

    sample_grid_model = SampleGridModel(sample_grid_model)

    if field_based.is_inter:
        from vsdeinterlace import reweave

        shift_y, shift_x = _descale_shift_norm(shift, False, self.descale)

        kwargs_tf, shift = sample_grid_model.for_src(clip, width, height, (shift_y[0], shift_x[0]), **kwargs)
        kwargs_bf, shift = sample_grid_model.for_src(clip, width, height, (shift_y[1], shift_x[1]), **kwargs)

        de_kwargs_tf = self.get_descale_args(clip, (shift_y[0], shift_x[0]), *de_base_args, **kwargs_tf)
        de_kwargs_bf = self.get_descale_args(clip, (shift_y[1], shift_x[1]), *de_base_args, **kwargs_bf)

        if height % 2:
            raise CustomIndexError("You can't descale to odd resolution when crossconverted!", self.descale)

        field_shift = 0.125 * height / clip.height

        fields = clip.std.SeparateFields(field_based.is_tff)

        descaled_tf = super().descale(
            fields[0::2],
            **de_kwargs_tf | {"src_top": de_kwargs_tf.get("src_top", 0.0) + field_shift},
        )
        descaled_bf = super().descale(
            fields[1::2],
            **de_kwargs_bf | {"src_top": de_kwargs_bf.get("src_top", 0.0) - field_shift},
        )
        descaled = reweave(descaled_tf, descaled_bf, field_based)
    else:
        shift = _descale_shift_norm(shift, True, self.descale)

        kwargs, shift = sample_grid_model.for_src(clip, width, height, shift, **kwargs)

        descaled = super().descale(clip, **self.get_descale_args(clip, shift, *de_base_args, **kwargs))

    return depth(descaled, bits)

def descale_function(
    self, clip: vs.VideoNode, width: int, height: int, *args: Any, **kwargs: Any
) -> ConstantFormatVideoNode:
    try:
        return core.descale.Decustom(
            clip, width, height, self.kernel, ceil(kwargs.pop("taps", self.kernel_radius)), *args, **kwargs
        )
    except vs.Error as e:
        if "Output dimension must be" in str(e):
            raise CustomValueError(
                f"Output dimension ({width}x{height}) must be less than or equal to "
                f"input dimension ({clip.width}x{clip.height}).",
                self.__class__,
            )

        raise CustomError(e, self.__class__) from e

@classmethod
def ensure_obj(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Ensure that the input is a scaler instance, resolving it if necessary.

    Args:
        scaler: Scaler identifier (string, class, or instance).
        func_except: Function returned for custom error handling.

    Returns:
        Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

@classmethod
def from_param(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExcept | None = None,
) -> type[Self]:
    """
    Resolve and return a scaler type from a given input (string, type, or instance).

    Args:
        scaler: Scaler identifier (string, class, or instance).
        func_except: Function returned for custom error handling.

    Returns:
        Resolved scaler type.
    """
    return _base_from_param(cls, scaler, 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.

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

    Returns:
        Dictionary of keyword arguments for the descale function.
    """
    return {"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.

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

    Returns:
        Dictionary of combined parameters.
    """
    return {"width": width, "height": height} | self.kwargs | kwargs

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

    Args:
        clip: The source clip.
        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.
        matrix: Target color matrix.
        matrix_in: Source color matrix.
        **kwargs: Additional arguments to pass to the resample function.

    Returns:
        Dictionary of keyword arguments for the resample function.
    """
    return {
        "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.

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

    Returns:
        Dictionary of keyword arguments for the rescale function.
    """
    return {"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.

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

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

@classproperty
@classmethod
def implemented_funcs(cls) -> frozenset[str]:
    """
    Returns a set of function names that are implemented in the current class and the parent classes.

    These functions determine which keyword arguments will be extracted from the __init__ method.

    Returns:
        Frozen set of function names.
    """
    return frozenset(func for klass in cls.mro() for func in getattr(klass, "_implemented_funcs", ()))

@abstractmethod
def kernel(self, *, x: float) -> float:
    """
    Define the kernel function at a given position.

    This method must be implemented by subclasses to provide the actual kernel logic.

    Args:
        x: The input position.

    Returns:
        The evaluated kernel value at position `x`.
    """

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

    Raises:
        CustomNotImplementedError: If no kernel radius is defined.

    Returns:
        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`.

    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.

    Args:
        clip: The source clip.
        multi: Supersampling factor.
        shift: Subpixel shift (top, left) applied during scaling.
        **kwargs: Additional arguments forwarded to the scale function.

    Returns:
        The supersampled clip.
    """
    return self.supersample(clip, multi, shift, **kwargs)

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

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

def resample(
    self,
    clip: vs.VideoNode,
    format: int | VideoFormatLike | HoldsVideoFormat,
    matrix: MatrixLike | None = None,
    matrix_in: MatrixLike | None = None,
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Resample a video clip to the given format.

    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.

    Args:
        clip: The source clip.
        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.
        matrix: An optional color transformation matrix to apply.
        matrix_in: An optional input matrix for color transformations.
        **kwargs: Additional keyword arguments passed to the `resample_function`.

    Returns:
        The resampled clip.
    """
    return self.resample_function(
        clip, **_norm_props_enums(self.get_resample_args(clip, format, matrix, matrix_in, **kwargs))
    )

def resample_function(
    self, clip: vs.VideoNode, width: int | None = None, height: int | None = None, *args: Any, **kwargs: Any
) -> ConstantFormatVideoNode:
    return self.scale_function(clip, width, height, *args, **kwargs)  # type: ignore[return-value]

def rescale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: ShiftT = (0, 0),
    *,
    # `linear` and `sigmoid` parameters from LinearDescaler
    linear: bool | None = None,
    sigmoid: bool | tuple[Slope, Center] = False,
    # ComplexDescaler adds border_handling, sample_grid_model, field_based, ignore_mask and blur
    border_handling: int | BorderHandling = BorderHandling.MIRROR,
    sample_grid_model: int | SampleGridModel = SampleGridModel.MATCH_EDGES,
    field_based: FieldBasedLike | None = None,
    ignore_mask: vs.VideoNode | None = None,
    blur: float | None = None,
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    """
    Rescale a clip to the given resolution from a previously descaled clip,
    with image borders handling and sampling grid alignment, optionally using linear light processing.

    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.

    Args:
        clip: The source clip.
        width: Target scaled width (defaults to clip width if None).
        height: Target scaled height (defaults to clip height if None).
        shift: Subpixel shift (top, left) or per-field shifts.
        linear: Whether to linearize the input before rescaling. If None, inferred from sigmoid.
        sigmoid: Whether to use sigmoid transfer curve. Can be True, False, or a tuple of (slope, center). `True`
            applies the defaults values (6.5, 0.75). Keep in mind sigmoid slope has to be in range 1.0-20.0
            (inclusive) and sigmoid center has to be in range 0.0-1.0 (inclusive).
        border_handling: Method for handling image borders during sampling.
        sample_grid_model: Model used to align sampling grid.
        field_based: Field-based processing mode (interlaced or progressive).
        ignore_mask: Optional mask specifying areas to ignore during rescaling.
        blur: Amount of blur to apply during rescaling.
        **kwargs: Additional arguments passed to `rescale_function`.

    Returns:
        The scaled clip.
    """
    width, height = self._wh_norm(clip, width, height)
    check_correct_subsampling(clip, width, height)

    field_based = FieldBased.from_param_or_video(field_based, clip)

    clip, bits = expect_bits(clip, 32)

    de_base_args = (width, height // (1 + field_based.is_inter))
    kwargs.update(
        border_handling=BorderHandling.from_param(border_handling, self.rescale), ignore_mask=ignore_mask, blur=blur
    )

    sample_grid_model = SampleGridModel(sample_grid_model)

    if field_based.is_inter:
        raise NotImplementedError
    else:
        shift = _descale_shift_norm(shift, True, self.rescale)

        kwargs, shift = sample_grid_model.for_src(clip, width, height, shift, **kwargs)

        rescaled = super().rescale(
            clip, **self.get_rescale_args(clip, shift, *de_base_args, **kwargs), linear=linear, sigmoid=sigmoid
        )

    return depth(rescaled, bits)

def rescale_function(
    self, clip: vs.VideoNode, width: int, height: int, *args: Any, **kwargs: Any
) -> ConstantFormatVideoNode:
    try:
        return core.descale.ScaleCustom(
            clip, width, height, self.kernel, ceil(kwargs.pop("taps", self.kernel_radius)), *args, **kwargs
        )
    except vs.Error as e:
        raise CustomError(e, self.__class__) from e

def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    # ComplexScaler adds shift per planes
    shift: tuple[TopShift | list[TopShift], LeftShift | list[LeftShift]] = (0, 0),
    *,
    # `linear` and `sigmoid` from LinearScaler
    linear: bool | None = None,
    sigmoid: bool | tuple[Slope, Center] = False,
    # `border_handling`, `sample_grid_model`, `sar`, `dar`, `dar_in` and `keep_ar` from KeepArScaler
    border_handling: BorderHandling = BorderHandling.MIRROR,
    sample_grid_model: SampleGridModel = SampleGridModel.MATCH_EDGES,
    sar: Sar | float | bool | None = None,
    dar: Dar | float | bool | None = None,
    dar_in: Dar | bool | float | None = None,
    keep_ar: bool | None = None,
    # ComplexScaler adds blur
    blur: float | None = None,
    **kwargs: Any,
) -> vs.VideoNode | ConstantFormatVideoNode:
    """
    Scale a clip to the given resolution, with aspect ratio and linear light support.

    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.

    Args:
        clip: The source clip.
        width: Target width (defaults to clip width if None).
        height: Target height (defaults to clip height if None).
        shift: Subpixel shift (top, left) applied during scaling. If a tuple is provided, it is used uniformly. If a
            list is given, the shift is applied per plane.
        linear: Whether to linearize the input before descaling. If None, inferred from sigmoid.
        sigmoid: Whether to use sigmoid transfer curve. Can be True, False, or a tuple of (slope, center). `True`
            applies the defaults values (6.5, 0.75). Keep in mind sigmoid slope has to be in range 1.0-20.0
            (inclusive) and sigmoid center has to be in range 0.0-1.0 (inclusive).
        border_handling: Method for handling image borders during sampling.
        sample_grid_model: Model used to align sampling grid.
        sar: Sample aspect ratio to assume or convert to.
        dar: Desired display aspect ratio.
        dar_in: Input display aspect ratio, if different from clip's.
        keep_ar: Whether to adjust dimensions to preserve aspect ratio.
        blur: Amount of blur to apply during scaling.

    Returns:
        Scaled clip, optionally aspect-corrected and linearized.
    """
    kwargs.update(
        linear=linear,
        sigmoid=sigmoid,
        border_handling=border_handling,
        sample_grid_model=sample_grid_model,
        sar=sar,
        dar=dar,
        dar_in=dar_in,
        keep_ar=keep_ar,
        blur=blur,
    )

    shift_top, shift_left = shift

    if isinstance(shift_top, (int, float)) and isinstance(shift_left, (int, float)):
        return super().scale(clip, width, height, (shift_top, shift_left), **kwargs)

    assert check_variable_format(clip, self.scale)

    n_planes = clip.format.num_planes

    shift_top = normalize_seq(shift_top, n_planes)
    shift_left = normalize_seq(shift_left, n_planes)

    if n_planes == 1:
        return super().scale(clip, width, height, (shift_top[0], shift_left[0]), **kwargs)

    width, height = self._wh_norm(clip, width, height)

    format_in = clip.format
    format_out = get_video_format(fallback(kwargs.pop("format", None), self.kwargs.get("format"), clip.format))

    chromaloc = ChromaLocation.from_video(clip, func=self.scale)
    chromaloc_in = ChromaLocation(
        fallback(kwargs.pop("chromaloc_in", None), self.kwargs.get("chromaloc_in"), chromaloc)
    )
    chromaloc_out = ChromaLocation(fallback(kwargs.pop("chromaloc", None), self.kwargs.get("chromaloc"), chromaloc))

    off_left, off_top = chromaloc_in.get_offsets(format_in)
    off_left_out, off_top_out = chromaloc_out.get_offsets(format_out)

    factor_w = 1 / 2**format_in.subsampling_w
    factor_h = 1 / 2**format_in.subsampling_h

    # Offsets for format out
    offc_left = (abs(off_left) + off_left_out) * factor_w
    offc_top = (abs(off_top) + off_top_out) * factor_h

    # Offsets for scale out
    if format_out.subsampling_w:
        offc_left = ((abs(off_left) + off_left * (clip.width / width)) * factor_w) + offc_left
    if format_out.subsampling_h:
        offc_top = ((abs(off_top) + off_top * (clip.height / height)) * factor_h) + offc_top

    for i in range(1, n_planes):
        shift_left[i] += offc_left
        shift_top[i] += offc_top

    scaled_planes = list[vs.VideoNode]()

    for i, (plane, top, left) in enumerate(zip(split(clip), shift_top, shift_left)):
        if i:
            w = round(width * 1 / 2**format_out.subsampling_h)
            h = round(height * 1 / 2**format_out.subsampling_h)
        else:
            w, h = width, height

        scaled_planes.append(
            super().scale(
                plane,
                w,
                h,
                (top, left),
                format=format_out.replace(color_family=vs.GRAY, subsampling_w=0, subsampling_h=0),
                **kwargs,
            )
        )

    merged = vs.core.std.ShufflePlanes(scaled_planes, [0, 0, 0], format_out.color_family, clip)

    if chromaloc_in != chromaloc_out:
        return chromaloc_out.apply(merged)

    return merged

def scale_function(
    self, clip: vs.VideoNode, width: int | None = None, height: int | None = None, *args: Any, **kwargs: Any
) -> vs.VideoNode:
    try:
        return core.resize2.Custom(
            clip, self.kernel, ceil(kwargs.pop("taps", self.kernel_radius)), width, height, *args, **kwargs
        )
    except vs.Error as e:
        raise CustomError(e, self.__class__) from e

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.

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

    Returns:
        A new clip with the applied shift.

    Raises:
        VariableFormatError: If the input clip has variable format.
        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:
        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, clip)

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.

    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.

    Args:
        clip: The source clip.
        rfactor: Scaling factor for supersampling.
        shift: Subpixel shift (top, left) applied during scaling.
        **kwargs: Additional arguments forwarded to the scale function.

    Raises:
        CustomValueError: If resulting resolution is non-positive.

    Returns:
        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]