LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Frame Attributes

Frame Attributes

ActiveUnit

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

Applicability

  • SkyFrame

    The ActiveUnit flag for a SkyFrame is always false (any value supplied using this routine is ignored).

  • SpecFrame

    The ActiveUnit flag for a SpecFrame is always true (any value supplied using this routine is ignored).

  • FluxFrame

    The ActiveUnit flag for a FluxFrame is always true (any value supplied using this routine is ignored).

  • CmpFrame

    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.

  • Region

    Regions always use active units if possible.

Notes

AlignSystem

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.

Applicability

Frame

The AlignSystem attribute for a basic Frame always equals "Cartesian", and may not be altered.

CmpFrame

The AlignSystem attribute for a CmpFrame always equals "Compound", and may not be altered.

FrameSet

The AlignSystem attribute of a FrameSet is the same as that of its current frame.

SkyFrame

The default AlignSystem attribute for a SkyFrame is "ICRS".

SpecFrame

The default AlignSystem attribute for a SpecFrame is "Wave" (wavelength).

TimeFrame

The default AlignSystem attribute for a TimeFrame is "MJD".

Bottom(axis)

The lowest axis value to be displayed (for instance, by the astGrid method). (double)

Applicability

Frame 

The default supplied by the Frame class is to display all axis
values, without any limit.

SkyFrame 

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.

Digits or Digits(axis)

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.

Applicability

Direction(axis)

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.

Applicability

  • Frame

    The default Direction(axis) Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction.

  • SkyFrame

    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.

  • FrameSet

    The Direction(axis) Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

  • Plot

    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.

Notes

  • The Direction(axis) Direction attribute does not directly affect the behaviour of the AST library. Instead, it serves as a hint to applications programs about the orientation in which they may wish to display any data associated with the Frame. Applications are free to ignore this hint if they wish.

Domain

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.

Applicability

Notes

  • All Domain Domain values are converted to upper case and white space is removed before use.

Dut1

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

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.

Input Formats

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:

  • Besselian Epoch Epoch: Expressed in decimal years, with or without decimal places ("B1950" or "B1976.13" for example).
  • Julian Epoch Epoch: Expressed in decimal years, with or without decimal places ("J2000" or "J2100.9" for example).
  • Year: Decimal years, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise.
  • Julian Date: With or without decimal places ("JD 2454321.9" for example).
  • Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).
  • Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).
  • Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

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.

Applicability

  • Frame

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

  • CmpFrame

    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.

  • FrameSet

    The Epoch Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

  • SkyFrame

    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.

  • TimeFrame

    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(axis)

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.

Applicability

  • Frame

    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.

  • SkyFrame

    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.

  • FrameSet

    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.

  • TimeFrame

    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.

SkyFrame Formats

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:

  • "+": Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used.
  • "z": Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added.
  • "i": Use the standard ISO field separator (a colon) between fields. This is the default behaviour.
  • "b": Use a blank to separate fields.
  • "l": Use a letter ("h"/"d", "m" or "s" as appropriate) to separate fields.
  • "g": Use a letter and symbols to separate fields ("h"/"d", "m" or "s", etc, as appropriate), but include escape sequences in the formatted value so that the Plot class will draw the separators as small super-scripts. The default escape sequences are optimised for the pgplot graphics package, but new escape sequences may be specified using function astSetSkyDelim.
  • "d": Include a degrees field. Expressing the angle purely in degrees is also the default if none of "h", "m", "s" or "t" are given.
  • "h": Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if "t" is given without either "m" or "s".
  • "m": Include a minutes field. By default this is not included.
  • "s": Include a seconds field. By default this is not included. This request is ignored if "d" or "h" is given, unless a minutes field is also included.
  • "t": Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either "d" or "h" is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If "t" is given without "d", "h", "m" or "s" being present, then it is equivalent to "h".
  • ".": Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The "." should be followed immediately by an unsigned integer which gives the number of decimal places required, or by an asterisk. If an asterisk is supplied, a default number of decimal places is used which is based on the value of the Digits or Digits(axis) Digits attribute.

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.

