noise ¶

def __call__(self, clip: vs.VideoNode, /, **kwargs: Any) -> vs.VideoNode | GrainerPartial:
    """To be implemented in subclasses."""
    raise NotImplementedError

def __call__(
    self,
    clip: vs.VideoNode | MissingT = MISSING,
    /,
    strength: float | Sequence[float] = 0,
    static: bool = False,
    scale: float | tuple[float, float] = 1.0,
    scaler: ScalerLike = LanczosTwoPasses,
    temporal: float | tuple[float, int] = (0.0, 0),
    post_process: Callable[[vs.VideoNode], vs.VideoNode]
    | Iterable[Callable[[vs.VideoNode], vs.VideoNode]]
    | None = None,
    protect_edges: bool | EdgeLimits = True,
    protect_neutral_chroma: bool | None = None,
    luma_scaling: float | None = None,
    planes: Planes = None,
    **kwargs: Any,
) -> vs.VideoNode | GrainerPartial:
    """
    Apply grain to a clip using the selected graining method.

    If no clip is passed, a partially applied grainer with the provided arguments is returned instead.

    Example usage:
        ```py
        # For PERLIN, SIMPLEX, and FBM_SIMPLEX, it is recommended to use `size` instead of `scale`,
        # as `size` allows for direct internal customization of each grain type.
        grained = Grainer.PERLIN(clip, (1.65, 0.65), temporal=(0.25, 2), luma_scaling=4, size=3.0, seed=333)
        ```

    Args:
        clip:
            The input clip to apply grain to. If omitted, returns a partially applied grainer.
        strength:
            Grain strength.
            A single float applies uniform strength to all planes.
            A sequence allows per-plane control.

        static:
            If True, the grain pattern is static (unchanging across frames).
        scale:
            Scaling divisor for the grain layer.
            Can be a float (uniform scaling) or a tuple (width, height scaling).
        scaler:
            Scaler used to resize the grain layer when `scale` is not 1.0.
        temporal:
            Temporal grain smoothing parameters. Either a float (weight) or a tuple of (weight, radius).
        post_process:
            One or more functions applied after grain generation (and temporal smoothing, if used).
        protect_edges:
            Protects edge regions of each plane from graining.

               - True: Use legal range based on clip format.
               - False: Disable edge protection.
               - Tuple: Specify custom edge limits per plane (see [EdgeLimits][vsdeband.noise.EdgeLimits]).

        protect_neutral_chroma:
            Whether to disable graining on neutral chroma.
        luma_scaling:
            Sensitivity of the luma-adaptive graining mask.
            Higher values reduce grain in brighter areas; negative values invert behavior.
        planes:
            Which planes to process. Default to all.
        **kwargs:
            Additional arguments to pass to the graining function or additional advanced options:

               - ``temporal_avg_func``: Temporal average function to use instead of the default standard mean.
               - ``protect_edges_blend``: Blend range (float) to soften edge protection thresholds.
               - ``protect_neutral_chroma_blend``: Blend range (float) for neutral chroma protection.
               - ``neutral_out``: (Boolean) Output the neutral layer instead of the merged clip.

    Returns:
        Grained video clip, or a [GrainerPartial][vsdeband.noise.GrainerPartial] if `clip` is not provided.
    """
    kwargs.update(
        strength=strength,
        scale=scale,
        scaler=scaler,
        temporal=temporal,
        protect_edges=protect_edges,
        post_process=post_process,
        protect_neutral_chroma=protect_neutral_chroma,
        luma_scaling=luma_scaling,
        planes=planes,
    )

    if clip is MISSING:
        return GrainerPartial(self, **kwargs)

    if self == Grainer.PLACEBO:
        assert static is False, "PlaceboGrain does not support static noise!"

        return _apply_grainer(
            clip,
            lambda clip, strength, planes, **kwds: placebo_deband(
                clip, 8, 0.0, strength, planes, iterations=1, **kwds
            ),
            **kwargs,
            func=self.name,
        )

    if not isinstance(size := kwargs.pop("size", (None, None)), tuple):
        size = (size, size)

    kwargs.update(xsize=size[0], ysize=size[1])

    def _noise_function(
        clip: vs.VideoNode, strength: float | Sequence[float], planes: Planes, **kwds: Any
    ) -> vs.VideoNode:
        strength = normalize_param_planes(clip, strength, planes, 0)

        if len(set(strength[1:])) != 1:
            raise CustomValueError("Inconsistent grain values on chroma planes.", self.name, strength[1:])

        return core.noise.Add(clip, strength[0], strength[1], type=self.value, constant=static, **kwds)

    return _apply_grainer(clip, _noise_function, **kwargs, func=self.name)

@staticmethod
def norm_brightness() -> Callable[[vs.VideoNode], vs.VideoNode]:
    """
    Normalize the brightness of the grained clip to match the original clip's average luminance.

    Designed for use in the `post_process` parameter of [Grainer()][vsdeband.Grainer.__call__].

    Returns:
        A function that takes a grained clip and returns a brightness-normalized version.
    """

    def _funtion(grained: vs.VideoNode) -> vs.VideoNode:
        for i in range(grained.format.num_planes):
            grained = core.std.PlaneStats(grained, plane=i, prop=f"PS{i}")

        if grained.format.sample_type is vs.FLOAT:
            expr = "x x.PS{plane_idx}Average -"
        else:
            expr = "x neutral range_size / x.PS{plane_idx}Average - range_size * +"

        return norm_expr(grained, expr, func=Grainer.norm_brightness)

    return _funtion

def __call__(self, clip: vs.VideoNode, /, **kwargs: Any) -> vs.VideoNode:
    """
    Apply the grainer to the given clip with optional argument overrides.

    Args:
        clip: Clip to be processed.
        **kwargs: Additional keyword arguments to override or extend the stored ones.

    Returns:
        Processed clip.
    """
    return self._grainer(clip, **self._kwargs | kwargs)

def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any,
) -> vs.VideoNode:
    assert check_variable_resolution(clip, self.__class__)

    if any(shift):
        raise CustomValueError("Shifting is unsupported.", self.__class__, shift)

    width, height = self._wh_norm(clip, width, height)

    if width / clip.width > 1.5 or height / clip.height > 1.5:
        # If the scale is too big, we need to scale it in two passes, else the window
        # will be too big and the grain will be dampened down too much
        mod = max(clip.format.subsampling_w, clip.format.subsampling_h) << 1
        clip = super().scale(
            clip, mod_x((width + clip.width) / 2, mod), mod_x((height + clip.height) / 2, mod), **kwargs
        )

    return super().scale(clip, width, height, (0, 0), **kwargs)