#### Description:

This function compares two Frames and determines whether it is possible to convert between the coordinate systems which they represent. If conversion is possible, it returns a FrameSet which describes the conversion and which may be used (as a Mapping) to transform coordinate values in either direction.

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. astConvert 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.

#### Synopsis

AstFrameSet ∗astConvert( AstFrame ∗from, AstFrame ∗to, const char ∗domainlist )

#### Parameters:

##### from

Pointer to a Frame which represents the `"` 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).

##### to

Pointer to a Frame which represents the `"` 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).

##### domainlist

Pointer to a null-terminated character string containing a comma-separated list of Frame domains. This may be used to define a priority order for the different intermediate coordinate systems that might be used to perform the conversion.

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 an empty 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.

#### Applicability

##### DSBSpecFrame

If the AlignSideBand attribute is non-zero, alignment occurs in the upper sideband expressed within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest. If AlignSideBand is zero, the two DSBSpecFrames are aligned as if they were simple SpecFrames (i.e. the SideBand is ignored).

##### Frame

This function applies to all Frames. Alignment occurs within the coordinate system given by attribute AlignSystem.

##### FrameSet

If either of the `"` from`"` or `"` to`"` parameters is a pointer to a FrameSet, then astConvert will attempt to convert from the coordinate system described by the current Frame of the `"` from`"` FrameSet to that described by the current Frame of the `"` to`"` FrameSet.

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.

##### SpecFrame

Alignment occurs within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest.

##### TimeFrame

Alignment occurs within the time system and time scale given by attributes AlignSystem and AlignTimeScale.

#### Returned Value

##### astConvert()

If the requested coordinate conversion is possible, the function returns a pointer to a FrameSet which describes the conversion. Otherwise, a null Object pointer (AST__NULL) is returned without error.

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`"` parameter. Frame number 2 (its current Frame) will describe the destination coordinate system, corresponding to the `"` to`"` parameter. 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 astTran2), 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.

#### Examples:

cvt = astConvert( a, b, `"` `"` );

  Attempts to convert between the coordinate systems represented by `"` a`"` and `"` b`"` (assumed to be Frames). If successful, a FrameSet is returned via the `"` cvt`"` pointer which may be used to apply the conversion to sets of coordinates (e.g. using astTran2).

cvt = astConvert( astSkyFrame(`"` `"` ), astSkyFrame(`"` Equinox=2005`"` ), `"` `"` );

  Creates a FrameSet which describes precession in the default FK5 celestial coordinate system between equinoxes J2000 (also the default) and J2005. The returned `"` cvt`"` pointer may then be passed to astTran2 to apply this precession correction to any number of coordinate values given in radians.

  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.

cvt = astConvert( a, b, `"` sky,detector,`"` );

  Attempts to convert between the coordinate systems represented by the current Frames of `"` a`"` and `"` b`"` (now assumed to be FrameSets), via the intermediate `"` 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 astConvert 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.

#### Notes:

- 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 the AST error status set, or if it should fail for any reason.

Copyright (C) 2021 East Asian Observatory