Main Content

hdl.npufun

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

    Description

    example

    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.

    example

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

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

    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 non-sampled 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 sampled input from the input array A. Supply kernelSum with the non-sampled input data coeff.

    A_summed = hdl.npufun(@kernelSum, kernelSize, A, 'NonSampleInput', coeff);

    The argument order of hdl.npufun for the sampled input data A and non-sampled input data coeff must match the input argument order of the kernel function kernelSum. In this example the sampled input data in is first and the non-sampled 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, 'NonSampleInput', 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 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

    Boundary constant to apply around the sampled input data, specified as an integer. Custom boundary constant that is applied around the sampled input array boundary. You can specify only one value for BoundaryConstant.

    Non-sampled input used in neighborhood processing algorithm in kernelFun function, specified as a numeric scalar. You can pass multiple non-sampled inputs by using this name-value argument more than once. When you specify NonSampleInput, ensure the input arguments in the hdl.npufun function are in the same order as the sampled and non-sampled input arguments in the kernelFun function.

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

    Output Arguments

    collapse all

    Output of the kernel operation in the kernelFun function, returned as a 2-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