Function Reference
— Function File: J = imadjust (I)
— Function File: J = imadjust (I,[low_in;high_in])
— Function File: J = imadjust (I,[low_in;high_in],[low_out;high_out])
— Function File: J = imadjust (..., gamma)
— Function File: newmap = imadjust (map, ...)
— Function File: RGB_out = imadjust (RGB, ...)

Adjust image or colormap values to a specified range

J=imadjust(I) adjusts intensity image 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 stretchlim) and mapping them to 0 and 1. J is an image of the same size as I which contains mapped values. This is equivalent to imadjust(I,stretchlim(I)).

J=imadjust(I,[low_in;high_in]) behaves as described but uses low_in and 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 [] is passes as [low_in;high_in] value, then [0;1] is taken as a default value.

J=imadjust(I,[low_in;high_in],[low_out;high_out]) behaves as described but maps output values between low_out and high_out instead of 0 and 1. A default value [] can also be used for this parameter, which is taken as [0;1].

J=imadjust(...,gamma) takes, in addition of 3 parameters explained above, an extra parameter 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 gamma is above 1, then function is weighted towards lower values, and if below 1, towards higher values.

newmap=imadjust(map,...) applies a transformation to a colormap map, which output is newmap. This transformation is the same as explained above, just using a map instead of an image. low_in, high_in, low_out, high_out and 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.

RGB_out=imadjust(RGB,...) adjust RGB image RGB (a M-by-N-by-3 array) the same way as specified in images and colormaps. Here too low_in, high_in, low_out, high_out and 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:

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

Compatibility notes:

  • Prior versions of imadjust allowed [low_in; high_in] and [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).
  • Previous version of imadjust, if low_in>high_in it "negated" output. Now it is negated if low_out>high_out, for compatibility with MATLAB.
  • Class of 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.

See also: stretchlim brighten