util ¶

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

    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: FuncExceptT | 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)

@BaseScalerMeta.cached_property
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.cached_property
def pretty_string(self) -> str:
    """
    Cached property returning a user-friendly string representation.

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

@classmethod
def from_func(
    cls,
    func: Callable[Concatenate[vs.VideoNode, P], vs.VideoNode] | None = None,
    /,
    sigmoid: bool | tuple[Slope, Center] = False,
    resampler: ResamplerLike = Catrom,
    out_fmt: int | VideoFormatT | HoldsVideoFormatT | None = None,
) -> Union[
    Callable[Concatenate[vs.VideoNode, P], vs.VideoNode],
    Callable[
        [Callable[Concatenate[vs.VideoNode, P], vs.VideoNode]], Callable[Concatenate[vs.VideoNode, P], vs.VideoNode]
    ],
]:
    """
    Decorator version of LinearLight.
    """

    if func is None:
        return partial(cls.from_func, sigmoid=sigmoid, resampler=resampler, out_fmt=out_fmt)

    @wraps(func)
    def _wrapped(clip: vs.VideoNode, *args: P.args, **kwargs: P.kwargs) -> vs.VideoNode:
        with cls(clip, sigmoid, resampler, out_fmt) as ll:
            ll.linear = func(clip, *args, **kwargs)
        return ll.out

    return _wrapped

def get_linear(self) -> vs.VideoNode:
    """
    Getter for `linear` cached property.
    """
    wclip = self.ll._resampler.resample(
        self.ll._wclip,
        vs.RGBS if self.ll._wclip.format.color_family in (vs.YUV, vs.RGB) else vs.GRAYS,
        matrix_in=self.ll._matrix,
        transfer_in=self.ll._curve,
        transfer=Transfer.LINEAR,
    )

    if self.ll.sigmoid:
        wclip = norm_expr(
            wclip,
            "{center} 1 {slope} / 1 x 0 max 1 min {scale} * {offset} + / 1 - log * -",
            center=self.ll._scenter,
            slope=self.ll._sslope,
            scale=self.ll._sscale,
            offset=self.ll._soffset,
            func=self.__class__,
        )

    return wclip

@cachedproperty
def out(self) -> vs.VideoNode:
    if not self.ll._exited:
        raise CustomRuntimeError(
            "You can't get .out while still inside of the context manager!", func=self.__class__
        )

    if not hasattr(self, "_linear"):
        raise CustomValueError("You need to set .linear before getting .out!", self.__class__)

    if self.ll.sigmoid:
        processed = norm_expr(
            self._linear,
            "1 1 {slope} {center} x 0 max 1 min - * exp + / {offset} - {scale} /",
            slope=self.ll._sslope,
            center=self.ll._scenter,
            offset=self.ll._soffset,
            scale=self.ll._sscale,
            func=self.__class__,
        )
    else:
        processed = self._linear

    processed = vs.core.resize2.Point(processed, transfer_in=Transfer.LINEAR, transfer=self.ll._curve)

    return resample_to(processed, self.ll._fmt, self.ll._matrix, self.ll._resampler)

def set_linear(self, processed: vs.VideoNode) -> None:
    """
    Setter for `linear` cached property.
    """
    if self.ll._exited:
        raise CustomRuntimeError(
            "You can't set .linear after going out of the context manager!", func=self.__class__
        )
    self._linear = processed

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

    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: FuncExceptT | 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)

@classmethod
def from_scaler(cls, scaler: ScalerLike) -> type[NoScale[Scaler]]:
    """
    Create a specialized NoScale class using a specific scaler.

    Args:
        scaler: A Scaler instance, type or string used as a base for specialization.

    Returns:
        A dynamically created NoScale subclass based on the given scaler.
    """
    return NoScale[Scaler.from_param(scaler)]  # type: ignore[return-value,misc]

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

@BaseScalerMeta.cached_property
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`.

    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.cached_property
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, LeftShift] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode | ConstantFormatVideoNode:
    """
    Return the input clip unscaled, validating that the dimensions are consistent.

    Args:
        clip: The source clip.
        width: Optional width to validate against the clip's width.
        height: Optional height to validate against the clip's height.
        shift: Subpixel shift (top, left).
        **kwargs: Additional arguments forwarded to the scale function.

    Raises:
        CustomValueError: If `width` or `height` differ from the clip's dimensions.
    """
    width, height = self._wh_norm(clip, width, height)

    if width != clip.width or height != clip.height:
        raise CustomValueError(
            "When using NoScale, `width` and `height` must match the clip's dimensions.",
            self.__class__,
            (width, height),
        )

    if shift == (0, 0) and not kwargs and not self.kwargs:
        return clip

    return super().scale(clip, width, height, shift, **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.

    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]