Main Content

interpn

Interpolation for 1-D, 2-D, 3-D, and N-D gridded data in ndgrid format

Description

example

Vq = interpn(X1,X2,...,Xn,V,Xq1,Xq2,...,Xqn) returns interpolated values of a function of n variables at specific query points using linear interpolation. The results always pass through the original sampling of the function. X1,X2,...,Xn contain the coordinates of the sample points. V contains the corresponding function values at each sample point. Xq1,Xq2,...,Xqn contain the coordinates of the query points.

Vq = interpn(V,Xq1,Xq2,...,Xqn) assumes a default grid of sample points. The default grid consists of the points, 1,2,3,...ni in each dimension. The value of ni is the length of the ith dimension in V. Use this syntax when you want to conserve memory and are not concerned about the absolute distances between points.

Vq = interpn(V) returns the interpolated values on a refined grid formed by dividing the interval between sample values once in each dimension.

example

Vq = interpn(V,k) returns the interpolated values on a refined grid formed by repeatedly halving the intervals k times in each dimension. This results in 2^k-1 interpolated points between sample values.

example

Vq = interpn(___,method) specifies an alternative interpolation method: 'linear', 'nearest', 'pchip','cubic', 'makima', or 'spline'. The default method is 'linear'.

example

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

If you omit the extrapval argument for queries outside the domain of the sample points, then based on the method argument interpn returns one of the following:

  • The extrapolated values for the 'spline' and 'makima' methods

  • NaN values for other interpolation methods

Examples

collapse all

Define the sample points and values.

x = [1 2 3 4 5];
v = [12 16 31 10 6];

Define the query points, xq, and interpolate.

xq = (1:0.1:5);
vq = interpn(x,v,xq,'cubic');

Plot the result.

figure
plot(x,v,'o',xq,vq,'-');
legend('Samples','Cubic Interpolation');

Figure contains an axes object. The axes object contains 2 objects of type line. One or more of the lines displays its values using only markers These objects represent Samples, Cubic Interpolation.

Create a set of grid points and corresponding sample values.

[X1,X2] = ndgrid((-5:1:5));
R = sqrt(X1.^2 + X2.^2)+ eps;
V = sin(R)./(R);

Interpolate over a finer grid using ntimes=1.

Vq = interpn(V,'cubic');
mesh(Vq);

Figure contains an axes object. The axes object contains an object of type surface.

Create a grid of 2-D sample points using ndgrid.

[x,y] = ndgrid(0:10,0:5);

Create two different sets of sample values at the sample points and concatenate them as pages in a 3-D array. Plot the two sets of sample values against the sample points. Because surf uses meshgrid format for grids, transpose the inputs for plotting.

