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.

    :param clip:            Input clip. Must be YUV.
    :param sigma:           Sigma for gaussian blur of weights, higher value is useful to dampen wrong directions.
    :param radius:          Radius of the reconstruct window. Higher will be more stable but also less sharp
                            and will adhere less to luma.
    :param 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.
    :param out_mode:        The luma/chroma output combination.
    :param include_edges:   Forcecully include all luma edges in the weighting.
    :param lin_cutoff:      Cutoff, or weight, in the linear regression.

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

    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(
            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(  # type: ignore
    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(  # type: ignore
    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 = Point.scale(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)

    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(  # type: ignore
    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(  # type: ignore
    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``.

    :param diff_sigma:  Gaussian blur sigma for the luma-mangled luma difference.
    :param 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 reccomended.
                        - < 50.0  => Will dampen haloing and normalize chroma to luma, removing eventual bleeding.
                        - > 100.0 => Placebo effect.

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