hdl.npufun

R2026b

Apply neighborhood processing and element-wise operations to incoming image or matrix for frame-to-sample conversion

Since R2022b

Syntax

out = hdl.npufun(kernelFcn,kernelSize,frame)

out = hdl.npufun(kernelFcn,kernelSize,frame1, ..., frameN)

[out1,...,outN] = hdl.npufun(___)

___ = hdl.npufun(___,"KernelArg",arg)

___ = hdl.npufun(___,Name=Value)

Description

out = hdl.npufun(kernelFcn,kernelSize,frame) applies the kernel function, kernelFcn, to each sliding window of the input data, frame, by using a sliding window determined by the kernel size, kernelSize.

Use hdl.npufun to process neighborhood and element-wise operations performed on frame-based inputs, such as filtering with a kernel.

Note

hdl.npufun is a utility function that applies a neighborhood processing operation from another function to incoming data.

out = hdl.npufun(kernelFcn,kernelSize,frame1, ..., frameN) applies the kernel function to multiple frame-based inputs and outputs one argument.

[out1,...,outN] = hdl.npufun(___) applies the kernel function to each sliding window of the frame-based input data and outputs the same number of outputs as the kernel function.

___ = hdl.npufun(___,"KernelArg",arg) passes the non-frame-based value arg to the kernel function on every function call. The function does not stream the value of arg.

___ = hdl.npufun(___,Name=Value) specifies one or more name-value arguments. Specify the name-value arguments after all the arguments in any of the previous syntaxes.

Examples

Apply Image Processing Algorithm

Apply image blurring to the input image A by using hdl.npufun.

Create the blurring kernel function, blurringKernel, that takes a sample of the image A as the input in, blurs it with an average filter, and outputs the result y.

function y = blurringKernel(in)
  y = sum(in(:),"native")/9;
end

Apply image blurring to the input image A with a kernel window for the blurring algorithm that is a 3-by-3 matrix.

A_blurred = hdl.npufun(@blurringKernel,[3 3],A);

To apply image blurring on the 3-D array or RGB image as an input image I, use this blurring kernel for hdl.npufun function:

I_out = hdl.npufun(@blurringKernel, [5 5], I);


function y = blurringKernel(N)

out_R = sum(reshape(N(:,:,1)/25,[],1));
out_G = sum(reshape(N(:,:,2)/25,[],1));
out_B = sum(reshape(N(:,:,3)/25,[],1));

y = [out_R out_G out_B];

end

When you pass a 3-D matrix to the hdl.npufun function, the function executes the kernel function on each sliding window in the input data. For each plane of the 3-D matrix, the function carries out the sliding window operation based on the defined kernel size. The function then maps the output of the kernel operation for each plane to the corresponding pixels in that plane.

Apply Neighborhood Processing with Custom Boundary Constant

Apply image blurring to an input image with a custom boundary constant.

Create the blurring kernel function, blurringKernel, that takes a sample of the image A as the input in, blurs it with an average filter, and outputs the result y.

function y = blurringKernel(in)
  y = sum(in(:),"native")/9;
end

Apply image blurring to the input image A with a custom boundary constant of five and a kernel window that is a 3-by-3 matrix.

A_blurred = hdl.npufun(@blurringKernel,[3 3],A,BoundaryConstant=5);

Apply Neighborhood Processing with Custom Coefficient for Input Data

Apply a neighborhood processing algorithm to an input array with a custom coefficient that is used in the kernel function.

Create the kernel function, kernelSum, that takes a sample of the input array A as the input in, multiplies it with the input coeff, and sums the output.

function out = kernelSum(in, coeff)​
  out = hdl.treesum(in .* coeff, "all");​
end

Apply the summation algorithm, kernelSum, to the streamed input from the input array A. Supply kernelSum with the input coeff.

A_summed = hdl.npufun(@kernelSum,kernelSize,A,"KernelArg",coeff);

The argument order of hdl.npufun for the streamed input data A and non-streamed input data coeff must match the input argument order of the kernel function kernelSum. In this example, the streamed input data in is first and the non-streamed input data coeff is second. If, for example, the kernelSum function has the syntax kernelSum(coeff, in)​, then hdl.npufun must match the argument order and have the syntax hdl.npufun(@kernelSum,kernelSize,"KernelArg",coeff,A).

Input Arguments

kernelFcn — User-defined kernel function

function handle

User-defined kernel function, specified as a function handle.

The kernel function must:

• Be a named user function

• Not be an anonymous function

• Have a fixed number of inputs and outputs

• Not use the varargin or varargout functions

