base ¶

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

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

@classproperty
@classmethod
def is_abstract(cls) -> bool:
    """Return True if this class can't be instantiated."""
    return _is_base_scaler_abstract(cls)

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

def bob(self, clip: vs.VideoNode, *, tff: FieldBasedLike | bool | None = None, **kwargs: Any) -> vs.VideoNode:
    """
    Apply bob deinterlacing to a given clip using the selected resizer.

    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
        tff: Field order of the clip.

    Returns:
        The bobbed clip.
    """
    clip_fieldbased = FieldBased.from_param_or_video(tff, clip, True, self.__class__)
    bob_args = self.get_bob_args(clip, tff=clip_fieldbased.is_tff, **kwargs)

    logger.debug("%s: Passing clip: %r; arguments: %s", self.bob, clip, bob_args)

    return self.bob_function(clip, **bob_args)

def deinterlace(
    self, clip: vs.VideoNode, *, tff: FieldBasedLike | bool | None = None, double_rate: bool = True, **kwargs: Any
) -> vs.VideoNode:
    """
    Apply deinterlacing to a given clip using the selected resizer.

    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
        tff: Field order of the clip.
        double_rate: Whether to double the frame rate (True) or retain the original rate (False).

    Returns:
        The bobbed clip.
    """
    bobbed = self.bob(clip, tff=tff, **kwargs)

    if not double_rate:
        return bobbed[::2]

    return bobbed

@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_bob_args(
    self, clip: vs.VideoNode, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> dict[str, Any]:
    """
    Generate the keyword arguments used for bobbing.

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

    Returns:
        Final dictionary of keyword arguments for the bob function.
    """
    return self.kwargs | kwargs

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

@classproperty
@classmethod
def is_abstract(cls) -> bool:
    """Return True if this class can't be instantiated."""
    return _is_base_scaler_abstract(cls)

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

def descale(
    self,
    clip: vs.VideoNode,
    width: int | None,
    height: int | None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Descale a clip to the given resolution.

    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) applied during scaling.

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

    descale_args = _norm_props_enums(self.get_descale_args(clip, shift, width, height, **kwargs))

    logger.debug("%s: Passing clip: %r; arguments: %s", self.descale, clip, descale_args)

    return self.descale_function(clip, **descale_args)

@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]:
    """
    Construct the argument dictionary used for descaling.

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

    Returns:
        Combined keyword argument dictionary.
    """
    return {"width": width, "height": height, "src_top": shift[0], "src_left": shift[1]} | self.kwargs | 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]:
    """
    Construct the argument dictionary used for upscaling.

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

    Returns:
        Combined keyword argument dictionary.
    """
    return {"width": width, "height": height, "src_top": shift[0], "src_left": shift[1]} | self.kwargs | kwargs

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

@classproperty
@classmethod
def is_abstract(cls) -> bool:
    """Return True if this class can't be instantiated."""
    return _is_base_scaler_abstract(cls)

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

def rescale(
    self,
    clip: vs.VideoNode,
    width: int | None,
    height: int | None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Rescale a clip to the given resolution from a previously descaled clip.

    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) applied during scaling.

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

    rescale_args = _norm_props_enums(self.get_rescale_args(clip, shift, width, height, **kwargs))

    logger.debug("%s: Passing clip: %r; arguments: %s", self.rescale, clip, rescale_args)

    return self.rescale_function(clip, **rescale_args)

def descale(
    self,
    clip: vs.VideoNode,
    width: int | None,
    height: int | None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Descale a clip to the given resolution.

    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) applied during scaling.

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

    descale_args = _norm_props_enums(self.get_descale_args(clip, shift, width, height, **kwargs))

    logger.debug("%s: Passing clip: %r; arguments: %s", self.descale, clip, descale_args)

    return self.descale_function(clip, **descale_args)

@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 _resolve_video_spec_args(clip, **{"width": width, "height": height} | self.kwargs | kwargs)

def get_resample_args(
    self,
    clip: vs.VideoNode,
    format: SupportsInt | VideoFormatLike | HoldsVideoFormat,
    matrix: MatrixLike | None,
    matrix_in: MatrixLike | None,
    transfer: TransferLike | None = None,
    transfer_in: TransferLike | None = None,
    primaries: PrimariesLike | None = None,
    primaries_in: PrimariesLike | None = 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.
        transfer: Target color transfer.
        transfer_in: Source color transfer.
        primaries: Target color primaries.
        primaries_in: Source color primaries.
        **kwargs: Additional arguments to pass to the resample function.

    Returns:
        Dictionary of keyword arguments for the resample function.
    """
    return {
        "format": get_video_format(format),
        "matrix": Matrix.from_param_with_fallback(matrix),
        "matrix_in": Matrix.from_param_with_fallback(matrix_in),
        "transfer": Transfer.from_param_with_fallback(transfer),
        "transfer_in": Transfer.from_param_with_fallback(transfer_in),
        "primaries": Primaries.from_param_with_fallback(primaries),
        "primaries_in": Primaries.from_param_with_fallback(primaries_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)