% -*- texinfo -*-
% @deftypefn {Function File} @var{J}= imadjust (@var{I})
% @deftypefnx {Function File} @var{J}= imadjust (@var{I},[@var{low_in};@var{high_in}])
% @deftypefnx {Function File} @var{J}= imadjust (@var{I},[@var{low_in};@var{high_in}],[@var{low_out};@var{high_out}])
% @deftypefnx {Function File} @var{J}= imadjust (..., @var{gamma})
% @deftypefnx {Function File} @var{newmap}= imadjust (@var{map}, ...)
% @deftypefnx {Function File} @var{RGB_out}= imadjust (@var{RGB}, ...)
% Adjust image or colormap values to a specified range.
%
% @code{J=imadjust(I)} adjusts intensity image @var{I} values so that
% 1% of data on lower and higher values (2% in total) of the image is
% saturated; choosing for that the corresponding lower and higher
% bounds (using @code{stretchlim}) and mapping them to 0 and 1. @var{J}
% is an image of the same size as @var{I} which contains mapped values.
% This is equivalent to @code{imadjust(I,stretchlim(I))}.
%
% @code{J=imadjust(I,[low_in;high_in])} behaves as described but uses
% @var{low_in} and @var{high_in} values instead of calculating them. It
% maps those values to 0 and 1; saturates values lower than first limit
% to 0 and values higher than second to 1; and finally maps all values
% between limits linearly to a value between 0 and 1. If @code{[]} is
% passes as @code{[low_in;high_in]} value, then @code{[0;1]} is taken
% as a default value.
%
% @code{J=imadjust(I,[low_in;high_in],[low_out;high_out])} behaves as
% described but maps output values between @var{low_out} and
% @var{high_out} instead of 0 and 1. A default value @code{[]} can also
% be used for this parameter, which is taken as @code{[0;1]}.
%
% @code{J=imadjust(...,gamma)} takes, in addition of 3 parameters
% explained above, an extra parameter @var{gamma}, which specifies the
% shape of the mapping curve between input elements and output
% elements, which is linear (as taken if this parameter is omitted). If
% @var{gamma} is above 1, then function is weighted towards lower
% values, and if below 1, towards higher values.
%
% @code{newmap=imadjust(map,...)} applies a transformation to a
% colormap @var{map}, which output is @var{newmap}. This transformation
% is the same as explained above, just using a map instead of an image.
% @var{low_in}, @var{high_in}, @var{low_out}, @var{high_out} and
% @var{gamma} can be scalars, in which case the same values are applied
% for all three color components of a map; or it can be 1-by-3
% vectors, to define unique mappings for each component.
%
% @code{RGB_out=imadjust(RGB,...)} adjust RGB image @var{RGB} (a
% M-by-N-by-3 array) the same way as specified in images and colormaps.
% Here too @var{low_in}, @var{high_in}, @var{low_out}, @var{high_out} and
% @var{gamma} can be scalars or 1-by-3 matrices, to specify the same
% mapping for all planes, or unique mappings for each.
%
% The formula used to realize the mapping (if we omit saturation) is:
%
% @code{J = low_out + (high_out - low_out) .* ((I - low_in) / (high_in - low_in)) .^ gamma;}
%
% @strong{Compatibility notes:}
%
% @itemize @bullet
% @item
% Prior versions of imadjust allowed @code{[low_in; high_in]} and
% @code{[low_out; high_out]} to be row vectors. Compatibility with this
% behaviour has been keeped, although preferred form is vertical vector
% (since it extends nicely to 2-by-3 matrices for RGB images and
% colormaps).
% @item
% Previous version of imadjust, if @code{low_in>high_in} it 'negated' output.
% Now it is negated if @code{low_out>high_out}, for compatibility with
% MATLAB.
% @item
% Class of @var{I} is not considered, so limit values are not
% modified depending on class of the image, just treated 'as is'. When
% Octave 2.1.58 is out, limits will be multiplied by 255 for uint8
% images and by 65535 for uint16 as in MATLAB.
% @end itemize
%
% @seealso{stretchlim, brighten}
% @end deftypefn