AST_TRANGRID

Transform a grid of positions

Description:

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

Invocation

CALL AST_TRANGRID( THIS, NCOORD_IN, LBND, UBND, TOL, MAXPIX, FORWARD, NCOORD_OUT, OUTDIM, OUT, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the Mapping to be applied.
NCOORD_IN = INTEGER (Given)
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( NCOORD_IN ) = INTEGER (Given)
An array containing the coordinates of the centre of the first pixel in the input grid along each dimension.
UBND( NCOORD_IN ) = INTEGER (Given)
An array 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. 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 = DOUBLE PRECISION (Given)
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 = INTEGER (Given)
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 = LOGICAL (Given)
A .TRUE. value indicates that the Mapping’ s forward coordinate transformation is to be applied, while a .FALSE. value indicates that the inverse transformation should be used.
NCOORD_OUT = INTEGER (Given)
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.
OUTDIM = INTEGER (Given)
The number of elements along the first dimension of the OUT array (which will contain the output coordinates). The value given should not be less than the number of points in the grid.
OUT( OUTDIM, NCOORD_OUT ) = DOUBLE PRECISION (Returned)
An array 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(POINT,COORD). 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).
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Handling of Huge Pixel Arrays

If the output grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments LBND, UBND, OUTDIM are changed from type INTEGER to type INTEGER∗8. The function name is changed by appending the digit " 8" to the name. Thus, AST_TRANGRID becomes AST_TRANGRID8.
Copyright (C) 2021 East Asian Observatory