Registering a Transformation Function

Having written your coordinate transformation function, the next step is to register it with AST. Registration is performed using astIntraRegastIntraReg, as follows:


\begin{terminalv}
void SqrTran( AstMapping *, int, int, const double *[], int, i...
...aReg( ''SqrTran'', 2, 2, SqrTran, 0, purpose, author, contact );
\end{terminalv}

Note that you should also provide a function prototype to describe the transformation function (the implementation of the function itself would suffice, of course).

The first argument to astIntraReg is a name by which the transformation function will be known. This will be used when we come to create an IntraMapIntraMap and is case sensitive. We recommend that you use the actual function name here and make this sufficiently unusual that it is unlikely to clash with any other functions in most people's software.

The next two arguments specify the number of input and output coordinates which the transformation function will handle. These correspond with the NinNin and NoutNout attributes of the IntraMap we will create. Here, we have set them both to 2, which means that we will only be able to create IntraMaps with 2 input and 2 output coordinates (despite the fact that the transformation function can actually handle other dimensionalities). We will see later (§20.8) how to remove this restriction.

The fourth argument should contain a set of flags which describe the transformation function in a little more detail. We will return to this shortly (§20.7 & §20.10). For now, we supply a value of zero.

The remaining arguments are character strings which document the transformation function, mainly for the benefit of anyone who is unfortunate enough to encounter a reference to it in their data which they cannot interpret. As explained above (§20.3), you should try and avoid this, but accidents will happen, so you should always provide strings containing the following:

  1. A short description of what the transformation function is for.
  2. The name of the author.
  3. Contact details, such as an e-mail or WWW address.

The idea is that anyone finding an IntraMap in their data, but lacking the necessary transformation function, should be able to contact the author and make a sensible enquiry in order to obtain it. If you expect many enquiries, you may like to set up a World Wide Web page and use that instead (in the example above, we use the WWW address of the relevant part of this document).