hdl.iteratorfun

Apply iterative operation to an incoming image or matrix for frame-to-sample conversion

Since R2022b

Syntax

out = hdl.iteratorfun(iterFun,I,outputData)

out = hdl.iteratorfun(iterFun,I,outputData, KernelArg)

Description

out = hdl.iteratorfun(iterFun,I,outputData) applies the iterative operation, iterFun, to each element of the input data I. outputData is the initial value of out and stores the output of each iteration of iterFun. The final value of outputData is the returned function output out.

hdl.iteratorfun supports iterative operations in iterFun, such as looping over arrays to produce a single output to an incoming image or matrix for histogram equalization and to compute statistics such as min and max.

Note

hdl.iteratorfun is a utility function that applies a iterative operation from another function to incoming data.

out = hdl.iteratorfun(iterFun,I,outputData, KernelArg) passes the non-streamed kernel input KernelArg to iterFun.

Examples

Compute Histogram

Compute a histogram from matrix data.

Create the histogram kernel function, hist_kernel_fcn, that takes a histogram of the input array data by binning each sample from the input array and storing the output in hist. The element index input idx must be defined as an input argument to the iterator function when using hdl.iteratorfun, even if idx is not used in the iterator function.

function hist = hist_kernel_fcn(sample, hist, idx)
  hist(sample +1) = hist(sample +1) + 1;
end

Initialize the size of the output data hist_init, which serves as the initialized output for the hist_kernel_fcn function, hist.

hist_init = zeros(1, 256, 'uint32');

Generate histogram data and apply the histogram kernel function, hist_kernel_fcn to the streamed input data data.

out = hdl.iteratorfun(@hist_kernel_fcn, data, hist_init);

Compute Maximum and Maximum Index of Input Data

Compute the maximum value of an input vector data and find the index of that maximum value.

Create an input vector data by using the randi function.

data = randi(100,1,10);

Create the iterator function kernel, max_fun, that finds the first maximum value and the maximum value index of the input array.

function max_val= max_fun(sample, max_val, idx)
  if sample > max_val(1)
    max_val(1) = sample;
    max_val(2) = idx;
  end
end

Initialize the size of the output data max_init, which serves as the initialized output for the max_fun function, max_val.

max_init = [-inf 0];

Calculate the first maximum value and the corresponding index of the input array data by applying the max function, max_fun, to the streamed input from the input array data.

out = hdl.iteratorfun(@max_fun, data, max_init);

Threshold Input Data

Count values above a certain threshold from an input array data.

Create the iterator function kernel, count_kernel, that counts each element of the input array data that is greater than the threshold value specified by the input threshold.

function count = count_kernel(sample, count, idx, threshold)
  if sample > threshold
    count = count + 1;
  end
end

Initialize the size of the output data count_init, which serves as the initialized output for the count_kernel function, count.

count_init = 0;

Count the values from the input data that are greater than the input value threshold by applying the count function, count_kernel to the streamed input from the input array data.

out = hdl.iteratorfun(@count_kernel, data, count_init, threshold);

Input Arguments

iterFun — Iterator function

function handle

Iterator function, specified as a function handle. The function you specify for iterFun must have the syntax out_data = iterFun(element,outputData,idx). The hdl.iteratorfun function passes to iterFun, in the specified input order, an element from the input I, the initialized output data outputData, and the element index idx in the input array I. You must specify each of these input arguments for iterFun, regardless of whether you use them in the iterative operation.

I — Input data for the iterative operation

2-D numeric array | 3-D numeric array

Input data for the iterative operation, specified as a 2-D or 3-D numeric array. The hdl.iteratorfun function applies the iterFun function to each element of the input data I. If this input is a frame-based value, then frame-to-sample conversion converts the input signal you specify for I from a frame input to single values streamed as sampled inputs.

outputData — Initial value for the output

scalar | vector | matrix

Initial value for the output of hdl.iteratorfun, specified as a scalar, vector, or matrix. You must initialize the size of outputData to match the size of the output of hdl.iteratorfun, out, and the size of the output of the iterFun function.

KernelArg — Additional kernel input data

scalar | vector | 2-D matrix

Additional kernel input data, specified as a scalar, vector, or 2-D matrix. This value can be any input that is not streamed from frame to samples by the frame-to-sample conversion. For example, you can use KernelArg in iterFun for to provide a threshold for the input data I.

Output Arguments

out — Output of the iterative operation

scalar | vector | matrix

Output of the iterative operation in iterFun, returned as a scalar, vector, or matrix. The size of out must match the size of outputData.

Version History

Introduced in R2022b

R2024b: Use 3-D matrices as input data

You can use 3-D matrices as input data for the hdl.iteratorfun function when you use the frame-to-sample conversion algorithm. You can perform iterative operations on RGB images or 3-D matrices to generate synthesizable HDL code using the frame-to-sample conversation.

R2022b: Renamed NonSampleInput argument

The input argument NonSampleInput is now called KernelArg. The behavior remains the same.