# NAME

cxLookupInterp - interpolate lattice data at one coordinate location

# C SPECIFICATION

#include <cx/Lookup.h>

int cxLookupInterp(cxLookup *lut, float *loc, void *val)

# FORTRAN SPECIFICATION

```integer function cxLookupInterp(lut, loc, val)
integer lut
real loc(*)
<type> val
```

# PARAMETERS

lut
Input lookup table structure.
loc
Input vector of the point location at which to look up data.
val
Output vector of data interpolated at location loc.

# FUNCTION RETURN VALUE

The return value for this function is an error code.

# DESCRIPTION

Interpolates using the lookup table lut at the sample point coordinates in the vector loc and stores the values into vector val. The number of values and the primitive type of the returned values, val, are identical to the nDataVar and primType of the lattice used to generate lut. The number of entries in loc is equal to the coordinate dimensionality, nCoordVar, of the lattice used to generate lut (for uniform and perimeter lattices nCoordVar equals nDim). The caller of cxLookupInterp should take care to allocate sufficient space in val and interpret the results in the right type.

For curvilinear lattices with nCoordVar > nDim (scattered data) NAG routines are used for interpolation within the bounding box, while an error exit is returned outside the bounding box. Strictly speaking this is a combination of interpolation (for points inside the lattice domain) and extrapolation (for points outside the lattice domain but inside the bounding box). The nearest neighbor method is faster, but less accurate than, the linear method.

When using this method the function returns zero to indicate success and one if a domain error is encountered, meaning that the sample point was outside the bounding box of the lattice. The returned vals are set to zero in this case.

For curvilinear lattices with nDim = nCoordVar (structured meshes), as well as all uniform and perimeter lattices, cxLookupInterp interpolates data by a three step process. First, it calculates which lattice cell contains the point loc. The cell is numbered according to the zero-based default uniform coordinate system for lattices. Second, cxLookupInterp calculates the fractional indices of the coordinate point within the cell. These fractional indices lie between zero and one in each index dimension of the lattice. Third, cxLookupInterp interpolates the corner values of the chosen cell according to the fractional indices found in step two. For uniform and perimeter lattices, steps one and two are performed at the same time and step three is inexpensive.

For curvilinear lattices in this category, a k-D tree is used to partition the k-dimensional coordinate space of the lattice so that the cell identification of step one runs quickly. A Newton iteration is performed in step two to discover the fractional lattice indices which, when interpolated in the lattice's coordinate space, yield the input coordinate location loc. Finally, the fractional indices are interpolated in data space to yield the data val. Both steps one and two are more expensive for curvilinear lattices than for uniform or perimeter lattices.

When using this method, the function returns zero to indicate success and one if a domain error is encountered, meaning that the sample point was outside the coordinate space of the lattice. For domains errors in uniform and perimeter lattices, the sample point is clamped to the domain and the interpolation is performed at that clamped value. For domains errors in curvilinear lattices, the returned vals are set to zero.

Lookup tables are used to preprocess colormap information for later color lookup, for example in the Contour module. Lookup tables are also used in the Interpolate and PickLat modules for data interpolation, and in modules that calculate particle trajectories, such as NAGAdvectSimple and NAGAdvectAnimate.