hdl.npufun calls the kernelFcn function to each sliding window of kernelSize of the input data. The function calls kernelFcn for each kernelSize window of the input and computes an element of the output of hdl.npufun.

Example: @blurringKernel

Data Types: function_handle

kernelSize — Size of kernel window

2-D positive integer array

Size of the kernel or sliding window for the neighborhood processing algorithm in kernelFcn, specified as a 2-D positive integer array.

Example: [3,3]

frame — Input data for neighborhood processing algorithm

2-D numeric array | 3-D numeric array

Input data for the neighborhood processing algorithm to convert in the frame-to-sample conversion, specified as a 2-D or 3-D numeric array.

Frame-to-sample conversion converts the input signal you specify for frame from a frame input to single values streamed as sampled inputs. The hdl.npufun function applies the kernelFcn function to each element of the streaming input data frame.

Example: out = hdl.npufun(@kernelFcn,kernelSize,frame1,frame2);

arg — Non-streamed kernel function input data

scalar | vector | 2-D matrix

Non-streamed kernel function 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 frame-to-sample conversion. You can specify multiple kernel arguments by repeating the "KernelArg" argument. For example:

value1 = 3;
value2 = 7.8;

out = hdl.npufun(@kernelFcn,kernelSize,frame1,"KernelArg",value1,"KernelArg",value2);

function y = kernelFcn(inFrame,value1,value2)
...
end

Example: out = hdl.npufun(@kernelFcn,kernelSize,frame1,"KernelArg",3);

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: BoundaryConstant=5

BoundaryConstant — Boundary constant around streamed input data

0 (default) | numeric scalar

Boundary constant around streamed input data, specified as a numeric scalar. Custom boundary constant that is applied around the streamed input array boundary. You can specify only one value for BoundaryConstant.

BoundaryMethod — Boundary replication method

"constant" (default) | "replicate" | "reflection"

Since R2024a

Boundary replication method, specified as "constant", "replicate", or "reflection".

To pad an array of pixels with a constant value, use constant. To pad an array of pixels by repeating the border, use replicate. To pad an array of pixels with a mirror reflection of the input, such as to provide a continuity of patterns and textures or to remove edge contrast at image boundaries, use reflection.

If BoundaryMethod is set to replicate or reflection, the BoundaryConstant argument has no effect.

Example: hdl.npufun(@kernelFcn,kernelSize,frame1,BoundaryMethod="replicate");

InputProcessingOrder — Order in which function traverses over input frames in simulation

"RowMajor" (default) | "ColumnMajor"

Since R2026b

Order in which the function traverses over the input frames in simulation, specified as "RowMajor" or "ColumnMajor".

If the kernel function uses persistent variables, the value of InputProcessingOrder must match the Input processing order HDL configuration parameter.

Example: out = hdl.npufun(@kernelFcn,kernelSize,frame1,InputProcessingOrder="ColumnMajor");

PaddingSize — Edge padding for frame-based input

"same" (default) | vector of four positive integers

Since R2026b

Edge padding for frame-based input, specified as one of these values:

• "same" — Add edge padding of size calculated by hdl.npufun such that the input and output data are the same size when the stride name-value argument is one.

• Vector [t b l r] of positive integers — Add edge padding of size t to the top, b to the bottom, l to the left, and r to the right of the frame-based input.

Note

Set the BoundaryMethod name-value argument to "constant" when the PaddingSize name-value argument adds edge padding.

Example: out = hdl.npufun(@kernelFcn,[3 3],frame1,PaddingSize="same");

RowColumnInputs — Row and column indices of current output sample

false (default) | true

Since R2026b

Row and column indices of the current output sample, specified as a Boolean.

When this argument is true, the function passes the current row index, row, and the current column index, col, to the kernel function input argument list.

You must manually specify the row and col inputs in your kernel function and row and col must be uint32 data types.

Append the row and col inputs after all windowed and non-windowed inputs to the kernel function.

Example: out = hdl.npufun(@kernelFcn,[3 3],frame1,RowColumnInputs=true);

Stride — Kernel window step size for traversing frame-based input

[1 1] (default) | vector of two positive integers

Since R2026b

Kernel window step size for traversing frame-based input, specified as a vector [r c] of two positive integers where r is the step size in the row dimension and c is the step size in the column dimension.

Example: out = hdl.npufun(@kernelFcn,[3 3],frame1,Stride=[1 2]);

Output Arguments

out — Output of kernel operation

2-D numeric array | 3-D numeric array

Output of the kernel operation in the kernelFcn function, returned as a 2-D or 3-D numeric array. The size of out is the size of frame.

