% ADAPTIVETHRESH - Wellner's adaptive thresholding
%
% Thresholds an image using a threshold that is varied across the image relative
% to the local mean, or median, at that point in the image. Works quite well on
% text with shadows
%
% Usage: bw = adaptivethresh(im, fsize, t, filterType, thresholdMode)
%
% bw = adaptivethresh(im) (uses default parameter values)
%
% Arguments: im - Image to be thresholded.
%
% fsize - Filter size used to determine the local weighted mean
% or local median.
% - If the filterType is 'gaussian' fsize specifies the
% standard deviation of Gaussian smoothing to be
% applied.
% - If the filterType is 'median' fsize specifies the
% size of the window over which the local median is
% calculated.
%
% The value for fsize should be large, around one tenth to
% one twentieth of the image size. It defaults to one
% twentieth of the maximum image dimension.
%
% t - Depending on the value of 'mode' this is the value
% expressed as a percentage or fixed amount, relative to
% the local average, or median grey value, below which
% the local threshold is set.
% Try values in the range -20 to +20.
% Use +ve values to threshold dark objects against a
% white background. Use -ve values if you are
% thresholding white objects on a predominatly
% dark background so that the local threshold is set
% above the local mean/median. This parameter defaults to 15.
%
% filterType - Optional string specifying smoothing to be used
% - 'gaussian' use Gaussian smoothing to obtain local
% weighted mean as the local reference value for setting
% the local threshold. This is the default
% - 'median' use median filtering to obtain local reference
% value for setting the local threshold
%
% thresholdMode - Optional string specifying the way the threshold is
% defined.
% - 'relative' the value of t represents the percentage,
% relative to the local average grey value, below which
% the local threshold is set. This is the default.
% - 'fixed' the value of t represents the fixed grey level
% relative to the local average grey value, below which
% the local threshold is set.
%
% Note that in the 'relative' threshold mode the amount the
% threshold differs from the local mean/median will vary in
% proportion with the local mean/median. A small difference
% from the local mean in the dark regions of the image will
% be more significant than the same difference in a bright
% portion of the image. This will match with human
% perception. However this does mean that the results will
% depend on the grey value origin and whether the image
% is,say, negated.
%
% The implementation differs from Pierre Wellner's original adaptive
% thresholding algorithm in that he calculated the local weighted mean just
% along the row, or pairs of rows, in the image using a recursive filter. Here
% we use symmetrical 2D Gaussian smoothing to calculate the local mean. This is
% slower but more general. This code also offers the option of using median
% filtering as a robust alternative to the mean (outliers will not influence the
% result) and offers the option of using a fixed threshold relative to the
% mean/median. Despite the potential advantage of median filtering being
% more robust I find the output from using Gaussian filtering more pleasing.
%
% Reference: Pierre Wellner, "Adaptive Thresholding for the DigitalDesk" Rank
% Xerox Technical Report EPC-1993-110 1993
% Copyright (c) 2008 Peter Kovesi
% School of Computer Science & Software Engineering
% The University of Western Australia
% pk at csse uwa edu au
% http://www.csse.uwa.edu.au/
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
% in the Software without restriction, subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in
% all copies or substantial portions of the Software.
%
% The Software is provided "as is", without warranty of any kind.
%
% August 2008
function bw = adaptivethresh(im, fsize, t, filterType, thresholdMode)
% Set up default parameter values as needed
if nargin < 2
fsize = fix(length(im)/20);
end
if nargin < 3
t = 15;
end
if nargin < 4
filterType = 'gaussian';
end
if nargin < 5
thresholdMode = 'relative';
end
% Apply Gaussian or median smoothing
if strncmpi(filterType, 'gaussian', 3)
g = fspecial('gaussian', 6*fsize, fsize);
fim = filter2(g, im);
elseif strncmpi(filterType, 'median', 3)
fim = medfilt2(im, [fsize fsize], 'symmetric');
else
error('Filtertype must be ''gaussian'' or ''median'' ');
end
% Finally apply the threshold
if strncmpi(thresholdMode,'relative',3)
bw = im > fim*(1-t/100);
elseif strncmpi(thresholdMode,'fixed',3)
bw = im > fim-t;
else
error('mode must be ''relative'' or ''fixed'' ');
end