Mapping (Starlink-UK API)

java.lang.Object
- uk.ac.starlink.ast.AstObject
- - uk.ac.starlink.ast.Mapping

Direct Known Subclasses:

CmpMap, DssMap, Frame, GrismMap, IntraMap, LutMap, MathMap, MatrixMap, PcdMap, PermMap, PolyMap, RateMap, SelectorMap, ShiftMap, SlaMap, SpecMap, SphMap, SwitchMap, TimeMap, TranMap, UnitMap, WcsMap, WinMap, ZoomMap
```
public class Mapping
extends AstObject
```
Java interface to the AST Mapping class - inter-relate 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.
Licence
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.
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 02110-1301, USA

See Also:

AST Mapping

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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

Fields
Modifier and Type	Field and Description
`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 nearest-neighbour interpolator for use in the resampling methods.
`static Mapping.Spreader`	`NEAREST_SPREADER` A nearest-neighbour spreader for use in the rebinning methods.

Fields inherited from class uk.ac.starlink.ast.AstObject
AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors
Modifier Constructor and Description

protected Mapping()
Dummy constructor.

Constructors
Modifier	Constructor and Description
`protected`	`Mapping()` Dummy constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 1-dimensional coordinates.
`double[][]`	`tran2(int npoint, double[] xin, double[] yin, boolean forward)` Transform 2-dimensional 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 N-dimensional coordinates.
`double[][]`	`tranP(int npoint, int ncoord_in, double[][] in, boolean forward, int ncoord_out)` Transform N-dimensional 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
  - NEAREST_INTERPOLATOR
```
public static final Mapping.Interpolator NEAREST_INTERPOLATOR
```
    A nearest-neighbour interpolator for use in the resampling methods. Provided static for convenience.
  - LINEAR_INTERPOLATOR
```
public static final Mapping.Interpolator LINEAR_INTERPOLATOR
```
    A linear interpolator for use in the resampling methods. Provided static for convenience.
  - NEAREST_SPREADER
```
public static final Mapping.Spreader NEAREST_SPREADER
```
    A nearest-neighbour spreader for use in the rebinning methods. Provided static for convenience.
  - LINEAR_SPREADER
```
public static final Mapping.Spreader LINEAR_SPREADER
```
    A linear spreader for use in the rebinning methods. Provided static for convenience.
- Constructor Detail
  - Mapping
```
protected Mapping()
```
    Dummy constructor. This constructor does not create a valid Mapping object, but is required for inheritance by Mapping's subclasses.
- Method Detail
  - invert
```
public void invert()
```
    Inverts a mapping by reversing the sense of its Invert attribute.
  - simplify
```
public Mapping simplify()
```
    Simplify a Mapping. This function simplifies a Mapping (which may be a compound Mapping such as a CmpMap) to eliminate redundant computational steps, or to merge separate steps which can be performed more efficiently in a single operation.
    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.
    Notes
    
    - This function can safely be applied even to Mappings which cannot be simplified. If no simplification is possible, it behaves exactly like astClone and returns a pointer to the original Mapping.
    - The Mapping returned by this function may not be independent of the original (even if simplification was possible), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using astCopy.
    - A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.
    
    Returns:
    
    A new pointer to the (possibly simplified) Mapping.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - decompose
```
public Mapping[] decompose(boolean[] series,
                           boolean[] inverts)
```
    Decompose a Mapping into two component Mappings. This function returns pointers to two Mappings which, when applied either in series or parallel, are equivalent to the supplied Mapping.
    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.
    Notes
    
    - The returned Invert values should be used in preference to the current values of the Invert attribute in map1 and map2. This is because the attributes may have changed value since the Mappings were combined.
    - Any changes made to the component Mappings using the returned pointers will be reflected in the supplied Mapping.
    
    Parameters:
    
    series - A one-element 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 two-element array to hold the Invert attribute vales for the constituent Mappings. If null is supplied, then the inversion information is not returned.
    
    Returns:
    
    An array of Mappings giving the components of this Mapping. If this Mapping is a CmpMap, it will be a 2-element array holding the two constituent Mappings which were used to create this Mapping, either in series or in parallel. If this Mapping is a CmpFrame, it will be a 2-element array containing the two constituent Frames which were used to create this CmpFrame in parallel. Otherwise, a 1-element array containing a clone of this object will be returned.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - mapBox
```
public double[] mapBox(double[] lbnd_in,
                       double[] ubnd_in,
                       boolean forward,
                       int coord_out,
                       double[] xl,
                       double[] xu)
