debanders ¶

@F3KDeband
def f3k_deband(
    clip: vs.VideoNode,
    radius: int = 16,
    thr: int | Sequence[int] = 96,
    grain: float | Sequence[float] = 0.0,
    planes: PlanesT = None,
    *,
    sample_mode: F3KDeband.SampleMode = F3KDeband.SampleMode.SQUARE,
    dynamic_grain: bool = False,
    blur_first: bool = True,
    seed: int | None = None,
    random: F3KDeband.RandomAlgo | tuple[F3KDeband.RandomAlgo, F3KDeband.RandomAlgo] = F3KDeband.RandomAlgo.UNIFORM,
    **kwargs: Any
) -> vs.VideoNode:
    """
    Debanding filter wrapper using the `neo_f3kdb` plugin.

    More informations can be found in the plugin documentation: https://github.com/HomeOfAviSynthPlusEvolution/neo_f3kdb

    :param clip:            Input clip.
    :param radius:          Radius used for banding detection. Valid range is [1, 255].
    :param thr:             Banding detection threshold(s) for each plane (Y, Cb, Cr).
                            A pixel is considered banded if the difference with its reference pixel(s)
                            is less than the corresponding threshold.
    :param grain:           Amount of grain to add after debanding. Accepts a float or sequence of floats.
    :param planes:          Specifies which planes to process. Default is all planes.
    :param sample_mode:     Strategy used to sample reference pixels. See [SampleMode][vsdeband.debanders.F3KDeband.SampleMode].
    :param dynamic_grain:   If True, generates a unique grain pattern for each frame.
    :param blur_first:      If True, compares current pixel to the mean of surrounding pixels.
                            If False, compares directly to all reference pixels. A pixel is marked as banded
                            only if all pixel-wise differences are below threshold.
    :param seed:            Random seed for grain generation.
    :param random:          Random number generation strategy.
                            Can be a single value for both reference and grain, or a tuple specifying separate algorithms.
                            See [RandomAlgo][vsdeband.debanders.F3KDeband.RandomAlgo].
    :param kwargs:          Additional keyword arguments passed directly to the `neo_f3kdb.Deband` plugin.

    :raises CustomValueError:           If inconsistent grain parameters are provided across chroma planes.
    :raises InvalidColorFamilyError:    If input clip is not YUV or GRAY.

    :return:                Debanded and optionally grained clip.
    """

    InvalidColorFamilyError.check(clip, (vs.GRAY, vs.YUV), f3k_deband)

    clip, bits = expect_bits(clip, 16)

    y, cb, cr = normalize_param_planes(clip, normalize_seq(thr, 3), planes, 0, f3k_deband)
    grainy, *ngrainc = normalize_param_planes(clip, normalize_seq(grain, 2), planes, 0, f3k_deband)

    if len(set(ngrainc)) > 1:
        raise CustomValueError("Inconsistent grain parameters across chroma planes.", f3k_deband)

    random_ref, random_grain = normalize_seq(random, 2)

    kwargs = (
        sample_mode.kwargs
        | dict(
            scale=True,
            random_algo_ref=random_ref,
            random_algo_grain=random_ref.sigma,
            random_param_ref=random_grain,
            random_param_grain=random_grain.sigma
        )
        | kwargs
    )

    debanded = core.neo_f3kdb.Deband(
        clip,
        radius,
        y,
        cb,
        cr,
        round(grainy * 255 * 0.8),
        round(ngrainc[0] * 255 * 0.8),
        sample_mode,
        seed,
        blur_first,
        dynamic_grain,
        **kwargs
    )

    return depth(debanded, bits)

