

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object uk.ac.starlink.ast.AstObject uk.ac.starlink.ast.Mapping
public class Mapping
Java interface to the AST Mapping class  interrelate two coordinate systems. This class provides the basic facilities for transforming a set of coordinates (representing "input" points) to give a new set of coordinates (representing "output" points). It is used to describe the relationship which exists between two different coordinate systems and to implement operations which make use of this (such as transforming coordinates and resampling grids of data). However, the Mapping class does not have a constructor function of its own, as it is simply a container class for a family of specialised Mappings which implement particular types of coordinate transformation.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.
You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 021101301, USA
Nested Class Summary  

static class 
Mapping.Interpolator
Controls the interpolation scheme used by Mapping 's
resampling methods. 
static class 
Mapping.Spreader
Controls the spreading scheme used by Mapping 's
rebinning methods. 
Field Summary  

static Mapping.Interpolator 
LINEAR_INTERPOLATOR
A linear interpolator for use in the resampling methods. 
static Mapping.Spreader 
LINEAR_SPREADER
A linear spreader for use in the rebinning methods. 
static Mapping.Interpolator 
NEAREST_INTERPOLATOR
A nearestneighbour interpolator for use in the resampling methods. 
static Mapping.Spreader 
NEAREST_SPREADER
A nearestneighbour spreader for use in the rebinning methods. 
Fields inherited from class uk.ac.starlink.ast.AstObject 

AST__BAD, AST__TUNULL, pointer 
Constructor Summary  

protected 
Mapping()
Dummy constructor. 
Method Summary  

Mapping[] 
decompose(boolean[] series,
boolean[] inverts)
Decompose a Mapping into two component Mappings. 
boolean 
getInvert()
Get mapping inversion flag. 
int 
getNin()
Get number of input coordinates for a Mapping. 
int 
getNout()
Get number of output coordinates for a Mapping. 
boolean 
getReport()
Get report transformed coordinates. 
boolean 
getTranForward()
Get forward transformation defined. 
boolean 
getTranInverse()
Get inverse transformation defined. 
void 
invert()
Inverts a mapping by reversing the sense of its Invert attribute. 
double[] 
linearApprox(double[] lbnd,
double[] ubnd,
double tol)
Obtain a linear approximation to a Mapping, if appropriate. 
double[] 
mapBox(double[] lbnd_in,
double[] ubnd_in,
boolean forward,
int coord_out,
double[] xl,
double[] xu)
Find a bounding box for a Mapping. 
Mapping 
mapSplit(int[] in,
int[] out)
Split a Mapping up into parallel component Mappings. 
double 
rate(double[] at,
int ax1,
int ax2)
Calculate the rate of change of a Mapping output. 
void 
rebin(double wlim,
int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
Object in,
Object in_var,
Mapping.Spreader spread,
boolean usebad,
double tol,
int maxpix,
Number badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
Object out,
Object out_var)
Rebin a region of a data grid. 
void 
rebinD(double wlim,
int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
double[] in,
double[] in_var,
Mapping.Spreader spread,
boolean usebad,
double tol,
int maxpix,
double badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
double[] out,
double[] out_var)
Rebinning method specific to double data. 
void 
rebinF(double wlim,
int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
float[] in,
float[] in_var,
Mapping.Spreader spread,
boolean usebad,
double tol,
int maxpix,
float badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
float[] out,
float[] out_var)
Rebinning method specific to float data. 
void 
rebinI(double wlim,
int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
int[] in,
int[] in_var,
Mapping.Spreader spread,
boolean usebad,
double tol,
int maxpix,
int badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
int[] out,
int[] out_var)
Rebinning method specific to int data. 
int 
resample(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
Object in,
Object in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
Number badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
Object out,
Object out_var)
Resample a region of a data grid. 
int 
resampleB(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
byte[] in,
byte[] in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
byte badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
byte[] out,
byte[] out_var)
Resampling method specific to byte data  see the resample method. 
int 
resampleD(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
double[] in,
double[] in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
double badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
double[] out,
double[] out_var)
Resampling method specific to double data  see the resample method. 
int 
resampleF(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
float[] in,
float[] in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
float badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
float[] out,
float[] out_var)
Resampling method specific to float data  see the resample method. 
int 
resampleI(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
int[] in,
int[] in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
int badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
int[] out,
int[] out_var)
Resampling method specific to int data  see the resample method. 
int 
resampleL(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
long[] in,
long[] in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
long badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
long[] out,
long[] out_var)
Resampling method specific to long data  see the resample method. 
int 
resampleS(int ndim_in,
int[] lbnd_in,
int[] ubnd_in,
short[] in,
short[] in_var,
Mapping.Interpolator interp,
ResampleFlags flags,
double tol,
int maxpix,
short badval,
int ndim_out,
int[] lbnd_out,
int[] ubnd_out,
int[] lbnd,
int[] ubnd,
short[] out,
short[] out_var)
Resampling method specific to short data  see the resample method. 
void 
setInvert(boolean invert)
Set mapping inversion flag. 
void 
setReport(boolean report)
Set report transformed coordinates. 
Mapping 
simplify()
Simplify a Mapping. 
double[] 
tran1(int npoint,
double[] xin,
boolean forward)
Transform 1dimensional coordinates. 
double[][] 
tran2(int npoint,
double[] xin,
double[] yin,
boolean forward)
Transform 2dimensional coordinates. 
double[][] 
tranGrid(int ncoord_in,
int[] lbnd,
int[] ubnd,
double tol,
int maxpix,
boolean forward,
int ncoord_out)
Transform a grid of positions. 
double[] 
tranN(int npoint,
int ncoord_in,
double[] in,
boolean forward,
int ncoord_out)
Transform Ndimensional coordinates. 
double[][] 
tranP(int npoint,
int ncoord_in,
double[][] in,
boolean forward,
int ncoord_out)
Transform Ndimensional coordinates held in separate arrays. 
Methods inherited from class uk.ac.starlink.ast.AstObject 

annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune 
Methods inherited from class java.lang.Object 

clone, getClass, notify, notifyAll, toString, wait, wait, wait 
Field Detail 

public static final Mapping.Interpolator NEAREST_INTERPOLATOR
public static final Mapping.Interpolator LINEAR_INTERPOLATOR
public static final Mapping.Spreader NEAREST_SPREADER
public static final Mapping.Spreader LINEAR_SPREADER
Constructor Detail 

protected Mapping()
Method Detail 

public void invert()
public Mapping simplify()
As a simple example, a Mapping which multiplied coordinates by 5, and then multiplied the result by 10, could be simplified to a single step which multiplied by 50. Similarly, a Mapping which multiplied by 5, and then divided by 5, could be reduced to a simple copying operation.
This function should typically be applied to Mappings which have undergone substantial processing or have been formed by merging other Mappings. It is of potential benefit, for example, in reducing execution time if applied before using a Mapping to transform a large number of coordinates.
AstException
 if an error occurred in the AST librarypublic Mapping[] decompose(boolean[] series, boolean[] inverts)
Since the Frame class inherits from the Mapping class, Frames can be considered as special types of Mappings and so this method can be used to decompose either CmpMaps or CmpFrames.
series
 A oneelement array to hold a boolean result indicating whether
the component Mappings are in series or not. If true, the
two Mappings should be joined in series to form this CmpMap,
if false then in parallel. For any object other than a
CmpMap, the returned value will be zero.
If null
is supplied, then the series information
is not returned.inverts
 A twoelement array to hold the Invert attribute vales for
the constituent Mappings.
If null
is supplied, then the inversion information
is not returned.
AstException
 if an error occurred in the AST librarypublic double[] mapBox(double[] lbnd_in, double[] ubnd_in, boolean forward, int coord_out, double[] xl, double[] xu)
The function works on one dimension at a time. When supplied with the lower and upper bounds of a rectangular region (box) of input coordinate space, it finds the lowest and highest values taken by a nominated output coordinate within that region. Optionally, it also returns the input coordinates where these bounding values are attained. It should be used repeatedly to obtain the extent of the bounding box in more than one dimension.
lbnd_in
 Pointer to an array of double, with one element for each
Mapping input coordinate. This should contain the lower bound
of the input box in each input dimension.ubnd_in
 Pointer to an array of double, with one element for each
Mapping input coordinate. This should contain the upper bound
of the input box in each input dimension.
Note that it is permissible for the upper bound to be less than the corresponding lower bound, as the values will simply be swapped before use.
forward
 If this value is nonzero, then the Mapping's forward
