% -*- texinfo -*-
% @deftypefn {Function File} {@var{BW2} = } bwmorph (@var{BW},@var{operation})
% @deftypefnx {Function File} {@var{BW2} = } bwmorph (@var{BW},@var{operation},@var{n})
% Perform a morphological operation on a binary image.
%
% BW2=bwmorph(BW,operation) performs a morphological operation
% specified by @var{operation} on binary image @var{BW}. All possible
% operations and their meaning are specified in a table below.
%
% BW2=bwmorph(BW,operation,n) performs a morphological operation
% @var{n} times. Keep in mind that it has no sense to apply some
% operations more than once, since some of them return the same result
% regardless how many iterations we request. Those return a warning if
% are called with n>1 and they compute the result for n=1.
%
% @var{n}>1 is actually used for the following operations: diag,
% dilate, erode, majority, shrink, skel, spur, thicken and thin.
%
% @table @code
% @item 'bothat'
% Performs a bottom hat operation, a closing operation (which is a
% dilation followed by an erosion) and finally substracts the original
% image.
%
% @item 'bridge'
% Performs a bridge operation. Sets a pixel to 1 if it has two nonzero
% neighbours which are not connected, so it 'bridges' them. There are
% 119 3-by-3 patterns which trigger setting a pixel to 1.
%
% @item 'clean'
% Performs an isolated pixel remove operation. Sets a pixel to 0 if all
% of its eight-connected neighbours are 0.
%
% @item 'close'
% Performs closing operation, which is a dilation followed by erosion.
% It uses a ones(3) matrix as structuring element for both operations.
%
% @item 'diag'
% Performs a diagonal fill operation. Sets a pixel to 1 if that
% eliminates eight-connectivity of the background.
%
% @item 'dilate'
% Performs a dilation operation. It uses ones(3) as structuring element.
%
% @item 'erode'
% Performs an erosion operation. It uses ones(3) as structuring element.
%
% @item 'fill'
% Performs a interior fill operation. Sets a pixel to 1 if all
% four-connected pixels are 1.
%
% @item 'hbreak'
% Performs a H-break operation. Breaks (sets to 0) pixels that are
% H-connected.
%
% @item 'majority'
% Performs a majority black operation. Sets a pixel to 1 if five
% or more pixels in a 3-by-3 window are 1. If not it is set to 0.
%
% @item 'open'
% Performs an opening operation, which is an erosion followed by a
% dilation. It uses ones(3) as structuring element.
%
% @item 'remove'
% Performs a iterior pixel remove operation. Sets a pixel to 0 if
% all of its four-connected neighbours are 1.
%
% @item 'shrink'
% Performs a shrink operation. Sets pixels to 0 such that an object
% without holes erodes to a single pixel (set to 1) at or near its
% center of mass. An object with holes erodes to a connected ring lying
% midway between each hole and its nearest outer boundary. It preserves
% Euler number.
%
% @item 'skel'
% Performs a skeletonization operation. It calculates a 'median axis
% skeleton' so that points of this skeleton are at the same distance of
% its nearby borders. It preserver Euler number. Please read
% compatibility notes for more info.
%
% It uses the same algorithm as skel-pratt but this could change for
% compatibility in the future.
%
% @item 'skel-lantuejol'
% Performs a skeletonization operation as described in Gonzalez & Woods
% 'Digital Image Processing' pp 538-540. The text references Lantuejoul
% as authour of this algorithm.
%
% It has the beauty of being a clean and simple approach, but skeletons
% are thicker than they need to and, in addition, not guaranteed to be
% connected.
%
% This algorithm is iterative. It will be applied the minimum value of
% @var{n} times or number of iterations specified in algorithm
% description. It's most useful to run this algorithm with @code{n=Inf}.
%
% @item 'skel-pratt'
% Performs a skeletonization operation as described by William K. Pratt
% in 'Digital Image Processing'.
%
% @item 'spur'
% Performs a remove spur operation. It sets pixel to 0 if it has only
% one eight-connected pixel in its neighbourhood.
%
% @item 'thicken'
% Performs a thickening operation. This operation 'thickens' objects
% avoiding their fusion. Its implemented as a thinning of the
% background. That is, thinning on negated image. Finally a diagonal
% fill operation is performed to avoid 'eight-connecting' objects.
%
% @item 'thin'
% Performs a thinning operation. When n=Inf, thinning sets pixels to 0
% such that an object without holes is converted to a stroke
% equidistant from its nearest outer boundaries. If the object has
% holes it creates a ring midway between each hole and its near outer
% boundary. This differ from shrink in that shrink converts objects
% without holes to a single pixels and thin to a stroke. It preserves
% Euler number.
%
% @item 'tophat'
% Performs a top hat operation, a opening operation (which is an
% erosion followed by a dilation) and finally substracts the original
% image.
% @end table
%
% Some useful concepts to understant operators:
%
% Operations are defined on 3-by-3 blocks of data, where the pixel in
% the center of the block. Those pixels are numerated as follows:
%
% @multitable @columnfractions 0.05 0.05 0.05
% @item X3 @tab X2 @tab X1
% @item X4 @tab X @tab X0
% @item X5 @tab X6 @tab X7
% @end multitable
%
% @strong{Neighbourhood definitions used in operation descriptions:}
% @table @code
% @item 'four-connected'
% It refers to pixels which are connected horizontally or vertically to
% X: X1, X3, X5 and X7.
% @item 'eight-connected'
% It refers to all pixels which are connected to X: X0, X1, X2, X3, X4,
% X5, X6 and X7.
% @end table
%
% @strong{Compatibility notes:}
% @table @code
% @item 'fill'
% Checking MATLAB behaviour is needed because its documentation doesn't
% make clear if it creates a black pixel if all eight-connected pixels
% are black or if four-connected suffice (as we do currently following
% Pratt's book).
% @item 'skel'
% Algorithm used here is described in Pratt's book. When applying it to
% the 'circles' image in MATLAB documentation, results are not the
% same. Perhaps MATLAB uses Blum's algoritm (for further info please
% read comments in code).
% @item 'skel-pratt'
% This option is not available in MATLAB.
% @item 'skel-lantuejoul'
% This option is not available in MATLAB.
% @item 'thicken'
% This implementation also thickens image borders. This can easily be
% avoided i necessary. MATLAB documentation doesn't state how it behaves.
% @end table
%
% References:
% W. K. Pratt, 'Digital Image Processing'
% Gonzalez and Woods, 'Digital Image Processing'
%
% @seealso{dilate, erode, makelut, applylut}
% @end deftypefn