next up previous 264
Next: AST_INVERT - Invert a Mapping
Up: AST Routine Descriptions
Previous: AST_INTRAMAP - Create an IntraMap


AST_INTRAREG - Register a transformation routine for use by an IntraMap

Description:
This function registers a privately-defined coordinate transformation routine written in Fortran so that it may be used to create an IntraMap. An IntraMap is a specialised form of Mapping which encapsulates the Fortran routine 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 routines is required before using the AST_INTRAMAP constructor function to create an IntraMap or reading an external representation of an IntraMap from a Channel.

Invocation:
CALL AST_INTRAREG( NAME, NIN, NOUT, TRAN, FLAGS, PURPOSE, AUTHOR, CONTACT, STATUS )
Arguments:
NAME = CHARACTER $*$ ( $*$ ) (Given)
A character string containing a unique name to be associated with the transformation routine in order to identify it. This name is case sensitive. All white space will be removed before use.
NIN = INTEGER (Given)
The number of input coordinates accepted by the transformation routine (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 routine is able to accommodate a variable number of input coordinates.
NOUT = INTEGER (Given)
The number of output coordinates produced by the transformation routine (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 routine is able to produce a variable number of output coordinates.
TRAN = SUBROUTINE (Given)
The transformation routine to be registered. This routine should perform whatever coordinate transformations are required and should have an interface like AST_TRANN (q.v.).

This transformation routine must also appear in an EXTERNAL statement in the routine which calls AST_INTRAREG.

FLAGS = INTEGER (Given)
This value may be used to supply a set of flags which describe the transformation routine 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 sum of a set of flags as described in the "Transformation Flags" section (below).
PURPOSE = CHARACTER $*$ ( $*$ ) (Given)
A character string containing a short (one line) textual comment to describe the purpose of the transformation routine.
AUTHOR = CHARACTER $*$ ( $*$ ) (Given)
A character string containing the name of the author of the transformation routine.
CONTACT = CHARACTER $*$ ( $*$ ) (Given)
A character string containing contact details for the author of the transformation routine (e.g. an e-mail or WWW address). If any IntraMap which uses this transformation routine is exported as part of a dataset to an external user who does not have access to the routine, then these contact details should allow them to obtain the necessary code.
STATUS = INTEGER (Given and Returned)
The global status.
Notes:
  • Beware that an external representation of an IntraMap (created by writing it to a Channel) will not include the coordinate transformation routine which it uses, so will only refer to the routine by its name (as assigned using AST_INTRAREG). Consequently, the external representation cannot be utilised by another program unless that program has also registered the same transformation routine with the same name using an identical invocation of AST_INTRAREG. If no such registration has been performed, then attempting to read the external representation will result in an error.

  • You may use AST_INTRAREG to register a transformation routine 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 routine 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 routine, this may be indicated by setting its STATUS argument to an error value 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). The AST__ITFER error value is defined in the AST_ERR include file.
Transformation Flags
The following flags are defined in the AST_PAR include file and allow you to provide further information about the nature of the transformation routine. Having selected the set of flags which apply, you should supply the sum of their values as the FLAGS argument to AST_INTRAREG.

  • AST__NOFWD: If this flag is set, it indicates that the transformation routine 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 routine itself will not be called with its FORWARD argument set to .TRUE.. By default, it is assumed that a forward transformation is provided.

  • AST__NOINV: If this flag is set, it indicates that the transformation routine 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 routine itself will not be called with its FORWARD argument set to .FALSE.. By default, it is assumed that an inverse transformation is provided.

  • AST__SIMPFI: You may set this flag if applying the transformation routine'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 AST_SIMPLIFY). It is not necessary that both transformations have actually been implemented.

  • AST__SIMPIF: You may set this flag if applying the transformation routine'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 AST_SIMPLIFY). It is not necessary that both transformations have actually been implemented.


next up previous 264
Next: AST_INVERT - Invert a Mapping
Up: AST Routine Descriptions
Previous: AST_INTRAMAP - Create an IntraMap

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

Copyright (C) 2009 Science \& Technology Facilities Council