hdl.npufun

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

Since R2022b

Syntax

output_data = hdl.npufun(kernelFun,kernelSize,input_data)

output_data = hdl.npufun(kernelFun,kernelSize,input_data,Name,Value)

Description

output_data = hdl.npufun(kernelFun,kernelSize,input_data) applies the kernelFun function to each sliding window of the input data, input_data, using a sliding window determined by kernelSize. The function outputs one argument for each output argument in the function kernelFun.

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.

output_data = hdl.npufun(kernelFun,kernelSize,input_data,Name,Value) applies the function using optional name-value arguments.

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, multiples 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

kernelFun — Kernel operator

function handle

Kernel operator, specified as a function handle. hdl.npufun applies the kernelFun function to each sliding window of kernelSize of the input data. The function calls kernelFun for each kernelSize window of the input and computes an element of the output.

Example: @blurringKernel

kernelSize — Size of kernel

2-D positive integer array

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

Example: [3,3]

input_data — 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 input_data from a frame input to single values streamed as sampled inputs. The hdl.npufun function applies the kernelFun function to each element of the streaming input data input_data.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'BoundaryConstant', 5

BoundaryConstant — Boundary constant around streamed input data

0 (default) | numeric scalar

Boundary constant to apply around the 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.

KernelArg — Kernel input value used in neighborhood processing algorithm

numeric scalar

Kernel input value used in the neighborhood processing algorithm in the kernelFun function, specified as a numeric scalar. This value can be any input that is not streamed from frame to samples by the frame-to-sample conversion. You can pass multiple non-streamed kernel inputs by using this name-value argument more than once. When you specify KernelArg, ensure the input arguments in the hdl.npufun function are in the same order as the streamed and non-streamed input arguments in the kernelFun function.

Example: hdl.npufun(@kernelFun,kernelSize,input_data,'KernelArg',3,'KernelArg',7.8);

BoundaryMethod — Boundary replication method

'constant' (default) | 'replicate'

Since R2024a

Boundary replication method to set during frame-to-sample conversions, specified as constant or replicate.

To pad an array of pixels with a constant value, use constant. To pad the array of pixels by repeating the border, use replicate.

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

Example: hdl.npufun(@kernelFun,kernelSize,input_data,'BoundaryMethod','replicate');

Output Arguments

output_data — Output of kernel operation

2-D numeric array | 3-D numeric array

Output of the kernel operation in the kernelFun function, returned as a 2-D or 3-D numeric array. The size of output_data is the size of input_data.

You can specify multiple output arguments for hdl.npufun if the kernelFun 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).

Version History

Introduced in R2022b

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.