LSST Applications g0f08755f38+82efc23009,g12f32b3c4e+e7bdf1200e,g1653933729+a8ce1bb630,g1a0ca8cf93+50eff2b06f,g28da252d5a+52db39f6a5,g2bbee38e9b+37c5a29d61,g2bc492864f+37c5a29d61,g2cdde0e794+c05ff076ad,g3156d2b45e+41e33cbcdc,g347aa1857d+37c5a29d61,g35bb328faa+a8ce1bb630,g3a166c0a6a+37c5a29d61,g3e281a1b8c+fb992f5633,g414038480c+7f03dfc1b0,g41af890bb2+11b950c980,g5fbc88fb19+17cd334064,g6b1c1869cb+12dd639c9a,g781aacb6e4+a8ce1bb630,g80478fca09+72e9651da0,g82479be7b0+04c31367b4,g858d7b2824+82efc23009,g9125e01d80+a8ce1bb630,g9726552aa6+8047e3811d,ga5288a1d22+e532dc0a0b,gae0086650b+a8ce1bb630,gb58c049af0+d64f4d3760,gc28159a63d+37c5a29d61,gcf0d15dbbd+2acd6d4d48,gd7358e8bfb+778a810b6e,gda3e153d99+82efc23009,gda6a2b7d83+2acd6d4d48,gdaeeff99f8+1711a396fd,ge2409df99d+6b12de1076,ge79ae78c31+37c5a29d61,gf0baf85859+d0a5978c5a,gf3967379c6+4954f8c433,gfb92a5be7c+82efc23009,gfec2e1e490+2aaed99252,w.2024.46
LSST Data Management Base Package
|
Pay attention to units when one Frame is used to match another (by Frame::findFrame or Frame::convert)? (bool)
If the ActiveUnit
flag is set in both template and target Frames then the returned Mapping takes into account any differences in axis units. The default value for simple Frames is zero, which preserves the behaviour of versions of AST prior to version 2.0.
If the ActiveUnit
flag of either Frame is false
then the Mapping will ignore any difference in the Unit attributes of corresponding template and target axes. In this mode, the Unit attributes are purely descriptive commentary for the benefit of human readers and do not influence the Mappings between Frames. This is the behaviour which all Frames had in older version of AST, prior to the introduction of this attribute.
If the ActiveUnit
flag of both Frames is true
then the Mapping from template to target will take account of any difference in the axis Unit attributes, where-ever possible. For instance, if corresponding target and template axes have Unit strings of "km" and "m", then the FrameSet class will use a ZoomMap to connect them which introduces a scaling of 1000. If no Mapping can be found between the corresponding units string, then an error is reported. In this mode, it is assumed that values of the Unit attribute conform to the syntax for units strings described in the FITS WCS Paper I "Representations of world coordinates in FITS" (Greisen & Calabretta). Particularly, any of the named unit symbols, functions, operators or standard multiplier prefixes listed within that paper can be used within a units string. A units string may contain symbols for unit which are not listed in the FITS paper, but transformation to any other units will then not be possible (except to units which depend only on the same unknown units - thus "flops" can be transformed to "Mflops" even though "flops" is not a standard FITS unit symbol).
A range of common non-standard variations of unit names and multiplier prefixes are also allowed, such as adding an "s" to the end of Angstrom, using a lower case "a" at the start of "angstrom", "micron" instead of "um", "sec" instead of "s", etc.
If the ActiveUnit
flag is true
, setting a new Unit value for an axis may also change its Label and Symbol attributes.For instance, if an axis has Unit "Hz" and Label "frequency", then changing its Unit to "log(Hz)" will change its Label to "log( frequency )". In addition, the Axis Format attribute will be cleared when-ever a new value is assigned to the Unit attribute.
Note, if a true
value is set for the ActiveUnit
flag, then changing a Unit value for the current Frame within a FrameSet will result in the Frame being re-mapped (that is, the Mappings which define the relationships between Frames within the FrameSet will be modified to take into account the change in Units).
The ActiveUnit
flag for a SkyFrame is always false
(any value supplied using this routine is ignored).
The ActiveUnit
flag for a SpecFrame is always true
(any value supplied using this routine is ignored).
The ActiveUnit
flag for a FluxFrame is always true
(any value supplied using this routine is ignored).
The default ActiveUnit
flag for a CmpFrame is true
if both of the component Frames are using active units, and false
otherwise. When a new value is set for the ActiveUnit
flag, the flag value is propagated to the component Frames. This change will be reflected through all references to the component Frames, not just those encapsulated within the CmpFrame.
Regions always use active units if possible.
ActiveUnit
flag is not truly a Frame attribute because it can only be accessed using Frame::getActiveUnit Frame::setActiveUnit. It cannot be tested or cleared (nor read or set using the protected Object attribute accessors).Coordinate system in which to align the Frame. (string)
This attribute controls how a Frame behaves when it is used (by Frame::findFrame or Frame::convert) as a template to match another (target) Frame. It identifies the coordinate system in which the two Frames will be aligned by the match.
The values which may be assigned to this attribute, and its default value, depend on the class of Frame and are described in the Applicability
section below. In general, the AlignSystem attribute will accept any of the values which may be assigned to the System attribute.
The Mapping returned by Frame::findFrame or Frame::convert will use the coordinate system specified by the AlignSystem attribute as an intermediate coordinate system. The total returned Mapping will first map positions from the first Frame into this intermediate coordinate system, using the attributes of the first Frame. It will then map these positions from the intermediate coordinate system into the second Frame, using the attributes of the second Frame.
The AlignSystem attribute for a basic Frame always equals "Cartesian", and may not be altered.
The AlignSystem attribute for a CmpFrame always equals "Compound", and may not be altered.
The AlignSystem attribute of a FrameSet is the same as that of its current frame.
The default AlignSystem attribute for a SkyFrame is "ICRS".
The default AlignSystem attribute for a SpecFrame is "Wave" (wavelength).
The default AlignSystem attribute for a TimeFrame is "MJD".
The lowest axis value to be displayed (for instance, by the astGrid method). (double)
The default supplied by the Frame class is to display all axis values, without any limit.
The SkyFrame class re-defines the default Bottom value to -90 degrees for latitude axes, and 0 degrees for co-latitude axes. The default for longitude axes is to display all axis values.
Number of digits of precision. (int)
This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a Frame axis (e.g. using Frame::format). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole.
Note that the Digits or Digits(axis) Digits value acts only as a means of determining a default Format(axis) Format string. Its effects are over-ridden if a Format(axis) Format string is set explicitly for an axis. However, if the Format(axis) Format attribute specifies the precision using the string ".*", then the Digits or Digits(axis) Digits attribute is used to determine the number of decimal places to produce.
The default Digits or Digits(axis) Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead.
The Digits or Digits(axis) Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the Current attribute).
The default Digits or Digits(axis) Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct.
The Digits or Digits(axis) Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format(axis) Format attribute).
Display axis in conventional direction? (bool)
This attribute is a boolean value which suggests how the axes of a Frame should be displayed (e.g.) in graphical output. By default, it has the value one, indicating that they should be shown in the conventional sense (increasing left to right for an abscissa, and bottom to top for an ordinate). If false
, this attribute indicates that the direction should be reversed, as would often be done for an astronomical magnitude or a right ascension axis.
The default Direction(axis) Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction.
The SkyFrame class re-defines the default Direction(axis) Direction value to suggest that certain axes (e.g. right ascension) should be plotted in reverse when appropriate.
The Direction(axis) Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).
The Direction(axis) Direction attribute of the base Frame in a Plot is set to indicate the sense of the two graphics axes, as implied by the graphics bounding box supplied when the Plot was created.
Coordinate system domain. (string)
This attribute contains a string which identifies the physical domain of the coordinate system that a Frame describes.
The Domain Domain attribute also controls how a Frame behaves when it is used (by Frame::findFrame) as a template to match another (target) Frame. It does this by specifying the Domain Domain that the target Frame should have in order to match the template. If the Domain Domain value in the template Frame is set, then only targets with the same Domain Domain value will be matched. If the template's Domain Domain value is not set, however, then the target's Domain Domain will be ignored.
The default Domain Domain value supplied by the Frame class is an empty string.
The SkyFrame class re-defines the default Domain Domain value to be "SKY".
The CmpFrame class re-defines the default Domain Domain value to be of the form "<dom1>-<dom2>", where <dom1>
and <dom2>
are the Domains of the two component Frames. If both these Domains are blank, then the string "CMP" is used as the default Domain Domain name.
The Domain Domain attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
The SpecFrame class re-defines the default Domain Domain value to be "SPECTRUM".
The DSBSpecFrame class re-defines the default Domain Domain value to be "DSBSPECTRUM".
The FluxFrame class re-defines the default Domain Domain value to be "FLUX".
The FluxFrame class re-defines the default Domain Domain value to be "SPECTRUM-FLUX".
The TimeFrame class re-defines the default Domain Domain value to be "TIME".
The UT1-UTC correction (sec). (double)
This attribute is used when calculating the Local Apparent Sidereal Time corresponding to SkyFrame's Epoch Epoch value (used when converting positions to or from the "AzEl" system). It should be set to the difference, in seconds, between the UT1 and UTC timescales at the moment in time represented by the SkyFrame's Epoch Epoch attribute. The value to use is unpredictable and depends on changes in the earth's rotation speed. Values for UT1-UTC can be obtained from the International Earth Rotation and Reference Systems Service (IERS) at http://www.iers.org/.
Currently, the correction is always less than 1 second. This is ensured by the occasional introduction of leap seconds into the UTC timescale. Therefore no great error will usually result if no value is assigned to this attribute (in which case a default value of zero is used). However, it is possible that a decision may be taken at some time in the future to abandon the introduction of leap seconds, in which case the DUT correction could grow to significant sizes.
Epoch of observation. (string or double in, double out)
This attribute is used to qualify the coordinate systems described by a Frame, by giving the moment in time when the coordinates are known to be correct. Often, this will be the date of observation, and is important in cases where coordinates systems move with respect to each other over the course of time.
The Epoch Epoch attribute is stored as a Modified Julian Date, but when setting its value it may be given in a variety of formats. See the "Input Formats" section (below) for details. Strictly, the Epoch Epoch value should be supplied in the TDB timescale, but for some purposes (for instance, for converting sky positions between different types of equatorial system) the timescale is not significant, and UTC may be used.
The formats accepted when setting an Epoch Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:
When enquiring Epoch Epoch values, the format used is the "Year" format described under "Input Formats". This is a value in decimal years which will be a Besselian epoch if less than 1984.0 and a Julian epoch otherwise. By omitting any character prefix, this format allows the Epoch Epoch value to be obtained as either a character string or a floating point value.
All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the System attribute).
The default Epoch Epoch value for a CmpFrame is selected as follows; if the Epoch Epoch attribute has been set in the first component Frame then the Epoch Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch Epoch attribute has been set in the second component Frame then the Epoch Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames.
The Epoch Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
The coordinates of sources within a SkyFrame can changed with time for various reasons, including: (i) changing aberration of light caused by the observer's velocity (e.g. due to the Earth's motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer's position with time, (iii) fictitious motion due to rotation of non-inertial coordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame class because it affects individual sources rather than the coordinate system as a whole).
The default Epoch Epoch value in a SkyFrame is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the System attribute) and J2000.0 (Julian) for all others.
Care must be taken to distinguish the Epoch Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar Equinox value. The latter is used to qualify a coordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator).
See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system.
A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch Epoch value. For this reason the TimeFrame class makes no use of the Epoch Epoch attribute. However, user code can still make use of the attribute if necessary to represent a "typical" time spanned by the TimeFrame. The default Epoch Epoch value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame's TimeOrigin attribute. If no value has been set for TimeOrigin, then the default Epoch Epoch value is J2000.0.
Format specification for axis values. (string)
This attribute specifies the format to be used when displaying coordinate values associated with a particular Frame axis (i.e. to convert values from binary to character form). It is interpreted by Frame::format and determines the formatting which it applies.
If no Format(axis) Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits or Digits(axis) Digits, or Digits or Digits(axis) Digits(axis), attribute and is chosen so that it displays the requested number of digits of precision.
The Frame class interprets this attribute as a format specification string to be passed to the C "printf" function (e.g. "%1.7G") in order to format a single coordinate value (supplied as a double precision number).
When supplying a value for this attribute, beware that the "%" character may be interpreted directly as a format specification by some printf-like functions (option strings in constructors and Object::set but not Frame::setFormat). You may need to double it (i.e. use "%%") to avoid this.
The SkyFrame class re-defines the syntax and default value of the Format(axis) Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format(axis) Format strings is described (below) in the "@ref SkyFrame Formats" section.
The Format(axis) Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute). Note that the syntax of the Format(axis) Format string is also determined by the current Frame.
The TimeFrame class extends the syntax of the Format(axis) Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format(axis) Format strings is described (below) in the "@ref TimeFrame Formats" section.
The Format(axis) Format string supplied for a SkyFrame should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity:
All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both "i" and "b" appear), then the character occurring last takes precedence, except that "d" and "h" always override "t".
If the format string starts with a percentage sign (%), then the whole format string is assumed to conform to the syntax defined by the Frame class, and the axis values is formated as a decimal radians value.
The Format(axis) Format string supplied for a TimeFrame should either use the syntax defined by the base Frame class (i.e. a C "printf" format string), or the extended "iso" syntax described below (the default value is inherited from the Frame class):
Physical units for unformated axis values. (string, read only)
This read-only attribute contains a textual representation of the physical units used to represent unformatted (i.e. floating point) values on a particular axis of a Frame, typically handled internally within application code. In most cases, the value of the InternalUnit(axis) InternalUnit attribute will be the same as Unit attribute (i.e. formatted and unformatted axis values will normally use the same system of units). The main exception to this is the SkyFrame class, which represents unformatted axis values in radians, regardless of the current setting of the Unit attribute.
Axis label. (string)
This attribute specifies a label to be attached to each axis of a Frame when it is represented (e.g.) in graphical output.
If a Label(axis) (string) Label value has not been set for a Frame axis, then a suitable default is supplied.
The default supplied by the Frame class is the string "Axis<n>", where <n>
is 1, 2, etc. for each successive axis.
The SkyFrame class re-defines the default Label(axis) (string) Label value (e.g. to "Right ascension" or "Galactic latitude") as appropriate for the particular celestial coordinate system being represented.
The TimeFrame class re-defines the default Label(axis) (string) Label value as appropriate for the particular time system being represented.
The Label(axis) (string) Label attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).
Match trailing axes? (bool)
This attribute is a boolean value which controls how a Frame behaves when it is used (by Frame::findFrame) as a template to match another (target) Frame. It applies only in the case where a match occurs between template and target Frames with different numbers of axes.
If the MatchEnd MatchEnd value of the template Frame is zero, then the axes which occur first in the target Frame will be matched and any trailing axes (in either the target or template) will be disregarded. If it is true
, the final axes in each Frame will be matched and any un-matched leading axes will be disregarded instead.
The default MatchEnd MatchEnd value for a Frame is zero, so that trailing axes are disregarded.
The MatchEnd MatchEnd attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
MaxAxes specifies the maximum number of axes that the target Frame may have when calling Frame::findFrame.
Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes.
The MaxAxes attribute of a CmpFrame defaults to a large number (1000000) which is much larger than any likely number of axes in a Frame. Combined with the MinAxes default of zero (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MaxAxes and MinAxes attributes to the number of axes in the CmpFrame.
The MaxAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
MinAxes specifies the minimum number of axes that the target Frame may have in order to match the template.
Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes.
The MinAxes attribute of a CmpFrame defaults to zero. Combined with the MaxAxes default of 1000000 (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MinAxes and MaxAxes attributes to the number of axes in the CmpFrame.
The MinAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
NAxes is the number of axes in the frame (i.e. the number of dimensions of the coordinate space which the Frame describes).
This value is determined when the Frame is created.
The NAxes attribute of a FrameSet is the same as that of its current frame.
The @ref Frame_NAxes "NAxes" attribute of a @ref CmpFrame is equal to the sum of the @ref Frame_NAxes "NAxes" values of its two component @ref Frame "Frames".
Normalised physical units for formatted axis values. (string, read only)
The value of this read-only attribute is derived from the current value of the Unit attribute. It will represent an equivalent system of units to the Unit attribute, but will potentially be simplified. For instance, if Unit is set to "s*(m/s)", the NormUnit value will be "m". If no simplification can be performed, the value of the NormUnit attribute will equal that of the Unit attribute.
The geodetic altitude of the observer (m). (double)
This attribute specifies the geodetic altitude of the observer, in metres, relative to the IAU 1976 reference ellipsoid. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.
All Frames have this attribute.
Together with the ObsLon ObsLon, Epoch Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
Together with the ObsLon ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)
The geodetic latitude of the observer. (string)
This attribute specifies the geodetic latitude of the observer, in degrees, relative to the IAU 1976 reference ellipsoid. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.
The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "22:19:23.2", "22 19 23.2", "22:19.387", "22.32311", "N22.32311", "-45.6", "S45.6". As indicated, the sign of the latitude can optionally be indicated using characters "N" and "S" in place of the usual "+" and "-". When converting the stored value to a string, the format "[s]dd:mm:ss.ss" is used, when "[s]" is "N" or "S".
All Frames have this attribute.
Together with the ObsLon ObsLon, Epoch Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
Together with the ObsLon ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)
The geodetic longitude of the observer. (string)
This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute ObsLat ObsLat. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.
The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "155:19:23.2", "155 19 23.2", "155:19.387", "155.32311", "E155.32311", "-204.67689", "W204.67689". As indicated, the sign of the longitude can optionally be indicated using characters "E" and "W" in place of the usual "+" and "-". When converting the stored value to a string, the format "[s]ddd:mm:ss.ss" is used, when "[s]" is "E" or "W" and the numerical value is chosen to be less than 180 degrees.
All Frames have this attribute.
Together with the ObsLon ObsLon, Epoch Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
Together with the ObsLon ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)
Allow axis permutation when used as a template? (bool)
This attribute is a boolean value which controls how a Frame behaves when it is used (by Frame::findFrame) as a template to match another (target) Frame. It specifies whether the axis order of the target Frame may be permuted in order to obtain a match.
If the template's Permute Permute value is zero, it will match a target only if it can do so without changing the order of its axes. Otherwise, it will attempt to permute the target's axes as necessary.
The default value is 1, so that axis permutation will be attempted.
All Frames have this attribute. However, the Frame class effectively ignores this attribute and behaves as if it has the value 1. This is because the axes of a basic Frame are not distinguishable and will always match any other Frame whatever their order.
Unlike a basic Frame, the SkyFrame class makes use of this attribute.
The Permute Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
Preserve found axes in result? (bool)
This attribute controls how a Frame behaves when it is used (by Frame::findFrame) as a template to match another (target) Frame. It determines which axes appear (and in what order) in the "result" Frame produced.
If PreserveAxes is zero in the template Frame, then the result Frame will have the same number (and order) of axes as the template. If it is true
, however, the axes of the target Frame will be preserved, so that the result Frame will have the same number (and order) of axes as the target.
The default value is zero, so that target axes are not preserved and the result Frame resembles the template.
All Frames have this attribute.
The PreserveAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
Axis symbol. (string)
This attribute specifies a short-form symbol to be used to represent coordinate values for a particular axis of a Frame. This might be used (e.g.) in algebraic expressions where a full description of the axis would be inappropriate. Examples include "RA" and "Dec" (for Right Ascension and Declination).
If a Symbol value has not been set for a Frame axis, then a suitable default is supplied.
The default Symbol value supplied by the Frame class is the string "<Domain><n>", where <n>
is 1, 2, etc. for successive axes, and <Domain>
is the value of the Frame's Domain Domain attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain Domain value has been set, "x" is used as the <Domain>
value in constructing this default string.
The SkyFrame class re-defines the default Symbol value (e.g. to "RA" or "Dec") as appropriate for the particular celestial coordinate system being represented.
The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented.
The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).
Coordinate system used to describe positions within the domain. (string)
In general it is possible for positions within a given physical domain to be described using one of several different coordinate systems. For instance, the SkyFrame class can use galactic coordinates, equatorial coordinates, etc, to describe positions on the sky. As another example, the SpecFrame class can use frequency, wavelength, velocity, etc, to describe a position within an electromagnetic spectrum. The System attribute identifies the particular coordinate system represented by a Frame. Each class of Frame defines a set of acceptable values for this attribute, as listed below (all are case insensitive). Where more than one alternative System value is shown, the first of will be returned when an enquiry is made.
The System attribute for a basic Frame always equals "Cartesian", and may not be altered.
The System attribute for a CmpFrame always equals "Compound", and may not be altered. In addition, the CmpFrame class allows the System attribute to be referenced for a component Frame by including the index of an axis within the required component Frame. For instance, "System(3)" refers to the System attribute of the component Frame which includes axis 3 of the CmpFrame.
The System attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
The SkyFrame class supports the following System values and associated celestial coordinate systems:
Currently, the default System value is "ICRS". However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in future). If you intend to use the ICRS system indefinitely, then you should specify it explicitly.
The SpecFrame class supports the following System values and associated spectral coordinate systems (the default is "WAVE" - wavelength). They are all defined in FITS-WCS paper III:
The default value for the Unit attribute for each system is shown in parentheses. Note that the default value for the ActiveUnit flag is true
for a SpecFrame, meaning that changes to the Unit attribute for a SpecFrame will result in the SpecFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information).
The TimeFrame class supports the following System values and associated coordinate systems (the default is "MJD"):
The default value for the Unit attribute for each system is shown in parentheses. Strictly, these systems should not allow changes to be made to the units. For instance, the usual definition of "MJD" and "JD" include the statement that the values will be in units of days. However, AST does allow the use of other units with all the above supported systems (except BEPOCH), on the understanding that conversion to the "correct" units involves nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined in terms of tropical years of 365.2422 days, rather than the usual Julian year of 365.25 days. Therefore, to avoid any confusion, the Unit attribute is automatically cleared to "yr" when a System value of BEPOCH System is selected, and an error is reported if any attempt is subsequently made to change the Unit attribute.
Note that the default value for the ActiveUnit flag is true
for a TimeFrame, meaning that changes to the Unit attribute for a TimeFrame will result in the TimeFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information).
The FluxFrame class supports the following System values and associated systems for measuring observed value:
The above lists specified the default units for each System. If an explicit value is set for the Unit attribute but no value is set for System, then the default System value is determined by the Unit string (if the units are not appropriate for describing any of the supported Systems then an error will be reported when an attempt is made to access the System value). If no value has been specified for either Unit or System, then System=FLXDN and Unit=W/m^2/Hz are used.
Frame title. (string)
This attribute holds a string which is used as a title in (e.g.) graphical output to describe the coordinate system which a Frame represents. Examples might be "Detector Coordinates" or "Galactic Coordinates".
If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame.
Title is intended purely for interpretation by human readers and not by software.
The default supplied by the Frame class is "<n>-d coordinate
system", where <n>
is the number of Frame axes (NAxes attribute).
The CmpFrame class re-defines the default Title value to be "<n>-d compound coordinate system", where <n>
is the number of CmpFrame axes (NAxes
attribute).
The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
The highest axis value to be displayed (for instance, by the astGrid method). (double)
The default supplied by the Frame class is to display all axis values, without any limit.
The SkyFrame class re-defines the default Top value to +90 degrees for latitude axes, and 180 degrees for co-latitude axes. The default for longitude axes is to display all axis values.
Physical units for formatted axis values. (string)
This attribute contains a textual representation of the physical units used to represent formatted coordinate values on a particular axis of a Frame.
The astSetActiveUnit function controls how the Unit values are used.
The default supplied by the Frame class is an empty string.
The SkyFrame class re-defines the default Unit value (e.g. to "hh:mm:ss.sss") to describe the character string returned by the astFormat function when formatting coordinate values. the AST_FORMAT function when formatting coordinate values.
The SpecFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit.
The TimeFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit (e.g. "km").
The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).