Find limits to contrast stretch an image.
Returns a 2 element column vector, [low; high],
with the pair of intensities to contrast stretch I which
saturates at most tol of the image. The output of this
function matches the input expected by imadjust.
The input argument tol, controls the fraction of the image to be
saturated and defaults to [0.01 0.99], i.e., a 1% saturation
on both sides of the image histogram. It can be specified in two ways:
0.05 is equivalent
to [0.05 0.95]. This value must be in the range [0 0.5].
A common use case wanting to maximize contrast without causing any
saturation. In such case tol should be 0 (zero). It is the
equivalent to [min(I(:)); max(I(:))] for a single
plane.
The return values are of class double and in the range [0 1] regardless
of the input image class. These values are scaled in the image class
range (see im2double).
If the input is a RGB image, i.e., the 3rd dimension has length 3, then
it returns a [2 3] matrix with separate limits for each colour.
It will actually do this for each plane, so an input of size,
[M N P] will return a [2 P] matrix.
Higher dimensions of I are also valid. As in the 3 dimensional
case, the limits for each 2 dimensional plane are returned in a 2 row
vector for each 2 dimensional plane, one dimension below. That is, an
input of size [M N P Q R] will return an array of size
[2 P Q R].
Note the detail that tol is the maximum fraction of saturation.
It is rare that there is a value for that exact saturation. In such
case, stretchlim will always round down and saturate less.
tol is the saturation limit. For example, if tol is
0.10, but there are only values that will lead to 5 or 11%
saturation, it will return the value for a 5% saturation.
See also: brighten, contrast, histeq, imadjust.
Package: image