Main Content

hdl.iteratorfun

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

Since R2022b

    Description

    example

    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.

    example

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

    Examples

    collapse all

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

    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

    collapse all

    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.

    Input data for the iterative operation, specified as a 2-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.

    Initial value for the output of hdl.iteratorfun, specified as a scalar, vector, or 2-D 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.

    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

    collapse all

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

    Version History

    Introduced in R2022b

    expand all