## Propagation-Separation approach for smoothing of 2D images

### Description

This functions implement the Propagation-Separation approach (local constant and local polynomial model) for smoothing images. Function `awsaniso` uses anisotropic location weights. This is done by evaluating local gradient estimates obtained from the actual estimated color values.

### Usage

```awsimage(object, hmax=4, aws=TRUE, varmodel=NULL, ladjust=1.25,
mask=NULL, xind = NULL, yind = NULL,
wghts=c(1,1,1,1), scorr=TRUE,
lkern="Plateau", plateau=NULL, homogen=TRUE, earlystop=TRUE,
demo=FALSE, graph=FALSE,
max.pixel=4.e2, clip = FALSE, compress=TRUE)
awspimage(object, hmax=12, aws=TRUE, degree=1, varmodel = NULL,
ladjust=1.0, xind = NULL, yind = NULL,
wghts=c(1,1,1,1), scorr= TRUE,
lkern="Plateau", plateau=NULL, homogen=TRUE, earlystop=TRUE,
demo=FALSE, graph=FALSE,
max.pixel= 4.e2, clip = FALSE, compress=TRUE)
awsaniso(object, hmax = 4, g = 3, rho = 0, aws = TRUE, varmodel = NULL,
ladjust = 1, xind = NULL, yind = NULL, wghts = c(1, 1, 1, 1),
scorr = TRUE, lkern = "Triangle", demo = FALSE, graph = FALSE,
satexp = 0.25, max.pixel = 400, clip = FALSE, compress = TRUE)
```

### Arguments

 `object` Image object, class "adimpro", as from `read.image`, `read.raw`, or `make.image`. `hmax` Maximum bandwidth to use in the iteration procedure. `g` Bandwidth for anisotropic smoothing gradient estimates, preferably g >= 3 for images with line type texture and small g approx 1 for improving edges between homogeneous regions (function `awsaniso` only). `rho` Regularization parameter for anisotropic smoothing gradient estimates, preferably rho = 0 for images with line type texture and large rho approx 3 for improving edges between homogeneous regions. (function `awsaniso` only) `aws` (logical). If `TRUE` the propagation - separation (PS) approach from Polzehl and Spokoiny (2006) is used. `aws=FALSE` turns off the statistical penalty resulting in a nonadaptive kernel estimate using a kernel with bandwidth `hmax`. `degree` Degree of the local polynomial model for `awspimage`. 0, 1, or 2 only. `varmodel` `varmodel` specifies how variances are to be estimated. This can be a homogeneous variance estimate (`varmodel="None"`) assuming uncorrelated errors (both spatial and between channels). Alternatives are an adaptive homogeneous or linear (function of the mean) variance estimate that depends on estimated correlations and on residuals from the last iteration step. The default `varmodel=NULL` corresponds to `varmodel == "Linear"` if `img\$gamma==FALSE` and `varmodel == "Constant"` otherwise. `ladjust` adjustment factor for lambda (>=1). Default values for lambda are selected for Gaussian distributions and default settings of parameters `lkern` and `plateau`. Skewed or heavy tailed distributions may require slightly larger values for lambda to meet the propagation condition. `ladjust` allows to increase lambda in such situations. `mask` logical array of the same size as the image or `NULL` (default). Smoothing is restricted to the smallest rectangle including all pixel where `mask==TRUE` and restricts computations to these pixel. This need not be a connected area (Typical usage: smooth all bright regions)! Only used if `is.null(xind)` `&&` `is.null(yind)`. Inactive if `mask==NULL`. Can only be used if `varmodel="None"`. `xind, yind` Restrict smoothing to rectangular area defined by pixel indices `xind,yind` in x- and y-direction. Full range if `NULL` (default). `wghts` allows to weight the information from different (up to 4) color channels. The weights are used in the statistical penalty of the PS-procedure. Note that lambda-values are selected for `wghts==c(1,1,1,1)`, please use parameter `ladjust` to set an appropriate value. `scorr` (logical). Specifies whether spatial correlation is to be estimated. Defaults to `TRUE`. Is set to `FALSE` if `mask` is not `NULL`. `lkern` Specifies the location kernel. Defaults to "Triangle", other choices are "Quadratic", "Cubic" and "Uniform". The use of "Triangle" corresponds to the Epanechnicov kernel nonparametric kernel regression. `plateau` Extension of the plateau in the statistical kernel. Can take values from (0,1), defaults to `0.25`. `homogen` If TRUE the algorithm determines, in each design point i, a circle of maximum radius, such that the statistical penalty `s_{ij}` for all points j within the circle is less than the value specified in `plateau`. In subsequent iteration steps the statistical penalty for such points is set to zero. This is only used if `plateau>0`. This results in more stable intermediate estimates and in a smoother reconstruction. `homogen=TRUE` leads to increased memory requirements. `earlystop` If TRUE the algorithm determines, in each design point i, a circle of minimal radius, such that the circle includes all point j with positive weights `w_{ij}`. if this radius is considerably smaller than the actual bandwidth then the estimate in point i is fixed. This should considarably reduce computing time in case of large `hmax`.`earlystop=TRUE` slightly increases memory requirements. `demo` (logical). If `demo=TRUE` the function pauses after each iteration. Defaults to `FALSE`. `graph` (logical). If `graph=TRUE` intermediate results are illustrated after each iteration step. Defaults to `FALSE`. `max.pixel` Maximum dimension of images for display if `graph=TRUE`. If the true dimension is larger, the images are downscaled for display. See also `show.image`. `satexp` exponent used for scaling saturation in anisotropy visualization (function `awsaniso` only) `clip` (logical). If `TRUE` a clipping region is selected, see `clip.image`, using the information contained in `xind` or `yind`. If both are `NULL` a clipping region can be defined by left mouse clicks. The image `object` is reduced to the clipping region before smoothing. `compress` logical, determines if image data are stored in raw-format.

