next up previous 264
Next: AST_TRANN - Transform N-dimensional coordinates
Up: AST Routine Descriptions
Previous: AST_TRANGRID - Transform a grid of positions


AST_TRANMAP - Create a TranMap

Description:
This function creates a new TranMap and optionally initialises its attributes.

A TranMap is a Mapping which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist).

When the forward transformation of the TranMap is referred to, the transformation actually used is the forward transformation of the first Mapping supplied when the TranMap was constructed. Likewise, when the inverse transformation of the TranMap is referred to, the transformation actually used is the inverse transformation of the second Mapping supplied when the TranMap was constructed.

Invocation:
RESULT = AST_TRANMAP( MAP1, MAP2, OPTIONS, STATUS )
Arguments:
MAP1 = INTEGER (Given)
Pointer to the first component Mapping, which defines the forward transformation.
MAP2 = INTEGER (Given)
Pointer to the second component Mapping, which defines the inverse transformation.
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new TranMap. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_TRANMAP = INTEGER
A pointer to the new TranMap.
Notes:
  • The number of output coordinates generated by the two Mappings (their Nout attribute) must be equal, as must the number of input coordinates accepted by each Mapping (their Nin attribute).

  • The forward transformation of the first Mapping must exist.

  • The inverse transformation of the second Mapping must exist.

  • Note that the component Mappings supplied are not copied by AST_TRANMAP (the new TranMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a TranMap containing a copy of its component Mappings is required, then a copy of the TranMap should be made using AST_COPY.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".


next up previous 264
Next: AST_TRANN - Transform N-dimensional coordinates
Up: AST Routine Descriptions
Previous: AST_TRANGRID - Transform a grid of positions

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