##
Writing a Transformation Function

The first stage in creating an IntraMapIntraMap is to write the coordinate transformation function. This should have a calling interface like the astTranPastTranP function provided by AST (q.v.). Here is a simple example of a suitable transformation function which transforms coordinates by squaring them: SqrTran

279#279

As you can see, the function comes in two halves which implement the forward and inverse coordinate transformations. The number of points to be transformed (“npoint”) and the numbers of input and output coordinates per point (“ncoord_in” and “ncoord_out”—in this case both are assumed equal) are passed to the function. A pair of loops then accesses all the coordinate values. Note that it is legitimate to omit one or other of the forward/inverse transformations and simply not to implement it, if it will not be required. It is also permissible to require that the numbers of input and output coordinates be fixed (e.g. at 2), or to write the function so that it can handle arbitrary dimensionality, as here.

Before using an incoming coordinate, the function must first check that it is not set to the value AST__BAD, which indicates missing data (§5.9). If it is, the same value is also assigned to any affected output coordinates. The value AST__BAD is also generated if any coordinates cannot be transformed. In this example, this can happen with the inverse transformation if negative values are encountered, so that the square root cannot be taken.

There are very few restrictions on what a coordinate transformation function may do. For example, it may freely perform I/O to access any external data needed, it may invoke other AST facilities (but beware of unwanted recursion), etc. Typically, you may also want to pass information to it via global variables. Remember, however, that whatever facilities the transformation function requires must be available in every program which uses it.

Generally, it is not a good idea to retain context information within a transformation function. That is, it should transform each set of coordinates as a single point and retain no memory of the points it has transformed before. This is in order to conform with the AST model of a MappingMapping.

If an error occurs within a transformation function, it should use the astSetStatusastSetStatus function (§4.15) to set the AST status to an error value before returning. This will alert AST to the error, causing it to abort the current operation. The error value AST__ITFER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error).