transformation will be used to transform the input
box. Otherwise, its inverse transformation will be used.
(If the inverse transformation is selected, then references to "input" and "output" coordinates in this description should be transposed. For example, the size of the "lbnd_in" and "ubnd_in" arrays should match the number of output coordinates, as given by the Mapping's Nout attribute. Similarly, the "coord_out" parameter, below, should nominate one of the Mapping's input coordinates.)
coord_out
 The index of the output coordinate for which the lower and
upper bounds are required. This value should be at least one,
and no larger than the number of Mapping output coordinates.xl
 An optional pointer to an array of double, with one element
for each Mapping input coordinate. If given, this array will
be filled with the coordinates of an input point (although
not necessarily a unique one) for which the nominated output
coordinate attains the lower bound value returned in
"*lbnd_out".
If these coordinates are not required, a NULL pointer may be supplied.
xu
 An optional pointer to an array of double, with one element
for each Mapping input coordinate. If given, this array will
be filled with the coordinates of an input point (although
not necessarily a unique one) for which the nominated output
coordinate attains the upper bound value returned in
"*ubnd_out".
If these coordinates are not required, a NULL pointer may be supplied.
AstException
 if an error occurred in the AST librarypublic Mapping mapSplit(int[] in, int[] out)
in
 Pointer to an
array holding the indices within the supplied Mapping of the inputs
which are to be picked from the Mapping.
This array should have "nin" elements.
If "Nin" is the number of inputs of the supplied Mapping, then each
element should have a value in the range 1 to Nin.out
 Pointer to an
array in which to return the indices of the outputs of the supplied
Mapping which are fed by the picked inputs. A value of one is
used to refer to the first Mapping output. The supplied array should
have a length at least equal to the number of outputs in the
supplied Mapping. The number of values stored in the array on
exit will equal the number of outputs in the returned Mapping.
The i'th element in the returned array holds the index within
the supplied Mapping which corresponds to the i'th output of
the returned Mapping.
AstException
 if an error occurred in the AST librarypublic int resample(int ndim_in, int[] lbnd_in, int[] ubnd_in, Object in, Object in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, Number badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, Object out, Object out_var)
You should use a resampling function which matches the numerical
type of the data you are processing by replacing
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, subpixel interpolation is performed between the neighbouring input pixels. This produces a resampled value which is then assigned to the output pixel. A choice of subpixel 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
astRebin
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 timeconsuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate nonlinear Mappings by a set of linear transformations which are applied piecewise to separate subregions 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 subdivided into two along its largest dimension and the process is repeated within each of the resulting subregions. This process of subdivision 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 input position (the transformed position of the output
pixel's centre) lies outside the boundary of the grid of input
pixels.
 The input position lies inside the boundary of a bad input
pixel. In this context, an input pixel is considered bad if its
data value is equal to "badval" and the AST__USEBAD flag is
set via the "flags" parameter.
(Positions which have halfintegral coordinate values, and
therefore lie on a pixel boundary, are regarded as lying within
the pixel with the larger, i.e. more positive, index.)
 The set of neighbouring input pixels (excluding those which
are bad) is unsuitable for calculating an interpolated
value. Whether this is true may depend on the subpixel
interpolation scheme in use.
 The interpolated value lies outside the range which can be
represented using the data type of the "out" array.
In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the "badval" value in the "out_var" array under any of the following circumstances:
 The associated resampled data value (in the "out" array) is bad.
 The set of neighbouring input pixels which contributed to the
output data value do not all have valid variance estimates
associated with them. In this context, an input variance
estimate may be regarded as bad either because it has the value
"badval" (and the AST__USEBAD flag is set), or because it is
negative.
 The set of neighbouring input pixels for which valid variance
values are available is unsuitable for calculating an overall
variance value. Whether this is true may depend on the subpixel
interpolation scheme in use.
 The variance value lies outside the range which can be
represented using the data type of the "out_var" array.
If the AST__NOBAD flag is specified via parameter "flags", then output array elements that would otherwise be set to "badval" are instead left holding the value they had on entry to this function. The number of such array elements is returned as the function 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 zerobased). 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 resampled. The
numerical type of this array should match the 1 or
2character type code appended to the function name (e.g. if
you are using astResampleF, 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 nonnegative 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 resampled output data will be calculated.
If no input variance estimates are being provided, a NULL pointer should be given.
interp
 an Interpolator
object which determines what
subpixel interpolation scheme should be used for the
resamplingflags
 flags object giving additional details about the resampling
proceduretol
 The maximum tolerable geometrical distortion which may be
introduced as a result of approximating nonlinear Mappings
by a set of piecewise linear transformations. This should be
expressed as a displacement in pixels in the input grid's
coordinate system.
If piecewise 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.
maxpix
 A value which specifies an initial scale size (in pixels) for
the adaptive algorithm which approximates nonlinear Mappings
with piecewise linear transformations. Normally, this should
be a large value (larger than any dimension of the region of
the output grid being used). In this case, a first attempt to
approximate the Mapping by a linear transformation will be
made over the entire output region.
If a smaller value is used, the output region will first be divided into subregions 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 generalpurpose 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).
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 astResample
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_out" elements,
containing the coordinates of the first pixel in the region
of the output grid for which a resampled value is to be
calculated.ubnd
 Pointer to an array of integers, with "ndim_out" elements,
