imhist

Histogram of image data

Syntax

[counts,binLocations] = imhist(I)

[counts,binLocations] = imhist(I,n)

[counts,binLocations] = imhist(X,map)

imhist(___)

Description

[counts,binLocations] = imhist(I) calculates the histogram for the grayscale image I. The imhist function returns the histogram counts in counts and the bin locations in binLocations. The number of bins in the histogram is determined by the image type.

[counts,binLocations] = imhist(I,n) specifies the number of bins, n, used to calculate the histogram.

[counts,binLocations] = imhist(X,map) calculates the histogram for the indexed image X with color map map. The histogram has one bin for each entry in the color map.

imhist(___) displays a plot of the histogram. If the input image is an indexed image, then the histogram shows the distribution of pixel values above a color bar of the color map map.

Examples

Calculate Histogram

Read a grayscale image into the workspace.

I = imread('pout.tif');

Display a histogram of the image. Since I is grayscale, by default the histogram will have 256 bins.

imhist(I)

Display the Histogram of a 3-D Intensity Image

Load a 3-D dataset.

load mristack

Display the histogram of the data. Since the image is grayscale, imhist uses 256 bins by default.

imhist(mristack)

Input Arguments

I — Grayscale image

numeric array

Grayscale image, specified as a numeric array of any dimension. If the image has data type single or double, then values must be in the range [0, 1]. If I has values outside the range [0, 1], then you can use the rescale function to rescale values to the expected range.

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

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

n — Number of bins

positive integer

Number of bins, specified as a positive integer. If I is a grayscale image, then imhist uses a default value of 256 bins. If I is a binary image, then imhist uses two bins.

Example: 50

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

X — Indexed image

numeric array

Indexed image, specified as a numeric array of any dimension.

Example: [X,map] = imread('trees.tif');

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

map — Color map

c-by-3 numeric matrix

Color map associated with indexed image X, specified as a c-by-3 numeric matrix with values in the range [0, 1]. Each row is a three-element RGB triplet that specifies the red, green, and blue components of a single color of the color map.The color map must be at least as long as the largest index in X.

Example: [X,map] = imread('trees.tif');

Data Types: double

Output Arguments

counts — Histogram counts

numeric array

Histogram counts, returned as a numeric array. If the histogram is computed for an indexed image, X, then the length of counts is the same as the length of the color map, map.

binLocations — Bin locations

numeric array

Bin locations, returned as a numeric array.

Tips

• For grayscale images, the n bins of the histogram are each half-open intervals of width A/(n−1). In particular, the pth bin is the half-open interval

  $$\frac{A(p-1.5)}{(n-1)}-B\le x<\frac{A(p-0.5)}{(n-1)}-B,$$

  where x is the intensity value. The scale factor A and offset B depend on the type of the image class as follows:

  	double	single	int8	int16	int32	uint8	uint16	uint32	logical
  A	1	1	255	65535	4294967295	255	65535	4294967295	1
  B	0	0	128	32768	2147483648	0	0	0	0

• To display the histogram from counts and binLocations, use the command stem(binLocations,counts).

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• imhist supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, imhist 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 Code Generation Using a Shared Library.

• If the first input is a binary image, then n must be a scalar constant of value 2 at compile time.

• Nonprogrammatic syntaxes are not supported. For example, the syntax imhist(I), where imhist displays the histogram, is not supported.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• If the first input is a binary image, then n must be a scalar constant of value 2 at compile time.

• Nonprogrammatic syntaxes are not supported. For example, the syntax imhist(I), where imhist displays the histogram, is not supported.

GPU Arrays

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

Usage notes and limitations:

• imhist does not support indexed images on a GPU.

• When you omit output arguments on a GPU, imhist does not display the histogram. In this case, the function returns the histogram counts in the variable ans and does not return the histogram bin locations.

For more information, see Image Processing on a GPU.