imhist

Histogram of image data

Syntax

[counts,binLocations]
= imhist(I)

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

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

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,cmap) calculates the histogram for the indexed image X with colormap cmap. The histogram has one bin for each entry in the colormap.

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 colormap cmap.

example

Examples

collapse all

Calculate Histogram

Open Live Script

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)

Figure contains 2 axes objects. Axes object 1 contains an object of type stem. Axes object 2 contains 2 objects of type image, line.

Display the Histogram of a 3-D Intensity Image

Open Live Script

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)

Figure contains 2 axes objects. Axes object 1 contains an object of type stem. Axes object 2 contains 2 objects of type image, line.

Input Arguments

collapse all

`I` — Grayscale image
numeric array

Grayscale image, specified as a numeric array of any dimension. The imhist function expects images of data type double and single to have values in the range [0, 1]. If I has values outside the range [0, 1], then you can rescale values to the expected range by using the rescale function..

`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

`X` — Indexed image
numeric array

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

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

`cmap` — Colormap
c-by-3 numeric matrix

Colormap 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 colormap. The colormap must be at least as long as the largest index in X.

Data Types: double

Output Arguments

collapse all

`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 colormap, cmap.

`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 \leq 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 data type of the image as follows:

Data Type A B
double 1 0
single 1 0
int8 255 128
int16 65,535 32,768
int32 4,294,967,295 2,147,483,648
uint8 255 0
uint16 65,535 0
uint32 4,294,967,295 0
logical 1 0
To display the histogram from counts and binLocations, use the command stem(binLocations,counts).

Data Type	A	B
`double`	`1`	`0`
`single`	`1`	`0`
`int8`	`255`	`128`
`int16`	`65,535`	`32,768`
`int32`	`4,294,967,295`	`2,147,483,648`
`uint8`	`255`	`0`
`uint16`	`65,535`	`0`
`uint32`	`4,294,967,295`	`0`
`logical`	`1`	`0`

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 Types of Code Generation Support in Image Processing Toolbox.
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.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

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.

Version History

Introduced before R2006a

expand all

R2022b: Support for thread-based environments

imhist now supports thread-based environments.

imhist

Syntax

Description

Examples

Calculate Histogram

Display the Histogram of a 3-D Intensity Image

Input Arguments

I — Grayscale image numeric array

n — Number of bins positive integer

X — Indexed image numeric array

cmap — Colormap c-by-3 numeric matrix

Output Arguments

counts — Histogram counts numeric array

binLocations — Bin locations numeric array

Tips

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

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

Version History

R2022b: Support for thread-based environments

See Also

`I` — Grayscale image
numeric array

`n` — Number of bins
positive integer

`X` — Indexed image
numeric array

`cmap` — Colormap
c-by-3 numeric matrix

`counts` — Histogram counts
numeric array

`binLocations` — Bin locations
numeric array

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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