containing the coordinates of the last pixel in the region of
the output grid for which a resampled value is to be
calculated.
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.
out
 Pointer to an array, with one element for each pixel in the
output grid, into which the resampled 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 resampled 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 subpixel interpolation schemes employed.
If no output variance estimates are required, a NULL pointer should be given.
AstException
 if an error occurred in the AST librarypublic int resampleB(int ndim_in, int[] lbnd_in, int[] ubnd_in, byte[] in, byte[] in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, byte badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, byte[] out, byte[] out_var)
public int resampleS(int ndim_in, int[] lbnd_in, int[] ubnd_in, short[] in, short[] in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, short badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, short[] out, short[] out_var)
public int resampleI(int ndim_in, int[] lbnd_in, int[] ubnd_in, int[] in, int[] in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, int badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, int[] out, int[] out_var)
public int resampleL(int ndim_in, int[] lbnd_in, int[] ubnd_in, long[] in, long[] in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, long badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, long[] out, long[] out_var)
public int resampleF(int ndim_in, int[] lbnd_in, int[] ubnd_in, float[] in, float[] in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, float badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, float[] out, float[] out_var)
public int resampleD(int ndim_in, int[] lbnd_in, int[] ubnd_in, double[] in, double[] in_var, Mapping.Interpolator interp, ResampleFlags flags, double tol, int maxpix, double badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, double[] out, double[] out_var)
public void rebin(double wlim, int ndim_in, int[] lbnd_in, int[] ubnd_in, Object in, Object in_var, Mapping.Spreader spread, boolean usebad, double tol, int maxpix, Number badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, Object out, Object out_var)
Note, if you will be rebining a sequence of input arrays and then
coadding them into a single array, the alternative
astRebinSeq
You should use a rebinning function which matches the numerical
type of the data you are processing by replacing
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 timeconsuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate nonlinear Mappings by a set of linear transformations which are applied piecewise to separate subregions 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 subdivided into two along its largest dimension and the process is repeated within each of the resulting subregions. This process of subdivision 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 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
astResample
 AST__NEAREST
 AST__LINEAR
 AST__SINC
 AST__SINCSINC
 AST__SINCCOS
 AST__SINCGAUSS
 AST__SOMBCOS
In addition, the following schemes can be used with
astRebin
 AST__GAUSS: This scheme uses a kernel of the form exp(k*x*x), with k
a positive constant determined by the fullwidth at halfmaximum (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).
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.
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 zerobased). 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
2character 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 nonnegative 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
 a Spreader
object which determines how each
input data value is divided up amongst the corresponding
output pixelsusebad
 if true, 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.tol
 The maximum tolerable geometrical distortion which may be
introduced as a result of approximating nonlinear Mappings
by a set of piecewise linear transformations. This should be
expressed as a displacement in pixels in the output grid's
coordinate system.
If piecewise 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 nonlinear Mappings
with piecewise 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 subregions 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 generalpurpose 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.
AstException
 if an error occurred in the AST librarypublic void rebinI(double wlim, int ndim_in, int[] lbnd_in, int[] ubnd_in, int[] in, int[] in_var, Mapping.Spreader spread, boolean usebad, double tol, int maxpix, int badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, int[] out, int[] out_var)
