imfilter([T], img, kernel, [border="replicate"], [alg]) --> imgfilt
imfilter([r], img, kernel, [border="replicate"], [alg]) --> imgfilt
imfilter(r, T, img, kernel, [border="replicate"], [alg]) --> imgfilt

Filter an array img with kernel kernel by computing their correlation.

kernel[0,0,..] corresponds to the origin (zero displacement) of the kernel; you can use centered to place the origin at the array center, or use the OffsetArrays package to set kernel's indices manually. For example, to filter with a random centered 3x3 kernel, you could use either of the following:

kernel = centered(rand(3,3))
kernel = OffsetArray(rand(3,3), -1:1, -1:1)

kernel can be specified as an array or as a "factored kernel," a tuple (filt1, filt2, ...) of filters to apply along each axis of the image. In cases where you know your kernel is separable, this format can speed processing. Each of these should have the same dimensionality as the image itself, and be shaped in a manner that indicates the filtering axis, e.g., a 3x1 filter for filtering the first dimension and a 1x3 filter for filtering the second dimension. In two dimensions, any kernel passed as a single matrix is checked for separability; if you want to eliminate that check, pass the kernel as a single-element tuple, (kernel,).

Optionally specify the border, as one of Fill(value), "replicate", "circular", "symmetric", "reflect", NA(), or Inner(). The default is "replicate". These choices specify the boundary conditions, and therefore affect the result at the edges of the image. See padarray for more information.

alg allows you to choose the particular algorithm: FIR() (finite impulse response, aka traditional digital filtering) or FFT() (Fourier-based filtering). If no choice is specified, one will be chosen based on the size of the image and kernel in a way that strives to deliver good performance. Alternatively you can use a custom filter type, like IIRGaussian.

Optionally, you can control the element type of the output image by passing in a type T as the first argument.

You can also dispatch to different implementations by passing in a resource r as defined by the ComputationalResources package. For example,

imfilter(ArrayFire(), img, kernel)

would request that the computation be performed on the GPU using the ArrayFire libraries.

See also: imfilter!, centered, padarray, Pad, Fill, Inner, IIRGaussian.

imfilter!(imgfilt, img, kernel, [border="replicate"], [alg])
imfilter!(r, imgfilt, img, kernel, border, [inds])
imfilter!(r, imgfilt, img, kernel, border::NoPad, [inds=indices(imgfilt)])

Filter an array img with kernel kernel by computing their correlation, storing the result in imgfilt.

The indices of imgfilt determine the region over which the filtered image is computed–-you can use this fact to select just a specific region of interest, although be aware that the input img might still get padded. Alteratively, explicitly provide the indices inds of imgfilt that you want to calculate, and use NoPad boundary conditions. In such cases, you are responsible for supplying appropriate padding: img must be indexable for all of the locations needed for calculating the output. This syntax is best-supported for FIR filtering; in particular, that that IIR filtering can lead to results that are inconsistent with respect to filtering the entire array.

See also: imfilter.

imgradients(img, [points], [method], [border])

Performs edge detection filtering in the N-dimensional array img. Gradients are computed at specified points (or indexes) in the array or everywhere.

Available methods for 2D images: "sobel", "prewitt", "ando3", "ando4", "ando5", "ando4_sep", "ando5_sep".

Available methods for ND images: "sobel", "prewitt", "ando3", "ando4".

Border options:"replicate", "circular", "reflect", "symmetric".

If points is specified, returns a 2D array G with the gradients as rows. The number of rows is the number of points at which the gradient was computed and the number of columns is the dimensionality of the array.

If points is ommitted, returns a tuple of arrays, each of the same size of the input image: (gradx, grady, ...)

extrema_filter(A, window) --> Array{(min,max)}

Calculate the running min/max over a window of width window[d] along dimension d, centered on the current point. The returned array has the same indices as the input A.

diff1, diff2 = sobel()

Return kernels for two-dimensional gradient compution using the Sobel operator. diff1 computes the gradient along the first (y) dimension, and diff2 computes the gradient along the second (x) dimension.

See also: KernelFactors.sobel, Kernel.prewitt, Kernel.ando.

diff1, diff2 = prewitt()

Return kernels for two-dimensional gradient compution using the Prewitt operator. diff1 computes the gradient along the first (y) dimension, and diff2 computes the gradient along the second (x) dimension.

See also: KernelFactors.prewitt, Kernel.sobel, Kernel.ando.

diff1, diff2 = ando3()

Return 3x3 kernels for two-dimensional gradient compution using the optimal "Ando" filters. diff1 computes the gradient along the y-axis (first dimension), and diff2 computes the gradient along the x-axis (second dimension).

Citation

Ando Shigeru, IEEE Trans. Pat. Anal. Mach. Int., vol. 22 no 3, March 2000

See also: KernelFactors.ando3, Kernel.ando4, Kernel.ando5.

diff1, diff2 = ando4()

Return 4x4 kernels for two-dimensional gradient compution using the optimal "Ando" filters. diff1 computes the gradient along the y-axis (first dimension), and diff2 computes the gradient along the x-axis (second dimension).