Formats

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):

  • C "printf" syntax: If the Format(axis) Format string is a C "printf" format description such as "%1.7G", the TimeFrame axis value will be formatted without change as a floating point value using this format. The formatted string will thus represent an offset from the zero point specified by the TimeFrame's TimeOrigin attribute, measured in units given by the TimeFrame's Unit attribute.
  • "iso" syntax: This is used to format a TimeFrame axis value as a Gregorian date followed by an optional time of day. If the Format(axis) Format value commences with the string "iso" then the TimeFrame axis value will be converted to an absolute MJD, including the addition of the current TimeOrigin value, and then formatted as a Gregorian date using the format "yyyy-mm-dd". Optionally, the Format(axis) Format value may include an integer precision following the "iso" specification (e.g. "iso.2"), in which case the time of day will be appended to the formatted date (if no time of day is included, the date field is rounded to the nearest day). The integer value in the Format(axis) Format string indicates the number of decimal places to use in the seconds field. For instance, a Format(axis) Format value of "iso.0" produces a time of day of the form "hh:mm:ss", and a Format(axis) Format value of "iso.2" produces a time of day of the form "hh:mm:ss.ss". The date and time fields will be separated by a space unless 'T' is appended to the end of string, in which case the letter T (upper case) will be used as the separator. The value of the Digits or Digits(axis) Digits attribute is ignored when using this "iso" format.

InternalUnit(axis)

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.

Label(axis) (string)

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.

Applicability

  • Frame

    The default supplied by the Frame class is the string "Axis<n>", where <n> is 1, 2, etc. for each successive axis.

  • SkyFrame

    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.

  • TimeFrame

    The TimeFrame class re-defines the default Label(axis) (string) Label value as appropriate for the particular time system being represented.

  • FrameSet

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

Notes

  • Axis labels are intended purely for interpretation by human readers and not by software.

MatchEnd

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.

Applicability

MaxAxes

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.

Applicability to Subclasses

MinAxes

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.

Applicability to subclasses

NAxes

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.

Applicability for subclasses

CmpFrame 

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

NormUnit(axis)

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.

ObsAlt

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.

Applicability

  • Frame

    All Frames have this attribute.

  • SpecFrame

    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.

  • TimeFrame

    Together with the ObsLon ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

ObsLat

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

Applicability

  • Frame

    All Frames have this attribute.

  • SpecFrame

    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.

  • TimeFrame

    Together with the ObsLon ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

ObsLon

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.

Applicability

  • Frame

    All Frames have this attribute.

  • SpecFrame

    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.

  • TimeFrame

    Together with the ObsLon ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

Permute

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.

Applicability

  • Frame

    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.

  • SkyFrame

    Unlike a basic Frame, the SkyFrame class makes use of this attribute.

  • FrameSet

    The Permute Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Frame_PreserveAxes

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.

Applicability

  • Frame

    All Frames have this attribute.

  • FrameSet

    The PreserveAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Frame_Symbol

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.

Applicability

  • Frame

    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.

  • SkyFrame

    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.

  • TimeFrame

    The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented.

  • FrameSet

    The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

System

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.

