morpho ¶

@inject_self
def binarize(
    self,
    clip: vs.VideoNode,
    midthr: float | Sequence[float] | None = None,
    lowval: float | Sequence[float] | None = None,
    highval: float | Sequence[float] | None = None,
    planes: Planes = None,
) -> vs.VideoNode:
    """
    Turns every pixel in the image into either `lowval`, if it's below `midthr`, or `highval` otherwise.

    Args:
        clip: Clip to process.
        midthr: Threshold separating `lowval` and `highval`. Defaults to the midpoint of the
            format's range. Can be specified per plane.
        lowval: Value assigned to pixels below `midthr`. Defaults to the lower bound of the
            format's range. Can be specified per plane.
        highval: Value assigned to pixels greater than or equal to `midthr`. Defaults to the
            upper bound of the format's range. Can be specified per plane.
        planes: Specifies which planes to process. Unprocessed planes are copied unchanged.
    """
    midthr, lowval, highval = (
        thr and [scale_value(t, 32, clip) for t in to_arr(thr)] for thr in (midthr, lowval, highval)
    )

    return core.std.Binarize(clip, midthr, lowval, highval, planes)

@inject_self
def binarize_mask(
    self,
    clip: vs.VideoNode,
    midthr: float | Sequence[float] | None = None,
    lowval: float | Sequence[float] | None = None,
    highval: float | Sequence[float] | None = None,
    planes: Planes = None,
) -> vs.VideoNode:
    """
    Turns every pixel in the mask clip into either `lowval` if it's below `midthr`, or `highval` otherwise.

    This variant is intended for use on mask clips where all planes share the same value range.

    Args:
        clip: Mask clip to process.
        midthr: Threshold separating `lowval` and `highval`. Defaults to the midpoint of the
            format's range. Can be specified per plane.
        lowval: Value assigned to pixels below `midthr`. Defaults to the lower bound of the
            format's range for mask clips. Can be specified per plane.
        highval: Value assigned to pixels greater than or equal to `midthr`. Defaults to the
            upper bound of the format's range for mask clips. Can be specified per plane.
        planes: Specifies which planes to process. Unprocessed planes are copied unchanged.
    """
    midthr, lowval, highval = (
        thr and [scale_value(t, 32, clip) for t in to_arr(thr)] for thr in (midthr, lowval, highval)
    )

    return core.std.BinarizeMask(clip, midthr, lowval, highval, planes)

@copy_signature(bottom_hat)
@inject_self
def black_hat(self, *args: Any, **kwargs: Any) -> vs.VideoNode:
    """Alias for [bottom_hat][vsmasktools.Morpho.bottom_hat]."""
    return self.top_hat(*args, **{"func": self.black_hat} | kwargs)

