focal_special {ursa}

Custom spatial filtering for image

Description

For each band and for each cell, function calculates value using specific matrix of square window. Focal operation of map algebra.

Usage

focal_special(x, type = c("custom", "gaussian", "laplacian", "osisaf",
                          "hires", "correl", "LoG", "sobel", "sobelG"),
             fmask = NULL, size = 3, alpha = 0.5, sigma = (size-1)/4,
             cover = 1 - 1e-06, fillNA = FALSE, saveMargin = FALSE, verbose = 0L)

Arguments

x

Object of class ursaRaster.

type

Character, which is checked by match.arg.

fmask

Numeric square matrix. Filter mask. If NULL then matrix(1,ncol=1) is used. Default is NULL.

size

Numeric. Diameter of circuled filter mask. Coerced to the nearest odd value not less than original value.

alpha

Nimeric. Parameter alpha for "Laplacian", "LoG", "hires", "correl" filters. Ignored for others. Default is 0.5.

sigma

Numeric. Parameter sigma for "Gaussian", "LoG" filters. Ignored for others. Default is 0.5.

cover

Numeric. 0<=cover<=1. Quota for NA values in the focal window in relation to the squared size of the focal window. Quota exceeding leads to recording NA value in the cell. Default is cover=1-1e-6.

fillNA

Logical. If TRUE then only NA values of source image can be changed, and non-NA values of source image are kept without changes. It may provide less reducing of spatial resolution in the task of spatial interpolation. Default is FALSE.

saveMargin

Logical. If TRUE then adaptive window size is used for cells, where original window goes over image boundary. If FALSE then image is expanded to the half size of focal window by NA values and argument cover is applied to this expanded part. Default is FALSE.

verbose

Integer of 0L, 1L, or 2L, or logical, which is coerced to integer. The level of verbosity. Values >0 provide some additional information on console, verbose=1L is less detailed, verbose=2L is more detailed. Default is 0L.

Details

Developed under impression from Matlab's "fspecial".

• type="custom"
  Filter mask (argument fmask) should be specified manually.

• type="gaussian"
  Gaussian filter. For cascade filtering (sequence of increasing or decreasing window size) sigma=(size-1)/4 produces the same distribution density relative to window size. If sigma is high but not Inf then it is low-pass filter with diameter=size of circular focal window.

• type="laplacian"
  Laplacian filter. Only size=3 makes sence. Any size is coerced to size=3.

• type="osisaf"
  Filter for edge detection. Only size=5 makes sence. Any size is coerced to size=5. TODO (pl): reference

         -0.0625 -0.0625 -0.0625 -0.0625 -0.0625
         -0.0625  0.1250  0.1250  0.1250 -0.0625
         -0.0625  0.1250  0.0000  0.1250 -0.0625
         -0.0625  0.1250  0.1250  0.1250 -0.0625
         -0.0625 -0.0625 -0.0625 -0.0625 -0.0625

• type="hires"
  Filter for unsharping. Only size=3 makes sence. Any size is coerced to size=3.

        -alpha   alpha-1 -alpha
         alpha-1 alpha+5  alpha-1
        -alpha   alpha-1 -alpha

• type="correl"
  Filter for contrast increasing. Only size=3 makes sence. Any size is coerced to size=3.

                   alpha^2    -alpha*(1+alpha^2)               alpha^2
        -alpha*(1+alpha^2)         (1+alpha^2)^2    -alpha*(1+alpha^2)
                   alpha^2    -alpha*(1+alpha^2)               alpha^2

• type="LoG"
  Laplacian of Gaussian. Filter for edge detection. sigma is used, alpha is ignored.

• type="sobel"
  Two-directional Sobel filtering. Only size=3 makes sence. Any size is coerced to size=3.

• type="sobelG"
  Sobel gradient. Only size=3 makes sence. Any size is coerced to size=3.

Value

Object of class ursaRaster with the same number of bands as in input raster.

Warning

Laplacian of Gaussian filter (type="LoG") is not implemented clearly due to applying continuous-valued formula to discrete matrix.

Author(s)

Nikita Platonov [e-mail]

References

TODO(pl): at least reference to 'osisaf'.

See Also

Other focal operations: focal_mean, focal_median, focal_extrem.

Examples

session_grid(NULL)
v <- round(runif(8,min=-1,max=1),3)
customFilter <- matrix(c(v[1:4],-sum(v),v[5:8]),ncol=3)
a <- ursa_dummy(1,mul=4/8,elements=32)
tpList <- eval(formals("focal_special")$type)
res <- c(src=a,as.ursa(bandname=tpList))
for (tp in tpList) {
   message(tp)
   res[tp] <- focal_special(a,tp,fmask=customFilter,size=11,sigma=1,alpha=0.8
                           ,saveMargin=0,verbose=2L)
}
print(res)
display(res,decor=FALSE)