% -*- texinfo -*-
% @deftypefn {Function File} @var{J} = imsmooth(@var{I}, @var{name}, @var{options})
% Smooth the given image using several different algorithms.
%
% The first input argument @var{I} is the image to be smoothed. If it is an RGB
% image, each color plane is treated separately.
% The variable @var{name} must be a string that determines which algorithm will
% be used in the smoothing. It can be any of the following strings
%
% @table @asis
% @item 'Gaussian'
% Isotropic Gaussian smoothing. This is the default.
% @item 'Average'
% Smoothing using a rectangular averaging linear filter.
% @item 'Disk'
% Smoothing using a circular averaging linear filter.
% @item 'Median'
% Median filtering.
% @item 'Bilateral'
% Gaussian bilateral filtering.
% @item 'Perona & Malik'
% @itemx 'Perona and Malik'
% @itemx 'P&M'
% Smoothing using anisotropic diffusion as described by Perona and Malik.
% @item 'Custom Gaussian'
% Gaussian smoothing with a spatially varying covariance matrix.
% @end table
%
% In all algorithms the computation is done in double precision floating point
% numbers, but the result has the same type as the input. Also, the size of the
% smoothed image is the same as the input image.
%
% @strong{Isotropic Gaussian smoothing}
%
% The image is convolved with a Gaussian filter with spread @var{sigma}.
% By default @var{sigma} is @math{0.5}, but this can be changed. If the third
% input argument is a scalar it is used as the filter spread.
%
% The image is extrapolated symmetrically before the convolution operation.
%
% @strong{Rectangular averaging linear filter}
%
% The image is convolved with @var{N} by @var{M} rectangular averaging filter.
% By default a 3 by 3 filter is used, but this can e changed. If the third
% input argument is a scalar @var{N} a @var{N} by @var{N} filter is used. If the third
% input argument is a two-vector @code{[@var{N}, @var{M}]} a @var{N} by @var{M}
% filter is used.
%
% The image is extrapolated symmetrically before the convolution operation.
%
% @strong{Circular averaging linear filter}
%
% The image is convolved with circular averaging filter. By default the filter
% has a radius of 5, but this can e changed. If the third input argument is a
% scalar @var{r} the radius will be @var{r}.
%
% The image is extrapolated symmetrically before the convolution operation.
%
% @strong{Median filtering}
%
% Each pixel is replaced with the median of the pixels in the local area. By
% default, this area is 3 by 3, but this can be changed. If the third input
% argument is a scalar @var{N} the area will be @var{N} by @var{N}, and if it's
% a two-vector [@var{N}, @var{M}] the area will be @var{N} by @var{M}.
%
% The image is extrapolated symmetrically before the filtering is performed.
%
% @strong{Gaussian bilateral filtering}
%
% The image is smoothed using Gaussian bilateral filtering as described by
% Tomasi and Manduchi [2]. The filtering result is computed as
% @example
% @var{J}(x0, y0) = k * SUM SUM @var{I}(x,y) * w(x, y, x0, y0, @var{I}(x0,y0), @var{I}(x,y))
% x y
% @end example
% where @code{k} a normalisation variable, and
% @example
% w(x, y, x0, y0, @var{I}(x0,y0), @var{I}(x,y))
% = exp(-0.5*d([x0,y0],[x,y])^2/@var{sigma_d}^2)
% * exp(-0.5*d(@var{I}(x0,y0),@var{I}(x,y))^2/@var{sigma_r}^2),
% @end example
% with @code{d} being the Euclidian distance function. The two paramteres
% @var{sigma_d} and @var{sigma_r} control the amount of smoothing. @var{sigma_d}
% is the size of the spatial smoothing filter, while @var{sigma_r} is the size
% of the range filter. When @var{sigma_r} is large the filter behaves almost
% like the isotropic Gaussian filter with spread @var{sigma_d}, and when it is
% small edges are preserved better. By default @var{sigma_d} is 2, and @var{sigma_r}
% is @math{10/255} for floating points images (with integer images this is
% multiplied with the maximal possible value representable by the integer class).
%
% The image is extrapolated symmetrically before the filtering is performed.
%
% @strong{Perona and Malik}
%
% The image is smoothed using anisotropic diffusion as described by Perona and
% Malik [1]. The algorithm iteratively updates the image using
%
% @example
% I += lambda * (g(dN).*dN + g(dS).*dS + g(dE).*dE + g(dW).*dW)
% @end example
%
% @noindent
% where @code{dN} is the spatial derivative of the image in the North direction,
% and so forth. The function @var{g} determines the behaviour of the diffusion.
% If @math{g(x) = 1} this is standard isotropic diffusion.
%
% The above update equation is repeated @var{iter} times, which by default is 10
% times. If the third input argument is a positive scalar, that number of updates
% will be performed.
%
% The update parameter @var{lambda} affects how much smoothing happens in each
% iteration. The algorithm can only be proved stable is @var{lambda} is between
% 0 and 0.25, and by default it is 0.25. If the fourth input argument is given
% this parameter can be changed.
%
% The function @var{g} in the update equation determines the type of the result.
% By default @code{@var{g}(@var{d}) = exp(-(@var{d}./@var{K}).^2)} where @var{K} = 25.
% This choice gives privileges to high-contrast edges over low-contrast ones.
% An alternative is to set @code{@var{g}(@var{d}) = 1./(1 + (@var{d}./@var{K}).^2)},
% which gives privileges to wide regions over smaller ones. The choice of @var{g}
% can be controlled through the fifth input argument. If it is the string
% @code{'method1'}, the first mentioned function is used, and if it is @var{'method2'}
% the second one is used. The argument can also be a function handle, in which case
% the given function is used. It should be noted that for stability reasons,
% @var{g} should return values between 0 and 1.
%
% The following example shows how to set
% @code{@var{g}(@var{d}) = exp(-(@var{d}./@var{K}).^2)} where @var{K} = 50.
% The update will be repeated 25 times, with @var{lambda} = 0.25.
%
% @example
% @var{g} = @@(@var{d}) exp(-(@var{d}./50).^2);
% @var{J} = imsmooth(@var{I}, 'p&m', 25, 0.25, @var{g});
% @end example
%
% @strong{Custom Gaussian Smoothing}
%
% The image is smoothed using a Gaussian filter with a spatially varying covariance
% matrix. The third and fourth input arguments contain the Eigenvalues of the
% covariance matrix, while the fifth contains the rotation of the Gaussian.
% These arguments can be matrices of the same size as the input image, or scalars.
% In the last case the scalar is used in all pixels. If the rotation is not given
% it defaults to zero.
%
% The following example shows how to increase the size of an Gaussian
% filter, such that it is small near the upper right corner of the image, and
% large near the lower left corner.
%
% @example
% [@var{lambda1}, @var{lambda2}] = meshgrid (linspace (0, 25, columns (@var{I})), linspace (0, 25, rows (@var{I})));
% @var{J} = imsmooth (@var{I}, 'Custom Gaussian', @var{lambda1}, @var{lambda2});
% @end example
%
% The implementation uses an elliptic filter, where only neighbouring pixels
% with a Mahalanobis' distance to the current pixel that is less than 3 are
% used to compute the response. The response is computed using double precision
% floating points, but the result is of the same class as the input image.
%
% @strong{References}
%
% [1] P. Perona and J. Malik,
% 'Scale-space and edge detection using anisotropic diffusion',
% IEEE Transactions on Pattern Analysis and Machine Intelligence,
% 12(7):629-639, 1990.
%
% [2] C. Tomasi and R. Manduchi,
% 'Bilateral Filtering for Gray and Color Images',
% Proceedings of the 1998 IEEE International Conference on Computer Vision, Bombay, India.
%
% @seealso{imfilter, fspecial}
% @end deftypefn