stretchlim函数分析

在看imadjust代码时，看到stretchlim函数，特此分析一下，代码注释如下

function lowhigh = stretchlim(varargin)
%STRETCHLIM Find limits to contrast stretch an image.
%   LOW_HIGH = STRETCHLIM(I,TOL) returns a pair of gray values that can be
%   used by IMADJUST to increase the contrast of an image.
%
%   TOL = [LOW_FRACT HIGH_FRACT] specifies the fraction of the image to
%   saturate at low and high pixel values.
%
%   If TOL is a scalar, TOL = LOW_FRACT, and HIGH_FRACT = 1 - LOW_FRACT,
%   which saturates equal fractions at low and high pixel values.
%
%   If you omit the argument, TOL defaults to [0.01 0.99], saturating 2%.
%
%   If TOL = 0, LOW_HIGH = [min(I(:)); max(I(:))].
%
%   LOW_HIGH = STRETCHLIM(RGB,TOL) returns a 2-by-3 matrix of pixel value
%   pairs to saturate each plane of the RGB image. TOL specifies the same
%   fractions of saturation for each plane.
%
%   Class Support
%   -------------
%   The input image can be uint8, uint16, int16, double, or single, and must
%   be real and nonsparse. The output limits are double and have values
%   between 0 and 1.
%
%   Note
%   ----
%   If TOL is too big, such that no pixels would be left after saturating
%   low and high pixel values, then STRETCHLIM returns [0; 1].
%
%   Example
%   -------
%       I = imread('pout.tif');
%       J = imadjust(I,stretchlim(I),[]);
%       figure, imshow(I), figure, imshow(J)
%
%   See also BRIGHTEN, DECORRSTRETCH, HISTEQ, IMADJUST.

%   Copyright 1999-2005 The MathWorks, Inc.
%   $Revision: 1.7.4.8 $ $Date: 2005/11/15 01:02:11 $

[img,tol] = ParseInputs(varargin{:});

if isa(img,'uint8')
    nbins = 256;
else
    nbins = 65536;
end

tol_low = tol(1);
tol_high = tol(2);

 % 获取第三维的维数
p = size(img,3);

if tol_low < tol_high
    ilowhigh = zeros(2,p);
    % 对于第三维的每一层进行寻找
    for i = 1:p                          % Find limits, one plane at a time
        N = imhist(img(:,:,i),nbins);
        cdf = cumsum(N)/sum(N); %cumulative distribution function
        ilow = find(cdf > tol_low, 1, 'first');        %找到满足累计频率>tol_low的下标
        ihigh = find(cdf >= tol_high, 1, 'first');    %找到满足累计频率>=tol_low的下标
        if ilow == ihigh   % this could happen if img is flat
            ilowhigh(:,i) = [1;nbins];
        else
            ilowhigh(:,i) = [ilow;ihigh];
        end
    end
    lowhigh = (ilowhigh - 1)/(nbins-1);  % convert to range [0 1]

else
    %   tol_low >= tol_high, this tolerance does not make sense. For example, if
    %   the tolerance is .5 then no pixels would be left after saturating
    %   low and high pixel values. In all of these cases, STRETCHLIM
    %   returns [0; 1]. See gecks 278249 and 235648.
    lowhigh = repmat([0;1],1,p);
end

%-----------------------------------------------------------------------------
function [img,tol] = ParseInputs(varargin)

iptchecknargin(1, 2, nargin, mfilename);

img = varargin{1};
iptcheckinput(img, {'uint8', 'uint16', 'double', 'int16', 'single'}, {'real', ...
    'nonsparse'}, mfilename, 'I or RGB', 1);
if (ndims(img) > 3)
    msgId = 'Images:stretchlim:dimTooHigh';
    error(msgId,'STRETCHLIM only supports individual images.');
end

% 默认值
tol = [.01 .99]; %default
if nargin == 2
    tol = varargin{2};
    switch numel(tol)    %判断tol数组元素个数
        case 1
            tol(2) = 1 - tol;

        case 2
            if (tol(1) >= tol(2))
                msgId = 'Images:stretchlim:invalidTolOrder';
                error(msgId,'TOL(1) must be less than TOL(2).');
            end
        otherwise
            msgId = 'Images:stretchlim:invalidTolSize';
            error(msgId,'TOL must have 1 or 2 elements.');
    end
end

if ( any(tol < 0) || any(tol > 1) || any(isnan(tol)) )
    msgId = 'Images:stretchlim:tolOutOfRange';
    error(msgId,'TOL must be in the range [0 1].');
end

主函数为stretchlim，其中子函数ParseInputs用于获取参数。

主函数中关键部分为

if tol_low < tol_high
    ilowhigh = zeros(2,p);
    % 对于第三维的每一层进行寻找
    for i = 1:p                          % Find limits, one plane at a time
        N = imhist(img(:,:,i),nbins);
        cdf = cumsum(N)/sum(N); %cumulative distribution function
        ilow = find(cdf > tol_low, 1, 'first');        %找到满足累计频率>tol_low的下标
        ihigh = find(cdf >= tol_high, 1, 'first');    %找到满足累计频率>=tol_low的下标
        if ilow == ihigh   % this could happen if img is flat
            ilowhigh(:,i) = [1;nbins];
        else
            ilowhigh(:,i) = [ilow;ihigh];
        end
    end
    lowhigh = (ilowhigh - 1)/(nbins-1);  % convert to range [0 1]

函数imhist是用于获取图像数据直方图，返回值是个一维矩阵，保存着图像中每个灰度等级的像素个数，如上，如果nbins等于256，代表灰度范围为0~255，则imhist获取图像img中符合每个灰度等级的像素个数，例如灰度等级3对应数组N下标4，图像中灰度等级为3的像素个数为5，则N(4)=5。

cdf = cumsum(N)/sum(N);

这一行中cumsum(N)计算一个数组各个元素的累加值，例如数组 N = [1 3 5]，则cumsum(N) = [1 4 9]，sum(N)获取数组N的元素个数，因此这个式子代表意思是每个灰度等级的累积频率，例子中sum(N)=3，则cdf=[1/3 4/3 9/3]。

ilow = find(cdf > tol_low, 1, 'first');        %找到满足累计频率>tol_low的下标
ihigh = find(cdf >= tol_high, 1, 'first');    %找到满足累计频率>=tol_low的下标

找到下标ilow和ihigh，可对应满足条件的灰度等级，因为cdf数组中下标也就是对应灰度等级的值加1。

lowhigh = (ilowhigh - 1)/(nbins-1);  % convert to range [0 1]

归一化，将范围[ilow ihigh]映射到[0 1]