You should use a resampling function which matches the numerical type of the data you are processing by replacing X in the generic function name astResampleX by an appropriate 1- or 2-character type code. For example, if you are resampling data with type "float", you should use the function astResampleF (see the "Data Type Codes" section below for the codes appropriate to other numerical types).
Resampling of the grid of input data is performed by transforming the coordinates of the centre of each output grid element (or pixel) into the coordinate system of the input grid. Since the resulting coordinates will not, in general, coincide with the centre of an input pixel, sub-pixel interpolation is performed between the neighbouring input pixels. This produces a resampled value which is then assigned to the output pixel. A choice of sub-pixel interpolation schemes is provided, but you may also implement your own.
This algorithm samples the input data value, it does not integrate it. Thus total data value in the input image will not, in general, be conserved. However, an option is provided (see the "Control Flags" section below) which can produce approximate flux conservation by scaling the output values using the ratio of the output pixel size to the input pixel size. However, if accurate flux conservation is important to you, consder using the astRebinX or astRebinSeqX family of functions instead.
Output pixel coordinates are transformed into the coordinate system of the input grid using the inverse transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping's forward transformation as they are transferred from the input to the output grid (although the Mapping's forward transformation is not explicitly used).
In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel.
This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the output grid which is being used. If this proves to be insufficiently accurate, the output region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly).
The number of input coordinates used by this Mapping (as given by its Nin attribute) should match the number of input grid dimensions given by the value of "ndim_in" below. Similarly, the number of output coordinates (Nout attribute) should match the number of output grid dimensions given by "ndim_out".
Note that "lbnd_in" and "ubnd_in" together define the shape and size of the input grid, its extent along a particular (j'th) dimension being ubnd_in[j]-lbnd_in[j]1 (assuming the index "j" to be zero-based). They also define the input grid's coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre.
The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used).
If no input variance estimates are being provided, a NULL pointer should be given.
Alternatively, you may supply a value which indicates that you will provide your own function to perform sub-pixel interpolation by means of the "finterp " parameter. Again, see the "Sub-Pixel Interpolation Schemes" section below for details.
If the "interp" parameter has any other value, corresponding to one of the pre-defined interpolation schemes, then this function will not be used and you may supply a NULL pointer.
If no additional parameters are required, this array is not used and a NULL pointer may be given.
If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.
If a smaller value is used, the output region will first be divided into sub-regions whose size does not exceed "maxpix" pixels in any dimension. Only at this point will attempts at approximation commence.
This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal.
If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting "tol" to zero). Although this may degrade performance, accurate results will still be obtained.
If the AST__USEBAD flag is set via the "flags" parameter, then this value is used to test for bad pixels in the "in" (and "in_var") array(s).
Unless the AST__NOBAD flag is set via the "flags" parameter, this value is also used to flag any output elements in the "out" (and "out_var") array(s) for which resampled values could not be obtained (see the "Propagation of Missing Data" section below for details of the circumstances under which this may occur). The astResampleX function return value indicates whether any such values have been produced. If the AST__NOBAD flag is set. then output array elements for which no resampled value could be obtained are left set to the value they had on entry to this function.
Note that "lbnd_out" and "ubnd_out" together define the shape, size and coordinate system of the output grid in the same way as "lbnd_in" and "ubnd_in" define the shape, size and coordinate system of the input grid.
Note that "lbnd" and "ubnd" together define the shape and position of a (hyper-)rectangular region of the output grid for which resampled values should be produced. This region should lie wholly within the extent of the output grid (as defined by the "lbnd_out" and "ubnd_out" arrays). Regions of the output grid lying outside this region will not be modified.
The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the sub-pixel interpolation schemes employed.
If no output variance estimates are required, a NULL pointer should be given.
In general, a balance must be struck between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features. The latter will often tend to introduce unwanted oscillations, typically visible as "ringing" around sharp features and edges, especially if the data are under-sampled (i.e. if the sharpest features are less than about two pixels across). In practice, a good interpolation scheme is likely to be a compromise and may exhibit some aspects of both these features.
For under-sampled data, some interpolation schemes may appear to preserve data resolution because they transform single input pixels into single output pixels, rather than spreading their data between several output pixels. While this may look better cosmetically, it can result in a geometrical shift of sharp features in the data. You should beware of this if you plan to use such features (e.g.) for image alignment.
The following are two easy-to-use sub-pixel interpolation schemes which are generally applicable. They are selected by supplying the appropriate value (defined in the "ast.h" header file) via the "interp" parameter. In these cases, the "finterp" and "params" parameters are not used:
From a practical standpoint, it is useful to divide the weighted sum of pixel values by the sum of the weights when determining the interpolated value. Strictly, this means that a true convolution is no longer being performed. However, the distinction is rarely important in practice because (for slightly subtle reasons) the sum of weights is always approximately constant for good interpolation kernels. The advantage of this technique, which is used here, is that it can easily accommodate missing data and tends to minimise unwanted oscillations at the edges of the data grid.
In the following schemes, which are based on a 1-dimensional interpolation kernel, the first element of the "params" array should be used to specify how many pixels are to contribute to the interpolated result on either side of the interpolation point in each dimension (the nearest integer value is used). Execution time increases rapidly with this number. Typically, a value of 2 is appropriate and the minimum value used will be 1 (i.e. two pixels altogether, one on either side of the interpolation point). A value of zero or less may be given for "params" to indicate that a suitable number of pixels should be calculated automatically.
In each of these cases, the "finterp" parameter is not used:
Note, this flag cannot be used in conjunction with the AST__NOBAD flag (an error will be reported if both flags are specified).
AST A Library for Handling World Coordinate Systems in Astronomy