various ¶

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

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

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

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                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.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

@Scaler.cached_property
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

@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 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)

        if self.masked:
            merged = merged.std.MaskedMerge(merge2, ringing_mask(smooth))
        else:
            merged = 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.

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

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

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

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

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                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.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

@Scaler.cached_property
def kernel_radius(self) -> int:
    return self._ref_scaler.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 scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any
) -> ConstantFormatVideoNode:
    assert check_variable(clip, self.__class__)

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

    ref = clip

    if isinstance(self.ref, vs.VideoNode):
        check_ref_clip(clip, self.ref)

        if TYPE_CHECKING:
            assert check_variable_format(self.ref, self.__class__)

        ref = self.ref

    if (ref.width, ref.height) != (width, height):
        ref = self._ref_scaler.scale(ref, width, height)  # type: ignore[assignment]

    kwargs = {
        'lambda': self.sigma, 'planes': self.planes,
        'src_left': shift[1], 'src_top': shift[0]
    } | self.kwargs | kwargs | {'read_chromaloc': True}

    return core.dpid.DpidRaw(clip, ref, **kwargs)

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]

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

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

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

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                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.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

@Scaler.cached_property
def kernel_radius(self) -> int:
    return self.scaler.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 scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    *,
    # LinearScaler adds `linear` and `sigmoid` parameters
    linear: bool | None = None,
    sigmoid: bool | tuple[Slope, Center] = False,
    **kwargs: Any,
) -> vs.VideoNode | ConstantFormatVideoNode:
    """
    Scale a clip to the given resolution with optional linearization.

    This method behaves like the base `Scaler.descale()` but adds support for
    linear or sigmoid-based preprocessing and postprocessing. When enabled, the clip
    is linearized before the scaling operation and de-linearized afterward.

    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 width (defaults to clip width if None).
    :param height:      Target height (defaults to clip height if None).
    :param shift:       Subpixel shift (top, left) applied during scaling.
    :param linear:      Whether to linearize the input before scaling. If None, inferred from sigmoid.
    :param 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).
    :param kwargs:      Additional arguments forwarded to the scale function.
    :return:            Scaled video clip.
    """
    return _linearize(
        self,
        clip,
        linear,
        sigmoid,
        partial(super().scale, width=width, height=height, shift=shift),
        self.scale,
        **kwargs
    )

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]