v1 = sin(x.*y)./(x+1);
v2 = x.*erf(y);
V = cat(3,v1,v2);
tiledlayout(1,2)
nexttile
surf(x',y',V(:,:,1)')
view(2)
nexttile
surf(x',y',V(:,:,2)')
view(2)

Figure contains 2 axes objects. Axes object 1 contains an object of type surface. Axes object 2 contains an object of type surface.

Create a set of query points for interpolation using ndgrid and then use interpn to find the values of each function at the query points. Plot the interpolated values against the query points.

[xq,yq] = ndgrid(0:0.2:10);
Vq = interpn(x,y,V,xq,yq);
tiledlayout(1,2)
nexttile
surf(xq',yq',Vq(:,:,1)')
view(2)
nexttile
surf(xq',yq',Vq(:,:,2)')
view(2)

Figure contains 2 axes objects. Axes object 1 contains an object of type surface. Axes object 2 contains an object of type surface.

Create the grid vectors, x1, x2, and x3. These vectors define the points associated with the values in V.

x1 = 1:100;
x2 = 1:50;
x3 = 1:30;

Define the sample values to be a 100-by-50-by-30 array of random numbers, V.

rng default
V = rand(100,50,30);

Evaluate V at three points outside the domain of x1, x2, and x3. Specify extrapval = -1.

xq1 = [0 0 0];
xq2 = [0 0 51];
xq3 = [0 101 102];
vq = interpn(x1,x2,x3,V,xq1,xq2,xq3,'linear',-1)
vq = 1×3

    -1    -1    -1

All three points evaluate to -1 because they are outside the domain of x1, x2, and x3.

Define an anonymous function that represents $f = te^{-x^{2}-y^{2}-z^{2}}$.

f = @(x,y,z,t) t.*exp(-x.^2 - y.^2 - z.^2);

Create a grid of points in $R^4$. Then, pass the points through the function to create the sample values, V.

[x,y,z,t] = ndgrid(-1:0.2:1,-1:0.2:1,-1:0.2:1,0:2:10);
V = f(x,y,z,t);

Now, create the query grid.

[xq,yq,zq,tq] = ...
ndgrid(-1:0.05:1,-1:0.08:1,-1:0.05:1,0:0.5:10);

Interpolate V at the query points.

Vq = interpn(x,y,z,t,V,xq,yq,zq,tq);

Create a movie to show the results.

figure('renderer','zbuffer');
nframes = size(tq, 4);
for j = 1:nframes
   slice(yq(:,:,:,j),xq(:,:,:,j),zq(:,:,:,j),...
         Vq(:,:,:,j),0,0,0);
   clim([0 10]);
   M(j) = getframe;
end
movie(M);

Input Arguments

collapse all

Sample grid points, specified as real arrays or vectors. The sample grid points must be unique.

  • If X1,X2,...,Xn are arrays, then they contain the coordinates of a full grid (in ndgrid format). Use the ndgrid function to create the X1,X2,...,Xn arrays together. These arrays must be the same size.

  • If X1,X2,...,Xn are vectors, then they are treated as grid vectors. The values in these vectors must be strictly monotonic, either increasing or decreasing.

Example: [X1,X2,X3,X4] = ndgrid(1:30,-10:10,1:5,10:13)

Data Types: single | double

Sample values, specified as a real or complex array. The size requirements for V depend on the size of the grid of sample points defined by X1,X2,...,Xn. The sample points X1,X2,...,Xn can be arrays or grid vectors, but in both cases they define an n-dimensional grid. V must be an array that at least has the same n dimension sizes, but it also can have extra dimensions beyond n:

  • If V also has n dimensions, then the size of V must match the size of the n-dimensional grid defined by X1,X2,...,Xn. In this case, V contains one set of sample values at the sample points. For example, if X1,X2,X3 are 3-by-3-by-3 arrays, then V can also be a 3-by-3-by-3 array.

  • If V has more than n dimensions, then the first n dimensions of V must match the size of the n-dimensional grid defined by X1,X2,...,Xn. The extra dimensions in V define extra sets of sample values at the sample points. For example, if X1,X2,X3 are 3-by-3-by-3 arrays, then V can be a 3-by-3-by-3-by-2 array to define two sets of sample values at the sample points.

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

Example: rand(10,5,3,2)

Data Types: single | double
Complex Number Support: Yes

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

  • If Xq1,Xq2,...,Xqn are scalars, then they are the coordinates of a single query point in Rn.

  • If Xq1,Xq2,...,Xqn are vectors of different orientations, then Xq1,Xq2,...,Xqn are treated as grid vectors in Rn.

  • If Xq1,Xq2,...,Xqn are vectors of the same size and orientation, then Xq1,Xq2,...,Xqn are treated as scattered points in Rn.

  • If Xq1,Xq2,...,Xqn are arrays of the same size, then they represent either a full grid of query points (in ndgrid format) or scattered points in Rn.

Example: [X1,X2,X3,X4] = ndgrid(1:10,1:5,7:9,10:11)

Data Types: single | double

Refinement factor, specified as a real, nonnegative, integer scalar. This value specifies the number of times to repeatedly divide the intervals of the refined grid in each dimension. This results in 2^k-1 interpolated points between sample values.

If k is 0, then Vq is the same as V.

interpn(V,1) is the same as interpn(V).

The following illustration depicts k=2 in R2. There are 72 interpolated values in red and 9 sample values in black.

Nine sample points in a grid with three interpolated points between the sample points in each dimension

Example: interpn(V,2)

Data Types: 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 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

'pchip'Shape-preserving piecewise cubic interpolation (for 1-D only). The interpolated value at a query point is based on a shape-preserving piecewise cubic interpolation of the values at neighboring grid points.C1
  • Requires at least four points

  • Requires more memory and computation time than 'linear'

'cubic'The interpolated value at a query point is based on a cubic interpolation of the values at neighboring grid points in each respective dimension. The interpolation is based on a cubic convolution.C1
  • Grid must have uniform spacing in each dimension, but the spacing does not have to be the same for all dimensions

  • Requires at least four points in each dimension

  • Requires more memory and computation time than 'linear'

'makima'Modified Akima cubic Hermite interpolation. The interpolated value at a query point is based on a piecewise function of polynomials with degree at most three evaluated using the values of neighboring grid points in each respective dimension. The Akima formula is modified to avoid overshoots.C1
  • Requires at least 2 points in each dimension

  • Produces fewer undulations than 'spline'

  • Computation time is typically less than 'spline', but the memory requirements are similar

'spline'The interpolated value at a query point is based on a cubic interpolation of the values at neighboring grid points in each respective dimension. The interpolation is based on a cubic spline using not-a-knot end conditions.C2
  • Requires four points in each dimension

  • Requires more memory and computation time than 'cubic'

Function value outside domain of X1,X2,...,Xn, specified as a real or complex scalar. interpn returns this constant value for all points outside the domain of X1,X2,...,Xn.

Example: 5

Example: 5+1i

Data Types: single | double
Complex Number Support: Yes

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.

  • If you specify sample points with X1,X2,...,Xn, or use the default grid, and V has the same number of dimensions as the n-dimensional grid of sample points, then Vq contains a single set of interpolated values at the query points defined by Xq1,Xq2,...,Xqn.

    • If Xq1,Xq2,...,Xqn are scalars, then Vq is a scalar.

    • If Xq1,Xq2,...,Xqn are vectors of the same size and orientation, then Vq is a vector with the same size and orientation.

    • If Xq1,Xq2,...,Xqn are grid vectors of mixed orientation, then Vq is an array with the same size as the grid implicitly defined by the grid vectors.

    • If Xq1,Xq2,...,Xqn are arrays of the same size, then Vq is an array with the same size.

  • If you specify sample points with X1,X2,...,Xn, or use the default grid, and V has more dimensions than the n-dimensional grid of sample points, then Vq contains multiple sets of interpolated values at the query points defined by Xq1,Xq2,...,Xqn. In this case, the first n dimensions of Vq follow the size rules for a single set of interpolated values above, but Vq also has the same extra dimensions as V with the same sizes.

  • With the syntaxes interpn(V) and interpn(V,k), the interpolation is performed by subdividing the default grid k times (where k=1 for interpn(V)). In this case, Vq is an array with the same number of dimensions as V where the size of the ith dimension is 2^k * (size(V,i)-1)+1.

More About

collapse all

Strictly Monotonic

A set of values that are always increasing or decreasing, without reversals. For example, the sequence, a = [2 4 6 8] is strictly monotonic and increasing. The sequence, b = [2 4 4 6 8] is not strictly monotonic because there is no change in value between b(2) and b(3). The sequence, c = [2 4 6 8 6] contains a reversal between c(4) and c(5), so it is not monotonic at all.

Full Grid (in ndgrid Format)

For interpn, the full grid consists of n arrays, X1,X2,...,Xn, whose elements represent a grid of points in Rn. The ith array, Xi, contains strictly monotonic, increasing values that vary most rapidly along the ith dimension.

Use the ndgrid function to create a full grid that you can pass to interpn. For example, the following code creates a full grid in R2 for the region, 1 ≤ X1 ≤ 3, 1≤ X2 ≤ 4.

[X1,X2] = ndgrid(-1:3,(1:4))
X1 =

    -1    -1    -1    -1
     0     0     0     0
     1     1     1     1
     2     2     2     2
     3     3     3     3


X2 =

     1     2     3     4
     1     2     3     4
     1     2     3     4
     1     2     3     4
     1     2     3     4

Grid Vectors

For interpn, grid vectors consist of n vectors of mixed-orientation that define the points of a grid in Rn.

For example, the following code creates the grid vectors in R3 for the region, 1 ≤ x1 ≤ 3, 4 ≤ x2 ≤ 5, and 6 ≤x3≤ 8:

x1 = 1:3;
x2 = (4:5)';
x3 = 6:8;

Scattered Points

For interpn, scattered points consist of n arrays or vectors, Xq1,Xq2,...,Xqn, that define a collection of points scattered in Rn. The ith array, Xi, contains the coordinates in the ith dimension.

For example, the following code specifies the points, (1, 19, 10), (6, 40, 1), (15, 33, 22), and (0, 61, 13) in R3.

Xq1 = [1 6; 15 0];
Xq2 = [19 40; 33 61];
Xq3 = [10 1; 22 13];

Extended Capabilities

Version History

Introduced before R2006a

expand all