@inject_self
def bottom_hat(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    A bottom hat or a black hat is the difference of the closing and the original clip.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.bottom_hat

    closed = self.closing(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return norm_expr([closed, clip], "x y -", planes, func=func)

@inject_self
def closing(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    A closing is an dilation followed by an erosion.

    Args:
        clip: Clip to process
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.closing

    dilated = self.dilation(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)
    eroded = self.erosion(dilated, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return eroded

@inject_self
def deflate(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces each pixel with the average of the (radius * 2 + 1) ** 2 - 1 pixels
    in its (radius * 2 + 1)x(radius * 2 + 1) neighbourhood, but only if that average
    is less than the center pixel.

    A radius of 1 will replace each pixel with the average of the 8 pixels in its 3x3 neighbourhood.
    A radius of 2 will replace each pixel with the average of the 24 pixels in its 5x5 neighbourhood.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    return self._xxflate(
        clip, radius, thr, iterations, coords, multiply, planes, func=func or self.deflate, inflate=False, **kwargs
    )

@inject_self
def dilation(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces each pixel with the largest value in its (radius * 2 + 1)x(radius * 2 + 1) neighbourhood.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    return self._mm_func(
        clip,
        radius,
        thr,
        iterations,
        coords,
        multiply,
        planes,
        func=func or self.dilation,
        mm_func=core.lazy.std.Maximum,
        op=ExprOp.MAX,
        **kwargs,
    )

@inject_self
def erosion(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces each pixel with the smallest value in its (radius * 2 + 1)x(radius * 2 + 1) neighbourhood.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    return self._mm_func(
        clip,
        radius,
        thr,
        iterations,
        coords,
        multiply,
        planes,
        func=func or self.erosion,
        mm_func=core.lazy.std.Minimum,
        op=ExprOp.MIN,
        **kwargs,
    )

@inject_self
def expand(
    self,
    clip: vs.VideoNode,
    sw: int,
    sh: int | None = None,
    mode: XxpandMode = XxpandMode.RECTANGLE,
    thr: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces multiple times each pixel with the largest value in its 3x3 neighbourhood.
    Specifying a mode will allow custom growing mode.

    Args:
        clip: Clip to process.
        sw: Number of horizontal iterations.
        sh: Number of vertical iterations.
        mode: Specifies the expand mode shape.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        planes: Which plane to process.
    """
    func = func or self.expand

    return self._xxpand_transform(clip, sw, sh, mode, thr, planes, op=ExprOp.MAX, func=func, **kwargs)

@inject_self
def gradient(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    A morphological gradient is the difference between a dilation and erosion.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.gradient

    if isinstance(radius, tuple):
        r, conv_mode = radius
    else:
        r, conv_mode = radius, ConvMode.SQUARE

    if iterations == 1 and conv_mode is not ConvMode.HV:
        return norm_expr(
            clip,
            "{dilated} {eroded} - {multiply}",
            planes,
            func=func,
            dilated=self._morpho_xx_imum(
                clip, (r, conv_mode), thr, coords, multiply, True, op=ExprOp.MAX, func=func
            )[0].to_str(),
            eroded=self._morpho_xx_imum(
                clip, (r, conv_mode), thr, coords, multiply, True, op=ExprOp.MIN, func=func
            )[0].to_str(),
            multiply="" if multiply is None else f"{multiply} *",
        )

    dilated = self.dilation(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)
    eroded = self.erosion(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return norm_expr([dilated, eroded], "x y -", planes, func=func)

@inject_self
def inflate(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces each pixel with the average of the (radius * 2 + 1) ** 2 - 1 pixels
    in its (radius * 2 + 1)x(radius * 2 + 1) neighbourhood, but only if that average is greater
    than the center pixel.

    A radius of 1 will replace each pixel with the average of the 8 pixels in its 3x3 neighbourhood.
    A radius of 2 will replace each pixel with the average of the 24 pixels in its 5x5 neighbourhood.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become greater
            than input + thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    return self._xxflate(
        clip, radius, thr, iterations, coords, multiply, planes, func=func or self.inflate, inflate=True, **kwargs
    )

@inject_self
def inner_hat(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    An inner hat is the difference of the original clip and the erosion.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.inner_hat

    if isinstance(radius, tuple):
        r, conv_mode = radius
    else:
        r, conv_mode = radius, ConvMode.SQUARE

    if iterations == 1 and conv_mode is not ConvMode.HV:
        return norm_expr(
            clip,
            "x {eroded} {multiply} -",
            planes,
            eroded=self._morpho_xx_imum(
                clip, (r, conv_mode), thr, coords, multiply, True, op=ExprOp.MIN, func=func
            )[0].to_str(),
            multiply="" if multiply is None else f"{multiply} *",
        )

    eroded = self.erosion(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return norm_expr([clip, eroded], "x y -", planes, func=func)

@inject_self
def inpand(
    self,
    clip: vs.VideoNode,
    sw: int,
    sh: int | None = None,
    mode: XxpandMode = XxpandMode.RECTANGLE,
    thr: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces multiple times each pixel with the smallest value in its 3x3 neighbourhood.
    Specifying a mode will allow custom growing mode.

    Args:
        clip: Clip to process.
        sw: Number of horizontal iterations.
        sh: Number of vertical iterations.
        mode: Specifies the expand mode shape.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        planes: Which plane to process.
    """
    func = func or self.expand

    return self._xxpand_transform(clip, sw, sh, mode, thr, planes, op=ExprOp.MIN, func=func, **kwargs)

@inject_self
def maximum(
    self,
    clip: vs.VideoNode,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces each pixel with the largest value in its 3x3 neighbourhood.

    This operation is also known as dilation with a radius of 1.

    Args:
        clip: Clip to process.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become greater
            than input + threshold The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the 3x3 neighbourhood are considered. If an element of this array is 0,
            the corresponding pixel is not considered when finding the maximum value. This must contain exactly 8
            numbers.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    return self.dilation(clip, 1, thr, iterations, coords, multiply, planes, func=func, **kwargs)

@inject_self
def minimum(
    self,
    clip: vs.VideoNode,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    Replaces each pixel with the smallest value in its 3x3 neighbourhood.

    This operation is also known as erosion with a radius of 1.

    Args:
        clip: Clip to process.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the 3x3 neighbourhood are considered. If an element of this array is 0,
            the corresponding pixel is not considered when finding the maximum value. This must contain exactly 8
            numbers.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    return self.erosion(clip, 1, thr, iterations, coords, multiply, planes, func=func, **kwargs)

@inject_self
def opening(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    An opening is an erosion followed by an dilation.

    Args:
        clip: Clip to process
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.opening

    eroded = self.erosion(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)
    dilated = self.dilation(eroded, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return dilated

@inject_self
def outer_hat(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    An outer hat is the difference of the dilation and the original clip.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.outer_hat

    if isinstance(radius, tuple):
        r, conv_mode = radius
    else:
        r, conv_mode = radius, ConvMode.SQUARE

    if iterations == 1 and conv_mode is not ConvMode.HV:
        return norm_expr(
            clip,
            "{dilated} {multiply} x -",
            planes,
            dilated=self._morpho_xx_imum(
                clip, (r, conv_mode), thr, coords, multiply, True, op=ExprOp.MAX, func=func
            )[0].to_str(),
            multiply="" if multiply is None else f"{multiply} *",
        )

    dilated = self.dilation(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return norm_expr([dilated, clip], "x y -", planes, func=func)

@inject_self
def top_hat(
    self,
    clip: vs.VideoNode,
    radius: RadiusLike = 1,
    thr: float | None = None,
    iterations: int = 1,
    coords: Sequence[int] | None = None,
    multiply: float | None = None,
    planes: Planes = None,
    *,
    func: FuncExcept | None = None,
    **kwargs: Any,
) -> vs.VideoNode:
    """
    A top hat or a white hat is the difference of the original clip and the opening.

    Args:
        clip: Clip to process.
        radius: A single integer specifies the size of the square matrix. A tuple of an integer and a ConvMode
            allows specification of the matrix type dimension as well.
        thr: Threshold (32-bit scale) to limit how much pixels are changed. Output pixels will not become less than
            input - thr. The default is no limit.
        iterations: Number of times to execute the function.
        coords: Specifies which pixels from the neighbourhood are considered. If an element of this array is 0, the
            corresponding pixel is not considered when finding the maximum value. This must contain exactly (radius
            * 2 + 1) ** 2 - 1 numbers eg. 8, 24, 48... When specified, this parameter takes precedence over radius.
        multiply: Optional multiplier of the final value.
        planes: Which plane to process.
    """
    func = func or self.top_hat

    opened = self.opening(clip, radius, thr, iterations, coords, multiply, planes, func=func, **kwargs)

    return norm_expr([clip, opened], "x y -", planes, func=func)

@copy_signature(top_hat)
@inject_self
def white_hate(self, *args: Any, **kwargs: Any) -> vs.VideoNode:
    """Alias for [top_hat][vsmasktools.Morpho.top_hat]."""
    return self.top_hat(*args, **{"func": self.white_hate} | kwargs)