various ¶

@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_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 the keyword arguments used for scaling.

    Args:
        clip: The source clip.
        shift: Subpixel shift (top, left).
        width: Target width.
        height: Target height.
        **kwargs: Extra parameters to merge.

    Returns:
        Final dictionary of keyword arguments for the scale function.
    """
    return {"width": width, "height": height, "src_top": shift[0], "src_left": shift[1]} | self.kwargs | 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", ()))

@Scaler.cachedproperty
def kernel_radius(self) -> int:
    if not isinstance(self.reference, vs.VideoNode):
        return max(self.reference.kernel_radius, self.base_scaler.kernel_radius)
    return self.base_scaler.kernel_radius

@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 scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any,
) -> ConstantFormatVideoNode:
    width, height = self._wh_norm(clip, width, height)

    base = self.base_scaler.scale(clip, width, height, shift, **kwargs)

    if isinstance(self.reference, vs.VideoNode):
        smooth = self.reference

        if shift != (0, 0):
            smooth = self.kernel.shift(smooth, shift)
    else:
        smooth = self.reference.scale(clip, width, height, shift)

    check_ref_clip(base, smooth)

    if TYPE_CHECKING:
        from vstools import check_variable_format

        assert check_variable_format(base, self.__class__)
        assert check_variable_format(smooth, self.__class__)

    merge_weight = self.strength / 100

    if self.limit is True:
        expression = "x {merge_weight} * y {ref_weight} * + a {undershoot} - z {overshoot} + clip"

        merged = norm_expr(
            [base, smooth, smooth.std.Maximum(), smooth.std.Minimum()],
            expression,
            merge_weight=merge_weight,
            ref_weight=1.0 - merge_weight,
            undershoot=scale_delta(self.undershoot, 32, clip),
            overshoot=scale_delta(self.overshoot, 32, clip),
            func=self.__class__,
        )
    else:
        merged = smooth.std.Merge(base, merge_weight)

        if isinstance(self.limit, Repair.Mode):
            merged = self.limit(merged, smooth)

    if self.operator is not None:
        merge2 = combine([smooth, base], self.operator)

        merged = merged.std.MaskedMerge(merge2, ringing_mask(smooth)) if self.masked else merge2
    elif self.masked:
        merged = merged.std.MaskedMerge(smooth, ringing_mask(smooth))

    return merged

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]

@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_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 the keyword arguments used for scaling.

    Args:
        clip: The source clip.
        shift: Subpixel shift (top, left).
        width: Target width.
        height: Target height.
        **kwargs: Extra parameters to merge.

    Returns:
        Final dictionary of keyword arguments for the scale function.
    """
    return {"width": width, "height": height, "src_top": shift[0], "src_left": shift[1]} | self.kwargs | 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", ()))

@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.
    """
    ...

@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 scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift | list[TopShift], LeftShift | list[LeftShift]] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode | ConstantFormatVideoNode:
    assert check_variable(clip, self.scale)

    width, height = self._wh_norm(clip, width, height)
    rfactor_w, rfactor_h = (width / clip.width), (height / clip.height)

    if any(not rf.is_integer() for rf in (rfactor_w, rfactor_h)):
        raise CustomValueError(
            "The supersampling factor must yield an integer result.", self.__class__, (rfactor_w, rfactor_h)
        )

    shift_top, shift_left = shift

    point = self._others[0]

    if isinstance(shift_top, (int, float)) and isinstance(shift_left, (int, float)):
        upscaled = super().scale(
            ChromaLocation.TOP_LEFT.apply(clip),
            width,
            height,
            (shift_top + 0.5 - 0.5 / rfactor_h, shift_left + 0.5 - 0.5 / rfactor_w),
            **kwargs,
        )

        processed = self.function(upscaled)

        downscaled = point.scale(processed, clip.width, clip.height, (0.5 - 0.5 * rfactor_h, 0.5 - 0.5 * rfactor_w))
    else:
        shift_top = normalize_seq(shift_top, clip.format.num_planes)
        shift_left = normalize_seq(shift_left, clip.format.num_planes)

        upscaled = super().scale(
            ChromaLocation.CENTER.apply(clip),
            width,
            height,
            ([x + 0.5 - 0.5 / rfactor_h for x in shift_top], [x + 0.5 - 0.5 / rfactor_w for x in shift_left]),
            **kwargs,
        )

        processed = self.function(upscaled)

        downscaled = point.scale(
            processed, clip.width, clip.height, ([0.5 - 0.5 * rfactor_h] * 3, [0.5 - 0.5 * rfactor_w] * 3)
        )

    return ChromaLocation.from_video(clip).apply(downscaled)

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]