AST_UINTERP

Perform sub-pixel interpolation on a grid of data

Description:

This is a fictitious routine which does not actually exist. Instead, this description constitutes a template so that you may implement a routine with this interface for yourself (and give it any name you wish). Such a routine may be passed via the FINTERP argument of the AST_RESAMPLE$<$X$>$ functions (q.v.) in order to perform sub-pixel interpolation during resampling of gridded data (you must also set the INTERP argument of AST_RESAMPLE$<$X$>$ to the value AST__UINTERP). This allows you to use your own interpolation algorithm in addition to those which are pre-defined.

The routine interpolates an input grid of data (and, optionally, processes associated statistical variance estimates) at a specified set of points.

Invocation

CALL AST_UINTERP( NDIM_IN, LBND_IN, UBND_IN, IN, IN_VAR, NPOINT, OFFSET, COORDS, PARAMS, FLAGS, BADVAL, OUT, OUT_VAR, NBAD, STATUS )

Arguments

NDIM_IN = INTEGER (Given)
The number of dimensions in the input grid. This will be at least one.
LBND_IN( NDIM_IN ) = INTEGER (Given)
An array containing the coordinates of the centre of the first pixel in the input grid along each dimension.
UBND_IN( NDIM_IN ) = INTEGER (Given)
An array containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that LBND_IN and UBND_IN together define the shape, size and coordinate system of the input grid in the same way as they do in AST_RESAMPLE$<$X$>$.

IN( $\ast$ ) = $<$Xtype$>$ (Given)
An array, with one element for each pixel in the input grid, containing the input data. This will be the same array as was passed to AST_RESAMPLE$<$X$>$ via the IN argument. The numerical type of this array should match that of the data being processed.
IN_VAR( $\ast$ ) = $<$Xtype$>$ (Given)
An optional second array with the same size and type as the IN array. This will only be given if the AST__USEVAR flag is set via the FLAGS argument (below). If given, it will contain the set of variance values associated with the input data and will be the same array as was passed to AST_RESAMPLE$<$X$>$ via the IN_VAR argument.

If the AST__USEVAR flag is not set, then no variance values are being processed. In this case, this array of variance values may be a dummy (e.g. one-element) array and should not be used.

NPOINT = INTEGER (Given)
The number of points at which the input grid is to be interpolated. This will be at least one.
OFFSET( NPOINT ) = INTEGER (Given)
For each interpolation point, this array will contain the offset from the start of the OUT (and OUT_VAR) array(s) at which the interpolated value (and its variance, if required) should be stored. For example, the interpolated value for point number POINT should be stored in OUT(1$+$OFFSET(POINT)).
COORDS( NPOINT, NDIM_IN ) = DOUBLE PRECISION (Given)
A 2-dimensional array containing the coordinates of the points at which interpolation should be performed. These will be stored so that coordinate number COORD for interpolation point number POINT is found in element COORDS(POINT,COORD).

If any interpolation point has any of its coordinates equal to the value AST__BAD (as defined in the AST_PAR include file), then the corresponding output data (and variance) should either be set to the value given by BADVAL, or left unchanged, depending on whether the AST__NOBAD flag is specified by FLAGS.

PARAMS( $\ast$ ) = DOUBLE PRECISION (Given)
This will be the same array as was given via the PARAMS argument of AST_RESAMPLE$<$X$>$. You may use this to pass any additional parameter values required by your interpolation algorithm.
FLAGS = INTEGER (Given)
This will be the same value as was given via the FLAGS argument of AST_RESAMPLE$<$X$>$. You may test this value to provide additional control over the operation of your resampling algorithm. Note that the special flag values AST__URESAMP1, 2, 3 & 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see AST_RESAMPLE$<$X$>$).
BADVAL = $<$Xtype$>$ (Given)
This will be the same value as was given for the BADVAL argument of AST_RESAMPLE$<$X$>$, and will have the same numerical type as the data being processed (i.e. as elements of the IN array). It should be used to test for bad pixels in the input grid (but only if the AST__USEBAD flag is set via the FLAGS argument) and (unless the AST__NOBAD flag is set in FLAGS) for identifying bad output values in the OUT (and OUT_VAR) array(s).
OUT( $\ast$ ) = $<$Xtype$>$ (Returned)
An array with the same numerical type as the IN array, into which the interpolated data values should be returned. Note that details of the storage order and number of dimensions of this array are not required, since the OFFSET array contains all necessary information about where each returned value should be stored.

In general, not all elements of this array (or the OUT_VAR array below) may be used in any particular invocation of the routine. Those which are not used should be returned unchanged.

OUT_VAR( $\ast$ ) = $<$Xtype$>$ (Returned)
An optional array with the same type and size as the OUT array, into which variance estimates for the resampled values should be returned. This array will only be given if the AST__USEVAR flag is set via the FLAGS argument.

If given, it is addressed in exactly the same way (via the OFFSET array) as the OUT array. The values returned should be estimates of the statistical variance of the corresponding values in the OUT array, on the assumption that all errors in input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors).

If the AST__USEVAR flag is not set, then variance values are not being processed. In this case, this array may be a dummy (e.g. one-element) array and should not be used.

• The data type $<$Xtype$>$ indicates the numerical type of the data being processed, as for AST_RESAMPLE$<$X$>$.
• This routine will typically be invoked more than once for each invocation of AST_RESAMPLE$<$X$>$.
• If an error occurs within this routine, it should set the STATUS argument to an error value before returning. This will cause an immediate return from AST_RESAMPLE$<$X$>$. The error value AST__UINER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). The AST__UINER error value is defined in the AST_ERR include file.