```
    Find a bounding box for a Mapping. This function allows you to find the "bounding box" which just encloses another box after it has been transformed by a Mapping (using either its forward or inverse transformation). A typical use might be to calculate the size of an image after being transformed by a Mapping.
    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.
    Notes
    
    - Any input points which are transformed by the Mapping to give output coordinates containing the value AST__BAD are regarded as invalid and are ignored. They will make no contribution to determining the output bounds, even although the nominated output coordinate might still have a valid value at such points.
    - An error will occur if the required output bounds cannot be found. Typically, this might happen if all the input points which the function considers turn out to be invalid (see above). The number of points considered before generating such an error is quite large, so this is unlikely to occur by accident unless valid points are restricted to a very small subset of the input coordinate space.
    - The values returned via "lbnd_out", "ubnd_out", "xl" and "xu" will be set to the value AST__BAD if this function should fail for any reason. Their initial values on entry will not be altered if the function is invoked with the AST error status set.
    
    Parameters:
    
    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 non-zero, 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.
    
    Returns:
    
    a two-element array giving the lowest (element 0) and highest (element 1) value taken by the nominated output coordinate within the specified region of input space
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - mapSplit
```
public Mapping mapSplit(int[] in,
                        int[] out)
```
    Split a Mapping up into parallel component Mappings. This function creates a new Mapping which connects specified inputs within a supplied Mapping to the corresponding outputs of the supplied Mapping. This is only possible if the specified inputs correspond to some subset of the Mapping outputs. That is, there must exist a subset of the Mapping outputs for which each output depends only on the selected Mapping inputs, and not on any of the inputs which have not been selected. Also, any output which is not in this subset must not depend on any of the selected inputs. If these conditions are not met by the supplied Mapping, then a NULL Mapping pointer is returned.
    Notes
    
    - If this function is invoked with the global error status set, or if it should fail for any reason, then a NULL value will be returned for the "map" pointer.
    
    Parameters:
    
    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.
    
    Returns:
    
    the returned mapping
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - resample
```
public 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. This is a set of functions for resampling 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. Resampling may be restricted to a specified region of the output 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 resampled output data. Propagation of missing data (bad pixels) is supported.
    You should use a resampling function which matches the numerical type of the data you are processing by replacing <X> in the generic function name astResample<X> by an appropriate 1- or 2-character type code. For example, if you are resampling data with type "float", you should use the function astResampleF (see the "Data Type Codes" section below for the codes appropriate to other numerical types).
    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, sub-pixel interpolation is performed between the neighbouring input pixels. This produces a resampled value which is then assigned to the output pixel. A choice of sub-pixel 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<X> or astRebinSeq<X> family of functions instead.
    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 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 output grid which is being used. If this proves to be insufficiently accurate, the output 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).
    Notes
    
    - A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason.
    Propagation of Missing Data
    Unless the AST__NOBAD flag is specified, instances of missing data (bad pixels) in the output grid are identified by occurrences of the "badval" value in the "out" array. These may be produced if any of the following happen:
    
    - 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 half-integral 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 sub-pixel 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 sub-pixel 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.
    
    Parameters:
    
    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 resampled. 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 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 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 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 sub-pixel interpolation scheme should be used for the resampling
    
    flags - flags object giving additional details about the resampling procedure
    
    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 input 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.
    
    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 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 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).
    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<X> function return value indicates whether any such values have been produced. If the AST__NOBAD flag is set. then output array elements for which no resampled value could be obtained are left set to the value they had on entry to this function.
    
    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 sub-pixel interpolation schemes employed.
    If no output variance estimates are required, a NULL pointer should be given.
    
    Returns:
    
    The number of output pixels for which no valid resampled value could be obtained. Thus, in the absence of any error, a returned value of zero indicates that all the required output pixels received valid resampled data values (and variances). See the "badval" and "flags" parameters.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - resampleB
