astRebinSeq <X >

Rebin a region of a sequence of data grids

Description:

This set of functions is identical to astRebin <X > except that the rebinned input data is added into the supplied output arrays, rather than simply over-writing the contents of the output arrays. Thus, by calling this function repeatedly, a sequence of input arrays can be rebinned and accumulated into a single output array, effectively forming a mosaic of the input data arrays.

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 astResample <X >). 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).

Synopsis

void astRebinSeq <X >( 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[], double weights[], int64_t nused );

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" . If " in" is NULL, the Mapping will not be used, but a valid Mapping must still be supplied.

wlim
This value is only used if the AST__REBINEND flag is specified via the " flags" parameter. It gives the required number of input pixel values which must contribute to an output pixel (i.e. the output pixel weight) 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. If the supplied value is less than 1.0E-10 then 1.0E-10 is used instead.
ndim_in
The number of dimensions in the input grid. This should be at least one. Not used if " in" is NULL.
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. Not used if " in" is NULL.
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. Not used if " in" is NULL.

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 astRebinSeqF, 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). 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.

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 neither the AST__USEVAR nor the AST__VARWGT flag is set, no input variance estimates are required and this pointer will not be used. A NULL pointer may then be supplied.
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 in the description of the astRebin <X > functions. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST__LINEAR). Not used if " in" is NULL.
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 in the description of the astRebin <X > functions.

If no additional parameters are required, this array is not used and a NULL pointer may be given. See also flag AST__PARWGT. Not used if " in" is NULL.

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. Not used if " in" is NULL.

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. Not used if " in" is NULL.

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. Not used if " in" is NULL.
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. Not used if " in" is NULL.

out
Pointer to an array, with one element for each pixel in the output grid. The rebined data values will be added into the original contents of this array. 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
A pointer to an array with the same type and size as the " out" array. This pointer will only be used if the AST__USEVAR or AST__GENVAR flag is set in which case variance estimates for the rebined data values will be added into the array. If neither the AST__USEVAR flag nor the AST__GENVAR flag is set, no output variance estimates will be calculated and this pointer will not be used. A NULL pointer may then be supplied.
weights
Pointer to an array of double, with one or two elements for each pixel in the output grid, depending on whether or not the AST__GENVAR flag has been supplied via the " flags" parameter. If AST__GENVAR has not been specified then the array should have one element for each output pixel, and it will be used to accumulate the weight associated with each output pixel. If AST__GENVAR has been specified then the array should have two elements for each output pixel. The first half of the array is again used to accumulate the weight associated with each output pixel, and the second half is used to accumulate the square of the weights. In each half, 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).
nused
A pointer to an int64_t containing the number of input data values that have been added into the output array so far. The supplied value is incremented on exit by the number of input values used. The value is initially set to zero if the AST__REBININIT flag is set in " flags" .

Data Type Codes

To select the appropriate rebinning function, you should replace <X > in the generic function name astRebinSeq <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:

For example, astRebinSeqD would be used to process " double" data, while astRebinSeqI would be used to process " int" data, etc.

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

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:

This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the " tol" parameter is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the " tol" parameter until the difference between adjacent panels is sufficiently small to be insignificant.

This flag should normally be supplied on each invocation of astRebinSeq <X > 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).

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 only produced if the AST__REBINEND flag is specified and a pixel has zero weight.

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.

Handling of Huge Pixel Arrays

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 " int" to type " int64_t" (defined in header file stdint.h). The function return type is similarly changed to type int64_t. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astRebinSeq <X > becomes astRebinSeq8 <X >.