hdl.iteratorfun

R2026b

(To be removed) Apply iterative operation to an incoming image or matrix for frame-to-sample conversion

Since R2022b

hdl.iteratorfun will be removed in a future release. Use hdl.iterfun instead. (since R2026b) For more information on updating your code, see Version History.

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

If you specify KernelArg, the kernel function must accept it as an additional input argument after idx, with the syntax out_data = iterFun(element,outputData,idx,kernelArg).

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. The outputData value also acts as persistent state across iterations. The output of iterFun from one iteration is passed back as the outputData input for the next iteration, so you can accumulate results by returning the same variable. 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 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.

Tips

Note

The function hdl.iteratorfun requires a dataflow representation. If you use hdl.iteratorfun in your MATLAB function, open the MATLAB HDL Workflow Advisor. In the HDL Code Generation task, in the Optimizations tab, enable the Aggressive Dataflow Conversion parameter.

Version History

Introduced in R2022b

R2026b: To be removed

The hdl.iteratorfun function will be removed in a future release. Use the hdl.iterfun function instead. There are differences between these functions that require updates to your code.

The hdl.iterfun function represents states explicitly by using persistent variables inside the kernel function. The hdl.iteratorfun function tracks states implicitly by using the kernel input, output, and iteration index arguments.

For example, this table compares the same frame-based algorithm and kernel function using hdl.iteratorfun and hdl.iterfun.

Using hdl.iteratorfun	Using hdl.iterfun
frame = randi(100,1,10); max_init = 0; out = hdl.iteratorfun(@maxKernel, frame, max_init); function max_value = maxKernel(in, max_value, idx) if idx == 1 max_value = 0; end if in > max_value(1) max_value(1) = in; end end	frame = randi(100,1,10); out = hdl.iterfun(@maxKernel, frame, RowColumnInputs=true) function out = maxKernel(in, row, col) persistent p; if isempty(p) p = cast(0,"like",in) end if row == 1 && col == 1 p = cast(0,"like",in) end if in > p p = in; end out = p; end

To update this algorithm from using hdl.iteratorfun to hdl.iterfun, follow these steps.

• Remove the initial value of the output data. In this example, the initial output data is max_init.

• Create a persistent variable inside the kernel function to track the global maximum value of the frame. In this example, the persistent variable is p.

• Use the RowColumnInputs name-value argument to generate row and col kernel function input arguments.

• Replace the kernel function initialization logic that uses the element index input, idx, with initialization logic that uses the row and col kernel function input arguments.

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.