You can specify multiple output arguments for hdl.npufun if the kernelFcn function has multiple output arguments. For example, you can specify multiple outputs for hdl.npufun with syntax like [a,b,c] = hdl.npufun(@multiOutKernel,[3 3],in), where the kernel has the function syntax [a_pix,b_pix,c_pix] = multiOutKernel(in_window).

Limitations

The PaddingSize name-value argument is not supported with multi-sample cycles. When using padding with hdl.npufun, you must set the Samples per cycle HDL configuration parameter to 1.

A value greater than one for the Stride name-value argument is not supported with multi-sample cycles. When using non-unit stride with hdl.npufun, you must set the Samples per cycle HDL configuration parameter to 1.

Extended Capabilities

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

Version History

Introduced in R2022b

R2026b: Support for InputProcessingOrder name-value argument

You can now control how hdl.npufun traverses frame-based input data during simulation. By default, HDL Coder traverses the frame in a row-major order. To traverse the frame in a column-major order, set InputProcessingOrder to "ColumnMajor".

R2026b: Support for PaddingSize name-value argument

You can now retain the edge information of frame-based input data by using the PaddingSize name-value argument of the hdl.npufun function. For example, this code pads all edges of the frame-based input data, frame, with one row of padding to the top and bottom, and one column of padding to the left and right. Each row and column of padding has a value of 0.

out = hdl.npufun(@kernelFcn,[3 3],frame,PaddingSize=[1 1 1 1]);

R2026b: Support for RowColumnInputs name-value argument

You can now track the location of the kernel with respect to the frame-based input by using the RowColumnInputs name-value argument. The row and column arguments must appear at the end of the argument list for the kernel function and must be uint32 data types.

Specify RowColumnInputs as true to pass row and column indices to the kernel function. For example, this code uses hdl.npufun to compute a mean and changes the kernel behavior to boost the pixels in the top-left corner of the frame.

out = hdl.npufun(@computeMean, [3 3], in, RowColumnInputs=true)

function out = computeMean(in, row, col)
    acc = uint32(0);
    for r = 1:3
        for c = 1:3
            acc = acc + uint32(in(r,c));
        end
    end
    meanVal = acc / 9;

    if (row == 1) && (col == 1)
        out = meanVal + uint32(10);
    else
        out = meanVal;
    end
end

R2026b: Support for Stride name-value argument

You can now control how frequently the sliding window of the hdl.npufun function samples the frame-based input data by using the Stride name-value argument. For example, this code traverses the frame-based input data, frame, with a vertical step size of two and a horizontal step size of one.

out = hdl.npufun(@kernelFcn,[3 3],frame,Stride=[2 1]);

R2026a: Support for reflection padding

You can now use reflection padding during frame-to-sample conversions. Reflection padding mirrors the image starting from the edge of the image. To enable reflection padding, set the BoundaryMethod input argument to reflection:

frameOut = hdl.npufun(fcnHandle, kSize, frameIn, ...
"BoundaryMethod", "reflection");

R2024b: Support for non-integer boundary constants

You can now specify the BoundaryConstant argument value as a numeric scalar. Previously, you could specify the value as an integer scalar only.

R2024b: Support for persistent variables with multiple samples per cycle

During the frame-to-sample optimization, you can now use persistent variables in the hdl.npufun kernel function when generating code with multiple samples per cycle. Previously, you could use persistent variable only when generating code with one sample per cycle.

To use persistent variables in hdl.npufun function, in the Configuration Parameters dialog, set:

• Input processing order to RowMajor

• Samples per cycle to any value

R2024b: Use 3-D matrices as input data

You can use 3-D matrices as inputs for the hdl.npufun function when you use the frame-to-sample conversion algorithm. You can now perform neighborhood processing and element-wise operations on RGB images or 3-D matrices to generate synthesizable HDL code using the frame-to-sample conversion.

R2024a: Sequence of name-value arguments

You must now place the input_data and KernelArg arguments before the name-value arguments. For example, this command was allowed in previous releases:

hdl.npufun(@kernel,[3 3],img,'BoundaryConstant',5,'KernelArg',2)

As of R2024a, you must use this syntax order:

hdl.npufun(@kernel,[3 3],img,'KernelArg',2,'BoundaryConstant',5)

R2024a: Support for persistent variables

During the frame-to-sample optimization, you can now use persistent variables in the hdl.npufun kernel functions. You cannot use System objects as persistent variables.

To use persistent variables in hdl.npufun functions, in the Configuration Parameters dialog, set:

• Input processing order is RowMajor.

• Samples per cycle is 1.

R2022b: Renamed NonSampleInput argument

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