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.

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

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

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

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\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 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).

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

R2022b: Support for thread-based environments

imhist now supports thread-based environments.