next up previous 264
Next: astInvert - Invert a Mapping
Up: AST Function Descriptions
Previous: astIntraMap - Create an IntraMap


astIntraReg - Register a transformation function for use by an IntraMap

Description:
This function registers a privately-defined coordinate transformation function written in C so that it may be used to create an IntraMap. An IntraMap is a specialised form of Mapping which encapsulates the C function so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation.

Registration of relevant transformation functions is required before using the astIntraMap constructor function to create an IntraMap or reading an external representation of an IntraMap from a Channel.

Synopsis:
astIntraReg( const char $*$name, int nin, int nout, void ($*$ tran)( AstMapping $*$, int, int, const double $*$[], int, int, double $*$[] ), unsigned int flags, const char $*$purpose, const char $*$author, const char $*$contact )
Parameters:
name
Pointer to a null-terminated string containing a unique name to be associated with the transformation function in order to identify it. This name is case sensitive. All white space will be removed before use.
nin
The number of input coordinates accepted by the transformation function (i.e. the number of dimensions of the space in which the input points reside). A value of AST__ANY may be given if the function is able to accommodate a variable number of input coordinates.
nout
The number of output coordinates produced by the transformation function (i.e. the number of dimensions of the space in which the output points reside). A value of AST__ANY may be given if the function is able to produce a variable number of output coordinates.
tran
Pointer to the transformation function to be registered. This function should perform whatever coordinate transformations are required and should have an interface like astTranP (q.v.).
flags
This value may be used to supply a set of flags which describe the transformation function and which may affect the behaviour of any IntraMap which uses it. Often, a value of zero will be given here, but you may also supply the bitwise OR of a set of flags as described in the "Transformation Flags" section (below).
purpose
Pointer to a null-terminated string containing a short (one line) textual comment to describe the purpose of the transformation function.
author
Pointer to a null-terminated string containing the name of the author of the transformation function.
contact
Pointer to a null-terminated string containing contact details for the author of the transformation function (e.g. an e-mail or WWW address). If any IntraMap which uses this transformation function is exported as part of a dataset to an external user who does not have access to the function, then these contact details should allow them to obtain the necessary code.
Notes:
  • Beware that an external representation of an IntraMap (created by writing it to a Channel) will not include the coordinate transformation function which it uses, so will only refer to the function by its name (as assigned using astIntraReg). Consequently, the external representation cannot be utilised by another program unless that program has also registered the same transformation function with the same name using an identical invocation of astIntraReg. If no such registration has been performed, then attempting to read the external representation will result in an error.

  • You may use astIntraReg to register a transformation function with the same name more than once, but only if the arguments supplied are identical on each occasion (i.e there is no way of changing things once a function has been successfully registered under a given name, and attempting to do so will result in an error). This feature simply allows registration to be performed independently, but consistently, at several places within your program, without having to check whether it has already been done.

  • If an error occurs in the transformation function, this may be indicated by setting the AST error status to an error value (using astSetStatus) before it returns. This will immediately terminate the current AST 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).
Transformation Flags
The following flags are defined in the ``ast.h'' header file and allow you to provide further information about the nature of the transformation function. Having selected the set of flags which apply, you should supply the bitwise OR of their values as the ``flags'' argument to astIntraReg.

  • AST__NOFWD: If this flag is set, it indicates that the transformation function does not implement a forward coordinate transformation. In this case, any IntraMap which uses it will have a TranForward attribute value of zero and the transformation function itself will not be invoked with its ``forward'' argument set to a non-zero value. By default, it is assumed that a forward transformation is provided.

  • AST__NOINV: If this flag is set, it indicates that the transformation function does not implement an inverse coordinate transformation. In this case, any IntraMap which uses it will have a TranInverse attribute value of zero and the transformation function itself will not be invoked with its ``forward'' argument set to zero. By default, it is assumed that an inverse transformation is provided.

  • AST__SIMPFI: You may set this flag if applying the transformation function's forward coordinate transformation, followed immediately by the matching inverse transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify). It is not necessary that both transformations have actually been implemented.

  • AST__SIMPIF: You may set this flag if applying the transformation function's inverse coordinate transformation, followed immediately by the matching forward transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify). It is not necessary that both transformations have actually been implemented.


next up previous 264
Next: astInvert - Invert a Mapping
Up: AST Function Descriptions
Previous: astIntraMap - Create an IntraMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council