# 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

example

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

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.

`"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.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]`.

## Version History

Introduced in R2024a