rebin(double, int, int[], int[], java.lang.Object, java.lang.Object, uk.ac.starlink.ast.Mapping.Spreader, boolean, double, int, java.lang.Number, int, int[], int[], int[], int[], java.lang.Object, java.lang.Object)
public void rebinF(double wlim, int ndim_in, int[] lbnd_in, int[] ubnd_in, float[] in, float[] in_var, Mapping.Spreader spread, boolean usebad, double tol, int maxpix, float badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, float[] out, float[] out_var)
rebin(double, int, int[], int[], java.lang.Object, java.lang.Object, uk.ac.starlink.ast.Mapping.Spreader, boolean, double, int, java.lang.Number, int, int[], int[], int[], int[], java.lang.Object, java.lang.Object)
public void rebinD(double wlim, int ndim_in, int[] lbnd_in, int[] ubnd_in, double[] in, double[] in_var, Mapping.Spreader spread, boolean usebad, double tol, int maxpix, double badval, int ndim_out, int[] lbnd_out, int[] ubnd_out, int[] lbnd, int[] ubnd, double[] out, double[] out_var)
rebin(double, int, int[], int[], java.lang.Object, java.lang.Object, uk.ac.starlink.ast.Mapping.Spreader, boolean, double, int, java.lang.Number, int, int[], int[], int[], int[], java.lang.Object, java.lang.Object)
public double[] tran1(int npoint, double[] xin, boolean forward)
npoint
 The number of points to be transformed.xin
 An array of "npoint" coordinate values for the input
(untransformed) points.forward
 A nonzero value indicates that the Mapping's forward
coordinate transformation is to be applied, while a zero
value indicates that the inverse transformation should be
used.
AstException
 if an error occurred in the AST librarypublic double[][] tran2(int npoint, double[] xin, double[] yin, boolean forward)
npoint
 The number of points to be transformed.xin
 An array of "npoint" Xcoordinate values for the input
(untransformed) points.yin
 An array of "npoint" Ycoordinate values for the input
(untransformed) points.forward
 A nonzero value indicates that the Mapping's forward
coordinate transformation is to be applied, while a zero
value indicates that the inverse transformation should be
used.
npoint
element array giving
the transformed X coordinates, and the second element
is an npoint
element array giving the
transformed Y coordinates.
AstException
 if an error occurred in the AST librarypublic double[] tranN(int npoint, int ncoord_in, double[] in, boolean forward, int ncoord_out)
If the coordinates are not stored in a single array, then the astTranP function might be more suitable.
npoint
 The number of points to be transformed.ncoord_in
 The number of coordinates being supplied for each input point
(i.e. the number of dimensions of the space in which the
input points reside).in
 The address of the first element in a 2dimensional array of
shape "[ncoord_in][indim]",
containing the coordinates of the input (untransformed)
points. These should be stored such that the value of
coordinate number "coord" for input point number "point" is
found in element "in[coord][point]".forward
 A nonzero value indicates that the Mapping's forward
coordinate transformation is to be applied, while a zero
value indicates that the inverse transformation should be
used.ncoord_out
 The number of coordinates being generated by the Mapping for
each output point (i.e. the number of dimensions of the
space in which the output points reside). This need not be
the same as "ncoord_in".
ncoord_out*npoint
coordinates representing the transformed points.
Coordinate number coord
for point point
must be stored at
in[npoint*coord+point]
, that is the
all the coordinates for the first dimension are stored
first, then all the coordinates for the second dimension ...
This is the same order as for the in
array.
AstException
 if an error occurred in the AST librarypublic double[][] tranP(int npoint, int ncoord_in, double[][] in, boolean forward, int ncoord_out)
If the coordinates are stored in a single (2dimensional) array, then the astTranN function might be more suitable.
npoint
 The number of points to be transformed.ncoord_in
 The number of coordinates being supplied for each input point
(i.e. the number of dimensions of the space in which the
input points reside).in
 An ncoord_in
element array of
npoint
element arrays. These give the
coordinates of the transformed points.forward
 A nonzero value indicates that the Mapping's forward
coordinate transformation is to be applied, while a zero
value indicates that the inverse transformation should be
used.ncoord_out
 The number of coordinates being generated by the Mapping for
each output point (i.e. the number of dimensions of the space
in which the output points reside). This need not be the same
as "ncoord_in".
ncoord_out
element array of
npoint
element arrays.
These give the coordinates of the points to transform.
AstException
 if an error occurred in the AST librarypublic double[][] tranGrid(int ncoord_in, int[] lbnd, int[] ubnd, double tol, int maxpix, boolean forward, int ncoord_out)
ncoord_in
 The number of coordinates being supplied for each box corner
(i.e. the number of dimensions of the space in which the
input points reside).lbnd
 Pointer to an array of integers, with "ncoord_in" elements,
