NAME

cxLookupInterpV - interpolate lattice data at a vector of coordinate locations

C SPECIFICATION

#include <cx/Lookup.h>

int cxLookupInterpV(cxLookup *lut, int n, float *loc, void *val)

FORTRAN SPECIFICATION

integer function cxLookupInterpV(lut, n, loc, val)
integer lut, n, val
real loc(n)

PARAMETERS

lut: Input lookup table structure.
n: Input number of locations stored in vector loc.
loc: Input vector of the n point locations at which to look up data.
val: Output vector of data interpolated at n locations loc.

FUNCTION RETURN VALUE

The return value for this function is the number of domain errors encountered.

DESCRIPTION

Interpolates using the lookup table lut at the n sample point coordinates in the vector loc and stores the values into vector val. The number of components in each interpolated 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 components in each location 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 cxLookupInterpV should take care to allocate sufficient space in val and interpret the results in the right type.

cxLookupInterpV interpolates data at each point by the same method as cxLookupInterp.

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 at least one 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, cxLookupInterpV 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, cxLookupInterpV 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, cxLookupInterpV 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 the number of domain errors encountered, that is, the number of sample points that were 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.