```
public 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.
  - resampleS
```
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)
```
    Resampling method specific to short data - see the resample method.
  - resampleI
```
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)
```
    Resampling method specific to int data - see the resample method.
  - resampleL
```
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)
```
    Resampling method specific to long data - see the resample method.
  - resampleF
```
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)
```
    Resampling method specific to float data - see the resample method.
  - resampleD
```
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)
```
    Resampling method specific to double data - see the resample method.
  - rebin
```
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)
```
    Rebin a region of a data grid. 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 astRebinSeq<X> 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 astRebin<X> 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).
    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 astResample<X> group of functions. That is, in a sub-pixel interpolation scheme the kernel specifies the weight to assign to each input pixel when forming the weighted mean of the input pixels, whereas the kernel in a pixel spreading scheme specifies the fraction of the input data value which is to be assigned to each output pixel. As for interpolation, the choice of suitable pixel spreading scheme involves stricking a balance between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features but which often tend to introduce unwanted artifacts. See the astResample<X> documentation for further discussion.
    The binning algorithm used has the ability to introduce artifacts not seen when using a resampling algorithm. Particularly, when viewing the output image at high contrast, systems of curves lines covering the entire image may be visible. These are caused by a beating effect between the input pixel positions and the output pixels position, and their nature and strength depend critically upon the nature of the Mapping and the spreading function being used. In general, the nearest neighbour spreading function demonstrates this effect more clearly than the other functions, and for this reason should be used with caution.
    The following values (defined in the "ast.h" header file) may be assigned to the "spread" parameter. See the astResample<X> 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
    In addition, the following schemes can be used with astRebin<X> but not with astResample<X>:
    
    - AST__GAUSS: This scheme uses a kernel of the form exp(-k*x*x), with k a positive constant determined by the full-width at half-maximum (FWHM). The FWHM should be supplied in units of output pixels by means of the "params[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).
    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.
    
    Parameters:
    
    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 - a Spreader object which determines how each input data value is divided up amongst the corresponding output pixels
    
    usebad - 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 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.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - rebinI
```
public 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.
    
    See Also:
    
    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)
  - rebinF
```
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)
```
    Rebinning method specific to float data.
    
    See Also:
    
    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)
  - rebinD
```
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)
```
    Rebinning method specific to double data.
    
    See Also:
    
    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)
  - tran1
```
public double[] tran1(int npoint,
                      double[] xin,
                      boolean forward)
```
    Transform 1-dimensional coordinates. This function applies a Mapping to transform the coordinates of a set of points in one dimension.
    Notes
    
    - The Mapping supplied must have the value 1 for both its Nin and Nout attributes.
    
    Parameters:
    
    npoint - The number of points to be transformed.
    
    xin - An array of "npoint" coordinate values for the input (untransformed) points.
    
    forward - A non-zero 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.
    
    Returns:
    
    an array of npoint elements representing the transformed points
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - tran2
```
public double[][] tran2(int npoint,
                        double[] xin,
                        double[] yin,
                        boolean forward)
```
    Transform 2-dimensional coordinates. This function applies a Mapping to transform the coordinates of a set of points in two dimensions.
    Notes
    
    - The Mapping supplied must have the value 2 for both its Nin and Nout attributes.
    
    Parameters:
    
    npoint - The number of points to be transformed.
    
    xin - An array of "npoint" X-coordinate values for the input (untransformed) points.
    
    yin - An array of "npoint" Y-coordinate values for the input (untransformed) points.
    
    forward - A non-zero 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.
    
    Returns:
    
    a two-element array of arrays of doubles. The first element is an npoint-element array giving the transformed X coordinates, and the second element is an npoint-element array giving the transformed Y coordinates.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - tranN
```
public double[] tranN(int npoint,
                      int ncoord_in,
                      double[] in,
                      boolean forward,
                      int ncoord_out)
```
    Transform N-dimensional coordinates. This function applies a Mapping to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in a single array (which they need not fill completely).
    If the coordinates are not stored in a single array, then the astTranP function might be more suitable.
    Notes
    
    - If the forward coordinate transformation is being applied, the Mapping supplied must have the value of "ncoord_in" for its Nin attribute and the value of "ncoord_out" for its Nout attribute. If the inverse transformation is being applied, these values should be reversed.
    
    Parameters:
    
    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 2-dimensional 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 non-zero 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".
    
    Returns:
    
    an array of 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.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - tranP