### Details

The function implements the Propagation-Separation (PS) approach to nonparametric smoothing (formerly introduced as Adaptive Weights Smoothing) for varying coefficient likelihood (awsimage) and local polynomial (awspimage) models for greyscale and color images.

The distribution of grey (color) values is considered to be Gaussian. Noise can be colored.

The numerical complexity of the procedure is mainly determined by `hmax`. The number of iterations is `2*log(hmax)/log(1.25)`. Comlexity in each iteration step is `Const*hakt*n` with `hakt` being the actual bandwith in the iteration step and `n` the number of pixels. `hmax` determines the maximal possible variance reduction.

All other parameters of the approach only depend on the specified values for `skern/lkern` and are therefore set internally to meaningful default values.

For a detailed description of the procedure see references below.

The script used to control the values of parameter `lambda` is stored in directory inst/adjust.

### Value

Object of class `"adimpro"`

 `img ` Contains the reconstructed image. `ni ` Contains the sum of weights, i.e. `trace(W_i)`, in all grid points `i`. `ni0 ` Contains the maximum sum of weights for an nonadaptive kernel estimate with the same bandwidth. `hmax ` Bandwidth used in the last iteration. `call ` The arguments of the function call. `varcoef ` Estimated coefficients in the variance model for the color channels, if `varmodel` is "Constant" or "Linear". `wghts ` The weights used for the color channels. `scorr` Estimated spatial correlations for each channel, if `scorr=TRUE` `chcorr` Estimated correlations between color channels, if `scorr=TRUE`

### Author(s)

Karsten Tabelow tabelow@wias-berlin.de and Joerg Polzehl polzehl@wias-berlin.de

### References

Polzehl and Spokoiny (2006). Propagation-Separation Approach for Local Likelihood Estimation. Probability Theory and Related Fields. 3 (135) 335 - 362.

Polzehl and Spokoiny (2005). Structural adaptive smoothing adaptive smoothing by Propagation-Separation-methods. WIAS-Preprint No. 1068.

Polzehl, J. and Tabelow, K. (2007). Adaptive smoothing of digital images, Journal of Statistical Software 19 (1).

`read.image`, `read.raw`, `make.image`, `show.image`, `clip.image`
```## Not run: demo(awsimage)