Determine how to convert between two coordinate systems AST_CONVERT
The same function may also be used to determine how to convert between two FrameSets (or between a Frame and a FrameSet, or vice versa). This mode is intended for use when (for example) two images have been calibrated by attaching a FrameSet to each. AST_CONVERT might then be used to search for a celestial coordinate system that both images have in common, and the result could then be used to convert between the pixel coordinates of both images – having effectively used their celestial coordinate systems to align them.
When using FrameSets, there may be more than one possible intermediate coordinate system in which to perform the conversion (for instance, two FrameSets might both have celestial coordinates, detector coordinates, pixel coordinates, etc.). A comma-separated list of coordinate system domains may therefore be given which defines a priority order to use when selecting the intermediate coordinate system. The path used for conversion must go via an intermediate coordinate system whose Domain attribute matches one of the domains given. If conversion cannot be achieved using the first domain, the next one is considered, and so on, until success is achieved.
" source"
coordinate system. This is the coordinate system in which you already have coordinates
available.
If a FrameSet is given, its current Frame (as determined by its Current attribute) is taken to describe
the source coordinate system. Note that the Base attribute of this FrameSet may be modified by this
function to indicate which intermediate coordinate system was used (see under " FrameSets" in the "
Applicability" section for details).
" destination" coordinate system. This is the coordinate system into which you wish to convert your
coordinates.
If a FrameSet is given, its current Frame (as determined by its Current attribute) is taken to describe
the destination coordinate system. Note that the Base attribute of this FrameSet may be modified
by this function to indicate which intermediate coordinate system was used (see under "
FrameSets" in the " Applicability" section for details).
The function will first try to obtain a conversion by making use only of an intermediate coordinate system whose Domain attribute matches the first domain in this list. If this fails, the second domain in the list will be used, and so on, until conversion is achieved. A blank domain (e.g. two consecutive commas) indicates that all coordinate systems should be considered, regardless of their domains.
This list is case-insensitive and all white space is ignored. If you do not wish to restrict the domain in this way, you should supply a blank string. This is normally appropriate if either of the source or destination coordinate systems are described by Frames (rather than FrameSets), since there is then usually only one possible choice of intermediate coordinate system.
To achieve this, it will consider all of the Frames within each FrameSet as a possible way of reaching an intermediate coordinate system that can be used for the conversion. There is then the possibility that more than one conversion path may exist and, unless the choice is sufficiently restricted by the DOMAINLIST string, the sequence in which the Frames are considered can be important. In this case, the search for a conversion path proceeds as follows:
Each field in the DOMAINLIST string is considered in turn.
The Frames within each FrameSet are considered in a specific order: (1) the base Frame is always
considered first, (2) after this come all the other Frames in Frame-index order (but omitting the base
and current Frames), (3) the current Frame is always considered last. However, if either FrameSet’ s
Invert attribute is set to a non-zero value (so that the FrameSet is inverted), then its Frames are
considered in reverse order. (Note that this still means that the base Frame is considered first
and the current Frame last, because the Invert value will also cause these Frames to swap
places.)
All source Frames are first considered (in the appropriate order) for conversion to the first destination Frame. If no suitable intermediate coordinate system emerges, they are then considered again for conversion to the second destination Frame (in the appropriate order), and so on.
Generally, the first suitable intermediate coordinate system found is used. However, the overall Mapping between the source and destination coordinate systems is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the TranForward and TranInverse attributes). If only one transformation is defined, the forward one is preferred.
If the domain of the intermediate coordinate system matches the current DOMAINLIST field, the conversion path is accepted. Otherwise, the next DOMAINLIST field is considered and the process repeated.
If conversion is possible, the Base attributes of the two FrameSets will be modified on exit to identify the Frames used to access the intermediate coordinate system which was finally accepted.
Note that it is possible to force a particular Frame within a FrameSet to be used as the basis for the intermediate coordinate system, if it is suitable, by (a) focussing attention on it by specifying its domain in the DOMAINLIST string, or (b) making it the base Frame, since this is always considered first.
If a FrameSet is returned, it will contain two Frames. Frame number 1 (its base Frame) will describe the source coordinate system, corresponding to the FROM argument. Frame number 2 (its current Frame) will describe the destination coordinate system, corresponding to the TO argument. The Mapping which inter-relates these two Frames will perform the required conversion between their respective coordinate systems.
Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with AST_TRAN2), then it provides a means of converting coordinates from the source to the destination coordinate system (or vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the destination coordinate system.
’ ’ , STATUS ) ’ ’
, STATUS ), AST_SKYFRAME( ’ Equinox=2005’ , STATUS ), ’ ’ , STATUS ) Note that the returned FrameSet also contains information about how to format coordinate values. This means that setting its Report attribute to 1 is a simple way to obtain printed output (formatted in sexagesimal notation) to show the coordinate values before and after conversion.
’ SKY,DETECTOR,’ , STATUS ) " SKY" coordinate system. This,
by default, is the Domain associated with a celestial coordinate system represented by a
SkyFrame.
If this fails (for example, because either FrameSet lacks celestial coordinate information), then the
user-defined " DETECTOR" coordinate system is used instead. If this also fails, then all other possible
ways of achieving conversion are considered before giving up.
The returned pointer CVT indicates whether conversion was possible and will have the value AST__NULL if it was not. If conversion was possible, CVT will point at a new FrameSet describing the conversion.
The Base attributes of the two FrameSets will be set by AST_CONVERT to indicate which of their Frames was used for the intermediate coordinate system. This means that you can subsequently determine which coordinate system was used by enquiring the Domain attribute of either base Frame.
The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the TO Frame. See the description of the AlignSystem attribute for further details.
When aligning (say) two images, which have been calibrated by attaching FrameSets to them, it is
usually necessary to convert between the base Frames (representing " native" pixel coordinates) of
both FrameSets. This may be achieved by inverting the FrameSets (e.g. using astInvert) so as to
interchange their base and current Frames before using astConvert.
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.