Main Content

fixed.interp3

Interpolation for 3-D gridded data in meshgrid format

Since R2024a

    Description

    Vq = fixed.interp3(X,Y,Z,V,Xq,Yq,Zq) returns interpolated values of a function of three variables at specific query points using linear interpolation. The results always pass through the original sampling of the function. X, Y, and Z contain the coordinates of the sample points. V contains the corresponding function values at each sample point. Xq, Yq, and Zq contain the coordinates of the query points.

    example

    Vq = fixed.interp3(V,Xq,Yq,Zq) assumes a default grid of sample points. The default grid points cover the region, X=1:n, Y=1:m, Z=1:p, where [m,n,p] = size(V). Use this syntax when you want to conserve memory and are not concerned about the absolute distances between points.

    Vq = fixed.interp3(___,method) specifies an alternative interpolation method: "linear" or "nearest". The default method is "linear".

    Vq = fixed.interp3(___,method,extrapval) specifies extrapval, a scalar value that is assigned to all queries that lie outside the domain of the sample points.

    Examples

    collapse all

    This example shows how to implement a three-dimensional fixed-point lookup table using fixed.interp3.

    Run the example multiple times to see the approximation over different query points.

    Create Lookup Table for Function

    Define a function f(x,y,z) to replace with a lookup table approximation.

    clearvars
    f = @(x,y,z) -x.^2+y.^2-y.*z;

    Define breakpoints x, y, and z for the lookup table. Note that m, n, and p do not have to be equal and x, y, and z do not have to be linearly spaced.

    m = 16;
    n = 16;
    p = 16;
    x = linspace(-5,5,n);
    y = linspace(-5,5,m);
    z = linspace(-5,5,p);
    [X,Y,Z] = meshgrid(x,y,z);

    Generate lookup table values V corresponding to the breakpoints.

    V = f(X,Y,Z);

    Query Lookup Table

    Choose a random query point (xq,yq) in the ranges of x and y.

    xq = fixed.example.realUniformRandomArray(x(1),x(end),1);
    yq = fixed.example.realUniformRandomArray(y(1),y(end),1);
    zq = fixed.example.realUniformRandomArray(z(1),z(end),1);

    Cast the inputs to 16-bit fixed-point.

    X = fi(X);
    Y = fi(Y);
    Z = fi(Z);
    V = fi(V);
    xq = fi(xq);
    yq = fi(yq);
    zq = fi(zq);

    The fixed.interp3 function computes vq, the lookup table approximation of f(xq,yq,zq).

    vq = fixed.interp3(X,Y,Z,V,xq,yq,zq)
    vq = 
       21.7305
    
              DataTypeMode: Fixed-point: binary point scaling
                Signedness: Signed
                WordLength: 16
            FractionLength: 9
    

    Compare Lookup Approximation to Actual Function Value

    Compare vq to the actual function evaluation f(xq,yq,zq).

    vq_expected = f(double(xq),double(yq),double(zq))
    vq_expected = 
    21.6975
    
    err = double(vq) - vq_expected
    err = 
    0.0330
    

    Input Arguments

    collapse all

    Sample grid points, specified as real arrays or vectors. The sample grid points must be strictly monotonically increasing in each dimension.

    • If X, Y, and Z are arrays, then they contain the coordinates of a full grid (in meshgrid format). Use the meshgrid function to create the X, Y, and Z arrays together. These arrays must be the same size.

    • If X, Y, and Z are vectors, then they are treated as a grid vectors. The values in these vectors must be strictly monotonically increasing.

    The inputs [X,Y,Z], V, and [Xq,Yq,Zq] must be the same data type: fi, half, single, or double. When using fi data, you can use the shortened function name interp3.

    Example: [X,Y,Z] = fi(meshgrid(1:30,-10:10,1:5))

    Example: [X,Y,Z] = half(meshgrid(1:30,-10:10,1:5))

    Data Types: fi | single | double

    Sample values, specified as a real or complex array. The size requirements for V depend on the size of X, Y, and Z:

    • If X, Y, and Z are arrays representing a full grid (in meshgrid format), then the size of V matches the size of X, Y, or Z.

    • If X, Y, and Z are grid vectors, then size(V) = [length(Y) length(X) length(Z)].

    If V contains complex numbers, then fixed.interp3 interpolates the real and imaginary parts separately.

    The inputs [X,Y,Z], V, and [Xq,Yq,Zq] must be the same data type: fi, half, single, or double. When using fi data, you can use the shortened function name interp3.

    Example: fi(rand(10,10,10),0,12,8)

    Example: half(rand(10,10,10))

    Data Types: fi | single | double
    Complex Number Support: Yes

    Query points, specified as a real scalars, vectors, or arrays.

    • If Xq, Yq, and Zq are scalars, then they are the coordinates of a single query point in R3.

    • If Xq, Yq, and Zq are vectors of different orientations, then Xq, Yq, and Zq are treated as grid vectors in R3.

    • If Xq, Yq, and Zq are vectors of the same size and orientation, then Xq, Yq, and Zq are treated as scattered points in R3.

    • If Xq, Yq, and Zq are arrays of the same size, then they represent either a full grid of query points (in meshgrid format) or scattered points in R3.

    The inputs [X,Y,Z], V, and [Xq,Yq,Zq] must be the same data type: fi, half, single, or double. When using fi data, you can use the shortened function name interp3.

    Example: [Xq,Yq,Zq] = fi(meshgrid((1:0.1:10),(-5:0.1:0),3:5))

    Example: [Xq,Yq,Zq] = half(meshgrid((1:0.1:10),(-5:0.1:0),3:5))

    Data Types: fi | single | double

    Interpolation method, specified as one of the options in this table.

    MethodDescriptionContinuityComments
    "linear"The interpolated value at a query point is based on linear interpolation of the values at neighboring grid points in each respective dimension. This method is the default interpolation method.C0
    • Requires at least two grid points in each dimension

    • Requires more memory than "nearest"

    "nearest"The interpolated value at a query point is the value at the nearest sample grid point. Discontinuous
    • Requires two grid points in each dimension

    • Fastest computation with modest memory requirements

    Function value outside the domain of X, Y, and Z, specified as a real or complex scalar. fixed.interp3 returns this constant value for all points outside the domain of X, Y, and Z. If the scalar value is nonzero and outside the range of the sample values v, then the value is set to the minimum or maximum value of v, whichever is closer.

    The data type of extrapval must be the same as [X,Y,Z], V, and [Xq,Yq,Zq].

    The default behavior with fi input data is to return 0 for query points outside the domain. The default behavior with half, single, or double input data is to return NaN for query points outside the domain.

    Example: fi(5)

    Example: half(5+1i)

    Data Types: fi | single | double
    Complex Number Support: Yes

    Note

    The default behavior of the interp3 function is to return NaN when a query point is outside the domain. The fixed.interp3 function with fi input data is not consistent with this behavior because fi casts NaN to 0.

    Output Arguments

    collapse all

    Interpolated values, returned as a real or complex scalar, vector, or array. The size and shape of Vq depends on the syntax you use and, in some cases, the size and value of the input arguments. The data type of Vq is the same as that of the sample values V.

    SyntaxesSpecial ConditionsSize of VqExample
    fixed.interp3(X,Y,Z,V,Xq,Yq,Zq),
    fixed.interp3(V,Xq,Yq,Zq),
    and variations of these syntaxes that include method or extrapval
    Xq, Yq, and Zq are scalars.Scalarsize(Vq) = [1 1] when you pass Xq, Yq, and Zq as scalars.
    Same as aboveXq, Yq, and Zq are vectors of the same size and orientation.Vector of same size and orientation as Xq, Yq, and ZqIf size(Xq) = [100 1],
    and size(Yq) = [100 1],
    and size(Zq) = [100 1],
    then size(Vq) = [100 1].
    Same as aboveXq, Yq, and Zq are vectors of mixed orientation.size(Vq) = [length(Y) length(X) length(Z)]If size(Xq) = [1 100],
    and size(Yq) = [50 1],
    and size(Zq) = [1 5],
    then size(Vq) = [50 100 5].
    Same as aboveXq, Yq, and Zq are arrays of the same size.Array of the same size as Xq, Yq, and ZqIf size(Xq) = [50 25],
    and size(Yq) = [50 25],
    and size(Zq) = [50 25],
    then size(Vq) = [50 25].

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

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

    Version History

    Introduced in R2024a