Function File: imadjust (I)
Function File: imadjust (I, [low_in; high_in])
Function File: imadjust (I, [low_in; high_in],[low_out; high_out])
Function File: imadjust (…, gamma)
Function File: imadjust (cmap, …)
Function File: imadjust (RGB, …)

Adjust image or colormap intensity (values).

Returns an image of equal dimensions to I, cmap, or RGB, with its intensity values adjusted, usually for the purpose of increasing the image contrast.

The values are rescaled according to the input and output limits, low_in and high_in, and low_out and high_out respectively. The first pair sets the lower and upper limits on the input image, values above and below them being clipped. The second pair sets the lower and upper limits for the output image, the interval to which the image will be scaled after clipping the input limits.

For example:

imadjust (img, [0.2; 0.9], [0; 1])

will clip all values in img outside the range [0.2 0.9], and then rescale them linearly into the range [0 1].

The input and output limits must be defined as arrays of 2 rows with values in the [0 1] range. Each 2 rows column corresponds to a single plane in the input image (or each column of a colormap), thus supporting images with any number of dimensions. If the limits have only 2 elements, the same limits are on all planes. This format is matched to stretchlim which is designed to create the input limits for imadjust.

By default, the limits are adjusted to maximize the contrast, using the whole range of values in the image class; and cause a 2% saturation (1% on the lower and upper end of the image). It is equivalent to:

imadjust (I, stretchlim (I, 0.01), [0; 1])

A common usage is to maximize the display range without saturation:

imadjust (img, stretchlim (img, 0)) # adjustment performed per plane
imadjust (img, stretchlim (img(:), 0)) # equal adjustment to all planes

For sake of MATAB compatibility, an empty array in any of the limits is interpreted as [0; 1].

If low_out is higher than high_out, the output image will be reversed (image negative or complement).

The gamma value shapes the mapping curve between the input and output elements. It defaults to 1, a linear mapping. Higher values of gamma will curve the mapping downwards and to the right, increasing the contrast in the brighter (higher) values of the input image. Lower values of gamma will curve the mapping upwards and to the left, increasing the contrast in the darker (lower) values of the input image.

As with the limits, gamma can have different values for each plane, a 1 row column per plane, thus supporting input images with any number of dimensions. If only a scalar, the same value is used in all planes.

The formula used to perform the mapping (omitting saturation) is:

low_out + (high_out - low_out) .* ((I - low_in) / (high_in - low_in)) .^ gamma

See also: brighten, contrast, histeq, stretchlim.

Package: image