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

    Args:
        clip: Input clip.
        radius: Radius used for banding detection. Valid range is [1, 255].
        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.
        grain: Amount of grain to add after debanding. Accepts a float or sequence of floats.
        planes: Specifies which planes to process. Default is all planes.
        sample_mode: Strategy used to sample reference pixels. See
            [SampleMode][vsdeband.debanders.F3KDeband.SampleMode].
        dynamic_grain: If True, generates a unique grain pattern for each frame.
        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.
        seed: Random seed for grain generation.
        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].
        **kwargs: Additional keyword arguments passed directly to the `neo_f3kdb.Deband` plugin.

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

    Returns:
        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
        | {
            "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,
    debander: _DebanderFunc[Any] = f3k_deband,
    dark_thr: float | Sequence[float] = 0.6,
    bright_thr: float | Sequence[float] = 0.6,
    elast: float | Sequence[float] = 3.0,
    planes: PlanesT = None,
) -> 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)
    ```

    Args:
        clip: Input clip.
        radius: Banding detection range.
        thr: Banding detection thr(s) for planes.
        debander: Specifies what debander callable to use.
        dark_thr: [limit_filter][vsrgtools.limit_filter] parameter.
            Threshold (8-bit scale) to limit dark filtering diff.
        bright_thr: [limit_filter][vsrgtools.limit_filter] parameter.
            Threshold (8-bit scale) to limit bright filtering diff.
        elast: [limit_filter][vsrgtools.limit_filter] parameter.
            Elasticity of the soft threshold.
        planes: Which planes to process.

    Returns:
        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, planes)
    db2 = debander(db1, rad2, thr, 0, planes)
    db3 = debander(db2, rad3, thr, 0, planes)

    limit = limit_filter(db3, clip, db1, dark_thr, bright_thr, elast, planes)

    return depth(limit, bits)

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

    Args:
        clip: Input clip.
        radius: Banding detection range.
        thr: Banding detection thr(s) for planes.
        prefilter: Prefilter used to blur the clip before debanding.
        debander: Specifies what debander callable to use.
        planes: Planes to process
        ref: [limit_filter][vsrgtools.limit_filter] parameter.
            Reference clip, to compute the weight to be applied on filtering diff.
        dark_thr: [limit_filter][vsrgtools.limit_filter] parameter.
            Threshold (8-bit scale) to limit dark filtering diff.
        bright_thr: [limit_filter][vsrgtools.limit_filter] parameter.
            Threshold (8-bit scale) to limit bright filtering diff.
        elast: [limit_filter][vsrgtools.limit_filter] parameter.
            Elasticity of the soft threshold.

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

    blur = prefilter(clip, planes=planes)
    smooth = debander(blur, radius, thr, planes=planes)
    limit = limit_filter(smooth, blur, ref, dark_thr, bright_thr, elast, planes)
    merge = norm_expr([clip, blur, limit], "z x y - +", planes, func=pfdeband)

    return depth(merge, 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

    Args:
        clip: Input clip.
        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.
        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.
        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.
        planes: Which planes to process. Defaults to all planes.
        iterations: Number of debanding steps to perform per sample. More iterations yield stronger effect but quickly
            lose efficiency beyond 4.

    Returns:
        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({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