Main Content


Frequency distribution


The visionhdl.Histogram System object™ computes the frequency distribution of pixel values in a video stream. You can configure the number and size of the bins. The object keeps a running histogram until you clear the bin values and provides a read interface for accessing each bin.

To compute the frequency distribution of pixel values in a video stream:

  1. Create the visionhdl.Histogram object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?



histo = visionhdl.Histogram returns a System object, histo, that computes image histograms over 256 bins. Each bin value is 16 bits wide.


histo = visionhdl.Histogram(Name,Value) sets properties using one or more name-value pairs. Enclose each property name in single quotes.


expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Number of histogram bins, specified as a string or character vector representing a power of two from '32' to '4096'. Choose the number of bins depending on the input word length (WL). If the number of bins is less than 2WL, the object truncates the least-significant bits of each pixel. If the number of bins is greater than 2WL, some bins are impossible to hit, and when you synthesize your design it will use more hardware resources than necessary.

Data Types: char | string

Data type of histogram values, specified as 'Unsigned fixed point', 'double', or 'single'.

The software supports double and single data types for simulation, but not for HDL code generation.

Data Types: char | string

Histogram bin word length, specified as a positive integer. If a bin overflows, the count saturates and the object shows a warning.


To enable this property, set the OutputDataType property to 'Unsigned fixed point'.




histo(~,~,~,~) performs an initial reset phase before processing input data. After object creation or reset, call the object with dummy arguments for NumBins cycles before applying data. You do not have to set the binreset argument to 1 (true) during this phase.


[dataout,readrdy,validout] = histo(pixelin,ctrlin,~,0) adds the input pixel, pixelin, to the internal histogram when the input control signals, ctrl indicate that the pixel is valid. Call the object with this syntax for each pixel in a frame. The object returns readrdy set to 1 (true) when the histogram for the frame is complete. For this syntax, the object returns dataout set to 0 and validout set to 0 (false).

This object uses a streaming pixel interface with a structure for frame control signals. The interface enables the object to operate independently of image size and format and connect with other Vision HDL Toolbox™ objects. The object accepts pixel data as integer, fixed-point, or floating-point data types. The object accepts control signals as a structure containing five signals. The control signals indicate the validity of each pixel and its location in the frame. To convert a pixel matrix into a pixel stream and control signals, use the visionhdl.FrameToPixels object. For a full description of the interface, see Streaming Pixel Interface.


[dataout,readrdy,validout] = histo(~,~,binaddr,0) reads the histogram bin specified by binaddr. Use this syntax after the object returns readrdy set to 1 (true). Call the object with this syntax for each histogram bin. After two further calls to the object (input arguments can change), the object returns dataout set to the bin value at binaddr and validout set to 1 (true).


[dataout,readrdy,validout] = histo(~,~,binaddr,binreset) resets the histogram values when binreset is 1(true). You can initiate the reset while also specifying a binaddr to read. Before applying more video data, complete the reset sequence by calling the object with dummy arguments for NumBins cycles.

To visualize the sequence of operations, see the timing diagrams in the Algorithms section of the Histogram block page.

Input Arguments

expand all

Single image pixel, specified as an unsigned scalar.

You can simulate System objects with a multipixel streaming interface, but you cannot generate HDL code for System objects that use multipixel streams. To generate HDL code for multipixel algorithms, use the equivalent Simulink® blocks.

The software supports double and single data types for simulation, but not for HDL code generation.

Data Types: uint | fi(0,W,0) | logical | double | single

Control signals accompanying the input pixel stream, specified as a pixelcontrol structure containing five logical data type signals. The signals describe the validity of the pixel and its location in the frame. For more details, see Pixel Control Structure.

Data Types: struct

Bin number for reading histogram values, specified as a nonnegative integer. The object expects this input after it has returned readrdy set to 1 (true). The data type must be fixdt(0,log2(NumBins),0).

Data Types: fixdt(0,N,0)

Reset histogram bin values, specified as 1 (true) or 0 (false). A binreset value of 1 (true) triggers a RAM initialization sequence that resets the histogram bin values. It takes NumBins calls to the object to clear all locations and ignores input arguments during this interval.

Data Types: logical

Output Arguments

expand all

Indication that histogram bins are available for read, returned as 1 (true) or 0 (false). When the object sets readrdy to 1 (true), the histogram bins are ready to read. The object returns readrdy as 1 (true) two cycles after the final pixel of a frame.

Data Types: logical

Histogram bin value that corresponds to the requested address, binaddr, returned as a nonnegative integer. The OutputDataType property specifies the data type for this value.

Indication that histogram value is valid, returned as 1 (true) or 0 (false). When the object returns validout as 1 (true), the histogram bin value, dataout, is valid.

Data Types: logical

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:


expand all

stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object


collapse all

Set the dimensions of the test image, and load a source image. Select a portion of the image matching the desired test size.

frmActivePixels = 64;
frmActiveLines = 48;
frmOrig = imread('rice.png');
frmInput = frmOrig(1:frmActiveLines,1:frmActivePixels);
title 'Input Image'

Create a serializer System object™ and define inactive pixel regions. Then, create a histogram System object. The default setting is 256 bins.

frm2pix = visionhdl.FrameToPixels(...

histo = visionhdl.Histogram();
bins = str2double(histo.NumBins);

Serialize the test image. pixelIn is a vector of intensity values and ctrlIn is a vector of control signal structures. Initialize output signals for the histogram results.

[pixelIn,ctrlIn] = frm2pix(frmInput);

[~,~,numPixelsPerFrame] = getparamfromfrm2pix(frm2pix);
readRdy = false(numPixelsPerFrame,1);
dataOut = zeros(bins-1,1,'uint8');
validOut  = false(bins-1,1);
noOpCtrl = pixelcontrolstruct(0,0,0,0,0);
noAddr = uint8(0);
noReset = false;

Call the object with dummy input to initialize the bin memory.

for p = 1:bins  

For each pixel in the padded frame, sort the pixel into a bin. The object returns readRdy as 1 (true) two cycles after the active frame is complete.

for p = 1:numPixelsPerFrame  
   [~,readRdy(p),~] = histo(pixelIn(p),ctrlIn(p),noAddr,noReset);

Once the frame is complete, as indicated by readRdy, read the bin values. The bin addresses are 0:bins-1. The object returns each bin value after two cycles of latency, so call the object bins+2 times.

if readRdy(numPixelsPerFrame) 
  for p = 1:bins+2
     if (p < bins) 
        % Read a normal bin
        [dataOut(p),~,validOut(p)] = histo(uint8(0),noOpCtrl,uint8(p-1),noReset);
     elseif (p == bins)
        % Read the final bin value and initiate binReset
        [dataOut(p),~,validOut(p)] = histo(uint8(0),noOpCtrl,uint8(p-1),true);
     elseif (p > bins) 
        % Flush final bin values with two more calls
        [dataOut(p),~,validOut(p)] = histo(uint8(0),noOpCtrl,noAddr,noReset);        

Graph the bin values.

dataOut = dataOut(validOut==1);
title('Histogram of Input Image')

Call the object with dummy input to clear the bin memory.

for p = 1:bins  


This object implements the algorithms described in the Algorithms section of the Histogram block page.

Extended Capabilities

Version History

Introduced in R2015a

expand all

See Also

| (Image Processing Toolbox) |