% -*- texinfo -*-
% @deftypefn {Function File} {@var{LOW_HIGH} = } stretchlim (@var{I},@var{TOL})
% @deftypefnx {Function File} {@var{LOW_HIGH} = } stretchlim (@var{I})
% @deftypefnx {Function File} {@var{LOW_HIGH} = } stretchlim (@var{RGB},@var{TOL})
% @deftypefnx {Function File} {@var{LOW_HIGH} = } stretchlim (@var{RGB})
% Finds limits to contrast stretch an image
%
% @code{LOW_HIGH=stretchlim(I,TOL)} returns a vector @var{LOW_HIGH}
% which contains a pair of intensities which can be used in
% @code{imadjust} to stretch the contrast of an image, first of them
% will be lower value (@code{imadjust} would assign 0 to it) and second
% is the upper bound. @var{TOL} specifies the fraction of the image to
% saturate at lower and upper limits. It can be a vector of length 2:
% @code{[LOW_FRACT, HIGH_FRACT]}, or it can be a scalar, in that case
% @code{[LOW_FRACT, HIGH_FRACT]=[TOL, 1-TOL]}.
%
% @var{TOL} can't be larger than 0.50 and for TOL=0 then
% @code{LOW_HIGH=[min(I(:)), max(I(:))]}.
%
% @code{LOW_HIGH=stretchlim(I)} behaves as described but defaults
% @var{TOL} to @code{[0.01, 0.99]}.
%
% @code{LOW_HIGH=stretchlim(RGB,TOL)} returns a 2-by-3 matrix in
% @var{LOW_HIGH} of lower and upper values to saturate for each plane
% of the RGB image in M-by-N-by-3 array @var{RGB}. @var{TOL} is a
% vector or a scalar, as described above, and the same fractions are
% applied for each plane.
%
% @code{LOW_HIGH=stretchlim(RGB)} uses @code{[0.01, 0.99]} as default
% value for @var{TOL}.
%
% @strong{Notes:}
%
% Values in @var{LOW_HIGH} are of type double and comprised between 0
% and 1 regardless class of input image.
%
% @strong{Compatibility notes:}
%
% @itemize @bullet
% @item
% int* and uint* types are still not implemented (waiting for support
% in Octave 2.1.58).
% @item
% This function tries to find limits that are nearer to saturate
% requested interval. So, for instance, if you requested a 5% and it
% has to choose between discarding a 1% and a 7%, it will choose the
% later despite being more than requested. This should be test against
% MATLAB behaviour.
% @end itemize
%
% @seealso{imadjust}
% @end deftypefn