Summary and function reference

Below, [] in an argument list means an optional argument.

Summary and function reference

Image loading and saving
Image construction, conversion, and views
Traits
Element transformation and intensity scaling
Storage-type transformation
Color channels
Color conversion
Image algorithms
Image metadata utilities
Image segmentation
ImageFeatures

Image loading and saving

FileIO.jl is an IO frontend that provides save and load to load images easily. The current available backends for image files are:

ImageMagick.jl covers most image formats and has extra functionality. This can be your first choice if you don't have a preference.
QuartzImageIO.jl exposes macOS's native image IO functionality to Julia. In some cases it's faster than ImageMagick, but it might not cover all your needs.
ImageIO.jl is a new image IO backend (requires julia >=v"1.3") that provides an optimized performance for PNG files. Check benchmark here
OMETIFF.jl supports OME-TIFF files. If you don't know what it is, then it is likely that you don't need this package.

Standard test images are provided by TestImages.jl

FileIO.load — Function

load(filename) loads the contents of a formatted file, trying to infer the format from filename and/or magic bytes in the file (see query).
load(strm) loads from an IOStream or similar object. In this case, there is no filename extension, so we rely on the magic bytes for format identification.
load(File{format"PNG"}(filename)) specifies the format directly, and bypasses the format query.
load(Stream{format"PNG"}(io)) specifies the format directly, and bypasses the format query.
load(f; options...) passes keyword arguments on to the loader.

FileIO.save — Function

save(filename, data...) saves the contents of a formatted file, trying to infer the format from filename.
save(Stream{format"PNG"}(io), data...) specifies the format directly, and bypasses the format query.
save(File{format"PNG"}(filename), data...) specifies the format directly, and bypasses the format query.
save(f, data...; options...) passes keyword arguments on to the saver.

TestImages.testimage — Function

img = testimage(filename; download_only=false, [ops...])

Load test image that partially matches filename, the first match is used if there're more than one.

If download_only=true, the full filepath is returned. Any other keyword arguments ops will be passed to image IO backend through FileIO.load.

Example

julia> using TestImages
julia> img = testimage("cameraman.tif"); # fullname
julia> img = testimage("cameraman"); # without extension works
julia> img = testimage("c"); # with only partial name also works

Extended help

The following is a complete list of testimages, you can also check them at https://testimages.juliaimages.org/

"airplaneF16"
"autumn_leaves"
"barbara_color"
"barbara_gray_512"
"blobs"
"cameraman"
"chelsea"
"coffee"
"earth_apollo17"
"fabio_color_256"
"fabio_color_512"
"fabio_gray_256"
"fabio_gray_512"
"hela-cells"
"house"
"jetplane"
"lake_color"
"lake_gray"
"lena_color_256"
"lena_color_512"
"lena_gray_16bit"
"lena_gray_256"
"lena_gray_512"
"lighthouse"
"livingroom"
"m51"
"mandril_color"
"mandril_gray"
"mandrill"
"monarch_color"
"monarch_color_256"
"moonsurface"
"morphology_test_512"
"mountainstream"
"mri-stack"
"multi-channel-time-series.ome"
"peppers_color"
"peppers_gray"
"pirate"
"resolution_test_1920"
"resolution_test_512"
"simple_3d_ball"
"simple_3d_psf"
"sudoku"
"toucan"
"walkbridge"
"woman_blonde"
"woman_darkhair"

Images.shepp_logan — Function

phantom = shepp_logan(N,[M]; highContrast=true)

output the NxM Shepp-Logan phantom, which is a standard test image usually used for comparing image reconstruction algorithms in the field of computed tomography (CT) and magnetic resonance imaging (MRI). If the argument M is omitted, the phantom is of size NxN. When setting the keyword argument highConstrast to false, the CT version of the phantom is created. Otherwise, the high contrast MRI version is calculated.

Image construction, conversion, and views

Any array can be treated as an Image. In graphical environments, only arrays with Colorant element types (Gray, RGB, ARGB, etc.) are automatically displayed as images.

ImageCore.colorview — Function

colorview(C, A)

returns a view of the numeric array A, interpreting successive elements of A as if they were channels of Colorant C.

Of relevance for types like RGB and BGR, the elements of A are interpreted in constructor-argument order, not memory order (see reinterpretc if you want to use memory order).

Example

A = rand(3, 10, 10)
img = colorview(RGB, A)

Traits

These functions are the preferred way to access certain types of "internal" data about an image. They can sometimes be useful in allowing you to write generic code.

ImageCore.pixelspacing — Function

pixelspacing(img) -> (sx, sy, ...)

Return a tuple representing the separation between adjacent pixels along each axis of the image. Defaults to (1,1,...). Use ImagesAxes for images with anisotropic spacing or to encode the spacing using physical units.

ImageCore.spacedirections — Function

spacedirections(img) -> (axis1, axis2, ...)

Return a tuple-of-tuples, each axis[i] representing the displacement vector between adjacent pixels along spatial axis i of the image array, relative to some external coordinate system ("physical coordinates").

By default this is computed from pixelspacing, but you can set this manually using ImagesMeta.

spacedirections(img)

Using ImageMetadata, you can set this property manually. For example, you could indicate that a photograph was taken with the camera tilted 30-degree relative to vertical using

img["spacedirections"] = ((0.866025,-0.5),(0.5,0.866025))

If not specified, it will be computed from pixelspacing(img), placing the spacing along the "diagonal". If desired, you can set this property in terms of physical units, and each axis can have distinct units.

ImageCore.sdims — Function

sdims(img)

Return the number of spatial dimensions in the image. Defaults to the same as ndims, but with ImagesAxes you can specify that some axes correspond to other quantities (e.g., time) and thus not included by sdims.

ImageCore.coords_spatial — Function

coords_spatial(img)

Return a tuple listing the spatial dimensions of img.

Note that a better strategy may be to use ImagesAxes and take slices along the time axis.

ImageCore.size_spatial — Function

size_spatial(img)

Return a tuple listing the sizes of the spatial dimensions of the image. Defaults to the same as size, but using ImagesAxes you can mark some axes as being non-spatial.

ImageCore.indices_spatial — Function

indices_spatial(img)

Return a tuple with the indices of the spatial dimensions of the image. Defaults to the same as indices, but using ImagesAxes you can mark some axes as being non-spatial.

ImageCore.nimages — Function

nimages(img)

Return the number of time-points in the image array. Defaults to

Use ImagesAxes if you want to use an explicit time dimension.

ImageAxes.timeaxis — Function

timeaxis(A)

Return the time axis, if present, of the array A, and nothing otherwise.

ImageAxes.istimeaxis — Function

istimeaxis(ax)

Test whether the axis ax corresponds to time.

ImageAxes.timedim — Function

timedim(img) -> d::Int

Return the dimension of the array used for encoding time, or 0 if not using an axis for this purpose.

Note: if you want to recover information about the time axis, it is generally better to use timeaxis.

ImageCore.assert_timedim_last — Function

assert_timedim_last(img)

Throw an error if the image has a time dimension that is not the last dimension.

ImageAxes.StreamIndexStyle — Type

style = StreamIndexStyle(A)

A trait that indicates the degree of support for indexing the streaming axes of A. Choices are IndexAny() and IndexIncremental() (for arrays that only permit advancing the time axis, e.g., a video stream from a webcam). The default value is IndexAny().

This should be specialized for the type rather than the instance. For a StreamingContainer S, you can define this trait via

StreamIndexStyle(::Type{P}, ::typeof(f!)) = IndexIncremental()

where P = typeof(parent(S)).

ImageAxes.IndexAny — Type

IndexAny()

Indicates that an axis supports full random-access indexing.

ImageAxes.IndexIncremental — Type

IndexIncremental()

Indicates that an axis supports only incremental indexing, i.e., from i to i+1. This is commonly used for the temporal axis with media streams.

Element transformation and intensity scaling

ImageCore.clamp01 — Function

clamp01(x) -> y

Produce a value y that lies between 0 and 1, and equal to x when x is already in this range. Equivalent to clamp(x, 0, 1) for numeric values. For colors, this function is applied to each color channel separately.

Storage-type transformation

ImageCore.float32 — Function

float32.(img)

converts the raw storage type of img to Float32, without changing the color space.

ImageCore.float64 — Function

float64.(img)

converts the raw storage type of img to Float64, without changing the color space.

ImageCore.n0f8 — Function

n0f8.(img)

converts the raw storage type of img to N0f8, without changing the color space.

ImageCore.n6f10 — Function

n6f10.(img)

converts the raw storage type of img to N6f10, without changing the color space.

ImageCore.n4f12 — Function

n4f12.(img)

converts the raw storage type of img to N4f12, without changing the color space.

ImageCore.n2f14 — Function

n2f14.(img)

converts the raw storage type of img to N2f14, without changing the color space.

ImageCore.n0f16 — Function

n0f16.(img)

converts the raw storage type of img to N0f16, without changing the color space.

Color channels

You can extract the numeric value of particular color channels:

ColorTypes.gray — Function

gray(c) returns the gray component of a grayscale opaque or transparent color.

ColorTypes.red — Function

red(c) returns the red component of an AbstractRGB opaque or transparent color.

ColorTypes.green — Function

green(c) returns the green component of an AbstractRGB opaque or transparent color.

ColorTypes.blue — Function

blue(c) returns the blue component of an AbstractRGB opaque or transparent color.

ColorTypes.alpha — Function

alpha(p) extracts the alpha component of a color. For a color without an alpha channel, it will always return 1.

You can also perform operations on channels:

ColorTypes.mapc — Function

mapc(f, rgb) -> rgbf
mapc(f, rgb1, rgb2) -> rgbf

mapc applies the function f to each color channel of the input color(s), returning an output color in the same colorspace.

Examples:

julia> mapc(x->clamp(x,0,1), RGB(-0.2,0.3,1.2))
RGB{Float64}(0.0,0.3,1.0)

julia> mapc(max, RGB(0.1,0.8,0.3), RGB(0.5,0.5,0.5))
RGB{Float64}(0.5,0.8,0.5)

julia> mapc(+, RGB(0.1,0.8,0.3), RGB(0.5,0.5,0.5))
RGB{Float64}(0.6,1.3,0.8)

ColorTypes.reducec — Function

reducec(op, v0, c)

Reduce across color channels of c with the binary operator op. v0 is the neutral element used to initiate the reduction. For grayscale,

reducec(op, v0, c::Gray) = op(v0, comp1(c))

whereas for RGB

reducec(op, v0, c::RGB) = op(comp3(c), op(comp2(c), op(v0, comp1(c))))

If c has an alpha channel, it is always the last one to be folded into the reduction.

ColorTypes.mapreducec — Function

mapreducec(f, op, v0, c)

Reduce across color channels of c with the binary operator op, first applying f to each channel. v0 is the neutral element used to initiate the reduction. For grayscale,

mapreducec(f, op, v0, c::Gray) = op(v0, f(comp1(c)))

whereas for RGB

mapreducec(f, op, v0, c::RGB) = op(f(comp3(c)), op(f(comp2(c)), op(v0, f(comp1(c)))))

If c has an alpha channel, it is always the last one to be folded into the reduction.

Color conversion

imgg = Gray.(img)

calculates a grayscale representation of a color image using the Rec 601 luma.

imghsv = HSV.(img)

converts to an HSV representation of color information.

The ColorTypes package has a rich set of traits that allow you to perform generic operations on color types, see its README for more information.

Image algorithms

Linear filtering

ImageFiltering.imfilter — Function

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 a one, two or multidimensional array img with a kernel by computing their correlation.

Details

The term filtering emerges in the context of a Fourier transformation of an image, which maps an image from its canonical spatial domain to its concomitant frequency domain. Manipulating an image in the frequency domain amounts to retaining or discarding particular frequency components—a process analogous to sifting or filtering [1]. Because the Fourier transform establishes a link between the spatial and frequency representation of an image, one can interpret various image manipulations in the spatial domain as filtering operations which accept or reject specific frequencies.

The phrase spatial filtering is often used to emphasise that an operation is, at least conceptually, devised in the context of the spatial domain of an image. One further distinguishes between linear and non-linear spatial filtering. A filter is called linear if the operation performed on the pixels is linear, and is labeled non-linear otherwise.

An image filter can be represented by a function

\[ w: \{s\in \mathbb{Z} \mid -k_1 \le s \le k_1 \} \times \{t \in \mathbb{Z} \mid -k_2 \le t \le k_2 \} \rightarrow \mathbb{R},\]

where $k_i \in \mathbb{N}$ (i = 1,2). It is common to define $k_1 = 2a+1$ and $k_2 = 2b + 1$, where $a$ and $b$ are integers, which ensures that the filter dimensions are of odd size. Typically, $k_1$ equals $k_2$ and so, dropping the subscripts, one speaks of a $k \times k$ filter. Since the domain of the filter represents a grid of spatial coordinates, the filter is often called a mask and is visualized as a grid. For example, a $3 \times 3$ mask can be potrayed as follows:

