fixed.interp3

Interpolation for 3-D gridded data in meshgrid format

Since R2024a

Syntax

Vq = fixed.interp3(X,Y,Z,V,Xq,Yq,Zq)

Vq = fixed.interp3(V,Xq,Yq,Zq)

Vq = fixed.interp3(___,method)

Vq = fixed.interp3(___,method,extrapval)

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.

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

Implement 3-D Fixed-Point Lookup Tables Using Interpolation

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

X,Y,Z — Sample grid points

arrays | vectors

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

V — Sample values

array

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

Xq,Yq,Zq — Query points

scalars | vectors | arrays

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 R³.

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

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

• 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 R³.

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

method — Interpolation method

"linear" (default) | "nearest"

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

Method	Description	Continuity	Comments
"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

extrapval — Function value outside domain of X, Y, and Z

scalar

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

Vq — Interpolated values

scalar | vector | array

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.

Syntaxes	Special Conditions	Size of Vq	Example
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.	Scalar	size(Vq) = [1 1] when you pass Xq, Yq, and Zq as scalars.
Same as above	Xq, Yq, and Zq are vectors of the same size and orientation.	Vector of same size and orientation as Xq, Yq, and Zq	If size(Xq) = [100 1], and size(Yq) = [100 1], and size(Zq) = [100 1], then size(Vq) = [100 1].
Same as above	Xq, 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 above	Xq, Yq, and Zq are arrays of the same size.	Array of the same size as Xq, Yq, and Zq	If 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