hdl.npufun
Apply neighborhood processing and element-wise operations to incoming image or matrix for frame-to-sample conversion
Since R2022b
Syntax
Description
applies the output_data
= hdl.npufun(kernelFun
,kernelSize
,input_data
)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.
applies the function using optional name-value arguments.output_data
= hdl.npufun(kernelFun
,kernelSize
,input_data
,Name,Value
)
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
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 R2022bR2024b: 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)
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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)