placebo ¶

@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]:
    kwargs.pop("format", None)

    return (
        {
            "sx": kwargs.pop("src_left", shift[1]),
            "sy": kwargs.pop("src_top", shift[0]),
            "width": width,
            "height": height,
            "filter": self._kernel,
            "radius": self.radius,
            "param1": self.b,
            "param2": self.c,
            "clamp": self.clamp,
            "taper": self.taper,
            "blur": self.blur,
            "antiring": self.antiring,
        }
        | self.kwargs
        | kwargs
        | {"linearize": False, "sigmoidize": False}
    )

@classproperty.cached
@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", ()))

@ComplexScaler.cachedproperty
def kernel_radius(self) -> int:
    if self.radius:
        return ceil(self.radius)

    if self.b or self.c:
        b, c = fallback(self.b, 0), fallback(self.c, 0.5)

        if (b, c) == (0, 0):
            return 1

    return 2

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

    If a `format` is provided, only a change in chroma subsampling is allowed.
    Other format characteristics (bit depth, sample type, color family, etc.) must match the source clip.

    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.
    """
    if fmt := fallback(kwargs.get("format"), self.kwargs.get("format"), False):
        fmt = get_video_format(fmt)

        if (
            clip.format.color_family != fmt.color_family
            or clip.format.num_planes != fmt.num_planes
            or clip.format.sample_type != fmt.sample_type
            or clip.format.bits_per_sample != fmt.bits_per_sample
        ):
            raise CustomValueError("Only YUV subsampling scaling is supported.", self.__class__, fmt.name)

        shift = (to_arr(shift[0]), to_arr(shift[1]))

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

def supersample(
    self, clip: vs.VideoNode, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> vs.VideoNode:
    """
    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)

@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]:
    kwargs.pop("format", None)

    return (
        {
            "sx": kwargs.pop("src_left", shift[1]),
            "sy": kwargs.pop("src_top", shift[0]),
            "width": width,
            "height": height,
            "filter": self._kernel,
            "radius": self.radius,
            "param1": self.b,
            "param2": self.c,
            "clamp": self.clamp,
            "taper": self.taper,
            "blur": self.blur,
            "antiring": self.antiring,
        }
        | self.kwargs
        | kwargs
        | {"linearize": False, "sigmoidize": False}
    )

@classproperty.cached
@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", ()))

@ComplexScaler.cachedproperty
def kernel_radius(self) -> int:
    if self.radius:
        return ceil(self.radius)

    if self.b or self.c:
        b, c = fallback(self.b, 0), fallback(self.c, 0.5)

        if (b, c) == (0, 0):
            return 1

    return 2

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

    If a `format` is provided, only a change in chroma subsampling is allowed.
    Other format characteristics (bit depth, sample type, color family, etc.) must match the source clip.

    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.
    """
    if fmt := fallback(kwargs.get("format"), self.kwargs.get("format"), False):
        fmt = get_video_format(fmt)

        if (
            clip.format.color_family != fmt.color_family
            or clip.format.num_planes != fmt.num_planes
            or clip.format.sample_type != fmt.sample_type
            or clip.format.bits_per_sample != fmt.bits_per_sample
        ):
            raise CustomValueError("Only YUV subsampling scaling is supported.", self.__class__, fmt.name)

        shift = (to_arr(shift[0]), to_arr(shift[1]))

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

def supersample(
    self, clip: vs.VideoNode, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> vs.VideoNode:
    """
    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)

@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]:
    kwargs.pop("format", None)

    return (
        {
            "sx": kwargs.pop("src_left", shift[1]),
            "sy": kwargs.pop("src_top", shift[0]),
            "width": width,
            "height": height,
            "filter": self._kernel,
            "radius": self.radius,
            "param1": self.b,
            "param2": self.c,
            "clamp": self.clamp,
            "taper": self.taper,
            "blur": self.blur,
            "antiring": self.antiring,
        }
        | self.kwargs
        | kwargs
        | {"linearize": False, "sigmoidize": False}
    )

@classproperty.cached
@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", ()))

@ComplexScaler.cachedproperty
def kernel_radius(self) -> int:
    if self.radius:
        return ceil(self.radius)

    if self.b or self.c:
        b, c = fallback(self.b, 0), fallback(self.c, 0.5)

        if (b, c) == (0, 0):
            return 1

    return 2

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

    If a `format` is provided, only a change in chroma subsampling is allowed.
    Other format characteristics (bit depth, sample type, color family, etc.) must match the source clip.

    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.
    """
    if fmt := fallback(kwargs.get("format"), self.kwargs.get("format"), False):
        fmt = get_video_format(fmt)

        if (
            clip.format.color_family != fmt.color_family
            or clip.format.num_planes != fmt.num_planes
            or clip.format.sample_type != fmt.sample_type
            or clip.format.bits_per_sample != fmt.bits_per_sample
        ):
            raise CustomValueError("Only YUV subsampling scaling is supported.", self.__class__, fmt.name)

        shift = (to_arr(shift[0]), to_arr(shift[1]))

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

def supersample(
    self, clip: vs.VideoNode, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> vs.VideoNode:
    """
    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)