```
public double[][] tranP(int npoint,
                        int ncoord_in,
                        double[][] in,
                        boolean forward,
                        int ncoord_out)
```
    Transform N-dimensional coordinates held in separate arrays. This function applies a Mapping to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in separate arrays, since each coordinate array is located by supplying a separate pointer to it.
    If the coordinates are stored in a single (2-dimensional) array, then the astTranN function might be more suitable.
    Notes
    
    - If the forward coordinate transformation is being applied, the Mapping supplied must have the value of "ncoord_in" for its Nin attribute and the value of "ncoord_out" for its Nout attribute. If the inverse transformation is being applied, these values should be reversed.
    - This routine is not available in the Fortran 77 interface to the AST library.
    
    Parameters:
    
    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 non-zero 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".
    
    Returns:
    
    an ncoord_out-element array of npoint-element arrays. These give the coordinates of the points to transform.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - tranGrid
```
public double[][] tranGrid(int ncoord_in,
                           int[] lbnd,
                           int[] ubnd,
                           double tol,
                           int maxpix,
                           boolean forward,
                           int ncoord_out)
```
    Transform a grid of positions. This function uses the supplied Mapping to transforms a regular square grid of points covering a specified box. It attempts to do this quickly by first approximating 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).
    Notes
    
    - If the forward coordinate transformation is being applied, the Mapping supplied must have the value of "ncoord_in" for its Nin attribute and the value of "ncoord_out" for its Nout attribute. If the inverse transformation is being applied, these values should be reversed.
    
    Parameters:
    
    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 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.
    
    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 within the output coordinate system of the Mapping.
    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. 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 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" 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 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.
    
    forward - A non-zero 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".
    
    Returns:
    
    The address of the first element in a 2-dimensional array of shape "[ncoord_out][outdim]", into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number "coord" for output point number "point" will be found in element "out[coord][point]". The points are ordered such that the first axis of the input grid changes most rapidly. For example, if the input grid is 2-dimensional and extends from (2,-1) to (3,1), the output points will be stored in the order (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1).
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - rate
```
public double rate(double[] at,
                   int ax1,
                   int ax2)
```
    Calculate the rate of change of a Mapping output. This function evaluates the rate of change of a specified output of the supplied Mapping with respect to a specified input, at a specified input position.
    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.
    Notes
    
    - A value of AST__BAD will be returned if this function is invoked with the global error status set, or if it should fail for any reason.
    
    Parameters:
    
    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).
    
    Returns:
    
    The rate of change of Mapping output "ax1" with respect to input "ax2", evaluated at "at", or AST__BAD if the value cannot be calculated.
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - linearApprox
```
public double[] linearApprox(double[] lbnd,
                             double[] ubnd,
                             double tol)
```
    Obtain a linear approximation to a Mapping, if appropriate. This function tests the forward coordinate transformation implemented by a Mapping over a given range of input coordinates. If the transformation is found to be linear to a specified level of accuracy, then an array of fit coefficients is returned. These may be used to implement a linear approximation to the Mapping's forward transformation within the specified range of output coordinates. If the transformation is not sufficiently linear, no coefficients are returned.
    Notes
    
    - This function fits the Mapping's forward transformation. To fit the inverse transformation, the Mapping should be inverted using astInvert before invoking this function.
    - A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason.
    If this mapping is not linear to the given tolerance, null will be returned.
    
    Parameters:
    
    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.
    
    Returns:
    
    Pointer to an array of doubles in which to return the co-efficients of the linear approximation to the specified transformation. This array should have at least "( Nin + 1 ) * Nout", elements. The first Nout elements hold the constant offsets for the transformation outputs. The remaining elements hold the gradients. So if the Mapping has 2 inputs and 3 outputs the linear approximation to the forward transformation is:
    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
    
    Throws:
    
    AstException - if an error occurred in the AST library
  - getInvert
```
public boolean getInvert()
```
    Get mapping inversion flag. This attribute controls which one of a Mapping's two possible coordinate transformations is considered the "forward" transformation (the other being the "inverse" transformation). If the attribute value is zero (the default), the Mapping's behaviour will be the same as when it was first created. However, if it is non-zero, its two transformations will be inter-changed, so that the Mapping displays the inverse of its original behaviour.
    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.
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    UnitMap
    The value of the Invert attribute has no effect on the behaviour of a UnitMap.
    FrameSet
    Inverting the boolean sense of the Invert attribute for a FrameSet will cause its base and current Frames (and its Base and Current attributes) to be interchanged. This, in turn, may affect other properties and attributes of the FrameSet (such as Nin, Nout, Naxes, TranForward, TranInverse, etc.). The Invert attribute of a FrameSet is not itself affected by selecting a new base or current Frame.
    
    Returns:
    
    this object's Invert attribute
  - setInvert
