This is a set of functions for rebinning gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a Mapping. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Rebinning may be restricted to a specified region of the input grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the rebined output data. Propagation of missing data (bad pixels) is supported.

Note, if you will be rebining a sequence of input arrays and then co-adding them into a single array, the alternative AST_REBINSEQ$<$X$>$ routines will in general be more efficient.

You should use a rebinning function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST_REBIN$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are rebinning data with type REAL, you should use the function AST_REBINR (see the " Data Type Codes" section below for the codes appropriate to other numerical types).

Rebinning of the grid of input data is performed by transforming the coordinates of the centre of each input grid element (or pixel) into the coordinate system of the output grid. The input pixel value is then divided up and assigned to the output pixels in the neighbourhood of the central output coordinates. A choice of schemes are provided for determining how each input pixel value is divided up between the output pixels. In general, each output pixel may be assigned values from more than one input pixel. All contributions to a given output pixel are summed to produce the final output pixel value. Output pixels can be set to the supplied bad value if they receive contributions from an insufficient number of input pixels. This is controlled by the WLIM argument.

Input pixel coordinates are transformed into the coordinate system of the output grid using the forward 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.

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 input grid which is being used. If this proves to be insufficiently accurate, the input 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).

CALL AST_REBIN$<$X$>$( THIS, WLIM, NDIM_IN, LBND_IN, UBND_IN, IN, IN_VAR, SPREAD, PARAMS, FLAGS, TOL, MAXPIX, BADVAL, NDIM_OUT, LBND_OUT, UBND_OUT, LBND, UBND, OUT, OUT_VAR, STATUS )

THIS = INTEGER (Given)

WLIM = DOUBLE PRECISION (Given)

NDIM_IN = INTEGER (Given)

LBND_IN( NDIM_IN ) = INTEGER (Given)

UBND_IN( NDIM_IN ) = INTEGER (Given)

IN( $\ast$ ) = $<$Xtype$>$ (Given)

IN_VAR( $\ast$ ) = $<$Xtype$>$ (Given)

SPREAD = INTEGER (Given)

PARAMS( $\ast$ ) = DOUBLE PRECISION (Given)

FLAGS = INTEGER (Given)

TOL = DOUBLE PRECISION (Given)

MAXPIX = INTEGER (Given)

BADVAL = $<$Xtype$>$ (Given)

NDIM_OUT = INTEGER (Given)

LBND_OUT( NDIM_OUT ) = INTEGER (Given)

UBND_OUT( NDIM_OUT ) = INTEGER (Given)

LBND( NDIM_IN ) = INTEGER (Given)

UBND( NDIM_IN ) = INTEGER (Given)

OUT( $\ast$ ) = $<$Xtype$>$ (Returned)

OUT_VAR( $\ast$ ) = $<$Xtype$>$ (Returned)

STATUS = INTEGER (Given and Returned)

To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name AST_REBIN$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows:

• D: DOUBLE PRECISION

• R: REAL

• I: INTEGER

• B: BYTE (treated as signed)

• UB: BYTE (treated as unsigned)

For example, AST_REBIND would be used to process DOUBLE PRECISION data, while AST_REBINI would be used to process integer data (stored in an INTEGER array), etc.

Note that, unlike AST_RESAMPLE$<$X$>$, the AST_REBIN$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes.

The pixel spreading scheme specifies the Point Spread Function (PSF) applied to each input pixel value as it is copied into the output array. It can be thought of as the inverse of the sub-pixel interpolation schemes used by the AST_RESAMPLE$<$X$>$ group of functions. That is, in a sub-pixel interpolation scheme the kernel specifies the weight to assign to each input pixel when forming the weighted mean of the input pixels, whereas the kernel in a pixel spreading scheme specifies the fraction of the input data value which is to be assigned to each output pixel. As for interpolation, the choice of suitable pixel spreading scheme involves stricking a balance between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features but which often tend to introduce unwanted artifacts. See the AST_RESAMPLE$<$X$>$ documentation for further discussion.

The binning algorithm used has the ability to introduce artifacts not seen when using a resampling algorithm. Particularly, when viewing the output image at high contrast, systems of curves lines covering the entire image may be visible. These are caused by a beating effect between the input pixel positions and the output pixels position, and their nature and strength depend critically upon the nature of the Mapping and the spreading function being used. In general, the nearest neighbour spreading function demonstrates this effect more clearly than the other functions, and for this reason should be used with caution.

The following values (defined in the AST_PAR include file) may be assigned to the SPREAD parameter. See the AST_RESAMPLE$<$X$>$ documentation for details of these schemes including the use of the FSPREAD and PARAMS arguments:

• AST__NEAREST

• AST__LINEAR

• AST__SINC

• AST__SINCSINC

• AST__SINCCOS

• AST__SINCGAUSS

• AST__SOMBCOS

In addition, the following schemes can be used with AST_REBIN$<$X$>$ but not with AST_RESAMPLE$<$X$>$:

• AST__GAUSS: This scheme uses a kernel of the form exp(-k$\ast$x$\ast$x), with k a positive constant determined by the full-width at half-maximum (FWHM). The FWHM should be supplied in units of output pixels by means of the PARAMS(2) value and should be at least 0.1. The PARAMS(1) value should be used to specify at what point the Gaussian is truncated to zero. This should be given as a number of output pixels on either side of the central output point in each dimension (the nearest integer value is used).

The following flags are defined in the AST_PAR include file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the sum of their values via the FLAGS argument:

• AST__USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for BADVAL and propagated to the output array(s). If this flag is not set, all input values are treated literally and the BADVAL value is only used for flagging output array values.

• AST__USEVAR: Indicates that variance information should be processed in order to provide estimates of the statistical error associated with the rebined values. If this flag is not set, no variance processing will occur and the IN_VAR and OUT_VAR arrays will not be used. (Note that this flag is only available in the Fortran interface to AST.)

Instances of missing data (bad pixels) in the output grid are identified by occurrences of the BADVAL value in the OUT array. These are produced if the sum of the weights of the contributing input pixels is less than WLIM.

An input pixel is considered bad (and is consequently ignored) if its data value is equal to BADVAL and the AST__USEBAD flag is set via the FLAGS argument.

In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the BADVAL value in the OUT_VAR array for similar reasons.

If the input or output grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments LBND_IN, UBND_IN, LBND_OUT, UBND_OUT, LBND, UBND are changed from type INTEGER to type INTEGER$\ast$8. The function return type is similarly changed to type INTEGER$\ast$8. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, AST_REBIN$<$X$>$ becomes AST_REBIN8$<$X$>$.