imhist — Compute or display grayscale and indexed-image histograms.
imhist returns histogram counts for grayscale images and indexed images. Statement-form calls render a bar-chart histogram when plotting is available.
Syntax
counts = imhist(I)
counts = imhist(I, n)
[counts, binLocations] = imhist(I)
[counts, binLocations] = imhist(I, n)
counts = imhist(X, map)
[counts, binLocations] = imhist(X, map)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
I | Any | Yes | — | Grayscale intensity image. |
n | NumericScalar | Yes | 256 | Number of bins. |
X | Any | Yes | — | Indexed image matrix. |
map | NumericArray | Yes | — | Colormap with one RGB row per indexed-image bin. |
Returns
| Name | Type | Description |
|---|---|---|
counts | NumericArray | Histogram bin counts as a column vector. |
binLocations | NumericArray | Intensity or colormap-index bin locations as a column vector. |
Returned values from imhist depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:imhist:InvalidArgument | Image input, bin count, or colormap arguments are malformed or unsupported. | imhist: invalid argument |
RunMat:imhist:UnsupportedImage | Input cannot be interpreted as a grayscale or indexed image. | imhist: unsupported image input |
RunMat:imhist:PlotFailed | Statement-form histogram rendering fails. | imhist: plotting failed |
RunMat:imhist:TooManyOutputs | More than two outputs are requested. | imhist: too many output arguments |
RunMat:imhist:Internal | Internal histogram assembly fails. | imhist: internal error |
How imhist works
imhist(I)returns a 256-by-1 count vector for numeric grayscale images.imhist(I, n)returns counts usingnpositive integer bins.[counts, binLocations] = imhist(I)also returns the image-class bin centers.- Count and bin-location outputs are double arrays.
- Floating-point grayscale images must be finite normalized
singleordoubledata in[0, 1]. uint8anduint16grayscale images use class ranges[0, 255]and[0, 65535]respectively.- Logical grayscale images use two bins for false and true values.
- Grayscale input supports int8, int16, int32, uint8, uint16, and uint32 in addition to floating and logical images. Int64 and uint64 images are rejected.
imhist(X, map)treatsXas an indexed image and returns one bin per row of the Nx3 colormap.- Indexed images reject non-finite, non-integer, and out-of-range indices. Colormap values must be finite RGB values in
[0, 1]. - A native typed-integer bin count is available only in
runmatcompatibility mode; MATLAB-compatible mode accepts the documented positive integer-valued double form. - Statement-form
imhist(...)displays the histogram and returns no value. Builds without plotting support complete successfully without rendering.
Does RunMat run imhist on the GPU?
imhist gathers gpuArray inputs before validating image shape and class-specific ranges.
imhist terminates fusion chains because histogram counts depend on all image elements.
GPU memory and residency
imhist returns host-resident count and bin-location tensors because histogram assembly currently runs on the host.
Examples
Count Intensities In A Byte Image
I = uint8([0 1 1; 2 2 2]);
[counts, bins] = imhist(I);
[peak, idx] = max(counts);
[bins(idx), peak]Expected output:
ans =
2 3Use Fewer Bins For A Normalized Image
I = [0 0.25 0.5 1.0];
[counts, bins] = imhist(I, 3);Expected output:
counts =
1
2
1Histogram An Indexed Image
X = [1 2; 3 2];
map = [1 0 0; 0 1 0; 0 0 1];
[counts, bins] = imhist(X, map);Expected output:
counts =
1
2
1Display A Histogram
I = uint8([0 64 128; 128 192 255]);
imhist(I);Using imhist with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how imhist changes the result.
Run a small imhist example, explain the result, then change one input and compare the output.
FAQ
Why does imhist reject double values greater than 1?⌄
MATLAB-style floating-point grayscale images are normalized image data. Use uint8 or uint16 when the values represent byte or word intensities.
How are indexed image offsets handled?⌄
Double and single indexed images use one-based indices into the colormap. uint8, uint16, and logical indexed images use zero-based indices.
Does statement-form imhist always render a plot?⌄
It renders when the plotting backend is available. Headless, no-plot, or non-main-thread contexts complete successfully without producing a value.
Related Image functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how imhist is executed, line by line, in Rust.
- View the source for imhist in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.