stretchlim

Find limits to contrast stretch image

Syntax

lowhigh = stretchlim(I)

lowhigh = stretchlim(I,Tol)

Description

lowhigh = stretchlim(I) computes the lower and upper limits that can be used for contrast stretching grayscale or RGB image I. The limits are returned in lowhigh. By default, the limits specify the bottom 1% and the top 1% of all pixel values.

You optionally can calculate the limits using a GPU (requires Parallel Computing Toolbox™). For more information, see Image Processing on a GPU.

lowhigh = stretchlim(I,Tol) specifies the fraction, Tol, of the image to saturate at low and high pixel values.

Examples

Find Limits to Stretch Contrast in Grayscale Image

Read grayscale image into the workspace and display it.

I = imread('pout.tif');
figure
imshow(I)

Adjust the contrast in the image using stretchlim to set the limits, and display the result. The example uses the default limits [0.01 0.99], saturating the upper 1% and the lower 1%.

J = imadjust(I,stretchlim(I),[]);
figure
imshow(J)

Find Limits to Stretch Contrast in Grayscale Image on a GPU

Read grayscale image, creating a gpuArray.

gpuarrayI = gpuArray(imread('pout.tif'));
figure, imshow(gpuarrayI)

Adjust the contrast in the image using stretchlim to set the limits. Display the result.

gpuarrayJ = imadjust(gpuarrayI,stretchlim(I),[]);
figure, imshow(gpuarrayJ)

Input Arguments

I — Image to be contrast stretched

2-D grayscale image | 2-D RGB image | gpuArray

Image to be contrast stretched, specified as a 2-D grayscale or RGB image.

To compute the limits using a GPU, specify I as a gpuArray that contains a 2-D grayscale or RGB image.

Example: I = imread('pout.tif');

Example: I = imread('peppers.png');

Example: I = gpuArray(imread('pout.tif'));

Data Types: single | double | int16 | uint8 | uint16

Tol — Fraction of image to saturate

[0.01 0.99] (default) | numeric scalar | 2-element numeric vector

Fraction of the image to saturate, specified as a numeric scalar or two-element vector [Low_Fract High_Fract] in the range [0 1].

Value	Description
Scalar	If Tol is a scalar, then Low_Fract = Tol, and High_Fract = 1 - Low_Fract, which saturates equal fractions at low and high pixel values.
0	If Tol = 0, then lowhigh = [min(I(:)); max(I(:))].
Default	If you omit the Tol argument, then [Low_Fract High_Fract] defaults to [0.01 0.99], saturating 2%.
Too big	If Tol is too big, such that no pixels would be left after saturating low and high pixel values, then stretchlim returns [0 1].

Example: lohi = stretchlim(I,[.02 .80]);

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

lowhigh — Lower and upper limits for contrast stretching

2-element numeric vector | 2-by-3 numeric matrix | gpuArray

Lower and upper limits for contrast stretching, returned as one of the following.

• A 2-element numeric vector when I is a grayscale image.

• A 2-by-3 numeric matrix when I is an RGB image. The columns indicate the lower and upper limit for each of the three color channels.

If the limits are computed using a GPU, then lowhigh is returned as a gpuArray containing a 2-element numeric vector or a 2-by-3 numeric array.

Data Types: double

Tips

• Use the imadjust function to adjust the contrast of image I using the limits, lowhigh.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• This function supports the generation of C code using MATLAB^® Coder™. Note that if you choose the generic MATLAB Host Computer target platform, the function generates code that uses a precompiled, platform-specific shared library. Use of a shared library preserves performance optimizations but limits the target platforms for which code can be generated. For more information, see Understand Code Generation with Image Processing Toolbox.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Image Processing on a GPU.