def mdb_bilateral(
    clip: vs.VideoNode,
    radius: int = 16,
    thr: float = 260,
    lthr: int | tuple[int, int] = (153, 0),
    elast: float = 3.0,
    bright_thr: int | None = None,
    debander: _DebanderFunc[Any] = f3k_deband
) -> vs.VideoNode:
    """
    Multi stage debanding, bilateral-esque filter.

    This function is more of a last resort for extreme banding.

    Example usage:
    ```py
    from vsdeband import mdb_bilateral, f3k_deband
    from functools import partial

    debanded = mdb_bilateral(clip, 17, 320, debander=partial(f3k_deband, split_planes=True))
    ```

    :param clip:        Input clip.
    :param radius:      Banding detection range.
    :param thr:         Banding detection thr(s) for planes.
    :param lthr:        Threshold of the limiting. Refer to `vsrgtools.limit_filter`.
    :param elast:       Elasticity of the limiting. Refer to `vsrgtools.limit_filter`.
    :param bright_thr:  Limiting over the bright areas. Refer to `vsrgtools.limit_filter`.
    :param debander:    Specifies what debander callable to use.

    :return:            Debanded clip.
    """
    assert check_variable(clip, mdb_bilateral)

    clip, bits = expect_bits(clip, 16)

    rad1, rad2, rad3 = round(radius * 4 / 3), round(radius * 2 / 3), round(radius / 3)

    db1 = debander(clip, rad1, [max(1, th // 2) for th in to_arr(thr)], 0.0)
    db2 = debander(db1, rad2, thr, 0)
    db3 = debander(db2, rad3, thr, 0)

    limit = limit_filter(db3, db2, clip, thr=lthr, elast=elast, bright_thr=bright_thr)

    return depth(limit, bits)

def pfdeband(
    clip: vs.VideoNode,
    radius: int = 16,
    thr: float | Sequence[float] = 96,
    lthr: float | tuple[float, float] = 0.5,
    elast: float = 1.5,
    bright_thr: int | None = None,
    prefilter: PrefilterLike | _SupportPlanesParam = gauss_blur,
    debander: _DebanderFunc[Any] = f3k_deband,
    planes: PlanesT = None,
    **kwargs: Any
) -> vs.VideoNode:
    """
    Prefilter and deband a clip.

    :param clip:        Input clip.
    :param radius:      Banding detection range.
    :param thr:         Banding detection thr(s) for planes.
    :param lthr:        Threshold of the limiting. Refer to `vsrgtools.limit_filter`.
    :param elast:       Elasticity of the limiting. Refer to `vsrgtools.limit_filter`.
    :param bright_thr:  Limiting over the bright areas. Refer to `vsrgtools.limit_filter`.
    :param prefilter:   Prefilter used to blur the clip before debanding.
    :param debander:    Specifies what debander callable to use.
    :param planes:      Planes to process

    :return:              Debanded clip.
    """
    clip, bits = expect_bits(clip, 16)

    blur = prefilter(clip, planes=planes, **kwargs)
    diff = clip.std.MakeDiff(blur, planes=planes)

    deband = debander(blur, radius, thr, planes=planes)

    merge = deband.std.MergeDiff(diff, planes=planes)
    limit = limit_filter(merge, clip, thr=lthr, elast=elast, bright_thr=bright_thr)

    return depth(limit, bits)

def placebo_deband(
    clip: vs.VideoNode,
    radius: float = 16.0,
    thr: float | Sequence[float] = 3.0,
    grain: float | Sequence[float] = 0.0,
    planes: PlanesT = None,
    *,
    iterations: int = 4,
    **kwargs: Any
) -> vs.VideoNode:
    """
    Debanding wrapper around the `placebo.Deband` filter from the VapourSynth `vs-placebo` plugin.

    For full plugin documentation, see:
    https://github.com/sgt0/vs-placebo?tab=readme-ov-file#deband

    :param clip:        Input clip.
    :param radius:      Initial debanding radius.
                        The radius increases linearly with each iteration.
                        A higher radius will find more gradients, but a lower radius will smooth more aggressively.
    :param thr:         Cut-off threshold(s) for each plane. Higher values increase debanding strength
                        but may remove fine details. Accepts a single float or a sequence per plane.
    :param grain:       Amount of grain/noise to add after debanding. Helps mask residual artifacts.
                        Accepts a float or a sequence per plane.
                        Note: For HDR content, grain can significantly affect brightness — consider reducing or disabling.
    :param planes:      Which planes to process. Defaults to all planes.
    :param iterations:  Number of debanding steps to perform per sample.
                        More iterations yield stronger effect but quickly lose efficiency beyond 4.
    :return:            Debanded and optionally grained clip.
    """

    assert check_variable(clip, placebo_deband)

    thr = normalize_param_planes(clip, normalize_seq(thr), planes, 0, placebo_deband)
    ngrain = normalize_param_planes(clip, normalize_seq(grain), planes, 0, placebo_deband)

    def _placebo(
        clip: ConstantFormatVideoNode, threshold: float, grain_val: float, planes: Sequence[int]
    ) -> ConstantFormatVideoNode:
        plane = 0

        if threshold == grain_val == 0:
            return clip

        for p in planes:
            plane |= pow(2, p)

        return clip.placebo.Deband(
            plane, iterations, threshold, radius, grain_val * (1 << 5) * 0.8, **kwargs
        )

    set_grn = set(ngrain)

    if set_grn == {0} or clip.format.num_planes == 1:
        debs = [_placebo(p, t, ngrain[0], [0]) for p, t in zip(split(clip), thr)]

        if len(debs) == 1:
            return debs[0]

        return join(debs, clip.format.color_family)

    plane_map = {
        tuple(i for i in range(clip.format.num_planes) if ngrain[i] == x): x for x in set_grn - {0}
    }

    debanded = clip

    for planes, grain_val in plane_map.items():
        if len(set(thr[p] for p in planes)) == 1:
            debanded = _placebo(debanded, thr[planes[0]], grain_val, planes)
        else:
            for p in planes:
                debanded = _placebo(debanded, thr[p], grain_val, planes)

    return debanded