\[\scriptsize \begin{matrix} \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(-1,-1) \\ \phantom{w(-9,-9)} \\ \end{matrix} } & \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(-1,0) \\ \phantom{w(-9,-9)} \\ \end{matrix} } & \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(-1,1) \\ \phantom{w(-9,-9)} \\ \end{matrix} } \\ \\ \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(0,-1) \\ \phantom{w(-9,-9)} \\ \end{matrix} } & \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(0,0) \\ \phantom{w(-9,-9)} \\ \end{matrix} } & \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(0,1) \\ \phantom{w(-9,-9)} \\ \end{matrix} } \\ \\ \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(1,-1) \\ \phantom{w(-9,-9)} \\ \end{matrix} } & \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(1,0) \\ \phantom{w(-9,-9)} \\ \end{matrix} } & \boxed{ \begin{matrix} \phantom{w(-9,-9)} \\ w(1,1) \\ \phantom{w(-9,-9)} \\ \end{matrix} } \end{matrix}.\]

The values of $w(s,t)$ are referred to as filter coefficients.

Discrete convolution versus correlation

There are two fundamental and closely related operations that one regularly performs on an image with a filter. The operations are called discrete correlation and convolution.

The correlation operation, denoted by the symbol $\star$, is given in two dimensions by the expression

\[\begin{aligned} g(x,y) = w(x,y) \star f(x,y) = \sum_{s = -a}^{a} \sum_{t=-b}^{b} w(s,t) f(x+s, y+t), \end{aligned}\]

whereas the comparable convolution operation, denoted by the symbol $\ast$, is given in two dimensions by

\[\begin{aligned} h(x,y) = w(x,y) \ast f(x,y) = \sum_{s = -a}^{a} \sum_{t=-b}^{b} w(s,t) f(x-s, y-t). \end{aligned}\]

Since a digital image is of finite extent, both of these operations are undefined at the borders of the image. In particular, for an image of size $M \times N$, the function $f(x \pm s, y \pm t)$ is only defined for $1 \le x \pm s \le N$ and $1 \le y \pm t \le M$. In practice one addresses this problem by artificially expanding the domain of the image. For example, one can pad the image with zeros. Other padding strategies are possible, and they are discussed in more detail in the Options section of this documentation.

One-dimensional illustration

The difference between correlation and convolution is best understood with recourse to a one-dimensional example adapted from [1]. Suppose that a filter $w:\{-1,0,1\}\rightarrow \mathbb{R}$ has coefficients

\[\begin{matrix} \boxed{1} & \boxed{2} & \boxed{3} \end{matrix}.\]

Consider a discrete unit impulse function $f: \{x \in \mathbb{Z} \mid 1 \le x \le 7 \} \rightarrow \{0,1\}$ that has been padded with zeros. The function can be visualised as an image

\[\boxed{ \begin{matrix} 0 & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{1} & \boxed{0} & \boxed{0} & \boxed{0} & 0 \end{matrix}}.\]

The correlation operation can be interpreted as sliding $w$ along the image and computing the sum of products at each location. For example,

\[\begin{matrix} 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 1 & 2 & 3 & & & & & & \\ & 1 & 2 & 3 & & & & & \\ & & 1 & 2 & 3 & & & & \\ & & & 1 & 2 & 3 & & & \\ & & & & 1 & 2 & 3 & & \\ & & & & & 1 & 2 & 3 & \\ & & & & & & 1 & 2 & 3, \end{matrix}\]

yields the output $g: \{x \in \mathbb{Z} \mid 1 \le x \le 7 \} \rightarrow \mathbb{R}$, which when visualized as a digital image, is equal to

\[\boxed{ \begin{matrix} \boxed{0} & \boxed{0} & \boxed{3} & \boxed{2} & \boxed{1} & \boxed{0} & \boxed{0} \end{matrix}}.\]

The interpretation of the convolution operation is analogous to correlation, except that the filter $w$ has been rotated by 180 degrees. In particular,

\[\begin{matrix} 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 3 & 2 & 1 & & & & & & \\ & 3 & 2 & 1 & & & & & \\ & & 3 & 2 & 1 & & & & \\ & & & 3 & 2 & 1 & & & \\ & & & & 3 & 2 & 1 & & \\ & & & & & 3 & 2 & 1 & \\ & & & & & & 3 & 2 & 1, \end{matrix}\]

yields the output $h: \{x \in \mathbb{Z} \mid 1 \le x \le 7 \} \rightarrow \mathbb{R}$ equal to

\[\boxed{ \begin{matrix} \boxed{0} & \boxed{0} & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{0} & \boxed{0} \end{matrix}}.\]

Instead of rotating the filter mask, one could instead rotate $f$ and still obtained the same convolution result. In fact, the conventional notation for convolution indicates that $f$ is flipped and not $w$. If $w$ is symmetric, then convolution and correlation give the same outcome.

Two-dimensional illustration

For a two-dimensional example, suppose the filter $w:\{-1, 0 ,1\} \times \{-1,0,1\} \rightarrow \mathbb{R}$ has coefficients

\[ \begin{matrix} \boxed{1} & \boxed{2} & \boxed{3} \\ \\ \boxed{4} & \boxed{5} & \boxed{6} \\ \\ \boxed{7} & \boxed{8} & \boxed{9} \end{matrix},\]

and consider a two-dimensional discrete unit impulse function

\[ f:\{x \in \mathbb{Z} \mid 1 \le x \le 7 \} \times \{y \in \mathbb{Z} \mid 1 \le y \le 7 \}\rightarrow \{ 0,1\}\]

that has been padded with zeros:

\[ \boxed{ \begin{matrix} 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ \\ 0 & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & 0 \\ \\ 0 & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & 0 \\ \\ 0 & \boxed{0} & \boxed{0} & \boxed{1} & \boxed{0} & \boxed{0} & 0 \\ \\ 0 & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & 0 \\ \\ 0 & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & 0 \\ \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 \end{matrix}}.\]

The correlation operation $w(x,y) \star f(x,y)$ yields the output

\[ \boxed{ \begin{matrix} \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} \\ \\ \boxed{0} & \boxed{9} & \boxed{8} & \boxed{7} & \boxed{0} \\ \\ \boxed{0} & \boxed{6} & \boxed{5} & \boxed{4} & \boxed{0} \\ \\ \boxed{0} & \boxed{3} & \boxed{2} & \boxed{1} & \boxed{0} \\ \\ \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} \end{matrix}},\]

whereas the convolution operation $w(x,y) \ast f(x,y)$ produces

\[ \boxed{ \begin{matrix} \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} \\ \\ \boxed{0} & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{0}\\ \\ \boxed{0} & \boxed{4} & \boxed{5} & \boxed{6} & \boxed{0} \\ \\ \boxed{0} & \boxed{7} & \boxed{8} & \boxed{9} & \boxed{0} \\ \\ \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} & \boxed{0} \end{matrix}}.\]

Discrete convolution and correlation as matrix multiplication

Discrete convolution and correlation operations can also be formulated as a matrix multiplication, where one of the inputs is converted to a Toeplitz matrix, and the other is represented as a column vector. For example, consider a function $f:\{x \in \mathbb{N} \mid 1 \le x \le M \} \rightarrow \mathbb{R}$ and a filter $w: \{s \in \mathbb{N} \mid -k_1 \le s \le k_1 \} \rightarrow \mathbb{R}$. Then the matrix multiplication

\[\begin{bmatrix} w(-k_1) & 0 & \ldots & 0 & 0 \\ \vdots & w(-k_1) & \ldots & \vdots & 0 \\ w(k_1) & \vdots & \ldots & 0 & \vdots \\ 0 & w(k_1) & \ldots & w(-k_1) & 0 \\ 0 & 0 & \ldots & \vdots & w(-k_1) \\ \vdots & \vdots & \ldots & w(k_1) & \vdots \\ 0 & 0 & 0 & 0 & w(k_1) \end{bmatrix} \begin{bmatrix} f(1) \\ f(2) \\ f(3) \\ \vdots \\ f(M) \end{bmatrix}\]

is equivalent to the convolution $w(s) \ast f(x)$ assuming that the border of $f(x)$ has been padded with zeros.

To represent multidimensional convolution as matrix multiplication one reshapes the multidimensional arrays into column vectors and proceeds in an analogous manner. Naturally, the result of the matrix multiplication will need to be reshaped into an appropriate multidimensional array.

Options

The following subsections describe valid options for the function arguments in more detail.

Choices for r

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

    imfilter(ArrayFireLibs(), img, kernel)

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

Choices for T

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

Choices for img

You can specify a one, two or multidimensional array defining your image.

Choices for kernel

The kernel[0,0,..] parameter 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)

The kernel parameter 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,).

Choices for border

At the image edge, border is used to specify the padding which will be used to extrapolate the image beyond its original bounds. As an indicative example of each option the results of the padding are illustrated on an image consisting of a row of six pixels which are specified alphabetically: $\boxed{a \, b \, c \, d \, e \, f}$. We show the effects of padding only on the left and right border, but analogous consequences hold for the top and bottom border.

"replicate" (default)

The border pixels extend beyond the image boundaries.

\[\boxed{ \begin{array}{l|c|r} a\, a\, a\, a & a \, b \, c \, d \, e \, f & f \, f \, f \, f \end{array} }\]

See also: Pad, padarray, Inner, NA and NoPad

"circular"

The border pixels wrap around. For instance, indexing beyond the left border returns values starting from the right border.

\[\boxed{ \begin{array}{l|c|r} c\, d\, e\, f & a \, b \, c \, d \, e \, f & a \, b \, c \, d \end{array} }\]

See also: Pad, padarray, Inner, NA and NoPad

"reflect"

The border pixels reflect relative to a position between pixels. That is, the border pixel is omitted when mirroring.

\[\boxed{ \begin{array}{l|c|r} e\, d\, c\, b & a \, b \, c \, d \, e \, f & e \, d \, c \, b \end{array} }\]

See also: Pad, padarray, Inner, NA and NoPad

"symmetric"

The border pixels reflect relative to the edge itself.

\[\boxed{ \begin{array}{l|c|r} d\, c\, b\, a & a \, b \, c \, d \, e \, f & f \, e \, d \, c \end{array} }\]

See also: Pad, padarray, Inner, NA and NoPad

Fill(m)

The border pixels are filled with a specified value $m$.

\[\boxed{ \begin{array}{l|c|r} m\, m\, m\, m & a \, b \, c \, d \, e \, f & m \, m \, m \, m \end{array} }\]

See also: Pad, padarray, Inner, NA and NoPad

Inner()

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

See also: Pad, padarray, Inner, NA and NoPad

NA()

Choose filtering using "NA" (Not Available) boundary conditions. This is most appropriate for filters that have only positive weights, such as blurring filters.

See also: Pad, padarray, Inner, NA and NoPad

Choices for alg

The alg parameter 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 KernelFactors.IIRGaussian.

Examples

The following subsections highlight some common use cases.

Convolution versus correlation


# Create a two-dimensional discrete unit impulse function.
f = fill(0,(9,9));
f[5,5] = 1;

# Specify a filter coefficient mask and set the center of the mask as the origin.
w = centered([1 2 3; 4 5 6 ; 7 8 9]);

#=
 The default operation of `imfilter` is correlation.  By reflecting `w` we
 compute the convolution of `f` and `w`.  `Fill(0,w)` indicates that we wish to
 pad the border of `f` with zeros. The amount of padding is automatically
 determined by considering the length of w.
=#
correlation = imfilter(f,w,Fill(0,w))
convolution = imfilter(f,reflect(w),Fill(0,w))

Miscellaneous border padding options

# Example function values f, and filter coefficients w.
f = reshape(1.0:81.0,9,9)
w = centered(reshape(1.0:9.0,3,3))

# You can designate the type of padding by specifying an appropriate string.
imfilter(f,w,"replicate")
imfilter(f,w,"circular")
imfilter(f,w,"symmetric")
imfilter(f,w,"reflect")

# Alternatively, you can explicitly use the Pad type to designate the padding style.
imfilter(f,w,Pad(:replicate))
imfilter(f,w,Pad(:circular))
imfilter(f,w,Pad(:symmetric))
imfilter(f,w,Pad(:reflect))

# If you want to pad with a specific value then use the Fill type.
imfilter(f,w,Fill(0,w))
imfilter(f,w,Fill(1,w))
imfilter(f,w,Fill(-1,w))

#=
  Specify 'Inner()' if you want to retrieve the interior sub-array of f for which
  the filtering operation is defined without padding.
=#
imfilter(f,w,Inner())

References

R. C. Gonzalez and R. E. Woods. Digital Image Processing (3rd Edition). Upper Saddle River, NJ, USA: Prentice-Hall, 2006.

ImageFiltering.imfilter! — Function

