In addition, the weights associated with each output pixel are returned. The weight of an output pixel indicates the number of input pixels which have been accumulated in that output pixel. If the entire value of an input pixel is assigned to a single output pixel, then the weight of that output pixel is incremented by one. If some fraction of the value of an input pixel is assigned to an output pixel, then the weight of that output pixel is incremented by the fraction used.
The start of a new sequence is indicated by specifying the AST__REBININIT flag via the "flags" parameter. This causes the supplied arrays to be filled with zeros before the rebinned input data is added into them. Subsequenct invocations within the same sequence should omit the AST__REBININIT flag.
The last call in a sequence is indicated by specifying the
AST__REBINEND flag. Depending on which flags are supplied, this may
cause the output data and variance arrays to be normalised before
being returned. This normalisation consists of dividing the data
array by the weights array, and can eliminate artifacts which may be
introduced into the rebinned data as a consequence of aliasing
between the input and output grids. This results in each output
pixel value being the weighted mean of the input pixel values that
fall in the neighbourhood of the output pixel (rather like
astResampleX
astResampleX).
Optionally, these normalised
values can then be multiplied by a scaling factor to ensure that the
total data sum in any small area is unchanged. This scaling factor
is equivalent to the number of input pixel values that fall into each
output pixel. In addition to
normalisation of the output data values, any output variances are
also appropriately normalised, and any output data values with
weight less than
"wlim" are set to "badval".
Output variances can be generated in two ways; by rebinning the supplied input variances with appropriate weights, or by finding the spread of input data values contributing to each output pixel (see the AST__GENVAR and AST__USEVAR flags).
The number of input coordinates used by this Mapping (as given by its NinNin attribute) should match the number of input grid dimensions given by the value of "ndim_in" below. Similarly, the number of output coordinates (NoutNout attribute) should match the number of output grid dimensions given by "ndim_out". If "in" is NULL, the Mapping will not be used, but a valid Mapping must still be supplied.
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.
Not used if "in" is NULL.
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 a NULL pointer is supplied for "in", then no data is added to the output arrays, but any initialisation or normalisation requested by "flags" is still performed.
If no additional parameters are required, this array is not used and a NULL pointer may be given. Not used if "in" is NULL.
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. Not used if "in" is NULL.
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. Not used if "in" is NULL.
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).
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 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. Not used if "in" is NULL.
Note that, unlike
astResampleX
, the astRebinSeq
X
set of functions does not yet support unsigned integer data types
or integers of different sizes.
This flag should normally be supplied on each invocation of
astRebinSeqX
within a given sequence.
Note, this flag cannot be used in conjunction with the AST__NOSCALE flag (an error will be reported if both flags are specified).
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.