astFindFrame

Find a coordinate system with specified characteristics

Description:

This function uses a " template" Frame to search another Frame (or FrameSet) to identify a coordinate system which has a specified set of characteristics. If a suitable coordinate system can be found, the function returns a pointer to a FrameSet which describes the required coordinate system and how to convert coordinates to and from it.

This function is provided to help answer general questions about coordinate systems, such as typically arise when coordinate information is imported into a program as part of an initially unknown dataset. For example:

You can also use this function as a means of reconciling a user s preference for a particular coordinate system (for example, what type of axes to draw) with what is actually possible given the coordinate information available.

To perform a search, you supply a " target" Frame (or FrameSet) which represents the set of coordinate systems to be searched. If a basic Frame is given as the target, this set of coordinate systems consists of the one described by this Frame, plus all other " virtual" coordinate systems which can potentially be reached from it by applying built-in conversions (for example, any of the celestial coordinate conversions known to the AST library would constitute a " built-in" conversion). If a FrameSet is given as the target, the set of coordinate systems to be searched consists of the union of those represented by all the individual Frames within it.

To select from this large set of possible coordinate systems, you supply a " template" Frame which is an instance of the type of Frame you are looking for. Effectively, you then ask the function to " find a coordinate system that looks like this" .

You can make your request more or less specific by setting attribute values for the template Frame. If a particular attribute is set in the template, then the function will only find coordinate systems which have exactly the same value for that attribute. If you leave a template attribute un-set, however, then the function has discretion about the value the attribute should have in any coordinate system it finds. The attribute will then take its value from one of the actual (rather than virtual) coordinate systems in the target. If the target is a FrameSet, its Current attribute will be modified to indicate which of its Frames was used for this purpose.

The result of this process is a coordinate system represented by a hybrid Frame which acquires some attributes from the template (but only if they were set) and the remainder from the target. This represents the " best compromise" between what you asked for and what was available. A Mapping is then generated which converts from the target coordinate system to this hybrid one, and the returned FrameSet encapsulates all of this information.

Synopsis

AstFrameSet astFindFrame( AstFrame target, AstFrame template, const char domainlist )

Parameters:

target
Pointer to the target Frame (or FrameSet).

Note that if a FrameSet is supplied (and a suitable coordinate system is found), then its Current attribute will be modified to indicate which Frame was used to obtain attribute values which were not specified by the template. This Frame will, in some sense, represent the " closest" non-virtual coordinate system to the one you requested.

template
Pointer to the template Frame, which should be an instance of the type of Frame you wish to find. If you wanted to find a Frame describing a celestial coordinate system, for example, then you might use a SkyFrame here. See the " Examples" section for more ideas.
domainlist
Pointer to a null-terminated character string containing a comma-separated list of Frame domains. This may be used to establish a priority order for the different types of coordinate system that might be found.

The function will first try to find a suitable coordinate system whose Domain attribute equals the first domain in this list. If this fails, the second domain in the list will be used, and so on, until a result is obtained. A blank domain (e.g. two consecutive commas) indicates that any coordinate system is acceptable (subject to the template) regardless of its domain.

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.

Applicability

Frame
This function applies to all Frames.
FrameSet
If the target is a FrameSet, the possibility exists that several of the Frames within it might be matched by the template. Unless the choice is sufficiently restricted by the " domainlist" string, the sequence in which Frames are searched can then become important. In this case, the search proceeds as follows:
  • Each field in the " domainlist" string is considered in turn.

  • An attempt is made to match the template to each of the target s Frames in the order: (1) the current Frame, (2) the base Frame, (3) each remaining Frame in the order of being added to the target FrameSet.

  • Generally, the first match found is used. However, the Mapping between the target coordinate system and the resulting Frame 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 a match is found and the domain of the resulting Frame also matches the current " domainlist" field, it is accepted. Otherwise, the next " domainlist" field is considered and the process repeated.

If a suitable coordinate system is found, the Current attribute of the target FrameSet will be modified on exit to identify the Frame whose match with the target was eventually accepted.

Returned Value