imfilter!(imgfilt, img, kernel, [border="replicate"], [alg])
imfilter!(r, imgfilt, img, kernel, border::Pad)
imfilter!(r, imgfilt, img, kernel, border::NoPad, [inds=axes(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.

Kernel

ImageFiltering.Kernel.sobel — Function

    diff1, diff2 = sobel()

Return $3 \times 3$ correlation kernels for two-dimensional gradient compution using the Sobel operator. The diff1 kernel computes the gradient along the y-axis (first dimension), and the diff2 kernel computes the gradient along the x-axis (second dimension). diff1 == rotr90(diff2)

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

Return (a tuple of) the N-dimensional correlation kernel for gradient compution along the dimension d using the Sobel operator. If extended[dim] is false, diff will have size 1 along that dimension.

Citation

P.-E. Danielsson and O. Seger, "Generalized and separable sobel operators," in Machine Vision for Three-Dimensional Scenes, H. Freeman, Ed. Academic Press, 1990, pp. 347–379. doi:10.1016/b978-0-12-266722-0.50016-6

ImageFiltering.Kernel.prewitt — Function

    diff1, diff2 = prewitt()

Return $3 \times 3$ correlation kernels for two-dimensional gradient compution using the Prewitt operator. The diff1 kernel computes the gradient along the y-axis (first dimension), and the diff2 kernel computes the gradient along the x-axis (second dimension). diff1 == rotr90(diff2)

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

Return (a tuple of) the N-dimensional correlation kernel for gradient compution along the dimension d using the Prewitt operator. If extended[dim] is false, diff will have size 1 along that dimension.

Citation

J. M. Prewitt, "Object enhancement and extraction," Picture processing and Psychopictorics, vol. 10, no. 1, pp. 15–19, 1970.

ImageFiltering.Kernel.ando3 — Function

    diff1, diff2 = ando3()

Return $3 \times 3$ correlation kernels for two-dimensional gradient compution using Ando's "optimal" filters. The diff1 kernel computes the gradient along the y-axis (first dimension), and the diff2 kernel computes the gradient along the x-axis (second dimension). diff1 == rotr90(diff2)

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

Return (a tuple of) the N-dimensional correlation kernel for gradient compution along the dimension d using Ando's "optimal" filters of size 3. If extended[dim] is false, diff will have size 1 along that dimension.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

ImageFiltering.Kernel.ando4 — Function

    diff1, diff2 = ando4()

Return $4 \times 4$ correlation kernels for two-dimensional gradient compution using Ando's "optimal" filters. The diff1 kernel computes the gradient along the y-axis (first dimension), and the diff2 kernel computes the gradient along the x-axis (second dimension). diff1 == rotr90(diff2)

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

Return (a tuple of) the N-dimensional correlation kernel for gradient compution along the dimension d using Ando's "optimal" filters of size 4. If extended[dim] is false, diff will have size 1 along that dimension.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

ImageFiltering.Kernel.ando5 — Function

    diff1, diff2 = ando5()

Return $5 \times 5$ correlation kernels for two-dimensional gradient compution using Ando's "optimal" filters. The diff1 kernel computes the gradient along the y-axis (first dimension), and the diff2 kernel computes the gradient along the x-axis (second dimension). diff1 == rotr90(diff2)

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

Return (a tuple of) the N-dimensional correlation kernel for gradient compution along the dimension d using Ando's "optimal" filters of size 5. If extended[dim] is false, diff will have size 1 along that dimension.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

ImageFiltering.Kernel.gaussian — Function

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.

KernelFactors

ImageFiltering.KernelFactors.sobel — Function

    kern1, kern2 = sobel()

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

Citation

    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.

ImageFiltering.KernelFactors.prewitt — Function

    kern1, kern2 = prewitt()

Return factored Prewitt filters for dimensions 1 and 2 of your image. Each is a 2-tuple of one-dimensional filters.

Citation

J. M. Prewitt, "Object enhancement and extraction," Picture processing and Psychopictorics, vol. 10, no. 1, pp. 15–19, 1970.

    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.

ImageFiltering.KernelFactors.ando3 — Function

    kern1, kern2 = ando3()

Return a factored form of Ando's "optimal" $3 \times 3$ gradient filters for dimensions 1 and 2 of your image.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

    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.

ImageFiltering.KernelFactors.ando4 — Function

    kern1, kern2 = ando4()

Return separable approximations of Ando's "optimal" 4x4 filters for dimensions 1 and 2 of your image.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

    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.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

ImageFiltering.KernelFactors.ando5 — Function

    kern1, kern2 = ando5()

Return a separable approximations of Ando's "optimal" 5x5 gradient filters for dimensions 1 and 2 of your image.

Citation

S. Ando, "Consistent gradient operators," IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 22, no.3, pp. 252–265, 2000. doi:10.1109/34.841757

    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.

ImageFiltering.KernelFactors.gaussian — Function

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.

ImageFiltering.KernelFactors.IIRGaussian — Function

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).

ImageFiltering.KernelFactors.TriggsSdika — Type

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.

ImageFiltering.KernelFactors.bickley — Function

    kern1, kern2 = bickley()

Return factored Bickley filters for dimensions 1 and 2 of your image. Each is a 2-tuple of one-dimensional filters.

Citation

W. G. Bickley, "Finite difference formulae for the square lattice," The Quarterly Journal of Mechanics and Applied Mathematics, vol. 1, no. 1, pp. 35–42, 1948. doi:10.1093/qjmam/1.1.35

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

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

ImageFiltering.KernelFactors.scharr — Function

    kern1, kern2 = scharr()

Return factored Scharr filters for dimensions 1 and 2 of your image. Each is a 2-tuple of one-dimensional filters.

Citation

H. Scharr and J. Weickert, "An anisotropic diffusion algorithm with optimized rotation invariance," Mustererkennung 2000, pp. 460–467, 2000. doi:10.1007/978-3-642-59802-9_58

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

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

Kernel utilities

ImageFiltering.centered — Function

shiftedkernel = centered(kernel)

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 axes.

Boundaries and padding

ImageFiltering.padarray — Function

    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.

Output

An expansion of the input image in which additional pixels are derived from the border of the input image using the extrapolation scheme specified by border.

Details

The function supports one, two or multi-dimensional images. You can specify the element type T of the output image.

Options

Valid border options are described below.

Pad

The type Pad designates the form of padding which should be used to extrapolate pixels beyond the boundary of an image. Instances must set style, a Symbol specifying the boundary conditions of the image.

Symbol must be on 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).

Refer to the documentation of Pad for more details and examples for each option.

Fill

The type Fill designates a particular value which will be used to extrapolate pixels beyond the boundary of an image. Refer to the documentation of Fill for more details and illustrations.

2D Examples

Each example is based on the input array

\[\mathbf{A} = \boxed{ \begin{matrix} 1 & 2 & 3 & 4 & 5 & 6 \\ 2 & 4 & 6 & 8 & 10 & 12 \\ 3 & 6 & 9 & 12 & 15 & 18 \\ 4 & 8 & 12 & 16 & 20 & 24 \\ 5 & 10 & 15 & 20 & 25 & 30 \\ 6 & 12 & 18 & 24 & 30 & 36 \end{matrix}}.\]

Examples with Pad

The command padarray(A, Pad(:replicate,4,4)) yields

\[\boxed{ \begin{array}{ccccccccccccc} 1 & 1 & 1 & 1 & 1 & 2 & 3 & 4 & 5 & 6 & 6 & 6 & 6 & 6 \\ 1 & 1 & 1 & 1 & 1 & 2 & 3 & 4 & 5 & 6 & 6 & 6 & 6 & 6 \\ 1 & 1 & 1 & 1 & 1 & 2 & 3 & 4 & 5 & 6 & 6 & 6 & 6 & 6 \\ 1 & 1 & 1 & 1 & 1 & 2 & 3 & 4 & 5 & 6 & 6 & 6 & 6 & 6 \\ 1 & 1 & 1 & 1 & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{4} & \boxed{5} & \boxed{6} & 6 & 6 & 6 & 6 \\ 2 & 2 & 2 & 2 & \boxed{2} & \boxed{4} & \boxed{6} & \boxed{8} & \boxed{10} & \boxed{12} & 12 & 12 & 12 & 12 \\ 3 & 3 & 3 & 3 & \boxed{3} & \boxed{6} & \boxed{9} & \boxed{12} & \boxed{15} & \boxed{18} & 18 & 18 & 18 & 18 \\ 4 & 4 & 4 & 4 & \boxed{4} & \boxed{8} & \boxed{12} & \boxed{16} & \boxed{20} & \boxed{24} & 24 & 24 & 24 & 24 \\ 5 & 5 & 5 & 5 & \boxed{5} & \boxed{10} & \boxed{15} & \boxed{20} & \boxed{25} & \boxed{30} & 30 & 30 & 30 & 30 \\ 6 & 6 & 6 & 6 & \boxed{6} & \boxed{12} & \boxed{18} & \boxed{24} & \boxed{30} & \boxed{36} & 36 & 36 & 36 & 36 \\ 6 & 6 & 6 & 6 & 6 & 12 & 18 & 24 & 30 & 36 & 36 & 36 & 36 & 36 \\ 6 & 6 & 6 & 6 & 6 & 12 & 18 & 24 & 30 & 36 & 36 & 36 & 36 & 36 \\ 6 & 6 & 6 & 6 & 6 & 12 & 18 & 24 & 30 & 36 & 36 & 36 & 36 & 36 \\ 6 & 6 & 6 & 6 & 6 & 12 & 18 & 24 & 30 & 36 & 36 & 36 & 36 & 36 \end{array} }.\]

The command padarray(A, Pad(:circular,4,4)) yields

\[\boxed{ \begin{array}{ccccccccccccc} 9 & 12 & 15 & 18 & 3 & 6 & 9 & 12 & 15 & 18 & 3 & 6 & 9 & 12 \\ 12 & 16 & 20 & 24 & 4 & 8 & 12 & 16 & 20 & 24 & 4 & 8 & 12 & 16 \\ 15 & 20 & 25 & 30 & 5 & 10 & 15 & 20 & 25 & 30 & 5 & 10 & 15 & 20 \\ 18 & 24 & 30 & 36 & 6 & 12 & 18 & 24 & 30 & 36 & 6 & 12 & 18 & 24 \\ 3 & 4 & 5 & 6 & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{4} & \boxed{5} & \boxed{6} & 1 & 2 & 3 & 4 \\ 6 & 8 & 10 & 12 & \boxed{2} & \boxed{4} & \boxed{6} & \boxed{8} & \boxed{10} & \boxed{12} & 2 & 4 & 6 & 8 \\ 9 & 12 & 15 & 18 & \boxed{3} & \boxed{6} & \boxed{9} & \boxed{12} & \boxed{15} & \boxed{18} & 3 & 6 & 9 & 12 \\ 12 & 16 & 20 & 24 & \boxed{4} & \boxed{8} & \boxed{12} & \boxed{16} & \boxed{20} & \boxed{24} & 4 & 8 & 12 & 16 \\ 15 & 20 & 25 & 30 & \boxed{5} & \boxed{10} & \boxed{15} & \boxed{20} & \boxed{25} & \boxed{30} & 5 & 10 & 15 & 20 \\ 18 & 24 & 30 & 36 & \boxed{6} & \boxed{12} & \boxed{18} & \boxed{24} & \boxed{30} & \boxed{36} & 6 & 12 & 18 & 24 \\ 3 & 4 & 5 & 6 & 1 & 2 & 3 & 4 & 5 & 6 & 1 & 2 & 3 & 4 \\ 6 & 8 & 10 & 12 & 2 & 4 & 6 & 8 & 10 & 12 & 2 & 4 & 6 & 8 \\ 9 & 12 & 15 & 18 & 3 & 6 & 9 & 12 & 15 & 18 & 3 & 6 & 9 & 12 \\ 12 & 16 & 20 & 24 & 4 & 8 & 12 & 16 & 20 & 24 & 4 & 8 & 12 & 16 \end{array} }.\]

The command padarray(A, Pad(:symmetric,4,4)) yields

\[\boxed{ \begin{array}{ccccccccccccc} 16 & 12 & 8 & 4 & 4 & 8 & 12 & 16 & 20 & 24 & 24 & 20 & 16 & 12 \\ 12 & 9 & 6 & 3 & 3 & 6 & 9 & 12 & 15 & 18 & 18 & 15 & 12 & 9 \\ 8 & 6 & 4 & 2 & 2 & 4 & 6 & 8 & 10 & 12 & 12 & 10 & 8 & 6 \\ 4 & 3 & 2 & 1 & 1 & 2 & 3 & 4 & 5 & 6 & 6 & 5 & 4 & 3 \\ 4 & 3 & 2 & 1 & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{4} & \boxed{5} & \boxed{6} & 6 & 5 & 4 & 3 \\ 8 & 6 & 4 & 2 & \boxed{2} & \boxed{4} & \boxed{6} & \boxed{8} & \boxed{10} & \boxed{12} & 12 & 10 & 8 & 6 \\ 12 & 9 & 6 & 3 & \boxed{3} & \boxed{6} & \boxed{9} & \boxed{12} & \boxed{15} & \boxed{18} & 18 & 15 & 12 & 9 \\ 16 & 12 & 8 & 4 & \boxed{4} & \boxed{8} & \boxed{12} & \boxed{16} & \boxed{20} & \boxed{24} & 24 & 20 & 16 & 12 \\ 20 & 15 & 10 & 5 & \boxed{5} & \boxed{10} & \boxed{15} & \boxed{20} & \boxed{25} & \boxed{30} & 30 & 25 & 20 & 15 \\ 24 & 18 & 12 & 6 & \boxed{6} & \boxed{12} & \boxed{18} & \boxed{24} & \boxed{30} & \boxed{36} & 36 & 30 & 24 & 18 \\ 24 & 18 & 12 & 6 & 6 & 12 & 18 & 24 & 30 & 36 & 36 & 30 & 24 & 18 \\ 20 & 15 & 10 & 5 & 5 & 10 & 15 & 20 & 25 & 30 & 30 & 25 & 20 & 15 \\ 16 & 12 & 8 & 4 & 4 & 8 & 12 & 16 & 20 & 24 & 24 & 20 & 16 & 12 \\ 12 & 9 & 6 & 3 & 3 & 6 & 9 & 12 & 15 & 18 & 18 & 15 & 12 & 9 \end{array} }.\]

The command padarray(A, Pad(:reflect,4,4)) yields

\[\boxed{ \begin{array}{ccccccccccccc} 25 & 20 & 15 & 10 & 5 & 10 & 15 & 20 & 25 & 30 & 25 & 20 & 15 & 10 \\ 20 & 16 & 12 & 8 & 4 & 8 & 12 & 16 & 20 & 24 & 20 & 16 & 12 & 8 \\ 15 & 12 & 9 & 6 & 3 & 6 & 9 & 12 & 15 & 18 & 15 & 12 & 9 & 6 \\ 10 & 8 & 6 & 4 & 2 & 4 & 6 & 8 & 10 & 12 & 10 & 8 & 6 & 4 \\ 5 & 4 & 3 & 2 & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{4} & \boxed{5} & \boxed{6} & 5 & 4 & 3 & 2 \\ 10 & 8 & 6 & 4 & \boxed{2} & \boxed{4} & \boxed{6} & \boxed{8} & \boxed{10} & \boxed{12} & 10 & 8 & 6 & 4 \\ 15 & 12 & 9 & 6 & \boxed{3} & \boxed{6} & \boxed{9} & \boxed{12} & \boxed{15} & \boxed{18} & 15 & 12 & 9 & 6 \\ 20 & 16 & 12 & 8 & \boxed{4} & \boxed{8} & \boxed{12} & \boxed{16} & \boxed{20} & \boxed{24} & 20 & 16 & 12 & 8 \\ 25 & 20 & 15 & 10 & \boxed{5} & \boxed{10} & \boxed{15} & \boxed{20} & \boxed{25} & \boxed{30} & 25 & 20 & 15 & 10 \\ 30 & 24 & 18 & 12 & \boxed{6} & \boxed{12} & \boxed{18} & \boxed{24} & \boxed{30} & \boxed{36} & 30 & 24 & 18 & 12 \\ 25 & 20 & 15 & 10 & 5 & 10 & 15 & 20 & 25 & 30 & 25 & 20 & 15 & 10 \\ 20 & 16 & 12 & 8 & 4 & 8 & 12 & 16 & 20 & 24 & 20 & 16 & 12 & 8 \\ 15 & 12 & 9 & 6 & 3 & 6 & 9 & 12 & 15 & 18 & 15 & 12 & 9 & 6 \\ 10 & 8 & 6 & 4 & 2 & 4 & 6 & 8 & 10 & 12 & 10 & 8 & 6 & 4 \end{array} }.\]

Examples with Fill

The command padarray(A, Fill(0,(4,4),(4,4))) yields

\[\boxed{ \begin{array}{ccccccccccccc} 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & \boxed{1} & \boxed{2} & \boxed{3} & \boxed{4} & \boxed{5} & \boxed{6} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & \boxed{2} & \boxed{4} & \boxed{6} & \boxed{8} & \boxed{10} & \boxed{12} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & \boxed{3} & \boxed{6} & \boxed{9} & \boxed{12} & \boxed{15} & \boxed{18} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & \boxed{4} & \boxed{8} & \boxed{12} & \boxed{16} & \boxed{20} & \boxed{24} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & \boxed{5} & \boxed{10} & \boxed{15} & \boxed{20} & \boxed{25} & \boxed{30} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & \boxed{6} & \boxed{12} & \boxed{18} & \boxed{24} & \boxed{30} & \boxed{36} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \end{array} }.\]

3D Examples

Each example is based on a multi-dimensional array $\mathsf{A} \in\mathbb{R}^{2 \times 2 \times 2}$ given by

\[\mathsf{A}(:,:,1) = \boxed{ \begin{array}{cc} 1 & 2 \\ 3 & 4 \end{array}} \quad \text{and} \quad \mathsf{A}(:,:,2) = \boxed{ \begin{array}{cc} 5 & 6 \\ 7 & 8 \end{array}}.\]

Note that each example will yield a new multi-dimensional array $\mathsf{A}' \in \mathbb{R}^{4 \times 4 \times 4}$ of type OffsetArray, where prepended dimensions may be negative or start from zero.

Examples with Pad

The command padarray(A,Pad(:replicate,1,1,1)) yields

\[\begin{aligned} \mathsf{A}'(:,:,0) & = \boxed{ \begin{array}{cccc} 1 & 1 & 2 & 2 \\ 1 & 1 & 2 & 2 \\ 3 & 3 & 4 & 4 \\ 3 & 3 & 4 & 4 \end{array}} & \mathsf{A}'(:,:,1) & = \boxed{ \begin{array}{cccc} 1 & 1 & 2 & 2 \\ 1 & \boxed{1} & \boxed{2} & 2 \\ 3 & \boxed{3} & \boxed{4} & 4 \\ 3 & 3 & 4 & 4 \end{array}} \\ \mathsf{A}'(:,:,2) & = \boxed{ \begin{array}{cccc} 5 & 5 & 6 & 6 \\ 5 & \boxed{5} & \boxed{6} & 6 \\ 7 & \boxed{7} & \boxed{8} & 8 \\ 7 & 7 & 8 & 8 \end{array}} & \mathsf{A}'(:,:,3) & = \boxed{ \begin{array}{cccc} 5 & 5 & 6 & 6 \\ 5 & 5 & 6 & 6 \\ 7 & 7 & 8 & 8 \\ 7 & 7 & 8 & 8 \end{array}} \end{aligned} .\]

The command padarray(A,Pad(:circular,1,1,1)) yields

\[\begin{aligned} \mathsf{A}'(:,:,0) & = \boxed{ \begin{array}{cccc} 8 & 7 & 8 & 7 \\ 6 & 5 & 6 & 5 \\ 8 & 7 & 8 & 7 \\ 6 & 5 & 6 & 5 \end{array}} & \mathsf{A}'(:,:,1) & = \boxed{ \begin{array}{cccc} 4 & 3 & 4 & 3 \\ 2 & \boxed{1} & \boxed{2} & 1 \\ 4 & \boxed{3} & \boxed{4} & 3 \\ 2 & 1 & 2 & 1 \end{array}} \\ \mathsf{A}'(:,:,2) & = \boxed{ \begin{array}{cccc} 8 & 7 & 8 & 7 \\ 6 & \boxed{5} & \boxed{6} & 5 \\ 8 & \boxed{7} & \boxed{8} & 7 \\ 6 & 5 & 6 & 5 \end{array}} & \mathsf{A}'(:,:,3) & = \boxed{ \begin{array}{cccc} 4 & 3 & 4 & 3 \\ 2 & 1 & 2 & 1 \\ 4 & 3 & 4 & 3 \\ 2 & 1 & 2 & 1 \end{array}} \end{aligned} .\]

The command padarray(A,Pad(:symmetric,1,1,1)) yields

\[\begin{aligned} \mathsf{A}'(:,:,0) & = \boxed{ \begin{array}{cccc} 1 & 1 & 2 & 2 \\ 1 & 1 & 2 & 2 \\ 3 & 3 & 4 & 4 \\ 3 & 3 & 4 & 4 \end{array}} & \mathsf{A}'(:,:,1) & = \boxed{ \begin{array}{cccc} 1 & 1 & 2 & 2 \\ 1 & \boxed{1} & \boxed{2} & 2 \\ 2 & \boxed{3} & \boxed{4} & 4 \\ 2 & 3 & 4 & 4 \end{array}} \\ \mathsf{A}'(:,:,2) & = \boxed{ \begin{array}{cccc} 5 & 5 & 6 & 6 \\ 5 & \boxed{5} & \boxed{6} & 6 \\ 7 & \boxed{7} & \boxed{8} & 8 \\ 7 & 7 & 8 & 8 \end{array}} & \mathsf{A}'(:,:,3) & = \boxed{ \begin{array}{cccc} 5 & 5 & 6 & 6 \\ 5 & 5 & 6 & 6 \\ 7 & 7 & 8 & 8 \\ 7 & 7 & 8 & 8 \end{array}} \end{aligned} .\]

The command padarray(A,Pad(:reflect,1,1,1)) yields

Examples with Fill

The command padarray(A,Fill(0,(1,1,1))) yields

\[\begin{aligned} \mathsf{A}'(:,:,0) & = \boxed{ \begin{array}{cccc} 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \end{array}} & \mathsf{A}'(:,:,1) & = \boxed{ \begin{array}{cccc} 0 & 0 & 0 & 0 \\ 0 & \boxed{1} & \boxed{2} & 0 \\ 0 & \boxed{3} & \boxed{4} & 0 \\ 0 & 0 & 0 & 0 \end{array}} \\ \mathsf{A}'(:,:,2) & = \boxed{ \begin{array}{cccc} 0 & 0 & 0 & 0 \\ 0 & \boxed{5} & \boxed{6} & 0 \\ 0 & \boxed{7} & \boxed{8} & 0 \\ 0 & 0 & 0 & 0 \end{array}} & \mathsf{A}'(:,:,3) & = \boxed{ \begin{array}{cccc} 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \end{array}} \end{aligned} .\]

ImageFiltering.Pad — Type

    struct Pad{N} <: AbstractBorder
        style::Symbol
        lo::Dims{N}    # number to extend by on the lower edge for each dimension
        hi::Dims{N}    # number to extend by on the upper edge for each dimension
    end

Pad is a type that designates the form of padding which should be used to extrapolate pixels beyond the boundary of an image. Instances must set style, a Symbol specifying the boundary conditions of the image.

Output

The type Pad specifying how the boundary of an image should be padded.

Details

When representing a spatial two-dimensional image filtering operation as a discrete convolution between the image and a $D \times D$ filter, the results are undefined for pixels closer than $D$ pixels from the border of the image. To define the operation near and at the border, one needs a scheme for extrapolating pixels beyond the edge. The Pad type allows one to specify the necessary extrapolation scheme.

The type facilitates the padding of one, two or multi-dimensional images.

You can specify a different amount of padding at the lower and upper borders of each dimension of the image (top, left, bottom and right in two dimensions).

Options

Some valid style options are described below. As an indicative example of each option the results of the padding are illustrated on an image consisting of a row of six pixels which are specified alphabetically: $\boxed{a \, b \, c \,d \, e \, f}$. We show the effects of padding only on the left and right border, but analogous consequences hold for the top and bottom border.

:replicate (Default)

The border pixels extend beyond the image boundaries.

\[\boxed{ \begin{array}{l|c|r} a\, a\, a\, a & a \, b \, c \, d \, e \, f & f \, f \, f \, f \end{array} }\]

See also: Fill, padarray, Inner and NoPad

:circular

The border pixels wrap around. For instance, indexing beyond the left border returns values starting from the right border.

\[\boxed{ \begin{array}{l|c|r} c\, d\, e\, f & a \, b \, c \, d \, e \, f & a \, b \, c \, d \end{array} }\]

See also: Fill, padarray, Inner and NoPad

:symmetric

The border pixels reflect relative to a position between pixels. That is, the border pixel is omitted when mirroring.

\[\boxed{ \begin{array}{l|c|r} e\, d\, c\, b & a \, b \, c \, d \, e \, f & e \, d \, c \, b \end{array} }\]

See also: Fill,padarray, Inner and NoPad

:reflect

The border pixels reflect relative to the edge itself.

\[\boxed{ \begin{array}{l|c|r} d\, c\, b\, a & a \, b \, c \, d \, e \, f & f \, e \, d \, c \end{array} }\]

See also: Fill,padarray, Inner and NoPad

ImageFiltering.Fill — Type

    struct Fill{T,N} <: AbstractBorder
        value::T
        lo::Dims{N}
        hi::Dims{N}
    end

Fill is a type that designates a particular value which will be used to extrapolate pixels beyond the boundary of an image.

Output

The type Fill specifying the value with which the boundary of the image should be padded.

Details

When representing a two-dimensional spatial image filtering operation as a discrete convolution between an image and a $D \times D$ filter, the results are undefined for pixels closer than $D$ pixels from the border of the image. To define the operation near and at the border, one needs a scheme for extrapolating pixels beyond the edge. The Fill type allows one to specify a particular value which will be used in the extrapolation. For more elaborate extrapolation schemes refer to the documentation of Pad.

The type facilitates the padding of one, two or multi-dimensional images.

You can specify a different amount of padding at the lower and upper borders of each dimension of the image (top, left, bottom and right in two dimensions).

Example

As an indicative illustration consider an image consisting of a row of six pixels which are specified alphabetically: $\boxed{a \, b \, c \, d \, e \, f}$. We show the effects of padding with a constant value $m$ only on the left and right border, but analogous consequences hold for the top and bottom border.

\[\boxed{ \begin{array}{l|c|r} m\, m\, m\, m & a \, b \, c \, d \, e \, f & m \, m \, m \, m \end{array} }\]

See also: Pad, padarray, Inner and NoPad

ImageFiltering.Inner — Type

Inner()
Inner(lo, hi)

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

Example:

imfilter(img, kernel, Inner())

ImageFiltering.NA — Type

NA(na=isnan)

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 value is normalized in the following way:

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

Array elements for which na returns true are also considered outside array boundaries.

ImageFiltering.NoPad — Type

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

The commands

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

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

Algorithms

ImageFiltering.Algorithm.FIR — Type

Filter using a direct algorithm

ImageFiltering.Algorithm.FFT — Type

Filter using the Fast Fourier Transform

ImageFiltering.Algorithm.IIR — Type

Filter with an Infinite Impulse Response filter

ImageFiltering.Algorithm.Mixed — Type

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

Internal machinery

ImageFiltering.KernelFactors.ReshapedOneD — Type

ReshapedOneD{N,Npre}(data)

Return an object of dimensionality N, where data must have dimensionality 1. The axes are 0:0 for the first Npre dimensions, have the axes 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.

Nonlinear filtering and transformation

ImageFiltering.MapWindow.mapwindow — Function

mapwindow(f, img, window; [border="replicate"], [indices=axes(img)]) -> imgf

Apply f to sliding windows of img, with window size or axes specified by window. For example, mapwindow(median!, img, window) returns an Array of values similar to img (median-filtered, of course), whereas mapwindow(extrema, img, window) returns an Array of (min,max) tuples over a window of size window centered on each point of img.

The function f receives a buffer buf for the window of data surrounding the current point. If window is specified as a Dims-tuple (tuple-of-integers), then all the integers must be odd and the window is centered around the current image point. For example, if window=(3,3), then f will receive an Array buf corresponding to offsets (-1:1, -1:1) from the imgf[i,j] for which this is currently being computed. Alternatively, window can be a tuple of AbstractUnitRanges, in which case the specified ranges are used for buf; this allows you to use asymmetric windows if needed.

border specifies how the edges of img should be handled; see imfilter for details.

Finally indices allows to omit unnecessary computations, if you want to do things like mapwindow on a subimage, or a strided variant of mapwindow. It works as follows:

mapwindow(f, img, window, indices=(2:5, 1:2:7)) == mapwindow(f,img,window)[2:5, 1:2:7]

Except more efficiently because it omits computation of the unused values.

Because the data in the buffer buf that is received by f is copied from img, and the buffer's memory is reused, f should not return references to buf. This

f = buf->copy(buf) # as opposed to f = buf->buf
mapwindow(f, img, window, indices=(2:5, 1:2:7))

would work as expected.

For functions that can only take AbstractVector inputs, you might have to first specialize default_shape:

f = v->quantile(v, 0.75)
ImageFiltering.MapWindow.default_shape(::typeof(f)) = vec

and then mapwindow(f, img, (m,n)) should filter at the 75th quantile.

Edge detection

Images.magnitude — Function

m = magnitude(grad_x, grad_y)

Calculates the magnitude of the gradient images given by grad_x and grad_y. Equivalent to sqrt(grad_x.^2 + grad_y.^2).

Returns a magnitude image the same size as grad_x and grad_y.

Images.phase — Function

phase(grad_x, grad_y) -> p

Calculate the rotation angle of the gradient given by grad_x and grad_y. Equivalent to atan(-grad_y, grad_x), except that when both grad_x and grad_y are effectively zero, the corresponding angle is set to zero.

Images.orientation — Function

orientation(grad_x, grad_y) -> orient

Calculate the orientation angle of the strongest edge from gradient images given by grad_x and grad_y. Equivalent to atan(grad_x, grad_y). When both grad_x and grad_y are effectively zero, the corresponding angle is set to zero.

Images.magnitude_phase — Function

magnitude_phase(grad_x, grad_y) -> m, p

Convenience function for calculating the magnitude and phase of the gradient images given in grad_x and grad_y. Returns a tuple containing the magnitude and phase images. See magnitude and phase for details.

Images.imedge — Function

grad_y, grad_x, mag, orient = imedge(img, kernelfun=KernelFactors.ando3, border="replicate")

Edge-detection filtering. kernelfun is a valid kernel function for imgradients, defaulting to KernelFactors.ando3. border is any of the boundary conditions specified in padarray.

Returns a tuple (grad_y, grad_x, mag, orient), which are the horizontal gradient, vertical gradient, and the magnitude and orientation of the strongest edge, respectively.

Images.thin_edges — Function

thinned = thin_edges(img, gradientangle, [border])
thinned, subpix = thin_edges_subpix(img, gradientangle, [border])
thinned, subpix = thin_edges_nonmaxsup(img, gradientangle, [border]; [radius::Float64=1.35], [theta=pi/180])
thinned, subpix = thin_edges_nonmaxsup_subpix(img, gradientangle, [border]; [radius::Float64=1.35], [theta=pi/180])

Edge thinning for 2D edge images. Currently the only algorithm available is non-maximal suppression, which takes an edge image and its gradient angle, and checks each edge point for local maximality in the direction of the gradient. The returned image is non-zero only at maximal edge locations.

border is any of the boundary conditions specified in padarray.

In addition to the maximal edge image, the _subpix versions of these functions also return an estimate of the subpixel location of each local maxima, as a 2D array or image of Graphics.Point objects. Additionally, each local maxima is adjusted to the estimated value at the subpixel location.

Currently, the _nonmaxsup functions are identical to the first two function calls, except that they also accept additional keyword arguments. radius indicates the step size to use when searching in the direction of the gradient; values between 1.2 and 1.5 are suggested (default 1.35). theta indicates the step size to use when discretizing angles in the gradientangle image, in radians (default: 1 degree in radians = pi/180).

Example:

g = rgb2gray(rgb_image)
gx, gy = imgradients(g)
mag, grad_angle = magnitude_phase(gx,gy)
mag[mag .< 0.5] = 0.0  # Threshold magnitude image
thinned, subpix =  thin_edges_subpix(mag, grad_angle)

Images.canny — Function

canny_edges = canny(img, (upper, lower), sigma=1.4)

Performs Canny Edge Detection on the input image.

Parameters :

(upper, lower) : Bounds for hysteresis thresholding sigma : Specifies the standard deviation of the gaussian filter

Example

imgedg = canny(img, (Percentile(80), Percentile(20)))

Images.Percentile — Type

Percentile(x)

Indicate that x should be interpreted as a percentile rather than an absolute value. For example,

canny(img, 1.4, (80, 20)) uses absolute thresholds on the edge magnitude image
canny(img, 1.4, (Percentile(80), Percentile(20))) uses percentiles of the edge magnitude image as threshold

Corner Detection

Images.imcorner — Function

corners = imcorner(img; [method])
corners = imcorner(img, threshold; [method])

Performs corner detection using one of the following methods -

1. harris
2. shi_tomasi
3. kitchen_rosenfeld

The parameters of the individual methods are described in their documentation. The maxima values of the resultant responses are taken as corners. If a threshold is specified, the values of the responses are thresholded to give the corner pixels. If threshold is a Percentile then its type will be preserved.

Images.harris — Function

harris_response = harris(img; [k], [border], [weights])

Performs Harris corner detection. The covariances can be taken using either a mean weighted filter or a gamma kernel.

Images.shi_tomasi — Function

shi_tomasi_response = shi_tomasi(img; [border], [weights])

Performs Shi Tomasi corner detection. The covariances can be taken using either a mean weighted filter or a gamma kernel.

Images.kitchen_rosenfeld — Function

kitchen_rosenfeld_response = kitchen_rosenfeld(img; [border])

Performs Kitchen Rosenfeld corner detection. The covariances can be taken using either a mean weighted filter or a gamma kernel.

Images.fastcorners — Function

fastcorners(img, n, threshold) -> corners

Performs FAST Corner Detection. n is the number of contiguous pixels which need to be greater (lesser) than intensity + threshold (intensity - threshold) for a pixel to be marked as a corner. The default value for n is 12.

Feature Extraction

See the ImageFeatures package for a much more comprehensive set of tools.

Images.blob_LoG — Function

blob_LoG(img, σscales, [edges], [σshape]) -> Vector{BlobLoG}

Find "blobs" in an N-D image using the negative Lapacian of Gaussians with the specifed vector or tuple of σ values. The algorithm searches for places where the filtered image (for a particular σ) is at a peak compared to all spatially- and σ-adjacent voxels, where σ is σscales[i] * σshape for some i. By default, σshape is an ntuple of 1s.

The optional edges argument controls whether peaks on the edges are included. edges can be true or false, or a N+1-tuple in which the first entry controls whether edge-σ values are eligible to serve as peaks, and the remaining N entries control each of the N dimensions of img.

Citation:

Lindeberg T (1998), "Feature Detection with Automatic Scale Selection", International Journal of Computer Vision, 30(2), 79–116.

Exposure

ImageContrastAdjustment.build_histogram — Function

edges, count = build_histogram(img)            # For 8-bit images only
edges, count = build_histogram(img, nbins)
edges, count = build_histogram(img, nbins; minval, maxval)
edges, count = build_histogram(img, edges)

Generates a histogram for the image over nbins spread between [minval, maxval]. Color images are automatically converted to grayscale.

Output

Returns edges which is a AbstractRange type that specifies how the interval [minval, maxval] is divided into bins, and an array count which records the concomitant bin frequencies. In particular, count has the following properties:

count[0] is the number satisfying x < edges[1]
count[i] is the number of values x that satisfy edges[i] <= x < edges[i+1]
count[end] is the number satisfying x >= edges[end].
length(count) == length(edges)+1.

Details

One can consider a histogram as a piecewise-constant model of a probability density function $f$ [1]. Suppose that $f$ has support on some interval $I = [a,b]$. Let $m$ be an integer and $a = a_1 < a_2 < \ldots < a_m < a_{m+1} = b$ a sequence of real numbers. Construct a sequence of intervals

\[I_1 = [a_1,a_2], I_2 = (a_2, a_3], \ldots, I_{m} = (a_m,a_{m+1}]\]

which partition $I$ into subsets $I_j$ $(j = 1, \ldots, m)$ on which $f$ is constant. These subsets satisfy $I_i \cap I_j = \emptyset, \forall i \neq j$, and are commonly referred to as bins. Together they encompass the entire range of data values such that $\sum_j |I_j | = | I |$. Each bin has width $w_j = |I_j| = a_{j+1} - a_j$ and height $h_j$ which is the constant probability density over the region of the bin. Integrating the constant probability density over the width of the bin $w_j$ yields a probability mass of $\pi_j = h_j w_j$ for the bin.

For a sample $x_1, x_2, \ldots, x_N$, let

\[n_j = \sum_{n = 1}^{N}\mathbf{1}_{(I_j)}(x_n), \quad \text{where} \quad \mathbf{1}_{(I_j)}(x) = \begin{cases} 1 & \text{if} \; x \in I_j,\\ 0 & \text{otherwise}, \end{cases},\]

represent the number of samples falling into the interval $I_j$. An estimate for the probability mass of the $j$th bin is given by the relative frequency $\hat{\pi} = \frac{n_j}{N}$, and the histogram estimator of the probability density function is defined as

\[\begin{aligned} \hat{f}_n(x) & = \sum_{j = 1}^{m}\frac{n_j}{Nw_j} \mathbf{1}_{(I_j)}(x) \\ & = \sum_{j = 1}^{m}\frac{\hat{\pi}_j}{w_j} \mathbf{1}_{(I_j)}(x) \\ & = \sum_{j = 1}^{m}\hat{h}_j \mathbf{1}_{(I_j)}(x). \end{aligned}\]

The function $\hat{f}_n(x)$ is a genuine density estimator because $\hat{f}_n(x) \ge 0$ and

\[\begin{aligned} \int_{-\infty}^{\infty}\hat{f}_n(x) \operatorname{d}x & = \sum_{j=1}^{m} \frac{n_j}{Nw_j} w_j \\ & = 1. \end{aligned}\]

Options

Various options for the parameters of this function are described in more detail below.

Choices for nbins

You can specify the number of discrete bins for the histogram. When specifying the number of bins consider the maximum number of graylevels that your image type supports. For example, with an image of type N0f8 there is a maximum of 256 possible graylevels. Hence, if you request more than 256 bins for that type of image you should expect to obtain zero counts for numerous bins.

Choices for minval

You have the option to specify the lower bound of the interval over which the histogram will be computed. If minval is not specified then the minimum value present in the image is taken as the lower bound.

Choices for maxval

You have the option to specify the upper bound of the interval over which the histogram will be computed. If maxval is not specified then the maximum value present in the image is taken as the upper bound.

Choices for edges

If you do not designate the number of bins, nor the lower or upper bound of the interval, then you have the option to directly stipulate how the intervals will be divided by specifying a AbstractRange type.

Example

Compute the histogram of a grayscale image.


using TestImages, FileIO, ImageView

img =  testimage("mandril_gray");
edges, counts  = build_histogram(img, 256, minval = 0, maxval = 1)

Given a color image, compute the histogram of the red channel.

img = testimage("mandrill")
r = red.(img)
edges, counts  = build_histogram(r, 256, minval = 0, maxval = 1)

References

[1] E. Herrholz, "Parsimonious Histograms," Ph.D. dissertation, Inst. of Math. and Comp. Sci., University of Greifswald, Greifswald, Germany, 2011.

ImageContrastAdjustment.HistogramAdjustmentAPI.adjust_histogram — Function

adjust_histogram([T::Type,] img, f::AbstractHistogramAdjustmentAlgorithm, args...; kwargs...)

Adjust histogram of img using algorithm f.

Output

The return image img_adjusted is an Array{T}.

If T is not specified, then it's inferred.

Examples

Just simply pass the input image and algorithm to adjust_histogram

img_adjusted = adjust_histogram(img, f)

This reads as "adjust_histogram of image img using algorithm f".

You can also explicitly specify the return type:

img_adjusted_float32 = adjust_histogram(Gray{Float32}, img, f)

See also adjust_histogram! for in-place histogram adjustment.

ImageContrastAdjustment.HistogramAdjustmentAPI.adjust_histogram! — Function

adjust_histogram!([out,] img, f::AbstractHistogramAdjustmentAlgorithm, args...; kwargs...)

Adjust histogram of img using algorithm f.

Output

If out is specified, it will be changed in place. Otherwise img will be changed in place.

Examples

Just simply pass an algorithm to adjust_histogram!:

img_adjusted = similar(img)
adjust_histogram!(img_adjusted, img, f)

For cases you just want to change img in place, you don't necessarily need to manually allocate img_adjusted; just use the convenient method:

adjust_histogram!(img, f)

Spatial transformations and resizing

ImageTransformations.imresize — Function

imresize(img, sz) -> imgr
imresize(img, inds) -> imgr
imresize(img; ratio) -> imgr

Change img to be of size sz (or to have indices inds). If ratio is used, then sz = ceil(Int, size(img).*ratio). This interpolates the values at sub-pixel locations. If you are shrinking the image, you risk aliasing unless you low-pass filter img first.

The keyword method takes any InterpolationType from Interpolations.jl or a Degree, which is used to define a BSpline interpolation of that degree, in order to set the interpolation method used in the image resizing.

Examples

julia> img = testimage("lena_gray_256") # 256*256
julia> imresize(img, 128, 128) # 128*128
julia> imresize(img, 1:128, 1:128) # 128*128
julia> imresize(img, (128, 128)) # 128*128
julia> imresize(img, (1:128, 1:128)) # 128*128
julia> imresize(img, (1:128, )) # 128*256
julia> imresize(img, 128) # 128*256
julia> imresize(img, ratio = 0.5) #128*128
julia> imresize(img, ratio = (2, 1)) # 256*128
julia> imresize(img, (128,128), method=Linear()) #128*128
julia> imresize(img, (128,128), method=BSpline(Linear())) #128*128
julia> imresize(img, (128,128), method=Lanczos4OpenCV()) #128*128

σ = map((o,n)->0.75*o/n, size(img), sz)
kern = KernelFactors.gaussian(σ)   # from ImageFiltering
imgr = imresize(imfilter(img, kern, NA()), sz)

Image statistics

Functions for image statistics are spreaded out in Images.jl, ImageDistances.jl and ImageQualityIndexes.jl

Images.minfinite — Function

m = minfinite(A) calculates the minimum value in A, ignoring any values that are not finite (Inf or NaN).

Images.maxfinite — Function

m = maxfinite(A) calculates the maximum value in A, ignoring any values that are not finite (Inf or NaN).

Images.maxabsfinite — Function

m = maxabsfinite(A) calculates the maximum absolute value in A, ignoring any values that are not finite (Inf or NaN).

Images.meanfinite — Function

M = meanfinite(img, region) calculates the mean value along the dimensions listed in region, ignoring any non-finite values.

Images.entropy — Function

entropy(logᵦ, img)
entropy(img; [kind=:shannon])

Compute the entropy of a grayscale image defined as -sum(p.*logᵦ(p)). The base β of the logarithm (a.k.a. entropy unit) is one of the following:

:shannon (log base 2, default), or use logᵦ = log2
:nat (log base e), or use logᵦ = log
:hartley (log base 10), or use logᵦ = log10

General Distances

type name	convenient syntax	math definition
Euclidean	`euclidean(x, y)`	`sqrt(sum((x - y) .^ 2))`
SqEuclidean	`sqeuclidean(x, y)`	`sum((x - y).^2)`
Cityblock	`cityblock(x, y)`	`sum(abs(x - y))`
TotalVariation	`totalvariation(x, y)`	`sum(abs(x - y)) / 2`
Minkowski	`minkowski(x, y, p)`	`sum(abs(x - y).^p) ^ (1/p)`
Hamming	`hamming(x, y)`	`sum(x .!= y)`
SumAbsoluteDifference	`sad(x, y)`	`sum(abs(x - y))`
SumSquaredDifference	`ssd(x, y)`	`sum((x - y).^2)`
MeanAbsoluteError	`mae(x, y)`, `sadn(x, y)`	`sum(abs(x - y))/len(x)`
MeanSquaredError	`mse(x, y)`, `ssdn(x, y)`	`sum((x - y).^2)/len(x)`
RootMeanSquaredError	`rmse(x, y)`	`sqrt(sum((x - y) .^ 2))`
NCC	`ncc(x, y)`	`dot(x,y)/(norm(x)*norm(y))`

Image-specific Distances

Distance type	Convenient syntax	References
`Hausdorff` and `ModifiedHausdorff`	`hausdorff(imgA,imgB)` and `modified_hausdorff(imgA,imgB)`	Dubuisson, M-P et al. 1994. A Modified Hausdorff Distance for Object-Matching.
`CIEDE2000`	`ciede2000(imgA,imgB)` and `ciede2000(imgA,imgB; metric=DE_2000())`	Sharma, G., Wu, W., and Dalal, E. N., 2005. The CIEDE2000 color‐difference formula.

Image metrics

ImageQualityIndexes.PSNR — Type

PSNR <: FullReferenceIQI
assess(PSNR(), x, ref, [, peakval])
assess_psnr(x, ref [, peakval])

Peak signal-to-noise ratio (PSNR) is used to measure the quality of image in present of noise and corruption.

For gray image x, PSNR (in dB) is calculated by 10log10(peakval^2/mse(x, ref)), where peakval is the maximum possible pixel value of image ref. x will be converted to type of ref when necessary.

Generally, for non-gray image x, PSNR is reported against each channel of ref and outputs a Vector, peakval needs to be a vector as well.

Info

Conventionally, m×n rgb image is treated as m×n×3 gray image. To calculated channelwise PSNR of rgb image, one could pass peakval as vector, e.g., psnr(x, ref, [1.0, 1.0, 1.0])

ImageQualityIndexes.SSIM — Type

SSIM([kernel], [(α, β, γ)]; crop=false) <: FullReferenceIQI
assess(iqi::SSIM, img, ref)
assess_ssim(img, ref; crop=false)

Structural similarity (SSIM) index is an image quality assessment method based on degradation of structural information.

The SSIM index is composed of three components: luminance, contrast, and structure; ssim = 𝐿ᵅ * 𝐶ᵝ * 𝑆ᵞ, where W := (α, β, γ) controls relative importance of each components. By default W = (1.0, 1.0, 1.0).

In practice, a mean version SSIM is used. At each pixel, SSIM is calculated locally with neighborhoods weighted by kernel, returning a ssim map; ssim is actaully mean(ssim_map). By default kernel = KernelFactors.gaussian(1.5, 11).

Tip

The default parameters comes from [1]. For benchmark usage, it is recommended to not change the parameters, because most other SSIM implementations follows the same settings. Keyword crop controls whether the boundary of ssim map should be dropped; you need to set it true to reproduce the result in [1].

Example

assess_ssim(img, ref) should be sufficient to get a benchmark for algorithms. One could also instantiate a customed SSIM, then pass it to assess or use it as a function. For example:

iqi = SSIM(KernelFactors.gaussian(2.5, 17), (1.0, 1.0, 2.0))
assess(iqi, img, ref)
iqi(img, ref) # both usages are equivalent

Info

SSIM is defined only for gray images. How RGB and other Color3 images are handled may vary in different implementations. For RGB images, channels are handled seperately when calculating 𝐿, 𝐶, and 𝑆. Generic Color3 images are converted to RGB first before calculation.

Reference

[1] Wang, Z., Bovik, A. C., Sheikh, H. R., & Simoncelli, E. P. (2004). Image quality assessment: from error visibility to structural similarity. IEEE transactions on image processing, 13(4), 600-612.

[2] Wang, Z., Bovik, A. C., Sheikh, H. R., & Simoncelli, E. P. (2003). The SSIM Index for Image Quality Assessment. Retrived May 30, 2019, from http://www.cns.nyu.edu/~lcv/ssim/

ImageQualityIndexes.colorfulness — Function

 M =  colorfulness(img)
 M =  colorfulness(HASLER_AND_SUSSTRUNK_M3(), img)

Measures the colorfulness of a natural image. Uses the HASLER_AND_SUSSTRUNK_M3 method by default.

Attribute	M3
Not colorful	0
slightly colorful	15
moderately colorful	33
averagely colorful	45
quite colorful	59
highly colorful	82
extremely colorful	109

Morphological operations

ImageMorphology.dilate — Function

imgd = dilate(img, [region])

perform a max-filter over nearest-neighbors. The default is 8-connectivity in 2d, 27-connectivity in 3d, etc. You can specify the list of dimensions that you want to include in the connectivity, e.g., region = [1,2] would exclude the third dimension from filtering.

Examples

julia> img = zeros(5, 5); img[3, 3] = 1.; img
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0

julia> dilate(img)
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  0.0  0.0  0.0  0.0

julia> dilate(img, 1)
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  0.0  0.0
 0.0  0.0  1.0  0.0  0.0
 0.0  0.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0

ImageMorphology.erode — Function

imge = erode(img, [region])

perform a min-filter over nearest-neighbors. The default is 8-connectivity in 2d, 27-connectivity in 3d, etc. You can specify the list of dimensions that you want to include in the connectivity, e.g., region = [1,2] would exclude the third dimension from filtering.

Examples

julia> img = zeros(5, 5); img[2:4, 2:4] .= 1.; img
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  0.0  0.0  0.0  0.0

julia> erode(img)
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0

julia> erode(img, 1)
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  1.0  1.0  1.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0

ImageMorphology.opening — Function

imgo = opening(img, [region]) performs the opening morphology operation, equivalent to dilate(erode(img)). region allows you to control the dimensions over which this operation is performed.

Examples

julia> img = zeros(5, 5); img[1, 1] = 1.; img[3:5, 3:5] .= 1.; img
5×5 Array{Float64,2}:
 1.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0
 0.0  0.0  1.0  1.0  1.0
 0.0  0.0  1.0  1.0  1.0

julia> opening(img)
5×5 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0
 0.0  0.0  1.0  1.0  1.0
 0.0  0.0  1.0  1.0  1.0

ImageMorphology.closing — Function

imgc = closing(img, [region]) performs the closing morphology operation, equivalent to erode(dilate(img)). region allows you to control the dimensions over which this operation is performed.

Examples

julia> img = zeros(7, 7); img[3:5, 3:5] .= 1.; img[4, 4] = 0.; img
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  0.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

julia> closing(img)
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

ImageMorphology.tophat — Function

imgth = tophat(img, [region]) performs top hat of an image, which is defined as the image minus its morphological opening. region allows you to control the dimensions over which this operation is performed.

Examples

julia> img = zeros(5, 5); img[1, 1] = 1.; img[3:5, 3:5] .= 1.; img
5×5 Array{Float64,2}:
 1.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0
 0.0  0.0  1.0  1.0  1.0
 0.0  0.0  1.0  1.0  1.0

julia> tophat(img)
5×5 Array{Float64,2}:
 1.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0

ImageMorphology.bothat — Function

imgbh = bothat(img, [region]) performs bottom hat of an image, which is defined as its morphological closing minus the original image. region allows you to control the dimensions over which this operation is performed.

Examples

julia> img = zeros(7, 7); img[3:5, 3:5] .= 1.; img[4, 4] = 0.; img
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  0.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

julia> bothat(img)
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  1.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

ImageMorphology.morphogradient — Function

imgmg = morphogradient(img, [region]) returns morphological gradient of the image, which is the difference between the dilation and the erosion of a given image. region allows you to control the dimensions over which this operation is performed.

Examples

julia> img = zeros(7, 7); img[3:5, 3:5] .= 1.; img
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

julia> morphogradient(img)
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  1.0  1.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  0.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  1.0  1.0  0.0
 0.0  1.0  1.0  1.0  1.0  1.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

ImageMorphology.morpholaplace — Function

imgml = morpholaplace(img, [region]) performs Morphological Laplacian of an image, which is defined as the arithmetic difference between the internal and the external gradient. region allows you to control the dimensions over which this operation is performed.

Examples

julia> img = zeros(7, 7); img[3:5, 3:5] .= 1.; img[4, 4] = 0.; img
7×7 Array{Float64,2}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  1.0  0.0  1.0  0.0  0.0
 0.0  0.0  1.0  1.0  1.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0

julia> morpholaplace(img)
7×7 Array{Float64,2}:
 0.0  0.0   0.0   0.0   0.0  0.0  0.0
 0.0  1.0   1.0   1.0   1.0  1.0  0.0
 0.0  1.0  -1.0  -1.0  -1.0  1.0  0.0
 0.0  1.0  -1.0   1.0  -1.0  1.0  0.0
 0.0  1.0  -1.0  -1.0  -1.0  1.0  0.0
 0.0  1.0   1.0   1.0   1.0  1.0  0.0
 0.0  0.0   0.0   0.0   0.0  0.0  0.0

ImageMorphology.label_components — Function

label = label_components(tf, [connectivity])
label = label_components(tf, [region])

Find the connected components in a binary array tf. There are two forms that connectivity can take:

It can be a boolean array of the same dimensionality as tf, of size 1 or 3 along each dimension. Each entry in the array determines whether a given neighbor is used for connectivity analyses. For example, connectivity = trues(3,3) would use 8-connectivity and test all pixels that touch the current one, even the corners.
You can provide a list indicating which dimensions are used to determine connectivity. For example, region = [1,3] would not test neighbors along dimension 2 for connectivity. This corresponds to just the nearest neighbors, i.e., 4-connectivity in 2d and 6-connectivity in 3d.

The default is region = 1:ndims(A).

The output label is an integer array, where 0 is used for background pixels, and each connected region gets a different integer index.

ImageMorphology.component_boxes — Function

component_boxes(labeled_array) -> an array of bounding boxes for each label, including the background label 0

ImageMorphology.component_lengths — Function

component_lengths(labeled_array) -> an array of areas (2D), volumes (3D), etc. for each label, including the background label 0

ImageMorphology.component_indices — Function

component_indices(labeled_array) -> an array of pixels for each label, including the background label 0

ImageMorphology.component_subscripts — Function

component_subscripts(labeled_array) -> an array of pixels for each label, including the background label 0

ImageMorphology.component_centroids — Function

component_centroids(labeled_array) -> an array of centroids for each label, including the background label 0

ImageMorphology.FeatureTransform.feature_transform — Function

feature_transform(I::AbstractArray{Bool, N}, [w=nothing]) -> F

Compute the feature transform of a binary image I, finding the closest "feature" (positions where I is true) for each location in I. Specifically, F[i] is a CartesianIndex encoding the position closest to i for which I[F[i]] is true. In cases where two or more features in I have the same distance from i, an arbitrary feature is chosen. If I has no true values, then all locations are mapped to an index where each coordinate is typemin(Int).

Optionally specify the weight w assigned to each coordinate. For example, if I corresponds to an image where voxels are anisotropic, w could be the voxel spacing along each coordinate axis. The default value of nothing is equivalent to w=(1,1,...).

Interpolation

Images.bilinear_interpolation — Function

P = bilinear_interpolation(img, r, c)

Bilinear Interpolation is used to interpolate functions of two variables on a rectilinear 2D grid.

The interpolation is done in one direction first and then the values obtained are used to do the interpolation in the second direction.

Integral Images

Images.integral_image — Function

integral_img = integral_image(img)

Returns the integral image of an image. The integral image is calculated by assigning to each pixel the sum of all pixels above it and to its left, i.e. the rectangle from (1, 1) to the pixel. An integral image is a data structure which helps in efficient calculation of sum of pixels in a rectangular subset of an image. See boxdiff for more information.

Images.boxdiff — Function

sum = boxdiff(integral_image, ytop:ybot, xtop:xbot)
sum = boxdiff(integral_image, CartesianIndex(tl_y, tl_x), CartesianIndex(br_y, br_x))
sum = boxdiff(integral_image, tl_y, tl_x, br_y, br_x)

An integral image is a data structure which helps in efficient calculation of sum of pixels in a rectangular subset of an image. It stores at each pixel the sum of all pixels above it and to its left. The sum of a window in an image can be directly calculated using four array references of the integral image, irrespective of the size of the window, given the yrange and xrange of the window. Given an integral image -

    A - - - - - - B -
    - * * * * * * * -
    - * * * * * * * -
    - * * * * * * * -
    - * * * * * * * -
    - * * * * * * * -
    C * * * * * * D -
    - - - - - - - - -

The sum of pixels in the area denoted by * is given by S = D + A - B - C.

Pyramids

Images.gaussian_pyramid — Function

pyramid = gaussian_pyramid(img, n_scales, downsample, sigma)

Returns a gaussian pyramid of scales n_scales, each downsampled by a factor downsample > 1 and sigma for the gaussian kernel.

Image metadata utilities

ImageMetadata.ImageMeta — Type

ImageMeta is an AbstractArray that can have metadata, stored in a dictionary.

Construct an image with ImageMeta(A, props) (for a properties dictionary props), or with ImageMeta(A, prop1=val1, prop2=val2, ...).

ImageAxes.arraydata — Function

arraydata(img::ImageMeta) -> array

Extract the data from img, omitting the properties dictionary. array shares storage with img, so changes to one affect the other.

Image segmentation

ImageSegmentation.SegmentedImage — Type

SegmentedImage type contains the index-label mapping, assigned labels, segment mean intensity and pixel count of each segment.

ImageSegmentation.ImageEdge — Type

edge = ImageEdge(index1, index2, weight)

Construct an edge in a Region Adjacency Graph. index1 and index2 are the integers corresponding to individual pixels/voxels (in the sense of linear indexing via sub2ind), and weight is the edge weight (measures the dissimilarity between pixels/voxels).

Images.otsu_threshold — Function

thres = otsu_threshold(img)
thres = otsu_threshold(img, bins)

Computes threshold for grayscale image using Otsu's method.

Parameters:

img = Grayscale input image
bins = Number of bins used to compute the histogram. Needed for floating-point images.

ImageSegmentation.labels_map — Function

img_labeled = labels_map(seg)

Return an array containing the label assigned to each pixel.

ImageSegmentation.segment_labels — Function

labels = segment_labels(seg)

Returns the list of assigned labels

ImageSegmentation.segment_pixel_count — Function

c = segment_pixel_count(seg, l)

Returns the count of pixels that are assigned label l. If no label is supplied, it returns a Dict(label=>pixel_count) of all the labels.

ImageSegmentation.segment_mean — Function

m = segment_mean(seg, l)

Returns the mean intensity of label l. If no label is supplied, it returns a Dict(label=>mean) of all the labels.

ImageSegmentation.seeded_region_growing — Function

seg_img = seeded_region_growing(img, seeds, [kernel_dim], [diff_fn])
seg_img = seeded_region_growing(img, seeds, [neighbourhood], [diff_fn])

Segments the N-D image img using the seeded region growing algorithm and returns a SegmentedImage containing information about the segments.

Arguments:

img : N-D image to be segmented (arbitrary axes are allowed)
seeds : Vector containing seeds. Each seed is a Tuple of a CartesianIndex{N} and a label. See below note for more information on labels.
kernel_dim : (Optional) Vector{Int} having length N or a NTuple{N,Int} whose ith element is an odd positive integer representing the length of the ith edge of the N-orthotopic neighbourhood
neighbourhood : (Optional) Function taking CartesianIndex{N} as input and returning the neighbourhood of that point.
diff_fn : (Optional) Function that returns a difference measure(δ) between the mean color of a region and color of a point

Note

The labels attached to points must be positive integers, although multiple points can be assigned the same label. The output includes a labelled array that has same indexing as that of input image. Every index is assigned to either one of labels or a special label '0' indicating that the algorithm was unable to assign that index to a unique label.

Examples

julia> img = zeros(Gray{N0f8},4,4);

julia> img[2:4,2:4] .= 1;

julia> seeds = [(CartesianIndex(3,1),1),(CartesianIndex(2,2),2)];

julia> seg = seeded_region_growing(img, seeds);

julia> labels_map(seg)
4×4 Matrix{Int64}:
 1  1  1  1
 1  2  2  2
 1  2  2  2
 1  2  2  2

Citation:

Albert Mehnert, Paul Jackaway (1997), "An improved seeded region growing algorithm", Pattern Recognition Letters 18 (1997), 1065-1071

ImageSegmentation.unseeded_region_growing — Function

seg_img = unseeded_region_growing(img, threshold, [kernel_dim], [diff_fn])
seg_img = unseeded_region_growing(img, threshold, [neighbourhood], [diff_fn])

Segments the N-D image using automatic (unseeded) region growing algorithm and returns a SegmentedImage containing information about the segments.

Arguments:

img : N-D image to be segmented (arbitrary axes are allowed)
threshold : Upper bound of the difference measure (δ) for considering pixel into same segment
kernel_dim : (Optional) Vector{Int} having length N or a NTuple{N,Int} whose ith element is an odd positive integer representing the length of the ith edge of the N-orthotopic neighbourhood
neighbourhood : (Optional) Function taking CartesianIndex{N} as input and returning the neighbourhood of that point.
diff_fn : (Optional) Function that returns a difference measure (δ) between the mean color of a region and color of a point

Examples

julia> img = zeros(Gray{N0f8},4,4);

julia> img[2:4,2:4] .= 1;

julia> seg = unseeded_region_growing(img, 0.2);

julia> labels_map(seg)
4×4 Matrix{Int64}:
 1  1  1  1
 1  2  2  2
 1  2  2  2
 1  2  2  2

ImageSegmentation.felzenszwalb — Function

segments                = felzenszwalb(img, k, [min_size])
index_map, num_segments = felzenszwalb(edges, num_vertices, k, [min_size])

Segments an image using Felzenszwalb's graph-based algorithm. The function can be used in either of two ways -

segments = felzenszwalb(img, k, [min_size])

Segments an image using Felzenszwalb's segmentation algorithm and returns the result as SegmentedImage. The algorithm uses euclidean distance in color space as edge weights for the region adjacency graph.

Parameters:

img = input image
k = Threshold for region merging step. Larger threshold will result in bigger segments.
min_size = Minimum segment size

index_map, num_segments = felzenszwalb(edges, num_vertices, k, [min_size])

Segments an image represented as Region Adjacency Graph(RAG) using Felzenszwalb's segmentation algorithm. Each pixel/region corresponds to a node in the graph and weights on each edge measure the dissimilarity between pixels. The function returns the number of segments and index mapping from nodes of the RAG to segments.

Parameters:

edges = Array of edges in RAG. Each edge is represented as ImageEdge.
num_vertices = Number of vertices in RAG
k = Threshold for region merging step. Larger threshold will result in bigger segments.
min_size = Minimum segment size

ImageSegmentation.fast_scanning — Function

seg_img = fast_scanning(img, threshold, [diff_fn])

Segments the N-D image using a fast scanning algorithm and returns a SegmentedImage containing information about the segments.

Arguments:

img : N-D image to be segmented (arbitrary axes are allowed)
threshold : Upper bound of the difference measure (δ) for considering pixel into same segment; an AbstractArray can be passed having same number of dimensions as that of img for adaptive thresholding
diff_fn : (Optional) Function that returns a difference measure (δ) between the mean color of a region and color of a point

Examples:

julia> img = zeros(Float64, (3,3));

julia> img[2,:] .= 0.5;

julia> img[:,2] .= 0.6;

julia> seg = fast_scanning(img, 0.2);

julia> labels_map(seg)
3×3 Matrix{Int64}:
 1  4  5
 4  4  4
 3  4  6

Citation:

Jian-Jiun Ding, Cheng-Jin Kuo, Wen-Chih Hong, "An efficient image segmentation technique by fast scanning and adaptive merging"

ImageSegmentation.watershed — Function

segments                = watershed(img, markers; compactness, mask)

Segments the image using watershed transform. Each basin formed by watershed transform corresponds to a segment. If you are using image local minimas as markers, consider using hmin_transform to avoid oversegmentation.

Parameters:

img = input grayscale image
markers = An array (same size as img) with each region's marker assigned a index starting from 1. Zero means not a marker. If two markers have the same index, their regions will be merged into a single region. If you have markers as a boolean array, use label_components.
compactness = Use the compact watershed algorithm with the given compactness parameter. Larger values lead to more regularly shaped watershed basins.^[1]
mask = Only segment pixels where the value of mask is true, used to restrict segmentation to only areas of interest

Example

julia> seeds = falses(100, 100); seeds[50, 25] = true; seeds[50, 75] = true;

julia> dists = distance_transform(feature_transform(seeds)); # calculate distances from seeds

julia> markers = label_components(seeds); # give each seed a unique integer id

julia> results = watershed(dists, markers);

julia> labels_map(results); # labels of segmented image

ImageSegmentation.hmin_transform — Function

out = hmin_transform(img, h)

Suppresses all minima in grayscale image whose depth is less than h.

H-minima transform is defined as the reconstruction by erosion of (img + h) by img. See Morphological image analysis by Soille pg 170-172.

ImageSegmentation.region_adjacency_graph — Function

G, vert_map = region_adjacency_graph(seg, weight_fn)

Constructs a region adjacency graph (RAG) from the SegmentedImage. It returns the RAG along with a Dict(label=>vertex) map. weight_fn is used to assign weights to the edges.

weight_fn(label1, label2)

Returns a real number corresponding to the weight of the edge between label1 and label2.

Missing docstring.

Missing docstring for rem_segment. Check Documenter's build log for details.

Missing docstring.

Missing docstring for rem_segment!. Check Documenter's build log for details.

ImageSegmentation.prune_segments — Function

new_seg = prune_segments(seg, rem_labels, diff_fn)

Removes all segments that have labels in rem_labels replacing them with their neighbouring segment having least diff_fn. rem_labels is a Vector of labels.

new_seg = prune_segments(seg, is_rem, diff_fn)

Removes all segments for which is_rem returns true replacing them with their neighbouring segment having least diff_fn.

is_rem(label) -> Bool

Returns true if label label is to be removed otherwise false.

d = diff_fn(rem_label, neigh_label)

A difference measure between label to be removed and its neighbors. isless must be defined for objects of the type of d.

ImageSegmentation.region_tree — Function

t = region_tree(img, homogeneous)

Creates a region tree from img by splitting it recursively until all the regions are homogeneous.

b = homogeneous(img)

Returns true if img is homogeneous.

Examples

julia> img = 0.1*rand(6, 6);

julia> img[4:end, 4:end] .+= 10;

julia> function homogeneous(img)
           min, max = extrema(img)
           max - min < 0.2
       end
homogeneous (generic function with 1 method)

julia> t = region_tree(img, homogeneous);

ImageSegmentation.region_splitting — Function

seg = region_splitting(img, homogeneous)

Segments img by recursively splitting it until all the segments are homogeneous.

b = homogeneous(img)

Returns true if img is homogeneous.

Examples

julia> img = 0.1*rand(6, 6);

julia> img[4:end, 4:end] .+= 10;

julia> function homogeneous(img)
           min, max = extrema(img)
           max - min < 0.2
       end
homogeneous (generic function with 1 method)

julia> seg = region_splitting(img, homogeneous);

ImageFeatures

Geometric features

ImageFeatures.hough_transform_standard — Function

lines = hough_transform_standard(
    img_edges::AbstractMatrix;
    stepsize=1,
    angles=range(0,stop=pi,length=minimum(size(img))),
    vote_threshold=minimum(size(img)) / stepsize -1,
    max_linecount=typemax(Int))

Returns a vector of tuples corresponding to the tuples of (r,t) where r and t are parameters for normal form of line: x * cos(t) + y * sin(t) = r

r = length of perpendicular from (1,1) to the line
t = angle between perpendicular from (1,1) to the line and x-axis

The lines are generated by applying hough transform on the image.

Parameters:

img_edges = Image to be transformed (eltype should be Bool)
stepsize = Discrete step size for perpendicular length of line
angles = List of angles for which the transform is computed
vote_threshold = Accumulator threshold for line detection
max_linecount = Maximum no of lines to return

Example

julia> using ImageFeatures

julia> img = fill(false,5,5); img[3,:] .= true; img
5×5 Array{Bool,2}:
 false  false  false  false  false
 false  false  false  false  false
  true   true   true   true   true
 false  false  false  false  false
 false  false  false  false  false

julia> hough_transform_standard(img)
1-element Array{Tuple{Float64,Float64},1}:
 (3.0, 1.5707963267948966)

ImageFeatures.hough_circle_gradient — Function

circle_centers, circle_radius = hough_circle_gradient(img_edges, img_phase, radii; scale=1, min_dist=minimum(radii), vote_threshold)

Returns two vectors, corresponding to circle centers and radius.

The circles are generated using a hough transform variant in which a non-zero point only votes for circle centers perpendicular to the local gradient. In case of concentric circles, only the largest circle is detected.

Parameters:

img_edges = edges of the image
img_phase = phase of the gradient image
radii = circle radius range
scale = relative accumulator resolution factor
min_dist = minimum distance between detected circle centers
vote_threshold = accumulator threshold for circle detection

canny and phase can be used for obtaining imgedges and imgphase respectively.

Example

julia> using Images, ImageFeatures, FileIO, ImageView

julia> img = load(download("http://docs.opencv.org/3.1.0/water_coins.jpg"));

julia> img = Gray.(img);

julia> img_edges = canny(img, (Percentile(99), Percentile(80)));

julia> dx, dy=imgradients(img, KernelFactors.ando5);

julia> img_phase = phase(dx, dy);

julia> centers, radii = hough_circle_gradient(img_edges, img_phase, 20:30);

julia> img_demo = Float64.(img_edges); for c in centers img_demo[c] = 2; end

julia> imshow(img_demo)

Types

ImageFeatures.Feature — Type

feature = Feature(keypoint, orientation = 0.0, scale = 0.0)

The Feature type has the keypoint, its orientation and its scale.

ImageFeatures.Features — Type

features = Features(boolean_img)
features = Features(keypoints)

Returns a Vector{Feature} of features generated from the true values in a boolean image or from a list of keypoints.

ImageFeatures.Keypoint — Type

keypoint = Keypoint(y, x)
keypoint = Keypoint(feature)

A Keypoint may be created by passing the coordinates of the point or from a feature.

ImageFeatures.Keypoints — Type

keypoints = Keypoints(boolean_img)
keypoints = Keypoints(features)

Creates a Vector{Keypoint} of the true values in a boolean image or from a list of features.

ImageFeatures.BRIEF — Type

brief_params = BRIEF([size = 128], [window = 9], [sigma = 2 ^ 0.5], [sampling_type = gaussian], [seed = 123])

Argument	Type	Description
size	Int	Size of the descriptor
window	Int	Size of sampling window
sigma	Float64	Value of sigma used for inital gaussian smoothing of image
sampling_type	Function	Type of sampling used for building the descriptor (See BRIEF Sampling Patterns)
seed	Int	Random seed used for generating the sampling pairs. For matching two descriptors, the seed used to build both should be same.

ImageFeatures.ORB — Type

orb_params = ORB([num_keypoints = 500], [n_fast = 12], [threshold = 0.25], [harris_factor = 0.04], [downsample = 1.3], [levels = 8], [sigma = 1.2])

Argument	Type	Description
num_keypoints	Int	Number of keypoints to extract and size of the descriptor calculated
n_fast	Int	Number of consecutive pixels used for finding corners with FAST. See [`fastcorners`]
threshold	Float64	Threshold used to find corners in FAST. See [`fastcorners`]
harris_factor	Float64	Harris factor `k` used to rank keypoints by harris responses and extract the best ones
downsample	Float64	Downsampling parameter used while building the gaussian pyramid. See [`gaussian_pyramid`] in Images.jl
levels	Int	Number of levels in the gaussian pyramid. See [`gaussian_pyramid`] in Images.jl
sigma	Float64	Used for gaussian smoothing in each level of the gaussian pyramid. See [`gaussian_pyramid`] in Images.jl

ImageFeatures.FREAK — Type

freak_params = FREAK([pattern_scale = 22.0])

Argument	Type	Description
pattern_scale	Float64	Scaling factor for the sampling window

ImageFeatures.BRISK — Type

brisk_params = BRISK([pattern_scale = 1.0])

Argument	Type	Description
`pattern_scale`	`Float64`	Scaling factor for the sampling window

ImageFeatures.HOG — Type

hog_params = HOG([orientations = 9], [cell_size = 8], [block_size = 2], [block_stride = 1], [norm_method = "L2-norm"])

Histogram of Oriented Gradient (HOG) is a dense feature desciptor usually used for object detection. See "Histograms of Oriented Gradients for Human Detection" by Dalal and Triggs.

Parameters:

orientations = number of orientation bins
cellsize = size of a cell is cellsize x cell_size (in pixels)
blocksize = size of a block is blocksize x block_size (in terms of cells)
block_stride = stride of blocks. Controls how much adjacent blocks overlap.
norm_method = block normalization method. Options: L2-norm, L2-hys, L1-norm, L2-sqrt.

Corners

ImageFeatures.corner_orientations — Function

orientations = corner_orientations(img)
orientations = corner_orientations(img, corners)
orientations = corner_orientations(img, corners, kernel)

Returns the orientations of corner patches in an image. The orientation of a corner patch is denoted by the orientation of the vector between intensity centroid and the corner. The intensity centroid can be calculated as C = (m01/m00, m10/m00) where mpq is defined as -

`mpq = (x^p)(y^q)I(y, x) for each p, q in the corner patch`

The kernel used for the patch can be given through the kernel argument. The default kernel used is a gaussian kernel of size 5x5.

BRIEF Sampling Patterns

ImageFeatures.random_uniform — Function

sample_one, sample_two = random_uniform(size, window, seed)

Builds sampling pairs using random uniform sampling.

ImageFeatures.random_coarse — Function

sample_one, sample_two = random_coarse(size, window, seed)

Builds sampling pairs using random sampling over a coarse grid.

ImageFeatures.gaussian — Function

sample_one, sample_two = gaussian(size, window, seed)

Builds sampling pairs using gaussian sampling.

ImageFeatures.gaussian_local — Function

sample_one, sample_two = gaussian_local(size, window, seed)

Pairs (Xi, Yi) are randomly sampled using a Gaussian distribution where first X is sampled with a standard deviation of 0.04*S^2 and then the Yi’s are sampled using a Gaussian distribution – Each Yi is sampled with mean Xi and standard deviation of 0.01 * S^2

ImageFeatures.center_sample — Function

sample_one, sample_two = center_sample(size, window, seed)

Builds sampling pairs (Xi, Yi) where Xi is (0, 0) and Yi is sampled uniformly from the window.

Feature Description

ImageFeatures.create_descriptor — Function

desc, keypoints = create_descriptor(img, keypoints, params)
desc, keypoints = create_descriptor(img, params)

Create a descriptor for each entry in keypoints from the image img. params specifies the parameters for any of several descriptors:

BRIEF
ORB
BRISK
FREAK
HOG

Some descriptors support discovery of the keypoints from fastcorners.

Feature Matching

ImageFeatures.hamming_distance — Function

distance = hamming_distance(desc_1, desc_2)

Calculates the hamming distance between two descriptors.

ImageFeatures.match_keypoints — Function

matches = match_keypoints(keypoints_1, keypoints_2, desc_1, desc_2, threshold = 0.1)

Finds matched keypoints using the hamming_distance function having distance value less than threshold.

Texture Matching

Gray Level Co-occurence Matrix

glcm
glcm_symmetric
glcm_norm
glcm_prop
max_prob
contrast
ASM
IDM
glcm_entropy
energy
dissimilarity
correlation
glcm_mean_ref
glcm_mean_neighbour
glcm_var_ref
glcm_var_neighbour

Local Binary Patterns

lbp
modified_lbp
direction_coded_lbp
lbp_original
lbp_uniform
lbp_rotation_invariant
multi_block_lbp

1https://www.tu-chemnitz.de/etit/proaut/publications/cwspSLICICPR.pdf