hdl.npufun

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

Since R2022b

collapse all in page

    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.

    example

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

    example

    Examples

    collapse all

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

    collapse all

    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

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

    collapse all

    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

    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.

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

    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

    collapse all

    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

    expand all

    See Also

    Topics