Applicability

  • Frame

    The System attribute for a basic Frame always equals "Cartesian", and may not be altered.

  • CmpFrame

    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.

  • FrameSet

    The System attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

  • SkyFrame

    The SkyFrame class supports the following System values and associated celestial coordinate systems:

    • "AZEL": Horizon coordinates. The longitude axis is azimuth such that geographic north has an azimuth of zero and geographic east has an azimuth of +PI/2 radians. The zenith has elevation +PI/2. When converting to and from other celestial coordinate systems, no corrections are applied for atmospheric refraction or polar motion (however, a correction for diurnal aberattion is applied). Note, unlike most other celestial coordinate systems, this system is right handed. Also, unlike other SkyFrame systems, the AzEl system is sensitive to the timescale in which the Epoch Epoch value is supplied. This is because of the gross diurnal rotation which this system undergoes, causing a small change in time to translate to a large rotation. When converting to or from an AzEl system, the Epoch Epoch value for both source and destination SkyFrames should be supplied in the TDB timescale. The difference between TDB and TT is between 1 and 2 milliseconds, and so a TT value can usually be supplied in place of a TDB value. The TT timescale is related to TAI via TT = TAI + 32.184 seconds.
    • "ECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox specified by the qualifying Equinox value.
    • "FK4": The old FK4 (barycentric) equatorial coordinate system, which should be qualified by an Equinox value. The underlying model on which this is based is non-inertial and rotates slowly with time, so for accurate work FK4 coordinate systems should also be qualified by an Epoch Epoch value.
    • "FK4-NO-E" or "FK4_NO_E": The old FK4 (barycentric) equatorial system but without the "E-terms of aberration" (e.g. some radio catalogues). This coordinate system should also be qualified by both an Equinox and an Epoch Epoch value.
    • "FK5" or "EQUATORIAL": The modern FK5 (barycentric) equatorial coordinate system. This should be qualified by an Equinox value.
    • "GALACTIC": Galactic coordinates (IAU 1958).
    • "GAPPT", "GEOCENTRIC" or "APPARENT": The geocentric apparent equatorial coordinate system, which gives the apparent positions of sources relative to the true plane of the Earth's equator and the equinox (the coordinate origin) at a time specified by the qualifying Epoch Epoch value. (Note that no Equinox is needed to qualify this coordinate system because no model "mean equinox" is involved.) These coordinates give the apparent right ascension and declination of a source for a specified date of observation, and therefore form an approximate basis for pointing a telescope. Note, however, that they are applicable to a fictitious observer at the Earth's centre, and therefore ignore such effects as atmospheric refraction and the (normally much smaller) aberration of light due to the rotational velocity of the Earth's surface. Geocentric apparent coordinates are derived from the standard FK5 (J2000.0) barycentric coordinates by taking account of the gravitational deflection of light by the Sun (usually small), the aberration of light caused by the motion of the Earth's centre with respect to the barycentre (larger), and the precession and nutation of the Earth's spin axis (normally larger still).
    • "HELIOECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox of J2000.0, in which an offset is added to the longitude value which results in the centre of the sun being at zero longitude at the date given by the Epoch Epoch attribute. Attempts to set a value for the Equinox attribute will be ignored, since this system is always referred to J2000.0.
    • "ICRS": The Internation Celestial Reference System, realised through the Hipparcos catalogue. Whilst not an equatorial system by definition, the ICRS is very close to the FK5 (J2000) system and is usually treated as an equatorial system. The distinction between ICRS and FK5 (J2000) only becomes important when accuracies of 50 milli-arcseconds or better are required. ICRS need not be qualified by an Equinox value.
    • "J2000": An equatorial coordinate system based on the mean dynamical equator and equinox of the J2000 epoch. The dynamical equator and equinox differ slightly from those used by the FK5 model, and so a "J2000" SkyFrame will differ slightly from an "FK5(Equinox=J2000)" SkyFrame. The J2000 System need not be qualified by an Equinox value
    • "SUPERGALACTIC": De Vaucouleurs Supergalactic coordinates.
    • "UNKNOWN": Any other general spherical coordinate system. No Mapping can be created between a pair of SkyFrames if either of the SkyFrames has System set to "Unknown".

    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.

  • SpecFrame

    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:

    • "FREQ": Frequency (GHz)
    • "ENER" or "ENERGY": Energy (J)
    • "WAVN" or "WAVENUM": Wave-number (1/m)
    • "WAVE" or "WAVELEN": Vacuum wave-length (Angstrom)
    • "AWAV" or "AIRWAVE": Wave-length in air (Angstrom)
    • "VRAD" or "VRADIO": Radio velocity (km/s)
    • "VOPT" or "VOPTICAL": Optical velocity (km/s)
    • "ZOPT" or "REDSHIFT": Redshift (dimensionless)
    • "BETA": Beta factor (dimensionless)
    • "VELO" or "VREL": Apparent radial ("relativistic") velocity (km/s)

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

  • TimeFrame

    The TimeFrame class supports the following System values and associated coordinate systems (the default is "MJD"):

    • "MJD": Modified Julian Date (d)
    • "JD": Julian Date (d)
    • "JEPOCH": Julian epoch (yr)
    • "BEPOCH": Besselian (yr)

    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:

    • "FLXDN": Flux per unit frequency (W/m^2/Hz)
    • "FLXDNW": Flux per unit wavelength (W/m^2/Angstrom)
    • "SFCBR": Surface brightness in frequency units (W/m^2/Hz/arcmin**2)
    • "SFCBRW": Surface brightness in wavelength units (W/m^2/Angstrom/arcmin**2)

    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.

Title

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.

Applicability

Frame

The default supplied by the Frame class is "<n>-d coordinate system", where <n> is the number of Frame axes (NAxes attribute).

CmpFrame

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

FrameSet

The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Top(axis)

The highest axis value to be displayed (for instance, by the astGrid method). (double)

Applicability

  • Frame

    The default supplied by the Frame class is to display all axis values, without any limit.

  • SkyFrame

    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.

Unit(axis)

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.

Applicability

  • Frame

    The default supplied by the Frame class is an empty string.

  • SkyFrame

    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.

  • SpecFrame

    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.

  • TimeFrame

    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").

  • FrameSet

    The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Notes

  • This attribute described the units used when an axis value is formatted into a string using Frame::format. In some cases these units may be different to those used to represent floating point axis values within application code (for instance a SkyFrame always uses radians to represent floating point axis values). The InternalUnit attribute described the units used for floating point values.
Generated on Fri Nov 26 2021 10:16:08 for LSST Applications by doxygen 1.9.1