regress ¶

@inject_self.init_kwargs
def debug(self, clip: vs.VideoNode, *args: Any, **kwargs: Any) -> tuple[vs.VideoNode, ...]:
    """
    In 'debug' mode you can see the various steps of mangled and demangled planes.

    Useful to determine if shifts and the sort are correct.

    The *args, **kwargs don't do anything and are there just to be able to
    hotswap reconstruct with this method without removing other arguments.
    """
    y, y_base, y_m, y_dm, chroma_base, chroma_dm = self._get_bases(clip, False, self.debug)

    return y, y_base, y_dm, *flatten(zip(chroma_base, chroma_dm))

@abstractmethod
def demangle_chroma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    """
    Return the demangled luma as best quality as you can.

    Assumes that the resolutions matches ``y_base``.
    """

@abstractmethod
def demangle_luma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    """
    Return the demangled luma. You may use the y_base to limit the damage that was done in ``get_mangled_luma``
    but it is important that some artifacting from demangling chroma in ``demangle_chroma`` remains.

    May it be blurring or the interpolator artifacts (like SangNom random bright/dark pixels).

    Assumes that the resolutions matches ``y_base``.
    """

@abstractmethod
def get_base_clip(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Get the base clip on which the linear regression will be applied to.

    Needs to be the native resolution the content was produced at.
    Additionally, chroma needs to be scaled to 444 for later comparison
    and overshoot/undershoot protection.

    For example, if the anime is 720p native, this function needs to output 720p 4:4:4.
    Later, chroma will be upscaled at this resolution maximum and
    will be upscaled/downscaled to 420/444 based on ``out_mode`` in ``reconstruct``.
    """

def get_chroma_shift(self, y_width: int, c_width: int) -> float:
    return 0.5 * c_width / y_width

@abstractmethod
def get_mangled_luma(self, clip: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    """
    Return the mangled luma to the base resolution of the content.

    Chroma might have been further mangled or can be better demangled,
    but this method assumes that the luma will be taken as the same resolution as the INPUT clip.

    So, for example, at 1080p 4:2:0 this method should return mangled luma like chroma was at 960x540.
    EVEN IF the native resolution is lower.
    """

@inject_self.init_kwargs
def reconstruct(
    self,
    clip: vs.VideoNode,
    sigma: float,
    radius: int,
    diff_mode: ReconDiffMode | ReconDiffModeConf,
    out_mode: ReconOutput | bool | None,
    include_edges: bool,
    lin_cutoff: float = 0.0,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Run the actual reconstructing implemented in this class.

    Args:
        clip: Input clip. Must be YUV.
        sigma: Sigma for gaussian blur of weights, higher value is useful to dampen wrong directions.
        radius: Radius of the reconstruct window. Higher will be more stable but also less sharp and will adhere
            less to luma.
        diff_mode: The mode to apply the difference to apply, calculated with linear regression, to the mangled
            chroma. Check ``ReconDiffMode`` to know what each mode means.
        out_mode: The luma/chroma output combination.
        include_edges: Forcecully include all luma edges in the weighting.
        lin_cutoff: Cutoff, or weight, in the linear regression.

    Returns:
        Clip with demangled chroma.
    """

    y, y_base, y_m, y_dm, chroma_base, chroma_dm = self._get_bases(clip, include_edges, self.reconstruct)

    reg = Regression.from_param(Regression.BlurConf(gauss_blur, sigma=sigma))  # pyright: ignore

    if not isinstance(diff_mode, ReconDiffModeConf):
        diff_mode = diff_mode()

    chroma_regs = reg.linear([y_dm, *chroma_dm], lin_cutoff, diff_mode.inter_scale)

    y_diff = norm_expr((y_base, y_dm), "x y -", func=self.reconstruct)

    y_diffxb = gauss_blur(
        norm_expr((y_base, y_dm), f"x y / {reg.eps} 1 clamp"), diff_mode.diff_sigma, func=self.reconstruct
    )

    fixup = (
        y_diff.recon.Reconstruct(  # type: ignore
            reg.slope,
            reg.correlation,
            radius=radius,
            intercept=(None if diff_mode.inter_scale == 0.0 else reg.intercept),
        )
        for reg in chroma_regs
    )

    fixed_chroma = (
        norm_expr((dm, fix, y_diffxb, base), diff_mode.mode.value, func=self.reconstruct)
        for dm, fix, base in zip(chroma_dm, fixup, chroma_base)
    )

    out_mode = ReconOutput.from_param(out_mode)

    top_shift = left_shift = 0.0

    if out_mode == ReconOutput.i420:
        left_shift = -self.get_chroma_shift(y.width, y_m.height)
    elif include_edges:
        top_shift = left_shift = 0.125 / 2

    shifted_chroma = (self._kernel.shift(p, (top_shift, left_shift)) for p in fixed_chroma)

    if out_mode != ReconOutput.NATIVE:
        y_base, targ_sizes = y, (clip.width, clip.height)

        if out_mode == ReconOutput.i420:
            targ_sizes = tuple[int, int](targ_size // 2 for targ_size in targ_sizes)  # type: ignore

        shifted_chroma = (self._scaler.scale(p, *targ_sizes) for p in shifted_chroma)

    return depth(join(y_base, *shifted_chroma), clip)

@inject_self.init_kwargs
def debug(self, clip: vs.VideoNode, *args: Any, **kwargs: Any) -> tuple[vs.VideoNode, ...]:
    """
    In 'debug' mode you can see the various steps of mangled and demangled planes.

    Useful to determine if shifts and the sort are correct.

    The *args, **kwargs don't do anything and are there just to be able to
    hotswap reconstruct with this method without removing other arguments.
    """
    y, y_base, y_m, y_dm, chroma_base, chroma_dm = self._get_bases(clip, False, self.debug)

    return y, y_base, y_dm, *flatten(zip(chroma_base, chroma_dm))

def demangle_chroma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    return self._kernel.scale(
        mangled, y_base.width, y_base.height, (0, self.get_chroma_shift(y_base.width, mangled.width))
    )

def demangle_luma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    src_left, self.src_left = self.src_left, self.src_left - 0.25
    luma = self.demangle_chroma(mangled, y_base)
    self.src_left = src_left
    return luma

def get_base_clip(self, clip: vs.VideoNode) -> vs.VideoNode:
    if self.native_res is None:
        return self._kernel.resample(clip, vs.YUV444PS)

    de_args = ScalingArgs.from_args(clip, self.native_res)

    descale = self._native_kernel.descale(clip, de_args.width, de_args.height, **de_args.kwargs())

    return join(
        self._kernel.shift(descale, de_args.src_top / 2, -de_args.src_left / 2),
        self._scaler.scale(clip, de_args.width, de_args.height, format=vs.YUV444PS),
    )

def get_chroma_shift(self, y_width: int, c_width: int) -> float:
    return 0.5 * c_width / y_width

def get_mangled_luma(self, clip: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    c_width, c_height = get_plane_sizes(clip, 1)

    return Catrom().scale(y_base, c_width, c_height, (0, -0.5 + self.get_chroma_shift(clip.width, c_width)))

@inject_self.init_kwargs
def reconstruct(
    self,
    clip: vs.VideoNode,
    sigma: float = 1.5,
    radius: int = 2,
    diff_mode: ReconDiffMode | ReconDiffModeConf = ReconDiffMode.MEAN,
    out_mode: ReconOutput | bool | None = ReconOutput.i420,
    include_edges: bool = False,
    lin_cutoff: float = 0.0,
    **kwargs: Any,
) -> vs.VideoNode:
    return super().reconstruct(clip, sigma, radius, diff_mode, out_mode, include_edges, lin_cutoff)

@inject_self.init_kwargs
def debug(self, clip: vs.VideoNode, *args: Any, **kwargs: Any) -> tuple[vs.VideoNode, ...]:
    """
    In 'debug' mode you can see the various steps of mangled and demangled planes.

    Useful to determine if shifts and the sort are correct.

    The *args, **kwargs don't do anything and are there just to be able to
    hotswap reconstruct with this method without removing other arguments.
    """
    y, y_base, y_m, y_dm, chroma_base, chroma_dm = self._get_bases(clip, False, self.debug)

    return y, y_base, y_dm, *flatten(zip(chroma_base, chroma_dm))

def demangle_chroma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    return self._kernel.scale(
        mangled, y_base.width, y_base.height, (0, self.get_chroma_shift(y_base.width, mangled.width))
    )

def demangle_luma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    src_left, self.src_left = self.src_left, self.src_left - 0.25
    luma = self.demangle_chroma(mangled, y_base)
    self.src_left = src_left
    return luma

def get_base_clip(self, clip: vs.VideoNode) -> vs.VideoNode:
    if self.native_res is None:
        return self._kernel.resample(clip, vs.YUV444PS)

    de_args = ScalingArgs.from_args(clip, self.native_res)

    descale = self._native_kernel.descale(clip, de_args.width, de_args.height, **de_args.kwargs())

    return join(
        self._kernel.shift(descale, de_args.src_top / 2, -de_args.src_left / 2),
        self._scaler.scale(clip, de_args.width, de_args.height, format=vs.YUV444PS),
    )

def get_chroma_shift(self, y_width: int, c_width: int) -> float:
    return 0.5 * c_width / y_width

def get_mangled_luma(self, clip: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    c_width, c_height = get_plane_sizes(clip, 1)

    return Catrom().scale(y_base, c_width, c_height, (0, -0.5 + self.get_chroma_shift(clip.width, c_width)))

@inject_self.init_kwargs
def reconstruct(
    self,
    clip: vs.VideoNode,
    sigma: float = 1.5,
    radius: int = 2,
    diff_mode: ReconDiffMode | ReconDiffModeConf = ReconDiffMode.MEAN,
    out_mode: ReconOutput | bool | None = ReconOutput.i420,
    include_edges: bool = False,
    lin_cutoff: float = 0.0,
    **kwargs: Any,
) -> vs.VideoNode:
    return super().reconstruct(clip, sigma, radius, diff_mode, out_mode, include_edges, lin_cutoff)

@inject_self.init_kwargs
def debug(self, clip: vs.VideoNode, *args: Any, **kwargs: Any) -> tuple[vs.VideoNode, ...]:
    """
    In 'debug' mode you can see the various steps of mangled and demangled planes.

    Useful to determine if shifts and the sort are correct.

    The *args, **kwargs don't do anything and are there just to be able to
    hotswap reconstruct with this method without removing other arguments.
    """
    y, y_base, y_m, y_dm, chroma_base, chroma_dm = self._get_bases(clip, False, self.debug)

    return y, y_base, y_dm, *flatten(zip(chroma_base, chroma_dm))

def demangle_chroma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    demangled = vs.core.resize.Point(mangled, y_base.width // 2, mangled.height)

    demangled = self._dm_wscaler.scale(demangled, mangled.width, y_base.height, (self.src_top, 0))
    demangled = self._dm_hscaler.scale(demangled, y_base.width, y_base.height, (0, self.src_left))

    return demangled

def demangle_luma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    a = self.demangle_chroma(mangled, y_base)

    y_base = self._kernel.shift(y_base, self.src_top, self.src_left)

    return limit_filter(a, y_base, a, thr=1, elast=4.5, bright_thr=10)

def get_base_clip(self, clip: vs.VideoNode) -> vs.VideoNode:
    if self.native_res is None:
        return self._kernel.resample(clip, vs.YUV444PS)

    de_args = ScalingArgs.from_args(clip, self.native_res)

    descale = self._native_kernel.descale(clip, de_args.width, de_args.height, **de_args.kwargs())

    return join(
        self._kernel.shift(descale, de_args.src_top / 2, -de_args.src_left / 2),
        self._scaler.scale(clip, de_args.width, de_args.height, format=vs.YUV444PS),
    )

def get_chroma_shift(self, y_width: int, c_width: int) -> float:
    return 0.5 * c_width / y_width

def get_mangled_luma(self, clip: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    cm_width, _ = get_plane_sizes(y_base, 1)
    c_width, c_height = get_plane_sizes(clip, 1)

    point = Point()

    y_m = point.scale(y_base, cm_width // 2, y_base.height, (0, -1))
    y_m = point.scale(y_m, c_width, y_base.height, (0, -0.25))
    y_m = Catrom().scale(y_m, c_width, c_height)

    return y_m

@inject_self.init_kwargs
def reconstruct(
    self,
    clip: vs.VideoNode,
    sigma: float = 2.0,
    radius: int = 4,
    diff_mode: ReconDiffMode | ReconDiffModeConf = ReconDiffMode.MEDIAN,
    out_mode: ReconOutput | bool | None = ReconOutput.NATIVE,
    include_edges: bool = True,
    lin_cutoff: float = 0.0,
    **kwargs: Any,
) -> vs.VideoNode:
    return super().reconstruct(clip, sigma, radius, diff_mode, out_mode, include_edges, lin_cutoff)

@inject_self.init_kwargs
def debug(self, clip: vs.VideoNode, *args: Any, **kwargs: Any) -> tuple[vs.VideoNode, ...]:
    """
    In 'debug' mode you can see the various steps of mangled and demangled planes.

    Useful to determine if shifts and the sort are correct.

    The *args, **kwargs don't do anything and are there just to be able to
    hotswap reconstruct with this method without removing other arguments.
    """
    y, y_base, y_m, y_dm, chroma_base, chroma_dm = self._get_bases(clip, False, self.debug)

    return y, y_base, y_dm, *flatten(zip(chroma_base, chroma_dm))

def demangle_chroma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    demangled = self._dm_hscaler.scale(mangled, mangled.width, y_base.height)
    return self._dm_wscaler.scale(demangled, y_base.width, y_base.height, (self.src_top, self.src_left))

def demangle_luma(self, mangled: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    src_left, self.src_left = self.src_left, self.src_left - 0.25
    luma = self.demangle_chroma(mangled, y_base)
    self.src_left = src_left
    return luma

def get_base_clip(self, clip: vs.VideoNode) -> vs.VideoNode:
    if self.native_res is None:
        return self._kernel.resample(clip, vs.YUV444PS)

    de_args = ScalingArgs.from_args(clip, self.native_res)

    descale = self._native_kernel.descale(clip, de_args.width, de_args.height, **de_args.kwargs())

    return join(
        self._kernel.shift(descale, de_args.src_top / 2, -de_args.src_left / 2),
        self._scaler.scale(clip, de_args.width, de_args.height, format=vs.YUV444PS),
    )

def get_chroma_shift(self, y_width: int, c_width: int) -> float:
    return 0.5 * c_width / y_width

def get_mangled_luma(self, clip: vs.VideoNode, y_base: vs.VideoNode) -> vs.VideoNode:
    c_width, c_height = get_plane_sizes(clip, 1)

    return Catrom().scale(y_base, c_width, c_height, (0, -0.5 + self.get_chroma_shift(clip.width, c_width)))

@inject_self.init_kwargs
def reconstruct(
    self,
    clip: vs.VideoNode,
    sigma: float = 1.5,
    radius: int = 2,
    diff_mode: ReconDiffMode | ReconDiffModeConf = ReconDiffMode.MEDIAN,
    out_mode: ReconOutput | bool | None = ReconOutput.i444,
    include_edges: bool = True,
    lin_cutoff: float = 0.0,
    **kwargs: Any,
) -> vs.VideoNode:
    return super().reconstruct(clip, sigma, radius, diff_mode, out_mode, include_edges, lin_cutoff)

def __call__(self, diff_sigma: float = 0.5, inter_scale: float = 0.0) -> ReconDiffModeConf:
    """
    Configure the current mode. **It will not have any effect with ``SIMPLE``.

    Args:
        diff_sigma: Gaussian blur sigma for the luma-mangled luma difference.
        inter_scale: Scaling for using the luma-chroma difference intercept.

               - ``= 0.0``   => Disable usage of intercept.
               - ``< 20.0``  => Will amplify and overshoot/undershoot all bright/dark spots. Not recommended.
               - ``< 50.0``  => Will dampen haloing and normalize chroma to luma, removing eventual bleeding.
               - ``> 100.0`` => Placebo effect.

    Returns:
        Configured mode.
    """
    return ReconDiffModeConf(self, diff_sigma, inter_scale)

@classmethod
def from_param(cls, value: int | ReconOutput | bool | None, func_except: FuncExceptT | None = None) -> ReconOutput:
    if isinstance(value, bool):
        value = 1 + int(value)
    elif value is None:
        return cls.NATIVE

    return super().from_param(value, func_except)  # type: ignore