|
| Frame (int naxes, std::string const &options="") |
|
virtual | ~Frame () |
|
| Frame (Frame const &)=default |
| Copy constructor: make a deep copy. More...
|
|
| Frame (Frame &&)=default |
|
Frame & | operator= (Frame const &)=delete |
|
Frame & | operator= (Frame &&)=default |
|
std::shared_ptr< Frame > | copy () const |
| Return a deep copy of this object. More...
|
|
double | angle (PointD const &a, PointD const &b, PointD const &c) const |
|
double | axAngle (PointD const &a, PointD const &b, int axis) const |
|
double | axDistance (int axis, double v1, double v2) const |
|
double | axOffset (int axis, double v1, double dist) const |
|
std::shared_ptr< FrameSet > | convert (Frame const &to, std::string const &domainlist="") |
|
double | distance (PointD const &point1, PointD const &point2) const |
|
std::shared_ptr< FrameSet > | findFrame (Frame const &tmplt, std::string const &domainlist="") |
|
std::string | format (int axis, double value) const |
|
bool | getActiveUnit () const |
|
std::string | getAlignSystem () const |
|
double | getBottom (int axis) const |
|
int | getDigits () const |
|
int | getDigits (int axis) const |
|
bool | getDirection (int axis) const |
|
std::string | getDomain () const |
|
double | getDut1 () const |
|
double | getEpoch () const |
|
std::string | getFormat (int axis) const |
|
std::string | getInternalUnit (int axis) const |
|
std::string | getLabel (int axis) const |
|
bool | getMatchEnd () const |
|
int | getMaxAxes () const |
|
int | getMinAxes () const |
|
int | getNAxes () const |
|
std::string | getNormUnit (int axis) const |
|
double | getObsAlt () const |
|
std::string | getObsLat () const |
|
std::string | getObsLon () const |
|
bool | getPermute () const |
|
bool | getPreserveAxes () const |
|
std::string | getSymbol (int axis) const |
|
std::string | getSystem () const |
|
std::string | getTitle () const |
|
double | getTop (int axis) const |
|
std::string | getUnit (int axis) const |
|
std::vector< double > | intersect (std::vector< double > const &a1, std::vector< double > const &a2, std::vector< double > const &b1, std::vector< double > const &b2) const |
|
std::vector< int > | matchAxes (Frame const &other) const |
|
CmpFrame | under (Frame const &next) const |
|
PointD | norm (PointD value) const |
|
PointD | offset (PointD point1, PointD point2, double offset) const |
|
DirectionPoint | offset2 (PointD const &point1, double angle, double offset) const |
|
void | permAxes (std::vector< int > perm) |
|
FrameMapping | pickAxes (std::vector< int > const &axes) const |
|
ResolvedPoint | resolve (std::vector< double > const &point1, std::vector< double > const &point2, std::vector< double > const &point3) const |
|
void | setAlignSystem (std::string const &system) |
|
void | setBottom (int axis, double bottom) |
|
void | setDigits (int digits) |
|
void | setDigits (int axis, int digits) |
|
void | setDirection (bool direction, int axis) |
|
virtual void | setDomain (std::string const &domain) |
|
void | setDut1 (double dut1) |
|
void | setEpoch (double epoch) |
|
void | setEpoch (std::string const &epoch) |
|
void | setFormat (int axis, std::string const &format) |
|
void | setLabel (int axis, std::string const &label) |
|
void | setMatchEnd (bool match) |
|
void | setMaxAxes (int maxAxes) |
|
void | setMinAxes (int minAxes) |
|
void | setObsAlt (double alt) |
|
void | setObsLat (std::string const &lat) |
|
void | setObsLon (std::string const &lon) |
|
void | setActiveUnit (bool enable) |
|
void | setPermute (bool permute) |
|
void | setPreserveAxes (bool preserve) |
|
void | setSymbol (int axis, std::string const &symbol) |
|
void | setSystem (std::string const &system) |
|
void | setTitle (std::string const &title) |
|
void | setTop (int axis, double top) |
|
void | setUnit (int axis, std::string const &unit) |
|
NReadValue | unformat (int axis, std::string const &str) const |
|
virtual | ~Mapping () |
|
| Mapping (Mapping const &)=default |
| Copy constructor: make a deep copy. More...
|
|
| Mapping (Mapping &&)=default |
|
Mapping & | operator= (Mapping const &)=delete |
|
Mapping & | operator= (Mapping &&)=default |
|
std::shared_ptr< Mapping > | copy () const |
| Return a deep copy of this object. More...
|
|
int | getNIn () const |
|
int | getNOut () const |
|
bool | getIsSimple () const |
|
bool | isInverted () const |
|
bool | getIsLinear () const |
|
bool | getReport () const |
|
bool | hasForward () const |
|
bool | hasInverse () const |
|
std::shared_ptr< Mapping > | inverted () const |
|
Array2D | linearApprox (PointD const &lbnd, PointD const &ubnd, double tol) const |
|
SeriesMap | then (Mapping const &next) const |
|
ParallelMap | under (Mapping const &next) const |
|
double | rate (PointD const &at, int ax1, int ax2) const |
|
void | setReport (bool report) |
|
std::shared_ptr< Mapping > | simplified () const |
|
void | applyForward (ConstArray2D const &from, Array2D const &to) const |
|
Array2D | applyForward (ConstArray2D const &from) const |
|
std::vector< double > | applyForward (std::vector< double > const &from) const |
|
void | applyInverse (ConstArray2D const &from, Array2D const &to) const |
|
Array2D | applyInverse (ConstArray2D const &from) const |
|
std::vector< double > | applyInverse (std::vector< double > const &from) const |
|
void | tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const |
|
Array2D | tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const |
|
void | tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const |
|
Array2D | tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const |
|
virtual | ~Object () |
|
| Object (Object const &object) |
| Copy constructor: make a deep copy. More...
|
|
| Object (Object &&)=default |
|
Object & | operator= (Object const &)=delete |
|
Object & | operator= (Object &&)=default |
|
bool | operator== (Object const &rhs) const |
|
bool | operator!= (Object const &rhs) const |
|
std::shared_ptr< Object > | copy () const |
| Return a deep copy of this object. More...
|
|
void | clear (std::string const &attrib) |
|
bool | hasAttribute (std::string const &attrib) const |
|
std::string | getClassName () const |
|
std::string | getID () const |
| Get ID: object identification string that is not copied. More...
|
|
std::string | getIdent () const |
| Get Ident: object identification string that is copied. More...
|
|
int | getNObject () const |
|
int | getObjSize () const |
| Get ObjSize: the in-memory size of the AST object in bytes. More...
|
|
int | getRefCount () const |
|
bool | getUseDefs () const |
| Get UseDefs: allow use of default values for Object attributes? More...
|
|
void | lock (bool wait) |
|
bool | same (Object const &other) const |
|
void | setID (std::string const &id) |
| Set ID: object identification string that is not copied. More...
|
|
void | setIdent (std::string const &ident) |
| Set Ident: object identification string that is copied. More...
|
|
void | setUseDefs (bool usedefs) |
| Set UseDefs: allow use of default values for Object attributes? More...
|
|
void | show (std::ostream &os, bool showComments=true) const |
|
std::string | show (bool showComments=true) const |
|
bool | test (std::string const &attrib) const |
|
void | unlock (bool report=false) |
|
AstObject const * | getRawPtr () const |
|
AstObject * | getRawPtr () |
|
|
| Frame (AstFrame *rawPtr) |
|
virtual std::shared_ptr< Object > | copyPolymorphic () const override |
|
| Mapping (AstMapping *rawMap) |
|
template<typename Class > |
std::shared_ptr< Class > | decompose (int i, bool copy) const |
|
| Object (AstObject *object) |
|
template<typename T , typename AstT > |
std::shared_ptr< T > | copyImpl () const |
|
bool | getB (std::string const &attrib) const |
|
std::string const | getC (std::string const &attrib) const |
|
double | getD (std::string const &attrib) const |
|
float | getF (std::string const &attrib) const |
|
int | getI (std::string const &attrib) const |
|
long int | getL (std::string const &attrib) const |
|
void | set (std::string const &setting) |
|
void | setB (std::string const &attrib, bool value) |
|
void | setC (std::string const &attrib, std::string const &value) |
|
void | setD (std::string const &attrib, double value) |
|
void | setF (std::string const &attrib, float value) |
|
void | setI (std::string const &attrib, int value) |
|
void | setL (std::string const &attrib, long int value) |
|
Frame is used to represent a coordinate system.
It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a Title (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two.
Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame.
Frames may also contain knowledge of how to transform to and from related coordinate systems.
Attributes
In addition to those provided by Mapping and Object, Frame provides the following attributes, where axis
is an axis number, starting from 1 and (axis)
may be omitted if the Frame has only one axis:
std::shared_ptr< FrameSet > ast::Frame::findFrame |
( |
Frame const & |
tmplt, |
|
|
std::string const & |
domainlist = "" |
|
) |
| |
Find a coordinate system with specified characteristics.
Use 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:
- Is there a wavelength scale?
- Is there a 2-dimensional coordinate system?
- Is there a celestial coordinate system?
- Can I plot the data in ecliptic coordinates?
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.
Applicability to Subclasses
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. 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, then the FrameSet's 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.
Examples
auto result = target.findFrame(ast::Frame(3))
Search for a 3-dimensional coordinate system in the target Frame (or FrameSet). No attributes have been set in the template Frame (created by ast::Frame), 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.
auto result = target.findFrame(astSkyFrame())
Search 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.
auto result = target.findFrame(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.
auto result = target.findFrame(astSkyFrame("System=FK5"))
Search 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.
auto result = target.findFrame(astFrame(2), "sky,pixel,")
Search 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 the search fail.
auto result = target.findFrame(astFrame(1, "Domain=WAVELENGTH"))
Searches for any 1-dimensional coordinate system in the target which has the domain "WAVELENGTH".
auto result = target.findFrame(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.
auto result = target.findFrame(Frame(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.
auto result = target.findFrame(SkyFrame("Permute=0"))
Search 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).
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:
- In general, a template will only match another Frame which belongs to the same class as the template, or to a derived (more specialised) class. For example, a SkyFrame template will match any other SkyFrame, but will not match a basic Frame. Conversely, a basic Frame template will match any class of Frame.
- The exception to this is that a Frame of any class can be used to match a CmpFrame, if that CmpFrame contains a Frame of the same class as the template. Note however, the MaxAxes and MinAxes attributes of the template must be set to suitable values to allow it to match the CmpFrame. That is, the MinAxes attribute must be less than or equal to the number of axes in the target, and the MaxAxes attribute must be greater than or equal to the number of axes in the target.
- If using a CmpFrame as a template frame, the MinAxes and MaxAxes for the template are determined by the MinAxes and MaxAxes values of the component Frames within the template. So if you want a template CmpFrame to be able to match Frames with different numbers of axes, then you must set the MaxAxes and/or MinAxes attributes in the component template Frames, before combining them together into the template CmpFrame.
- If a template has a value set for any of its main attributes, then it will only match Frames which have an identical value for that attribute (or which can be transformed, using a built-in conversion, so that they have the required value for that attribute). If any attribute in the template is un-set, however, then Frames are matched regardless of the value they may have for that attribute. You may therefore make a template more or less specific by choosing the attributes for which you set values. This requirement does not apply to 'descriptive' attributes such as titles, labels, symbols, etc.
- An important application of this principle involves the Domain attribute. Setting the Domain attribute of the template has the effect of restricting the search to a particular type of Frame (with the domain you specify). Conversely, if the Domain attribute is not set in the template, then the domain of the Frame found is not relevant, so all Frames are searched. Note that the "domainlist" string provides an alternative way of restricting the search in the same manner, but is a more convenient interface if you wish to search automatically for another domain if the first search fails.
- Normally, a template will only match a Frame which has the same number of axes as itself. However, for some classes of template, this default behaviour may be changed by means of the MinAxes, MaxAxes and MatchEnd attributes. In addition, the behaviour of a template may be influenced by its Permute and PreserveAxes attributes, which control whether it matches Frames whose axes have been permuted, and whether this permutation is retained in the Frame which is returned (as opposed to returning the axes in the order specified in the template, which is the default behaviour). You should consult the descriptions of these attributes for details of this more advanced use of templates.
- Parameters
-
[in,out] | tmplt | 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. |
[in] | domainlist | 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. |
- Returns
- A std::shared_ptr<FrameSet> which contains the Frame found and a description of how to convert to (and from) the coordinate system it represents. If the Frame is not found then return a null pointer.
This FrameSet 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, 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.
Notes
- This method is not const because if called on a FrameSet then the BASE frame of the FrameSet may be changed. No other kind of frame will be altered.
- Similarly the
tmpl
argument is not const because if it is a FrameSet then the BASE frame of the template may be changed. No other kind of frame will be altered.
- The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the "template" Frame. See the description of the AlignSystem for further details.
- Beware of setting the
Domain
attribute of the template and then using a "domainlist" string which does not include the template's domain (or a blank field). If you do so, no coordinate system will be found.
NReadValue ast::Frame::unformat |
( |
int |
axis, |
|
|
std::string const & |
str |
|
) |
| const |
|
inline |
Read a formatted coordinate value (given as a character string) for a Frame axis and return the number of characters read and the value.
The principle use of this function is in decoding user-supplied input which contains formatted coordinate values. Free-format input is supported as far as possible. If input is ambiguous, it is interpreted with reference to the Frame's attributes (in particular, the Format string associated with the Frame's axis).
This function is, in essence, the inverse of astFormat.
Applicability:
Frame This function applies to all Frames. See the "Frame Input
Format" section below for details of the input formats accepted by a basic Frame.
SkyFrame The SkyFrame class re-defines the input format to be suitable for representing angles and times, with the resulting coordinate value returned in radians. See the "SkyFrame
Input Format" section below for details of the formats accepted.
FrameSet The input formats accepted by a FrameSet are determined by its current Frame (as specified by the Current attribute).
Frame Input Format:
The input format accepted for a basic Frame axis is as follows:
- An optional sign, followed by:
- A sequence of one or more digits possibly containing a decimal point, followed by:
- An optional exponent field.
- The exponent field, if present, consists of "E" or "e" followed by a possibly signed integer.
Examples of acceptable Frame input formats include:
99
1.25
-1.6
1E8
-.99e-17
<bad>
SkyFrame Input Format:
The input format accepted for a SkyFrame axis is as follows:
- An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. "-12 42 03").
- Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as "124.707", while degrees and decimal arc-minutes might be given as "-13 33.8").
- The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. "720 45 31" is valid, whereas "11 45 61" is not).
- Fields may be separated by white space or by ":" (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. "- 2: 04 : 7.1").
- The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: "d"—degrees; "h"—hours; "m"—minutes of arc or time; "s"—seconds of arc or time; "'" (single quote)—minutes of arc; """ (double quote)—seconds of arc.
Either lower or upper case may be used. Fields must be given in
order of decreasing significance (e.g. "-11D 3' 14.4"" or "22h14m11.2s").
- The presence of any of the field identification characters "d", "'" (single quote) or """ (double quote) indicates that the
value is to be interpreted as an angle. Conversely, the presence
of "h" indicates that it is to be interpreted as a time (with 24
hours corresponding to 360 degrees). Incompatible angle/time
identification characters may not be mixed (e.g. "10h14'3"" is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either.
- If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by astFormat are correctly interpreted by Frame.unformat.
- If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by Frame.format are correctly interpreted by Frame.unformat.
- Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. "-05m13s" is equivalent to "-:05:13"). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. "14:25.4s" specifies minutes and seconds, while "14::25.4s" specifies degrees and seconds).
- If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. "01:02"), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that astFormat would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that astFormat would produce.
- If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. "01:02"), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that Frame.format would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that Frame.format would produce.
This final convention is intended to ensure that values formatted by Frame.format which contain less than three fields will be correctly interpreted if read back using Frame.unformat, even if they do not contain field identification characters.
Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include:
- ‘-14d 13m 22.2s (-14d 13’ 22.2")`
- `+ 12:34:56.7` (12d 34' 56.7" or 12h 34m 56.7s)
001 : 02 : 03.4
(1d 02' 03.4" or 1h 02m 03.4s)
- <tt>22h 30</tt> (22h 30m 00s)
- <tt>136::10" (136d 00' 10" or 136h 00m 10s)
- `-14M 27S` (-0d 14' 27" or -0h 14m 27s)
-:14:
(-0d 14' 00" or -0h 14m 00s)
- `-::4.1` (-0d 00' 04.1" or -0h 00m 04.1s)
.9"</tt> (0d 00' 00.9")
`d12m` (0d 12' 00")
- <tt>H 12:22.3s</tt> (0h 12m 22.3s)
- <tt>\<bad\></tt> (<tt>AST__BAD</tt>)
Where alternative interpretations are shown, the choice of angle or
time depends on the associated Format(axis) attribute.
@param [in] axis The number of the Frame axis for which the coordinate value
is to be read (axis numbering starts at zero for the first axis).
@param [in] str String containing the formatted coordinate value.
@return an NReadValue containing the number of characters read and the value;
if nread is 0 then the value is certainly invalid.
@subsubsection autotoc_md130 Notes
- Any white space at the beginning of the string will be
skipped, as also will any trailing white space following the
coordinate value read. The number of characters read will reflect this.
- The number of characters will be 0 and the value undefined
if the string supplied does not contain a suitably formatted value.
- The string "<bad>" is recognised as a special case and will generate the value AST__BAD, without error. The test for this string is case-insensitive and permits embedded white space.