Reference

restrict(img[, dims]) -> imgr

Reduce the size of img by approximately two-fold along the dimensions listed in dims, or all spatial coordinates if dims is not specified.

Output

The type of output array imgr depends on the input type:

• If img is an OffsetArray, then output array imgr will also be an OffsetArray.
• If img is not an OffsetArray, then output array imgr will be an Array type even if it has offset indices.

The size of imgr is approximately 1/2 of the original size. More specifically:

• if Nₖ = size(img, k) is odd, then size(imgr, k) == (Nₖ+1) ÷ 2.
• if Nₖ = size(img, k) is even, then size(imgr, k) == (Nₖ÷2) + 1.

Examples

The optional argument dims can be a Tuple or Integer:

A = rand(5, 5) # size: (5, 5)

restrict(A) # size: (3, 3)

restrict(A, 1) # size: (3, 5)
restrict(A, 2) # size: (5, 3)

restrict(A, (1, )) # size: (3, 5)
restrict(A, (1, 2)) # size: (3, 3)

Unless the input array is 1-based, the origin will be halfed:

julia> using ImageBase, OffsetArrays

julia> Ao = OffsetArray(rand(5, 4), 5, 6);

julia> Ar = restrict(Ao);

julia> axes(Ao)
(OffsetArrays.IdOffsetRange(values=6:10, indices=6:10), OffsetArrays.IdOffsetRange(values=7:10, indices=7:10))

julia> axes(Ar)
(OffsetArrays.IdOffsetRange(values=3:5, indices=3:5), OffsetArrays.IdOffsetRange(values=4:6, indices=4:6))

Extended help

The term restrict is taken from the coarsening operation of algebraic multigrid methods; it is the adjoint of "prolongation" (which is essentially interpolation). restrict anti-aliases the image as it goes, so is better than a naive summation over 2x2 blocks. The implementation of restrict has been tuned for performance, and should be a fast method for constructing pyramids.

If l is the size of img along a particular dimension, restrict produces an array of size (l+1)÷2 for odd l, and l÷2 + 1 for even l. See the example below for an explanation.

See also ImageTransformations.imresize.

Example

a_course = [0, 1, 0.3]

If we were to interpolate this at the halfway points, we'd get

a_fine = [0, 0.5, 1, 0.65, 0.3]

Note that a_fine is obtained from a_course via the prolongation operator P as P*a_course, where

P = [1   0   0;      # this line "copies over" the first point
     0.5 0.5 0;      # this line takes the mean of the first and second point
     0   1   0;      # copy the second point
     0   0.5 0.5;    # take the mean of the second and third
     0   0   1]      # copy the third

restrict is the adjoint of prolongation. Consequently,

julia> restrict(a_fine)
3-element Array{Float64,1}:
 0.125
 0.7875
 0.3125

