Reference

localmean(A, [ord=ForwardFilter,] B=3)

yields the local mean of A in a neighborhood defined by B. The result is an array similar to A. If B is not specified, the neighborhood is a hyper-rectangular sliding window of size 3 in every dimension. Otherwise, B may be specified as a Cartesian box, or as an array of booleans of same number of dimensions as A. If B is a single odd integer (as it is by default), the neighborhood is assumed to be a hyper-rectangular sliding window of size B in every dimension.

See also localmean! and localfilter!.

localmean!(dst, A, [ord=ForwardFilter,] B=3) -> dst

overwrites dst with the local mean of A in a neighborhood defined by B and returns dst.

See also localmean and localfilter!.

convolve(A, B=3)

yields the discrete convolution of array A by the kernel defined by B. The result dst is an array similar to A.

Using Sup(A) to denote the set of valid indices for array A and assuming B is an array of values, the discrete convolution of A by B writes:

T = promote_type(eltype(A), eltype(B))
for i ∈ Sup(A)
    v = zero(T)
    @inbounds for j ∈ Sup(B) ∩ (i - Sup(A))
        v += A[i-j]*B[j]
    end
    dst[i] = v
end

with T the type of the product of elements of A and B, and where Sup(B) ∩ (i - Sup(A)) denotes the subset of indices k such that k ∈ Sup(B) and i - k ∈ Sup(A) and thus for which B[k] and A[i-k] are valid.

See also convolve! and localfilter!.

convolve!(dst, A, B) -> dst

overwrites dst with the discrete convolution of A by the kernel B and returns dst.

See also convolve and localfilter!.

erode(A, [ord=ForwardFilter,] B=3) -> Amin

yields the erosion of A by the structuring element defined by B. The erosion is the array of local minima of A. The returned result Amin is similar to A (same size and type).

If B is not a kernel (that is, if B is not an array or is an instance of CartesianIndices), kernel(Dims{N},B) is called to build a kernel with N the number of dimensions of A.

If the structuring element B is equivalent to a simple hyper-rectangular sliding window (which is the case by default), the much faster van Herk-Gil-Werman algorithm is used.

An erosion is one of the most basic operations of mathematical morphology. See erode! for an in-place version of the method, dilate for retrieving the local maxima, and localextrema for performing an erosion and a dilation in a single pass.

erode!(Amin, A, [ord=ForwardFilter,] B=3) -> Amin

overwrites Amin with the erosion of the array A by the structuring element defined by B and returns Amin.

If the structuring element B is equivalent to a simple hyper-rectangular sliding window (which is the case by default), the much faster van Herk-Gil-Werman algorithm is used and the operation can be done in-place. That is, A and Amin can be the same arrays. In that case, the following syntax is allowed:

erode!(A, [ord=ForwardFilter,] B=3) -> A

See erode for an out-of-place version and for more information.

dilate(A, [ord=ForwardFilter,] B=3) -> Amax

yields the dilation of A by the structuring element defined by B. The dilation is the array of local maxima of A. The returned result Amax is similar to A (same size and type).

If B is not a kernel (that is, if B is not an array or is an instance of CartesianIndices), kernel(Dims{N},B) is called to build a kernel with N the number of dimensions of A.

If the structuring element B is equivalent to a simple hyper-rectangular sliding window (which is the case by default), the much faster van Herk-Gil-Werman algorithm is used.

A dilation is one of the most basic operations of mathematical morphology. See dilate! for an in-place version of the method, erode for retrieving the local minima, and localextrema for performing an erosion and a dilation in a single pass.

dilate!(Amax, A, [ord=ForwardFilter,] B=3) -> Amax

overwrites Amax with a dilation of the array A by the structuring element defined by B and returns Amax.

If the structuring element B is equivalent to a simple hyper-rectangular sliding window (which is the case by default), the much faster van Herk-Gil-Werman algorithm is used and the operation can be done in-place. That is, A and Amin can be the same arrays. In that case, the following syntax is allowed:

dilate!(A, [ord=ForwardFilter,] B=3) -> A

See dilate for an out-of-place version and for more information.

localextrema(A, [ord=ForwardFilter,] B=3) -> Amin, Amax

yields the results of performing an erosion and a dilation of A by the structuring element defined by B in a single pass. Calling this method is usually almost twice as fast as calling erode and dilate.

See localextrema! for an in-place version of the method, and erode or dilate for a description of these operations.

localextrema!(Amin, Amax, A, [ord=ForwardFilter,] B=3) -> Amin, Amax

overwrites Amin and Amax with, respectively, an erosion and a dilation of the array A by the structuring element defined by B in a single pass.

See localextrema for an out-of-place version for more information.

closing(A, [ord=ForwardFilter,] B=3) -> dst

yields a closing of array A by the structuring element defined by B. A closing is a dilation followed by an erosion. The result dst is an array similar to A.

See closing! for an in-place version of the method, opening for a related filter, and erode or dilate for a description of these operations.