```
public void setInvert(boolean invert)
```
    Set mapping inversion flag. This attribute controls which one of a Mapping's two possible coordinate transformations is considered the "forward" transformation (the other being the "inverse" transformation). If the attribute value is zero (the default), the Mapping's behaviour will be the same as when it was first created. However, if it is non-zero, its two transformations will be inter-changed, so that the Mapping displays the inverse of its original behaviour.
    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.
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    UnitMap
    The value of the Invert attribute has no effect on the behaviour of a UnitMap.
    FrameSet
    Inverting the boolean sense of the Invert attribute for a FrameSet will cause its base and current Frames (and its Base and Current attributes) to be interchanged. This, in turn, may affect other properties and attributes of the FrameSet (such as Nin, Nout, Naxes, TranForward, TranInverse, etc.). The Invert attribute of a FrameSet is not itself affected by selecting a new base or current Frame.
    
    Parameters:
    
    invert - the Invert attribute of this object
  - getNin
```
public int getNin()
```
    Get number of input coordinates for a Mapping. This attribute gives the number of coordinate values required to specify an input point for a Mapping (i.e. the number of dimensions of the space in which the Mapping's input points reside).
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    CmpMap
    If a CmpMap's component Mappings are joined in series, then its Nin attribute is equal to the Nin attribute of the first component (or to the Nout attribute of the second component if the the CmpMap's Invert attribute is non-zero).
    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 non-zero).
    Frame
    The Nin attribute for a Frame is always equal to the number of Frame axes (Naxes attribute).
    FrameSet
    The Nin attribute of a FrameSet is equal to the number of axes (Naxes attribute) of its base Frame (as specified by the FrameSet's Base attribute). The Nin attribute value may therefore change if a new base Frame is selected.
    
    Returns:
    
    this object's Nin attribute
  - getNout
```
public int getNout()
```
    Get number of output coordinates for a Mapping. This attribute gives the number of coordinate values generated by a Mapping to specify each output point (i.e. the number of dimensions of the space in which the Mapping's output points reside).
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    CmpMap
    If a CmpMap's component Mappings are joined in series, then its Nout attribute is equal to the Nout attribute of the second component (or to the Nin attribute of the first component if the the CmpMap's Invert attribute is non-zero).
    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 non-zero).
    Frame
    The Nout attribute for a Frame is always equal to the number of Frame axes (Naxes attribute).
    FrameSet
    The Nout attribute of a FrameSet is equal to the number of FrameSet axes (Naxes attribute) which, in turn, is equal to the Naxes attribute of the FrameSet's current Frame (as specified by the Current attribute). The Nout attribute value may therefore change if a new current Frame is selected.
    
    Returns:
    
    this object's Nout attribute
  - getReport
```
public boolean getReport()
```
    Get report transformed coordinates. This attribute controls whether coordinate values are reported whenever a Mapping is used to transform a set of points. If its value is zero (the default), no report is made. However, if it is non-zero, the coordinates of each point are reported (both before and after transformation) by writing them to standard output.
    This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs.
    Notes
    
    - Unlike most other attributes, the value of the Report attribute is not transferred when a Mapping is copied. Instead, its value is undefined (and therefore defaults to zero) in any copy. Similarly, it becomes undefined in any external representation of a Mapping produced by the astWrite function.
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    CmpMap
    When applied to a compound Mapping (CmpMap), only the Report attribute of the CmpMap, and not those of its component Mappings, is used. Coordinate information is never reported for the component Mappings individually, only for the complete CmpMap.
    Frame
    When applied to any Frame, the formatting capabilities of the Frame (as provided by the astFormat function) will be used to format the reported coordinates.
    FrameSet
    When applied to any FrameSet, the formatting capabilities of the base and current Frames will be used (as above) to individually format the input and output coordinates, as appropriate. The Report attribute of a FrameSet is not itself affected by selecting a new base or current Frame, but the resulting formatting capabilities may be.
    
    Returns:
    
    this object's Report attribute
  - setReport