astFindFrame()
If the search is successful, the function returns a pointer to a FrameSet which contains the Frame found and a description of how to convert to (and from) the coordinate system it represents. 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) represents the target coordinate system and will be the same as the (base Frame of the) target. Frame number 2 (its current Frame) will be a Frame representing the coordinate system which the function found. The Mapping which inter-relates these two Frames will describe how to convert 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 target coordinate system into the new coordinate system that was found (and vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the new coordinate system.

Examples:

result = astFindFrame( target, astFrame( 3, " " ), " " );
Searches for a 3-dimensional coordinate system in the target Frame (or FrameSet). No attributes have been set in the template Frame (created by astFrame), so no restriction has been placed on the required coordinate system, other than that it should have 3 dimensions. The first suitable Frame found will be returned as part of the " result" FrameSet.
result = astFindFrame( target, astSkyFrame( " " ), " " );
Searches for a celestial coordinate system in the target Frame (or FrameSet). The type of celestial coordinate system is unspecified, so astFindFrame will return the first one found as part of the " result" FrameSet. If the target is a FrameSet, then its Current attribute will be updated to identify the Frame that was used.

If no celestial coordinate system can be found, a value of AST__NULL will be returned without error.

result = astFindFrame( target, astSkyFrame( " MaxAxes=100" ), " " );
This is like the last example, except that in the event of the target being a CmpFrame, the component Frames encapsulated by the CmpFrame will be searched for a SkyFrame. If found, the returned Mapping will included a PermMap which selects the required axes from the target CmpFrame.

This is acomplished by setting the MaxAxes attribute of the template SkyFrame to a large number (larger than or equal to the number of axes in the target CmpFrame). This allows the SkyFrame to be used as a match for Frames containing from 2 to 100 axes.

result = astFindFrame( target, astSkyFrame( " System=FK5" ), " " );
Searches for an equatorial (FK5) coordinate system in the target. The Equinox value for the coordinate system has not been specified, so will be obtained from the target. If the target is a FrameSet, its Current attribute will be updated to indicate which SkyFrame was used to obtain this value.
result = astFindFrame( target, astFrame( 2, " " ), " sky,pixel," );
Searches for a 2-dimensional coordinate system in the target. Initially, a search is made for a suitable coordinate system whose Domain attribute has the value " SKY" . If this search fails, a search is then made for one with the domain " PIXEL" . If this also fails, then any 2-dimensional coordinate system is returned as part of the " result" FrameSet.

Only if no 2-dimensional coordinate systems can be reached by applying built-in conversions to any of the Frames in the target will a value of AST__NULL be returned.

result = astFindFrame( target, astFrame( 1, " Domain=WAVELENGTH" ), " " );
Searches for any 1-dimensional coordinate system in the target which has the domain " WAVELENGTH" .
result = astFindFrame( target, astFrame( 1, " " ), " wavelength" );
This example has exactly the same effect as that above. It illustrates the equivalence of the template s Domain attribute and the fields in the " domainlist" string.
result = astFindFrame( target, astFrame( 1, " MaxAxes=3" ), " " );
This is a more advanced example which will search for any coordinate system in the target having 1, 2 or 3 dimensions. The Frame returned (as part of the " result" FrameSet) will always be 1-dimensional, but will be related to the coordinate system that was found by a suitable Mapping (e.g. a PermMap) which simply extracts the first axis.

If we had wanted a Frame representing the actual (1, 2 or 3-dimensional) coordinate system found, we could set the PreserveAxes attribute to a non-zero value in the template.

result = astFindFrame( target, astSkyFrame( " Permute=0" ), " " );
Searches for any celestial coordinate system in the target, but only finds one if its axes are in the conventional (longitude,latitude) order and have not been permuted (e.g. with astPermAxes).

Notes:

More on Using Templates

A Frame (describing a coordinate system) will be found by this function if (a) it is " matched" by the template you supply, and (b) the value of its Domain attribute appears in the " domainlist" string (except that a blank field in this string permits any domain). A successful match by the template depends on a number of criteria, as outlined below: