visionhdl.Histogram

Frequency distribution

Description

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?

Creation

Syntax

histo = visionhdl.Histogram

histo = visionhdl.Histogram(Name,Value)

Description

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.

Properties

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.

NumBins — Number of histogram bins

'256' (default) | '32' | '64' | '128' | '512' | '1024' | '2048' | '4096'

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 2^WL, the object truncates the least-significant bits of each pixel. If the number of bins is greater than 2^WL, some bins are impossible to hit, and when you synthesize your design it will use more hardware resources than necessary.

Data Types: char | string

OutputDataType — Data type of histogram values

'Unsigned fixed point' (default) | 'double' | 'single'

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

OutputWordLength — Histogram bin word length

16 (default) | positive integer

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

Dependencies

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

Usage

Syntax

histo(~,~,~,~)

[dataout,readrdy,validout] = histo(pixelin,ctrlin,~,0)

[dataout,readrdy,validout] = histo(~,~,binaddr,0)

[dataout,readrdy,validout] = histo(~,~,binaddr,binreset)

Description

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

pixelin — Input pixel stream

unsigned scalar

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

ctrlin — Control signals accompanying input pixel stream

pixelcontrol structure

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

binaddr — Bin number for reading histogram values

nonnegative integer

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)

binreset — Reset histogram bin values

true or 1 | false or 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

readrdy — Indicates histogram bins available for read

true or 1 | false or 0

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

dataout — Bin value for requested address

nonnegative integer

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.

validout — Indicates that histogram value is valid

true or 1 | false or 0

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:

release(obj)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Compute Histogram of Image

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);
figure
imshow(frmInput,'InitialMagnification',300)
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(...
      'NumComponents',1,...
      'VideoFormat','custom',...
      'ActivePixelsPerLine',frmActivePixels,...
      'ActiveVideoLines',frmActiveLines,...
      'TotalPixelsPerLine',frmActivePixels+10,...
      'TotalVideoLines',frmActiveLines+10,...
      'StartingActiveLine',6,...     
      'FrontPorch',5);

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  
    histo(uint8(0),noOpCtrl,noAddr,noReset);
end

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);
end

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);        
     end
  end  
end

Graph the bin values.

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

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

for p = 1:bins  
    histo(uint8(0),noOpCtrl,noAddr,noReset);
end

Algorithms

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

Extended Capabilities

C/C++ Code Generation

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

This System object supports C/C++ code generation for accelerating MATLAB^® simulations, and for DPI component generation. For more information about acceleration, see Accelerate Pixel-Streaming Designs Using MATLAB Coder. For more information about DPI component generation, see Considerations for DPI Component Generation with MATLAB (HDL Verifier).

HDL Code Generation

Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

To generate HDL code from Vision HDL Toolbox System objects, see Design Hardware-Targeted Image Filters in MATLAB.

Version History

Introduced in R2015a

R2022b: Two pixels-per-clock streaming

The object now supports multipixel streams that have 2 pixels per clock cycle.

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.

R2022a: Multipixel streaming

The object now supports multipixel streams. For multipixel streaming, the object supports input column vectors of 4, or 8 pixels. The ctrl argument remains scalar, and the control signals in the pixelcontrol structure apply to all pixels in the vector. The output interface is the same whether the input is scalar or vector.

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.

R2019b: Increased histogram sizes

You can now configure the object to have 2048 or 4096 histogram bins.