astRebinX - Rebin a region of a data grid

**Description:**- 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 astRebinSeqX functions 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 astRebinX by an appropriate 1- or 2-character type code. For example, if you are rebinning data with type

`"`float`"`, you should use the function astRebinF (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`"`parameter.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).

- 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.
**Synopsis:**`void astRebinX( AstMapping this, double wlim, int ndim_in, const int lbnd_in[], const int ubnd_in[], const Xtype in[], const Xtype in_var[], int spread, const double params[], int flags, double tol, int maxpix, Xtype badval, int ndim_out, const int lbnd_out[], const int ubnd_out[], const int lbnd[], const int ubnd[], Xtype out[], Xtype out_var[] );`

**Parameters:****this**-
Pointer to a Mapping, whose forward transformation will be
used to transform the coordinates of pixels in the input
grid into the coordinate system of the output grid.
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`"`. **wlim**-
Gives the required number of input pixel values which must contribute
to an output pixel in order for the output pixel value to be
considered valid. If the sum of the input pixel weights contributing
to an output pixel is less than the supplied
`"`wlim`"`value, then the output pixel value is returned set to the supplied bad value. **ndim_in**- The number of dimensions in the input grid. This should be at least one.
**lbnd_in**-
Pointer to an array of integers, with
`"`ndim_in`"`elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. **ubnd_in**-
Pointer to an array of integers, with
`"`ndim_in`"`elements, 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 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. **in**-
Pointer to an array, with one element for each pixel in the
input grid, containing the input data to be rebined. The
numerical type of this array should match the 1- or
2-character type code appended to the function name (e.g. if
you are using astRebinF, the type of each array element
should be
`"`float`"`).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).

**in_var**-
An optional pointer to a second array with the same size and
type as the
`"`in`"`array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the`"`in`"`array. If this array is supplied (together with the corresponding`"`out_var`"`array), then estimates of the variance of the rebined output data will be calculated.If no input variance estimates are being provided, a NULL pointer should be given.

**spread**-
This parameter specifies the scheme to be used for dividing
each input data value up amongst the corresponding output pixels.
It may be used to select
from a set of pre-defined schemes by supplying one of the
values described in the
`"`Pixel Spreading Schemes`"`section below. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST__LINEAR). **params**-
An optional pointer to an array of double which should contain
any additional parameter values required by the pixel
spreading scheme. If such parameters are required, this
will be noted in the
`"`Pixel Spreading Schemes`"`section below.If no additional parameters are required, this array is not used and a NULL pointer may be given.

**flags**-
The bitwise OR of a set of flag values which may be used to
provide additional control over the rebinning operation. See
the
`"`Control Flags`"`section below for a description of the options available. If no flag values are to be set, a value of zero should be given. **tol**-
The maximum tolerable geometrical distortion which may be
introduced as a result of approximating non-linear Mappings
by a set of piece-wise linear transformations. This should be
expressed as a displacement in pixels in the output grid's
coordinate system.
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 the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used.

**maxpix**-
A value which specifies an initial scale size (in pixels) for
the adaptive algorithm which approximates non-linear Mappings
with piece-wise linear transformations. Normally, this should
be a large value (larger than any dimension of the region of
the input grid being used). In this case, a first attempt to
approximate the Mapping by a linear transformation will be
made over the entire input region.
If a smaller value is used, the input 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. **badval**-
This argument should have the same type as the elements of
the
`"`in`"`array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays.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).In all cases, this value is also used to flag any output elements in the

`"`out`"`(and`"`out_var`"`) array(s) for which rebined values could not be obtained (see the`"`Propagation of Missing Data`"`section below for details of the circumstances under which this may occur). **ndim_out**- The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid.
**lbnd_out**-
Pointer to an array of integers, with
`"`ndim_out`"`elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. **ubnd_out**-
Pointer to an array of integers, with
`"`ndim_out`"`elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension.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. **lbnd**-
Pointer to an array of integers, with
`"`ndim_in`"`elements, containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. **ubnd**-
Pointer to an array of integers, with
`"`ndim_in`"`elements, containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array.Note that

`"`lbnd`"`and`"`ubnd`"`together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the`"`lbnd_in`"`and`"`ubnd_in`"`arrays). Regions of the input grid lying outside this region will not be used. **out**-
Pointer to an array, with one element for each pixel in the
output grid, in which the rebined data values will be
returned. The numerical type of this array should match that
of the
`"`in`"`array, and the data storage order 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). **out_var**-
An optional pointer to an array with the same type and size
as the
`"`out`"`array. If given, this array will be used to return variance estimates for the rebined data values. This array will only be used if the`"`in_var`"`array has also been supplied.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 pixel spreading schemes employed.

If no output variance estimates are required, a NULL pointer should be given.

**Data Type Codes**- To select the appropriate rebinning function, you should
replace X in the generic function name astRebinX 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
- F: float
- I: int

`"`double`"`data, while astRebinI would be used to process`"`int`"`data, etc.Note that, unlike astResampleX, the astRebinX set of functions does not yet support unsigned integer data types or integers of different sizes.

- D: double

- To select the appropriate rebinning function, you should
replace X in the generic function name astRebinX 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:
**Pixel Spreading Schemes**- 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
astResampleX
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
astResampleX
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.h`"`header file) may be assigned to the`"`spread`"`parameter. See the astResampleX documentation for details of these schemes including the use of the`"`fspread`"`and`"`params`"`parameters:- AST__NEAREST
- AST__LINEAR
- AST__SINC
- AST__SINCSINC
- AST__SINCCOS
- AST__SINCGAUSS
- AST__SOMBCOS

- AST__GAUSS: This scheme uses a kernel of the form exp(-kxx), 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[1]`"`value and should be at least 0.1. The`"`params[0]`"`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).

- AST__NEAREST

- 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
astResampleX
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
astResampleX
documentation for further discussion.
**Control Flags**- The following flags are defined in the
`"`ast.h`"`header file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the bitwise OR of their values via the`"`flags`"`parameter:- 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__USEBAD: Indicates that there may be bad pixels in the
input array(s) which must be recognised by comparing with the
value given for

- The following flags are defined in the
**Propagation of Missing Data**- 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`"`parameter.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.

- Instances of missing data (bad pixels) in the output grid are
identified by occurrences of the

Starlink User Note 211

R.F. Warren-Smith & D.S. Berry

25th February 2013

E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2014 Science \& Technology Facilities Council