Citation

Ando Shigeru, IEEE Trans. Pat. Anal. Mach. Int., vol. 22 no 3, March 2000

See also: KernelFactors.ando4, Kernel.ando3, Kernel.ando5.

diff1, diff2 = ando5()

Return 5x5 kernels for two-dimensional gradient compution using the optimal "Ando" filters. diff1 computes the gradient along the y-axis (first dimension), and diff2 computes the gradient along the x-axis (second dimension).

Citation

Ando Shigeru, IEEE Trans. Pat. Anal. Mach. Int., vol. 22 no 3, March 2000

See also: KernelFactors.ando5, Kernel.ando3, Kernel.ando4.

gaussian((σ1, σ2, ...), [(l1, l2, ...]) -> g
gaussian(σ)                  -> g

Construct a multidimensional gaussian filter, with standard deviation σd along dimension d. Optionally provide the kernel length l, which must be a tuple of the same length.

If σ is supplied as a single number, a symmetric 2d kernel is constructed.

See also: KernelFactors.gaussian.

DoG((σp1, σp2, ...), (σm1, σm2, ...), [l1, l2, ...]) -> k
DoG((σ1, σ2, ...))                                   -> k
DoG(σ::Real)                                         -> k

Construct a multidimensional difference-of-gaussian kernel k, equal to gaussian(σp, l)-gaussian(σm, l). When only a single σ is supplied, the default is to choose σp = σ, σm = √2 σ. Optionally provide the kernel length l; the default is to extend by two max(σp,σm) in each direction from the center. l must be odd.

If σ is provided as a single number, a symmetric 2d DoG kernel is returned.

See also: KernelFactors.IIRGaussian.

LoG((σ1, σ2, ...)) -> k
LoG(σ)             -> k

Construct a Laplacian-of-Gaussian kernel k. σd is the gaussian width along dimension d. If σ is supplied as a single number, a symmetric 2d kernel is returned.

See also: KernelFactors.IIRGaussian and Kernel.Laplacian.

Laplacian((true,true,false,...))
Laplacian(dims, N)
Lacplacian()

Laplacian kernel in N dimensions, taking derivatives along the directions marked as true in the supplied tuple. Alternatively, one can pass dims, a listing of the dimensions for differentiation. (However, this variant is not inferrable.)

Laplacian() is the 2d laplacian, equivalent to Laplacian((true,true)).

The kernel is represented as an opaque type, but you can use convert(AbstractArray, L) to convert it into array format.

kern1, kern2 = sobel()

Factored Sobel filters for dimensions 1 and 2 of a two-dimensional image. Each is a 2-tuple of one-dimensional filters.

kern = sobel(extended::NTuple{N,Bool}, d)

Return a factored Sobel filter for computing the gradient in N dimensions along axis d. If extended[dim] is false, kern will have size 1 along that dimension.

kern1, kern2 = prewitt() returns factored Prewitt filters for dimensions 1 and 2 of your image

kern = prewitt(extended::NTuple{N,Bool}, d)

Return a factored Prewitt filter for computing the gradient in N dimensions along axis d. If extended[dim] is false, kern will have size 1 along that dimension.

kern1, kern2 = ando3() returns optimal 3x3 gradient filters for dimensions 1 and 2 of your image, as defined in Ando Shigeru, IEEE Trans. Pat. Anal. Mach. Int., vol. 22 no 3, March 2000.

See also: ando4, ando5.

kern = ando3(extended::NTuple{N,Bool}, d)

Return a factored Ando filter (size 3) for computing the gradient in N dimensions along axis d. If extended[dim] is false, kern will have size 1 along that dimension.

kern1, kern2 = ando4() returns separable approximations of the optimal 4x4 filters for dimensions 1 and 2 of your image, as defined in Ando Shigeru, IEEE Trans. Pat. Anal. Mach. Int., vol. 22 no 3, March 2000.

See also: Kernel.ando4.

kern = ando4(extended::NTuple{N,Bool}, d)

Return a factored Ando filter (size 4) for computing the gradient in N dimensions along axis d. If extended[dim] is false, kern will have size 1 along that dimension.

kern1, kern2 = ando5_sep() returns separable approximations of the optimal 5x5 gradient filters for dimensions 1 and 2 of your image, as defined in Ando Shigeru, IEEE Trans. Pat. Anal. Mach. Int., vol. 22 no 3, March 2000.

See also: Kernel.ando5.

kern = ando5(extended::NTuple{N,Bool}, d)

Return a factored Ando filter (size 5) for computing the gradient in N dimensions along axis d. If extended[dim] is false, kern will have size 1 along that dimension.

gaussian(σ::Real, [l]) -> g

Construct a 1d gaussian kernel g with standard deviation σ, optionally providing the kernel length l. The default is to extend by two σ in each direction from the center. l must be odd.

gaussian((σ1, σ2, ...), [l]) -> (g1, g2, ...)

Construct a multidimensional gaussian filter as a product of single-dimension factors, with standard deviation σd along dimension d. Optionally provide the kernel length l, which must be a tuple of the same length.

IIRGaussian([T], σ; emit_warning::Bool=true)

Construct an infinite impulse response (IIR) approximation to a Gaussian of standard deviation σ. σ may either be a single real number or a tuple of numbers; in the latter case, a tuple of such filters will be created, each for filtering a different dimension of an array.

Optionally specify the type T for the filter coefficients; if not supplied, it will match σ (unless σ is not floating-point, in which case Float64 will be chosen).

Citation

I. T. Young, L. J. van Vliet, and M. van Ginkel, "Recursive Gabor Filtering". IEEE Trans. Sig. Proc., 50: 2798-2805 (2002).

TriggsSdika(a, b, scale, M)

Defines a kernel for one-dimensional infinite impulse response (IIR) filtering. a is a "forward" filter, b a "backward" filter, M is a matrix for matching boundary conditions at the right edge, and scale is a constant scaling applied to each element at the conclusion of filtering.

Citation

B. Triggs and M. Sdika, "Boundary conditions for Young-van Vliet recursive filtering". IEEE Trans. on Sig. Proc. 54: 2365-2367 (2006).

TriggsSdika(ab, scale)

Create a symmetric Triggs-Sdika filter (with a = b = ab). M is calculated for you. Only length 3 filters are currently supported.

centered(kernel) -> shiftedkernel

Shift the origin-of-coordinates to the center of kernel. The center-element of kernel will be accessed by shiftedkernel[0, 0, ...].

This function makes it easy to supply kernels using regular Arrays, and provides compatibility with other languages that do not support arbitrary indices.

See also: imfilter.

kernelfactors(factors::Tuple)

Prepare a factored kernel for filtering. If passed a 2-tuple of vectors of lengths m and n, this will return a 2-tuple of ReshapedVectors that are effectively of sizes m×1 and 1×n. In general, each successive factor will be reshaped to extend along the corresponding dimension.

If passed a tuple of general arrays, it is assumed that each is shaped appropriately along its "leading" dimensions; the dimensionality of each is "extended" to N = length(factors), appending 1s to the size as needed.

reflect(kernel) --> reflectedkernel

Compute the pointwise reflection around 0, 0, ... of the kernel kernel. Using imfilter with a reflectedkernel performs convolution, rather than correlation, with respect to the original kernel.

padarray([T], img, border) --> imgpadded

Generate a padded image from an array img and a specification border of the boundary conditions and amount of padding to add. border can be a Pad, Fill, or Inner object.

Optionally provide the element type T of imgpadded.

Pad is a type that stores choices about padding. Instances must set style, a Symbol specifying the boundary conditions of the image, one of:

• :replicate (repeat edge values to infinity)

• :circular (image edges "wrap around")

• :symmetric (the image reflects relative to a position between pixels)

• :reflect (the image reflects relative to the edge itself)

The default value is :replicate.

It's worth emphasizing that padding is most straightforwardly specified as a string,

imfilter(img, kernel, "replicate")

rather than

imfilter(img, kernel, Pad(:replicate))

Fill(val)
Fill(val, lo, hi)

Pad the edges of the image with a constant value, val.

Optionally supply the extent of the padding, see Pad.

Example:

imfilter(img, kernel, Fill(zero(eltype(img))))

Inner()
Inner(lo, hi)

Indicate that edges are to be discarded in filtering, only the interior of the result it to be returned.

Example:

imfilter(img, kernel, Inner())

NA()
NA(lo, hi)

Choose filtering using "NA" (Not Available) boundary conditions. This is most appropriate for filters that have only positive weights, such as blurring filters. Effectively, the output pixel value is normalized in the following way:

          filtered img with Fill(0) boundary conditions
output =  ---------------------------------------------
          filtered 1   with Fill(0) boundary conditions

As a consequence, filtering has the same behavior as nanmean. Indeed, invalid pixels in img can be marked as NaN and then they are effectively omitted from the filtered result.

NoPad()
NoPad(border)

Indicates that no padding should be applied to the input array, or that you have already pre-padded the input image. Passing a border object allows you to preserve "memory" of a border choice; it can be retrieved by indexing with [].

Example

np = NoPad(Pad(:replicate))
imfilter!(out, img, kernel, np)

runs filtering directly, skipping any padding steps. Every entry of out must be computable using in-bounds operations on img and kernel.

Filter using a direct algorithm

Filter using the Fast Fourier Transform

Filter with an Infinite Impulse Response filter

Filter with a cascade of mixed types (IIR, FIR)

ReshapedOneD{N,Npre}(data)

Return an object of dimensionality N, where data must have dimensionality 1. The indices are 0:0 for the first Npre dimensions, have the indices of data for dimension Npre+1, and are 0:0 for the remaining dimensions.

data must support eltype and ndims, but does not have to be an AbstractArray.

ReshapedOneDs allow one to specify a "filtering dimension" for a 1-dimensional filter.