containing the coordinates of the centre of the first pixel
in the input grid along each dimension.ubnd
 Pointer to an array of integers, with "ncoord_in" elements,
containing the coordinates of the centre of the last pixel in
the input grid along each dimension.
Note that "lbnd" and "ubnd" together define the shape and size of the input grid, its extent along a particular (j'th) dimension being ubnd[j]lbnd[j]+1 (assuming the index "j" to be zerobased). They also define the input grid's coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre.
tol
 The maximum tolerable geometrical distortion which may be
introduced as a result of approximating nonlinear Mappings
by a set of piecewise linear transformations. This should be
expressed as a displacement within the output coordinate system
of the Mapping.
If piecewise 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. If this is a problem, reduce the tolerance value used.
maxpix
 A value which specifies an initial scale size (in input grid points)
for the adaptive algorithm which approximates nonlinear Mappings
with piecewise 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 subregions whose size does not exceed "maxpix" grid points 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 grid points can also be employed as a safeguard in generalpurpose 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.
forward
 A nonzero value indicates that the Mapping's forward
coordinate transformation is to be applied, while a zero
value indicates that the inverse transformation should be
used.ncoord_out
 The number of coordinates being generated by the Mapping for
each output point (i.e. the number of dimensions of the
space in which the output points reside). This need not be
the same as "ncoord_in".
AstException
 if an error occurred in the AST librarypublic double rate(double[] at, int ax1, int ax2)
The result is estimated by interpolating the function using a fourth order polynomial in the neighbourhood of the specified position. The size of the neighbourhood used is chosen to minimise the RMS residual per unit length between the interpolating polynomial and the supplied Mapping function. This method produces good accuracy but can involve evaluating the Mapping 100 or more times.
at
 The address of an
array holding the axis values at the position at which the rate
of change is to be evaluated. The number of elements in this
array should equal the number of inputs to the Mapping.ax1
 The index of the Mapping output for which the rate of change is to
be found (output numbering starts at 1 for the first output).ax2
 The index of the Mapping input which is to be varied in order to
find the rate of change (input numbering starts at 1 for the first
input).
AstException
 if an error occurred in the AST librarypublic double[] linearApprox(double[] lbnd, double[] ubnd, double tol)
If this mapping is not linear to the given tolerance, null will be returned.
lbnd
 Pointer to an array of doubles
containing the lower bounds of a box defined within the input
coordinate system of the Mapping. The number of elements in this
array should equal the value of the Mapping's Nin attribute. This
box should specify the region over which linearity is required.ubnd
 Pointer to an array of doubles
containing the upper bounds of the box specifying the region over
which linearity is required.tol
 The maximum permitted deviation from linearity, expressed as
a positive Cartesian displacement in the output coordinate
space of the Mapping. If a linear fit to the forward
transformation of the Mapping deviates from the true transformation
by more than this amount at any point which is tested, then no fit
coefficients will be returned.
X_out = fit[0] + fit[3]*X_in + fit[4]*Y_in
Y_out = fit[1] + fit[5]*X_in + fit[6]*Y_in
Z_out = fit[2] + fit[7]*X_in + fit[8]*Y_in
AstException
 if an error occurred in the AST librarypublic boolean getInvert()
Inverting the boolean sense of the Invert attribute will cause the values of a Mapping's Nin and Nout attributes to be interchanged. The values of its TranForward and TranInverse attributes will also be interchanged. This operation may be performed with the astInvert function.
public void setInvert(boolean invert)
Inverting the boolean sense of the Invert attribute will cause the values of a Mapping's Nin and Nout attributes to be interchanged. The values of its TranForward and TranInverse attributes will also be interchanged. This operation may be performed with the astInvert function.
invert
 the Invert attribute of this objectpublic int getNin()
If a CmpMap's component Mappings are joined in parallel, then its Nin attribute is given by the sum of the Nin attributes of each component (or to the sum of their Nout attributes if the CmpMap's Invert attribute is nonzero).
public int getNout()
If a CmpMap's component Mappings are joined in parallel, then its Nout attribute is given by the sum of the Nout attributes of each component (or to the sum of their Nin attributes if the CmpMap's Invert attribute is nonzero).
public boolean getReport()
This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs.
public void setReport(boolean report)
This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs.
report
 the Report attribute of this objectpublic boolean getTranForward()
public boolean getTranInverse()


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 