```
public void setReport(boolean report)
```
    Set report transformed coordinates. This attribute controls whether coordinate values are reported whenever a Mapping is used to transform a set of points. If its value is zero (the default), no report is made. However, if it is non-zero, the coordinates of each point are reported (both before and after transformation) by writing them to standard output.
    This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs.
    Notes
    
    - Unlike most other attributes, the value of the Report attribute is not transferred when a Mapping is copied. Instead, its value is undefined (and therefore defaults to zero) in any copy. Similarly, it becomes undefined in any external representation of a Mapping produced by the astWrite function.
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    CmpMap
    When applied to a compound Mapping (CmpMap), only the Report attribute of the CmpMap, and not those of its component Mappings, is used. Coordinate information is never reported for the component Mappings individually, only for the complete CmpMap.
    Frame
    When applied to any Frame, the formatting capabilities of the Frame (as provided by the astFormat function) will be used to format the reported coordinates.
    FrameSet
    When applied to any FrameSet, the formatting capabilities of the base and current Frames will be used (as above) to individually format the input and output coordinates, as appropriate. The Report attribute of a FrameSet is not itself affected by selecting a new base or current Frame, but the resulting formatting capabilities may be.
    
    Parameters:
    
    report - the Report attribute of this object
  - getTranForward
```
public boolean getTranForward()
```
    Get forward transformation defined. This attribute indicates whether a Mapping is able to transform coordinates in the "forward" direction (i.e. converting input coordinates into output coordinates). If this attribute is non-zero, the forward transformation is available. Otherwise, it is not.
    Notes
    
    - An error will result if a Mapping with a TranForward value of zero is used to transform coordinates in the forward direction.
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    CmpMap
    The TranForward attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping.
    FrameSet
    The TranForward attribute of a FrameSet applies to the transformation which converts between the FrameSet's base Frame and its current Frame (as specified by the Base and Current attributes). This value is given by the boolean AND of the TranForward values which apply to each of the individual sub-Mappings required to perform this conversion. The TranForward attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected.
    
    Returns:
    
    this object's TranForward attribute
  - getTranInverse
```
public boolean getTranInverse()
```
    Get inverse transformation defined. This attribute indicates whether a Mapping is able to transform coordinates in the "inverse" direction (i.e. converting output coordinates back into input coordinates). If this attribute is non-zero, the inverse transformation is available. Otherwise, it is not.
    Notes
    
    - An error will result if a Mapping with a TranInverse value of zero is used to transform coordinates in the inverse direction.
    Class Applicability
    
    Mapping
    All Mappings have this attribute.
    CmpMap
    The TranInverse attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping.
    FrameSet
    The TranInverse attribute of a FrameSet applies to the transformation which converts between the FrameSet's current Frame and its base Frame (as specified by the Current and Base attributes). This value is given by the boolean AND of the TranInverse values which apply to each of the individual sub-Mappings required to perform this conversion. The TranInverse attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected.
    
    Returns:
    
    this object's TranInverse attribute

Class Mapping

Licence

Nested Class Summary

Field Summary

Fields inherited from class uk.ac.starlink.ast.AstObject

Constructor Summary

Method Summary

Methods inherited from class uk.ac.starlink.ast.AstObject

Methods inherited from class java.lang.Object

Field Detail

NEAREST_INTERPOLATOR

LINEAR_INTERPOLATOR

NEAREST_SPREADER

LINEAR_SPREADER

Constructor Detail

Mapping

Method Detail

invert

simplify

Notes

decompose

Notes

mapBox

Notes

mapSplit

Notes

resample

Notes

Propagation of Missing Data

resampleB

resampleS

resampleI

resampleL

resampleF

resampleD

rebin

Pixel Spreading Schemes

Propagation of Missing Data

rebinI

rebinF

rebinD

tran1

Notes

tran2

Notes

tranN

Notes

tranP

Notes

tranGrid

Notes

rate

Notes

linearApprox

Notes

getInvert

Class Applicability

setInvert

Class Applicability

getNin

Class Applicability

getNout

Class Applicability

getReport

Notes

Class Applicability

setReport

Notes

Class Applicability

getTranForward

Notes

Class Applicability

getTranInverse

Notes

Class Applicability