closing!(dst, wrk, A, B=3) -> dst

overwrites dst with the result of a closing of A by the structuring element defined by B using wrk as a workspace array. The arguments dst, wrk, and A must be similar arrays, dst and A may be identical, but wrk must not be the same array as A or dst. The destination dst is returned.

See closing for a description of this kind of filter and for the meaning of the arguments.

opening(A, B=3) -> dst

yields an opening of array A by the structuring element defined by B. An opening is an erosion followed by a dilation. The result dst is an array similar to A.

See opening! for an in-place version of the method, closing for a related filter, and erode or dilate for a description of these operations.

opening!(dst, wrk, A, B=3) -> dst

overwrites dst with the result of an opening of A by the structuring element defined by B using wrk as a workspace array. The arguments dst, wrk, and A must be similar arrays, dst and A may be identical, but wrk must not be the same array as A or dst. The destination dst is returned.

See opening for a description of this kind of filter and for the meaning of the arguments.

top_hat(A, B=3 [, C]) -> dst

performs a summit detection by applying a top-hat filter to array A using the structuring element defined by B for the feature detection. Top-hat filtering is equivalent to:

dst = A .- opening(A, B)

Optional argument C specifies the structuring element for smoothing A prior to top-hat filtering. If B and C are specified as the radii of the structuring elements, then C should be smaller than B. For instance:

top_hat(bitmap, 3, 1)

may be used to detect text or lines in a bitmap image.

See bottom_hat for a related operation, LocalFilters.top_hat! for an in-place version.

LocalFilters.top_hat!(dst, wrk, A, [ord=ForwardFilter,] B=3) -> dst

overwrites dst with the result of a top-hat filter applied to A with structuring element B, and using wrk as a workspace whose contents is not preserved. The arguments A, dst, and wrk must be similar but different arrays. The destination dst is returned.

See also top_hat for more details.

bottom_hat(A, B=3 [, C]) -> dst

performs a valley detection by applying a bottom-hat filter to array A using the structuring element defined by B for the feature detection. Bottom-hat filtering is equivalent to:

dst = closing(A, B) .- A

Optional argument C specifies the structuring element for smoothing A prior to bottom-hat filtering. If B and C are specified as the radii of the structuring elements, then C should be smaller than B.

See top_hat for a related operation, LocalFilters.bottom_hat! for an in-place version.

LocalFilters.bottom_hat!(dst, wrk, A, B=3) -> dst

overwrites dst with the result of a bottom-hat filter applied to A with structuring element B and optional smoothing element C. Argument wrk is a workspace array whose contents is not preserved. The arguments A, dst, and wrk must be similar but different arrays. The destination dst is returned.

See also bottom_hat for more details.

strel(T, A)

yields a structuring element suitable for mathematical morphology operations. The result is an array whose elements have type T (which can be Bool or a floating-point type). Argument A can be a hyper-rectangular Cartesian sliding window or an array with boolean elements.

If T is a floating-point type, then the result is a so-called flat structuring element whose coefficients are zero(T) inside the shape defined by A and -T(Inf) elsewhere.

bilateralfilter([T=float(eltype(A)),] A, F, [ord=ForwardFilter,] G...=3)

yields the result of applying the bilateral filter on array A.

Argument F specifies how to smooth the differences in values. It can be:

• a function, say f, which is called as f(A[i],A[j]) to yield a nonnegative weight for i the central index and j the index in a nearby position;

• a positive real, say σ, which is assumed to be the standard deviation of a Gaussian.

Arguments G, ... specify the settings of the distance filter for smoothing differences in coordinates. There are several possibilities:

• G... = wgt an array of nonnegative weights or of booleans. The axes of wgt must have offsets so that the zero index is part of the indices of wgt.

• G... = f, w with f a function and w any kind of argument that can be used to build a window win specifying the extension of the neighborhood. The value of the distance filter will be max(f(i),0) for all Cartesian index i of win such that win[i] is true. See kernel for the different ways to specify a window.

• G... = σ or , G... = σ, w with σ a positive real assumed to be the standard deviation of a Gaussian function and w any kind of argument that can be used to build a window win specifying the extension of the neighborhood. If w is not specified, a default window of size ±3σ is assumed.

Optional argument T can be used to force the element type of the result. This argument is needed if the element type of A is not a real.

See bilateralfilter! for an in-place version of this function and see Wikipedia for a description of the bilateral filter.

bilateralfilter!(dst, A, F, [ord=ForwardFilter,] G...) -> dst

overwrites dst with the result of applying the bilateral filter on array A and returns dst.

See bilateralfilter for a description of the other arguments than dst and see Wikipedia for a description of the bilateral filter.

localfilter([T=eltype(A),] A, dims, op, [ord=ForwardFilter,]
            rngs[, wrk]) -> dst

