LSSTApplications  18.0.0+106,18.0.0+50,19.0.0,19.0.0+1,19.0.0+10,19.0.0+11,19.0.0+13,19.0.0+17,19.0.0+2,19.0.0-1-g20d9b18+6,19.0.0-1-g425ff20,19.0.0-1-g5549ca4,19.0.0-1-g580fafe+6,19.0.0-1-g6fe20d0+1,19.0.0-1-g7011481+9,19.0.0-1-g8c57eb9+6,19.0.0-1-gb5175dc+11,19.0.0-1-gdc0e4a7+9,19.0.0-1-ge272bc4+6,19.0.0-1-ge3aa853,19.0.0-10-g448f008b,19.0.0-12-g6990b2c,19.0.0-2-g0d9f9cd+11,19.0.0-2-g3d9e4fb2+11,19.0.0-2-g5037de4,19.0.0-2-gb96a1c4+3,19.0.0-2-gd955cfd+15,19.0.0-3-g2d13df8,19.0.0-3-g6f3c7dc,19.0.0-4-g725f80e+11,19.0.0-4-ga671dab3b+1,19.0.0-4-gad373c5+3,19.0.0-5-ga2acb9c+2,19.0.0-5-gfe96e6c+2,w.2020.01
LSSTDataManagementBasePackage
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

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

Notes

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

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:

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

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

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:

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

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

Notes

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

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

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

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_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_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

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

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

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

Notes

Generated on Wed Jan 8 2020 09:11:27 for LSSTApplications by   doxygen 1.8.13