julia> (P'*a_fine)/2
3-element Array{Float64,1}:
 0.125
 0.7875
 0.3125

where the division by 2 approximately preserves the mean intensity of the input.

As we see here, for odd-length a_fine, restriction is the adjoint of interpolation at half-grid points. When length(a_fine) is even, restriction is the adjoint of interpolation at 1/4 and 3/4-grid points. This turns out to be the origin of the l->l÷2 + 1 behavior.

One consequence of this definition is that the edges move towards zero:

julia> restrict(ones(11))
6-element Array{Float64,1}:
 0.75
 1.0
 1.0
 1.0
 1.0
 0.75

In some applications (e.g., image registration), you may find it useful to trim the edges.

Although stored as an array, image can also be viewed as a function from discrete grid space Zᴺ to continuous space R if it is gray image, to C if it is complex-valued image (MRI rawdata), to Rᴺ if it is colorant image, etc. This module provides the discrete version of gradient-related operators by viewing image arrays as functions.

This module provides:

• forward/backward difference fdiff are the Images-flavor of Base.diff
• gradient operator fgradient and its adjoint via keyword adjoint=true.
• divergence operator fdiv computes the sum of discrete derivatives of vector fields.
• laplacian operator flaplacian is the divergence of the gradient fields.

Every function in this module has its in-place version.

fdiff!(dst::AbstractArray, src::AbstractArray; dims::Int, rev=false, boundary=:periodic)

The in-place version of fdiff

fdiff(A::AbstractArray; dims::Int, rev=false, boundary=:periodic)

A one-dimension finite difference operator on array A. Unlike Base.diff, this function doesn't shrink the array size.

Take vector as an example, it computes (A[2]-A[1], A[3]-A[2], ..., A[1]-A[end]).

Keywords

• rev::Bool If rev==true, then it computes the backward difference (A[end]-A[1], A[1]-A[2], ..., A[end-1]-A[end]).
• boundary By default it computes periodically in the boundary, i.e., :periodic. In some cases, one can fill zero values with boundary=:zero.

Examples

julia> A = [2 4 8; 3 9 27; 4 16 64]
3×3 Matrix{Int64}:
 2   4   8
 3   9  27
 4  16  64

julia> diff(A, dims=2) # this function exists in Base
3×2 Matrix{Int64}:
  2   4
  6  18
 12  48

julia> fdiff(A, dims=2)
3×3 Matrix{Int64}:
  2   4   -6
  6  18  -24
 12  48  -60

julia> fdiff(A, dims=2, rev=true) # reverse diff
3×3 Matrix{Int64}:
  -6   2   4
 -24   6  18
 -60  12  48

julia> fdiff(A, dims=2, boundary=:zero) # fill boundary with zeros
3×3 Matrix{Int64}:
  2   4  0
  6  18  0
 12  48  0

See also fdiff! for the in-place version.

fdiv!(out, Vs...)

The in-place version of divergence operator fdiv.

fdiv(Vs...)

Compute the divergence of vector fields Vs.

See also fdiv! for the in-place version.

fgradient!(∇X::Tuple, X::AbstractArray; adjoint=false)

The in-place version of (adjoint) gradient operator fgradient.

The input ∇X = (∂₁X, ∂₂X, ..., ∂ₙX) is a tuple of arrays that are similar to X, i.e., eltype(∂ᵢX) == eltype(X) and axes(∂ᵢX) == axes(X) for all i.

fgradient(X::AbstractArray; adjoint=false) -> (∂₁X, ∂₂X, ..., ∂ₙX)

Computes the gradient fields of X. If adjoint==true then it computes the adjoint gradient fields.

Each gradient vector is computed as forward difference along specific dimension, e.g., ∂ᵢX = fdiff(X, dims=i).

Mathematically, the adjoint operator ∂ᵢ' of ∂ᵢ is defined as <∂ᵢu, v> := <u, ∂ᵢ'v>.

See also the in-place version fgradient!(X) to reuse the allocated memory.

flaplacian!(out, X)
flaplacian!(out, ∇X::Tuple, X)

The in-place version of the laplacian operator flaplacian.

!!! tip Avoiding allocations The two-argument method will allocate memory to store the intermediate gradient fields ∇X. If you call this repeatedly with images of consistent size and type, consider using the three-argument form with pre-allocated memory for ∇X, which will eliminate allocation by this function.

flaplacian(X::AbstractArray)

The discrete laplacian operator, i.e., the divergence of the gradient fields of X.

See also flaplacian! for the in-place version.

minimum_finite([f=identity], A; kwargs...)

Calculate minimum(f, A) while ignoring any values that are not finite, e.g., Inf or NaN.

If A is a colorant array with multiple channels (e.g., Array{RGB}), the min comparison is done in channel-wise sense.

The supported kwargs are those of minimum(f, A; kwargs...).

maximum_finite([f=identity], A; kwargs...)

Calculate maximum(f, A) while ignoring any values that are not finite, e.g., Inf or NaN.

If A is a colorant array with multiple channels (e.g., Array{RGB}), the max comparison is done in channel-wise sense.

The supported kwargs are those of maximum(f, A; kwargs...).

meanfinite([f=identity], A; kwargs...)

Compute mean(f, A) while ignoring any non-finite values.

The supported kwargs are those of sum(f, A; kwargs...).

varfinite(A; kwargs...)

Compute the variance of A, ignoring any non-finite values.

The supported kwargs are those of sum(f, A; kwargs...).

sumfinite([f=identity], A; kwargs...)

Compute sum(f, A) while ignoring any non-finite values.

The supported kwargs are those of sum(f, A; kwargs...).