yields the result of applying van Herk-Gil-Werman algorithm to filter array A along dimension(s) dims with (associative) binary operation op and contiguous structuring element(s) defined by the interval(s) rngs. Optional argument wrk is a workspace array with elements of type T which is automatically allocated if not provided; otherwise, it must be a vector with the same element type as A and it is resized as needed (by calling the resize! method). The optional argument T allows to specify another type of element than eltype(A) for the result.

Argument dims specifies along which dimension(s) of A the filter is to be applied, it can be a single integer, a tuple of integers, or a colon : to apply the operation to all dimensions. Dimensions are processed in the order given by dims (the same dimension may appear several times) and there must be a matching interval in rngs to specify the structuring element (except that if rngs is a single interval, it is used for every dimension in dims). An interval is either an integer or an integer valued unit range in the form kmin:kmax. An interval specified as a single integer yields an approximately centered range og this length.

Assuming a mono-dimensional array A, the single filtering pass:

dst = localfilter(A, :, op, rng)

amounts to computing (assuming forward ordering):

dst[j] =  A[i+kmin] ⋄ A[i+kmin+1] ⋄ ... ⋄ A[i+kmax-1] ⋄ A[i+kmax]

for all j ∈ axes(dst,1), with x ⋄ y = op(x, y), kmin = first(rng) and kmax = last(rng). Note that if kmin = kmax = k, the result of the filter is to operate a simple shift by k along the corresponding dimension and has no effects if k = 0. This can be exploited to not filter some dimension(s).

Flat boundary conditions are assumed for A[i+k] in the above formula.

Examples

The morphological erosion (local minimum) of the array A on a centered structuring element of width 7 in every dimension can be obtained by:

localfilter(A, :, min, -3:3)

Index interval 0:0 may be specified to do nothing along the corresponding dimension. For instance, assuming A is a three-dimensional array:

localfilter(A, :, max, (-3:3, 0:0, -4:4))

yields the morphological dilation (i.e. local maximum) of A in a centered local neighborhood of size 7×1×9 (nothing is done along the second dimension). The same result may be obtained with:

localfilter(A, (1,3), max, (-3:3, -4:4))

where the second dimension is omitted from the list of dimensions.

The local average of the two-dimensional array A on a centered moving window of size 11×11 can be computed as:

localfilter(A, :, +, (-5:5, -5:5))*(1/11)

See localfilter! for an in-place version of the method.

localfilter!([dst = A,] A, dims, op, [ord=ForwardFilter,] rngs[, wrk])

overwrites the contents of dst with the result of applying van Herk-Gil-Werman algorithm to filter array A along dimension(s) dims with (associative) binary operation op and contiguous structuring element(s) defined by the interval(s) rngs and using optional argument wrk as a workspace array. The destination dst must have the same indices as the source A (that is, axes(dst) == axes(A)). Operation may be done in-place and dst and A can be the same; this is the default behavior if dst is not specified.

See localfilter for a full description of the method.

The in-place morphological erosion (local minimum) of the array A on a centered structuring element of width 7 in every dimension can be obtained by:

localfilter!(A, :, min, -3:3)

localfilter!(dst, A, [ord = ForwardFilter,] B, initial, update,
             final = identity) -> dst

overwrites the destination dst with the result of a local filter applied to the source A, on a relative neighborhood defined by B, and implemented by initial, update, and final. The purpose of these latter arguments is explained by the following pseudo-codes implementing the local filtering. If ord = ForwardFilter:

@inbounds for i ∈ indices(dst)
    v = initial
    for j ∈ indices(A) ∩ (indices(B) + i)
        v = update(v, A[j], B[j-i])
    end
    dst[i] = final(v)
end

else if ord = ReverseFilter:

@inbounds for i ∈ indices(dst)
    v = initial
    for j ∈ indices(A) ∩ (i - indices(B))
        v = update(v, A[j], B[i-j])
    end
    dst[i] = final(v)
end

where indices(A) denotes the range of indices of any array A while indices(B) + i and i - indices(B) respectively denote the set of indices j such that j - i ∈ indices(B) and i - j ∈ indices(B). In other words, j ∈ indices(A) ∩ (i - indices(B)) means all indices j such that j ∈ indices(A) and i - j ∈ indices(B) so that A[j] and B[i-j] are in-bounds.

For example, implementing a local minimum filter (that is, an erosion), is as simple as:

localfilter!(dst, A, ord, B, typemax(eltype(a)),
             (v,a,b) -> ifelse(b, min(v,a), v))

As another example, implementing a convolution by B writes:

T = promote_type(eltype(A), eltype(B))
localfilter!(dst, A, ord, B, zero(T), (v,a,b) -> v + a*b)

LocalFilters.ball(Dims{N}, r)

yields a boolean mask which is a N-dimensional array with all dimensions odd and equal and set to true where position is inside a N-dimensional ball of radius r.

To have a mask with centered index ranges, call:

LocalFilters.centered(LocalFilters.ball(Dims{N}, r))