#
AST Attribute Descriptions

Abbrev(axis) Abbreviate leading fields within numerical axis labels? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether matching leading fields should be removed from adjacent numerical axis labels. It takes a separate value for each physical axis of a PlotPlot so that, for instance, the setting " Abbrev(2)=0" specifies that matching leading fields should not be removed on the second axis.

If the Abbrev value of a Plot is non-zero (the default), then leading fields will be removed from adjacent axis labels if they are equal. Integer (boolean). Plot All Plots have this attribute. If no axis is specified, (e.g. " Abbrev" instead of " Abbrev(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the Abbrev(1) value. Adaptive Should the area adapt to changes in the coordinate system? The coordinate system represented by a RegionRegion may be changed by assigning new values to attributes such as SystemSystem, Unit, etc. For instance, a Region representing an area on the sky in ICRS coordinates may have its System attribute changed so that it represents (say) Galactic coordinates instead of ICRS. This attribute controls what happens when the coordinate system represented by a Region is changed in this way.

If Adaptive is non-zero (the default), then the area represented by the Region adapts to the new coordinate system. That is, the numerical values which define the area represented by the Region are changed by mapping them from the old coordinate system into the new coordinate system. Thus the Region continues to represent the same physical area.

If Adaptive is zero, then area represented by the Region does not adapt to the new coordinate system. That is, the numerical values which define the area represented by the Region are left unchanged. Thus the physical area represented by the Region will usually change.

As an example, consider a Region describe a range of wavelength from 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region is changed from Angstrom to " nm" (nanometre), what happens depends on the setting of Adaptive. If Adaptive is non-zero, the MappingMapping from the old to the new coordinate system is found. In this case it is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). This Mapping is then used to modify the numerical values within the Region, changing 2000 to 200 and 4000 to 400. Thus the modified region represents 200 nm to 400 nm, the same physical space as the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive had been zero, then the numerical values would not have been changed, resulting in the final Region representing 2000 nm to 4000 nm.

Setting Adaptive to zero can be necessary if you need to correct inaccurate attribute settings in an existing Region. For instance, when creating a Region you may not know what EpochEpoch value to use, so you would leave Epoch unset resulting in some default value being used. If at some later point in the application, the correct Epoch value is determined, you could assign the correct value to the Epoch attribute. However, you would first need to set Adaptive temporarily to zero, because otherwise the area represented by the Region would be Mapped from the spurious default Epoch to the new correct Epoch, which is not what is required. Integer (boolean). Region All Regions have this attribute. AlignOffset Align SkyFrames using the offset coordinate system? This attribute is a boolean value which controls how a SkyFrameSkyFrame behaves when it is used (by astFindFrameastFindFrame or astConvertastConvert) as a template to match another (target) SkyFrame. It determines the coordinate system in which the two SkyFrames are aligned if a match occurs.

If the template and target SkyFrames both have defined offset coordinate systems (i.e. the SkyRefIsSkyRefIs attribute is set to either " Origin" or " Pole" ), and they both have a non-zero value for AlignOffset, then alignment occurs within the offset coordinate systems (that is, a UnitMapUnitMap will always be used to align the two SkyFrames). If either the template or target SkyFrame has zero (the default value) for AlignOffset, or if either SkyFrame has SkyRefIs set to " Ignored" , then alignment occurring within the coordinate system specified by the AlignSystemAlignSystem attribute. Integer (boolean). SkyFrame All SkyFrames have this attribute. AlignSideBand Should the SideBand attribute be taken into account when aligning this DSBSpecFrameDSBSpecFrame with another DSBSpecFrame? This attribute controls how a DSBSpecFrame behaves when an attempt is made to align it with another DSBSpecFrame using astFindFrameastFindFrame or astConvertastConvert. If both DSBSpecFrames have a non-zero value for AlignSideBand, the value of the SideBandSideBand attribute in each DSBSpecFrame is used so that alignment occurs between sidebands. That is, if one DSBSpecFrame represents USB and the other represents LSB then astFindFrame and astConvert will recognise that the DSBSpecFrames represent different sidebands and will take this into account when constructing the MappingMapping that maps positions in one DSBSpecFrame into the other. If AlignSideBand in either DSBSpecFrame is set to zero, then the values of the SideBand attributes are ignored. In the above example, this would result in a frequency in the first DSBSpecFrame being mapped onto the same frequency in the second DSBSpecFrame, even though those frequencies refer to different sidebands. In other words, if either AlignSideBand attribute is zero, then the two DSBSpecFrames aligns like basic SpecFrames. The default value for AlignSideBand is zero.

When astFindFrame or astConvert is used on two DSBSpecFrames (potentially describing different spectral coordinate systems and/or sidebands), it returns a Mapping which can be used to transform a position in one DSBSpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order:

If both DSBSpecFrames have a value of 1 for the AlignSideBand attribute, map values from the target' s current sideband (given by its SideBand attribute) to the observed sideband (whether USB or LSB). If the target already represents the observed sideband, this step will leave the values unchanged. If either of the two DSBSpecFrames have a value of zero for its AlignSideBand attribute, then this step is omitted.

Map the values from the spectral system of the target to the spectral system of the template. This Mapping takes into account all the inherited SpecFrameSpecFrame attributes such as SystemSystem, StdOfRestStdOfRest, Unit, etc.

If both DSBSpecFrames have a value of 1 for the AlignSideBand attribute, map values from the result' s observed sideband to the result' s current sideband (given by its SideBand attribute). If the result already represents the observed sideband, this step will leave the values unchanged. If either of the two DSBSpecFrames have a value of zero for its AlignSideBand attribute, then this step is omitted. Integer (boolean). DSBSpecFrame All DSBSpecFrames have this attribute. AlignSpecOffset Align SpecFrames using the offset coordinate system? This attribute is a boolean value which controls how a SpecFrameSpecFrame behaves when it is used (by astFindFrameastFindFrame or astConvertastConvert) as a template to match another (target) SpecFrame. It determines whether alignment occurs between the offset values defined by the current value of the SpecOffset attribute, or between the corresponding absolute spectral values.

The default value of zero results in the two SpecFrames being aligned so that a given absolute spectral value in one is mapped to the same absolute value in the other. A non-zero value results in the SpecFrames being aligned so that a given offset value in one is mapped to the same offset value in the other. Integer (boolean). SpecFrame All SpecFrames have this attribute. AlignStdOfRest Standard of rest to use when aligning SpecFrames This attribute controls how a SpecFrameSpecFrame behaves when it is used (by astFindFrameastFindFrame or astConvertastConvert) as a template to match another (target) SpecFrame. It identifies the standard of rest in which alignment is to occur. See the StdOfRestStdOfRest attribute for a desription of the values which may be assigned to this attribute. The default AlignStdOfRest value is " Helio" (heliocentric).

When astFindFrame or astConvert is used on two SpecFrames (potentially describing different spectral coordinate systems), it returns a MappingMapping which can be used to transform a position in one SpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order:

Map values from the system used by the target (wavelength, apparent radial velocity, etc) to the system specified by the AlignSystemAlignSystem attribute, using the target' s rest frequency if necessary.

Map these values from the target' s standard of rest to the standard of rest specified by the AlignStdOfRest attribute, using the EpochEpoch, ObsLatObsLat, ObsLonObsLon, ObsAltObsAlt, RefDecRefDec and RefRARefRA attributes of the target to define the two standards of rest.

Map these values from the standard of rest specified by the AlignStdOfRest attribute, to the template' s standard of rest, using the Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the template to define the two standards of rest.

Map these values from the system specified by the AlignSystem attribute, to the system used by the template, using the template' s rest frequency if necessary. String. SpecFrame All SpecFrames have this attribute. AlignSystem Coordinate system in which to align the Frame This attribute controls how a FrameFrame behaves when it is used (by astFindFrameastFindFrame or astConvertastConvert) 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 SystemSystem attribute.

The MappingMapping returned by AST_FINDFRAME or AST_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. String. Frame The AlignSystem attribute for a basic Frame always equals " Cartesian" , and may not be altered. CmpFrameCmpFrame The AlignSystem attribute for a CmpFrame always equals " Compound" , and may not be altered. FrameSetFrameSet The AlignSystem attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). SkyFrameSkyFrame The default AlignSystem attribute for a SkyFrame is " ICRS" . SpecFrameSpecFrame The default AlignSystem attribute for a SpecFrame is " Wave" (wavelength). TimeFrameTimeFrame The default AlignSystem attribute for a TimeFrame is " MJD" . AlignTimeScale Time scale to use when aligning TimeFrames This attribute controls how a TimeFrameTimeFrame behaves when it is used (by astFindFrameastFindFrame or astConvertastConvert) as a template to match another (target) TimeFrame. It identifies the time scale in which alignment is to occur. See the TimeScaleTimeScale attribute for a desription of the values which may be assigned to this attribute. The default AlignTimeScale value depends on the current value of TimeScale: if TimeScale is UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all other TimeScales the default is TAI.

When astFindFrame or astConvert is used on two TimeFrames (potentially describing different time coordinate systems), it returns a MappingMapping which can be used to transform a position in one TimeFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order:

Map values from the system used by the target (MJD, JD, etc) to the system specified by the AlignSystemAlignSystem attribute.

Map these values from the target' s time scale to the time scale specified by the AlignTimeScale attribute.

Map these values from the time scale specified by the AlignTimeScale attribute, to the template' s time scale.

Map these values from the system specified by the AlignSystem attribute, to the system used by the template. String. TimeFrame All TimeFrames have this attribute. AllVariants A list of the variant Mappings associated with the current Frame This attribute gives a space separated list of the names of all the variant Mappings associated with the current FrameFrame (see attribute " VariantVariant" ). If the current Frame has no variant Mappings, then the list will hold a single entry equal to the DomainDomain name of the current Frame. String, read-only. FrameSetFrameSet All FrameSets have this attribute. AllWarnings A list of all currently available condition names This read-only attribute is a space separated list of all the conditions names recognized by the WarningsWarnings attribute. The names are listed below. String, read-only FitsChanFitsChan All FitsChans have this attribute. Conditions The following conditions are currently recognised (all are case-insensitive):

" BadCel" : This condition arises when reading a FrameSetFrameSet from a non-Native encoded FitsChan if an unknown celestial co-ordinate system is specified by the CTYPE keywords.

" BadCTYPE" : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if an illegal algorithm code is specified by a CTYPE keyword, and the illegal code can be converted to an equivalent legal code.

" BadKeyName" : This condition arises if a FITS keyword name is encountered that contains an illegal character (i.e. one not allowed by the FITS standard).

" BadKeyValue" : This condition arises if the value of a FITS keyword cannot be determined from the content of the header card.

" BadLat" : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if the latitude of the reference point has an absolute value greater than 90 degrees. The actual absolute value used is set to exactly 90 degrees in these cases.

" BadMat" : This condition arises if the matrix describing the transformation from pixel offsets to intermediate world coordinates cannot be inverted. This matrix describes the scaling, rotation, shear, etc., applied to the pixel axes, and is specified by keywords such as PCi_j, CDi_j, CROTA, etc. For example, the matrix will not be invertable if any rows or columns consist entirely of zeros. The FITS-WCS Paper I " Representation of World Coordinates in FITS" by Greisen & Calabretta requires that this matrix be invertable. Many operations (such as grid plotting) will not be possible if the matrix cannot be inverted.

" BadPV" : This condition arises when reading a FrameSet from a non-Native encoded FitsChan. It is issued if a PVi_mPVi_m header is found that refers to a projection parameter that is not used by the projection type specified by CTYPE, or the PV values are otherwise inappropriate for the projection type.

" BadVal" : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if it is not possible to convert the value of a FITS keywords to the expected type. For instance, this can occur if the FITS header contains a string value for a keyword which should have a floating point value, or if the keyword has no value at all (i.e. is a comment card).

" Distortion" : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if any of the CTYPE keywords specify an unsupported distortion code using the " 4-3-3" format specified in FITS-WCS paper IV. Such distortion codes are ignored.

" NoCTYPE" : This condition arises if a default CTYPE value is used within astReadastRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings.

" NoEquinox" : This condition arises if a default equinox value is used within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings.

" NoRadesys" : This condition arises if a default reference frame is used for an equatorial co-ordinate system within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings.

" NoLonpole" : This condition arises if a default value is used for the LONPOLE keyword within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings.

" NoLatpole" : This condition arises if a default value is used for the LATPOLE keyword within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings.

" NoMjd-obs" : This condition arises if a default value is used for the date of observation within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings.

" Tnx" : This condition arises if a FrameSet is read from a FITS header containing an IRAF " TNX" projection which includes terms not supproted by AST. Such terms are ignored and so the resulting FrameSet may be inaccurate.

" Zpx" : This condition arises if a FrameSet is read from a FITS header containing an IRAF " ZPX" projection which includes " lngcor" or " latcor" correction terms. These terms are not supported by AST and are ignored. The resulting FrameSet may therefore be inaccurate. AltAxes Controls generation of FITS-WCS alternate axis descriptions This attribute controls the generation of FITS-WCS alternate axis keywords by the astWriteastWrite method. It determines which of the Frames in the FrameSetFrameSet supplied to astWrite are used to create a set of alternate axis descriptions. It may be set to one of the following values (case insensitive):

" ALL" : A set of alternate axes will be created for each FrameFrame in the supplied FrameSet, excluding the BaseBase and CurrentCurrent Frames. This is the default.

" NONE" : No alternate axes will be created for any of the Frames in the supplied FrameSet.

" IDENT" : Alternate axes will be created for a Frame only if its IdentIdent attribute is set to a single upper case alphabetical character (A-Z). String. FitsChanFitsChan All FitsChans have this attribute. This attribute is used only if the EncodingEncoding attribute of the FitsChan is set to (or defaults to) " FITS-WCS" or " FITS-PC" .

The Current Frame in the FrameSet is always used to create the primary axis descriptions in the output FITS header.

The Base Frame in the FrameSet is never used to create a set of alternate axis descriptions. AsTime(axis) Format celestal coordinates as times? This attribute specifies the default style of formatting to be used (e.g. by astFormatastFormat) for the celestial coordinate values described by a SkyFrameSkyFrame. It takes a separate boolean value for each SkyFrame axis so that, for instance, the setting " AsTime(2)=0" specifies the default formatting style for celestial latitude values.

If the AsTime attribute for a SkyFrame axis is zero, then coordinates on that axis will be formatted as angles by default (using degrees, minutes and seconds), otherwise they will be formatted as times (using hours, minutes and seconds).

The default value of AsTime is chosen according to the sky coordinate system being represented, as determined by the SkyFrame' s SystemSystem attribute. This ensures, for example, that right ascension values will be formatted as times by default, following normal conventions. Integer (boolean). SkyFrame All SkyFrames have this attribute. The AsTime attribute operates by changing the default value of the corresponding Format(axis)Format(axis) attribute. This, in turn, may also affect the value of the Unit(axis)Unit(axis) attribute.

Only the default style of formatting is affected by the AsTime value. If an explicit Format(axis) value is set, it will over-ride any effect from the AsTime attribute. Base FrameSet base Frame index This attribute gives the index of the FrameFrame which is to be regarded as the " base" Frame within a FrameSetFrameSet. The default is the first Frame added to the FrameSet when it is created (this Frame always has an index of 1).

When setting a new value for this attribute, a string may be supplied instead of an integer index. In this case a search is made within the FrameSet for a Frame that has its DomainDomain attribute value equal to the supplied string (the comparison is case-insensitive). If found, the Frame is made the base Frame. Otherwise an error is reported. Integer. FrameSet All FrameSets have this attribute. Inverting a FrameSet (inverting the boolean sense of its InvertInvert attribute, with the astInvertastInvert function for example) will interchange the values of its Base and CurrentCurrent attributes. Border Draw a border around valid regions of a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether a border is drawn around regions corresponding to the valid physical coordinates of a PlotPlot (c.f. astBorderastBorder).

If the Border value of a Plot is non-zero, then this border will be drawn as part of the grid. Otherwise, the border is not drawn (although axis labels and tick marks will still appear, unless other relevant Plot attributes indicate that they should not). The default behaviour is to draw the border if tick marks and numerical labels will be drawn around the edges of the plotting area (see the LabellingLabelling attribute), but to omit it otherwise. Integer (boolean). Plot All Plots have this attribute. Bottom(axis) Lowest axis value to display This attribute gives the lowest axis value to be displayed (for instance, by the astGridastGrid method). Floating point. FrameFrame The default supplied by the Frame class is to display all axis values, without any limit. SkyFrameSkyFrame 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. When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. Bounded Is the Region bounded? This is a read-only attribute indicating if the RegionRegion is bounded. A Region is bounded if it is contained entirely within some finite-size bounding box. Integer (boolean), read-only. Region All Regions have this attribute. CDMatrix Use CDi_j keywords to represent pixel scaling, rotation, etc? This attribute is a boolean value which specifies how the linear transformation from pixel coordinates to intermediate world coordinates should be represented within a FitsChanFitsChan when using FITS-WCS encoding. This transformation describes the scaling, rotation, shear, etc., of the pixel axes.

If the attribute has a non-zero value then the transformation is represented by a set of CDi_j keywords representing a square matrix (where " i" is the index of an intermediate world coordinate axis and " j" is the index of a pixel axis). If the attribute has a zero value the transformation is represented by a set of PCi_j keywords (which also represent a square matrix) together with a corresponding set of CDELTi keywords representing the axis scalings. See FITS-WCS paper II " Representation of Celestial Coordinates in FITS" by M. Calabretta & E.W. Greisen, for a complete description of these two schemes.

The default value of the CDMatrix attribute is determined by the contents of the FitsChan at the time the attribute is accessed. If the FitsChan contains any CDi_j keywords then the default value is non-zero. Otherwise it is zero. Note, reading a FrameSetFrameSet from a FitsChan will in general consume any CDi_j keywords present in the FitsChan. Thus the default value for CDMatrix following a read will usually be zero, even if the FitsChan originally contained some CDi_j keywords. This behaviour is similar to that of the EncodingEncoding attribute, the default value for which is determined by the contents of the FitsChan at the time the attribute is accessed. If you wish to retain the original value of the CDMatrix attribute (that is, the value before reading the FrameSet) then you should enquire the default value before doing the read, and then set that value explicitly. Integer (boolean). FitsChan All FitsChans have this attribute. CarLin Ignore spherical rotations on CAR projections? This attribute is a boolean value which specifies how FITS " CAR" (plate carree, or " Cartesian" ) projections should be treated when reading a FrameSetFrameSet from a foreign encoded FITS header. If zero (the default), it is assumed that the CAR projection conforms to the conventions described in the FITS world coordinate system (FITS-WCS) paper II " Representation of Celestial Coordinates in FITS" by M. Calabretta & E.W. Greisen. If CarLin is non-zero, then these conventions are ignored, and it is assumed that the mapping from pixel coordinates to celestial coordinates is a simple linear transformation (hence the attribute name " CarLin" ). This is appropriate for some older FITS data which claims to have a " CAR" projection, but which in fact do not conform to the conventions of the FITS-WCS paper.

The FITS-WCS paper specifies that headers which include a CAR projection represent a linear mapping from pixel coordinates to " native spherical coordinates" , NOT celestial coordinates. An extra mapping is then required from native spherical to celestial. This mapping is a 3D rotation and so the overall MappingMapping from pixel to celestial coordinates is NOT linear. See the FITS-WCS papers for further details. Integer (boolean). FitsChanFitsChan All FitsChans have this attribute. Card Index of current FITS card in a FitsChan This attribute gives the index of the " current" FITS header card within a FitsChanFitsChan, the first card having an index of 1. The choice of current card affects the behaviour of functions that access the contents of the FitsChan, such as astDelFitsastDelFits, astFindFitsastFindFits and astPutFitsastPutFits.

A value assigned to Card will position the FitsChan at any desired point, so that a particular card within it can be accessed. Alternatively, the value of Card may be enquired in order to determine the current position of a FitsChan.

The default value of Card is 1. This means that clearing this attribute (using astClearastClear) effectively " rewinds" the FitsChan, so that the first card is accessed next. If Card is set to a value which exceeds the total number of cards in the FitsChan (as given by its NcardNcard attribute), it is regarded as pointing at the " end-of-file" . In this case, the value returned in response to an enquiry is always one more than the number of cards in the FitsChan. Integer. FitsChan All FitsChans have this attribute. CardComm The comment for the current card in a FitsChan This attribute gives the comment for the current card of the FitsChanFitsChan. A zero-length string is returned if the card has no comment. String, read-only. FitsChan All FitsChans have this attribute. CardName The keyword name of the current card in a FitsChan This attribute gives the name of the keyword for the current card of the FitsChanFitsChan. String, read-only. FitsChan All FitsChans have this attribute. CardType The data type of the current card in a FitsChan This attribute gives the data type of the keyword value for the current card of the FitsChanFitsChan. It will be one of the following integer constants: AST__NOTYPE, AST__COMMENT, AST__INT, AST__FLOAT, AST__STRING, AST__COMPLEXF, AST__COMPLEXI, AST__LOGICAL, AST__CONTINUE, AST__UNDEF. Integer, read-only. FitsChan All FitsChans have this attribute. Class Object class name This attribute gives the name of the class to which an ObjectObject belongs. Character string, read-only. Object All Objects have this attribute. Clean Remove cards used whilst reading even if an error occurs? This attribute indicates whether or not cards should be removed from the FitsChanFitsChan if an error occurs within astReadastRead. A succesful read on a FitsChan always results in the removal of the cards which were involved in the description of the returned ObjectObject. However, in the event of an error during the read (for instance if the cards in the FitsChan have illegal values, or if some required cards are missing) no cards will be removed from the FitsChan if the Clean attribute is zero (the default). If Clean is non-zero then any cards which were used in the aborted attempt to read an object will be removed.

This provides a means of " cleaning" a FitsChan of WCS related cards which works even in the event of the cards not forming a legal WCS description. Integer (boolean). FitsChan All FitsChans have this attribute. Clip Clip lines and/or markers at the Plot boundary? This attribute controls whether curves and markers are clipped at the boundary of the graphics box specified when the PlotPlot was created. A value of 3 implies both markers and curves are clipped at the Plot boundary. A value of 2 implies markers are clipped, but not curves. A value of 1 implies curves are clipped, but not markers. A value of zero implies neither curves nor markers are clipped. The default value is 1. Note, this attributes controls only the clipping performed internally within AST. The underlying graphics system may also apply clipping. In such cases, removing clipping using this attribute does not guarantee that no clipping will be visible in the final plot.

The astClipastClip function can be used to establish generalised clipping within arbitrary regions of the Plot. Integer. Plot All Plots have this attribute. ClipOp Combine Plot clipping limits using a boolean OR? This attribute controls how the clipping limits specified for each axis of a PlotPlot (using the astClipastClip function) are combined. This, in turn, determines which parts of the graphical output will be visible.

If the ClipOp attribute of a Plot is zero (the default), graphical output is visible only if it satisfies the clipping limits on all the axes of the clipping FrameFrame (a boolean AND). Otherwise, if ClipOp is non-zero, output is visible if it satisfies the clipping limits on one or more axes (a boolean OR).

An important use of this attribute is to allow areas of a Plot to be left clear (e.g. as a background for some text). To achieve this, the lower and upper clipping bounds supplied to astClip should be reversed, and the ClipOp attribute of the Plot should be set to a non-zero value. Integer (boolean). Plot All Plots have this attribute. Closed Should the boundary be considered to be inside the region? This attribute controls whether points on the boundary of a RegionRegion are considered to be inside or outside the region. If the attribute value is non-zero (the default), points on the boundary are considered to be inside the region (that is, the Region is " closed" ). However, if the attribute value is zero, points on the bounary are considered to be outside the region. Integer (boolean). Region All Regions have this attribute. PointListPointList The value of the Closed attribute is ignored by PointList regions. If the PointList region has not been negated, then it is always assumed to be closed. If the PointList region has been negated, then it is always assumed to be open. This is required since points have zero volume and therefore consist entirely of boundary. CmpRegionCmpRegion The default Closed value for a CmpRegion is the Closed value of its first component Region. StcStc The default Closed value for an Stc is the Closed value of its encapsulated Region. MocMoc The Moc class ignored this attribute, and the behaviour for boundary points is undefined (i.e. they may be inside or outside the Region, depending on the position being tested and the nature of the Moc). Colour(element) Colour index for a Plot element This attribute determines the colour index used when drawing each element of graphical output produced by a PlotPlot. It takes a separate value for each graphical element so that, for instance, the setting " Colour(title)=2" causes the Plot title to be drawn using colour index 2. The synonym " Color" may also be used.

The range of integer colour indices available and their appearance is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default colour index supplied by this graphics system (normally, this is likely to result in white plotting on a black background, or vice versa). Integer. Plot All Plots have this attribute. For a list of the graphical elements available, see the description of the Plot class.

If no graphical element is specified, (e.g. " Colour" instead of " Colour(title)" ), then a " set" or " clear" operation will affect the attribute value of all graphical elements, while a " get" or " test" operation will use just the Colour(TextLab) value. ColumnLenC(column) The largest string length of any value in a column This attribute holds the minimum length which a character variable must have in order to be able to store the longest value currently present (at any row) in a specified column of the supplied TableTable. This does not include room for a trailing null character. The required column name should be placed inside the parentheses in the attribute name. If the named column holds vector values, then the attribute value is the length of the longest element of the vector value. Integer, read-only. Table All Tables have this attribute. If the named column holds numerical values, the length returned is the length of the largest string that would be generated if the column values were accessed as strings. ColumnLength(column) The number of elements in each value in a column This attribute holds the number of elements in each value stored in a named column. Each value can be a scalar (in which case the ColumnLength attribute has a value of 1), or a multi-dimensional array ( in which case the ColumnLength value is equal to the product of the array dimensions). Integer, read-only. TableTable All Tables have this attribute. ColumnNdim(column) The number of axes spanned by each value in a column This attribute holds the number of axes spanned by each value in a column. If each cell in the column is a scalar, ColumnNdim will be zero. If each cell in the column is a 1D spectrum, ColumnNdim will be one. If each cell in the column is a 2D image, ColumnNdim will be two, etc. The required column name should be placed inside the parentheses in the attribute name. Integer, read-only. TableTable All Tables have this attribute. ColumnType(column) The data type of each value in a column This attribute holds a integer value indicating the data type of a named column in a TableTable. This is the data type which was used when the column was added to the Table using astAddColumnastAddColumn. The required column name should be placed inside the parentheses in the attribute name.

The attribute value will be one of AST__INTTYPE (for integer), AST__SINTTYPE (for short int), AST__BYTETYPE (for unsigned bytes - i.e. unsigned chars), AST__DOUBLETYPE (for double precision floating point), AST__FLOATTYPE (for single precision floating point), AST__STRINGTYPE (for character string), AST__OBJECTTYPE (for AST ObjectObject pointer), AST__POINTERTYPE (for arbitrary C pointer) or AST__UNDEFTYPE (for undefined values created by astMapPutUastMapPutU). Integer, read-only. Table All Tables have this attribute. Comment Include textual comments in output? This is a boolean attribute which controls whether textual comments are to be included in the output generated by a ChannelChannel. If included, they will describe what each item of output represents.

If Comment is non-zero, then comments will be included. If it is zero, comments will be omitted. Integer (boolean). Channel The default value is non-zero for a normal Channel. FitsChanFitsChan The default value is non-zero for a FitsChan. XmlChanXmlChan The default value is zero for an XmlChan. YamlChanYamlChan This attribute is ignored by the YamlChan class. Comments are never produced. Current FrameSet current Frame index This attribute gives the index of the FrameFrame which is to be regarded as the " current" Frame within a FrameSetFrameSet. The default is the most recent Frame added to the FrameSet (this Frame always has an index equal to the FrameSet' s NframeNframe attribute).

When setting a new value for this attribute, a string may be supplied instead of an integer index. In this case a search is made within the FrameSet for a Frame that has its DomainDomain attribute value equal to the supplied string (the comparison is case-insensitive). If found, the Frame is made the current Frame. Otherwise an error is reported. Integer. FrameSet All FrameSets have this attribute. Inverting a FrameSet (inverting the boolean sense of its InvertInvert attribute, with the astInvertastInvert function for example) will interchange the values of its BaseBase and Current attributes. DSBCentre The central position of interest in a dual sideband spectrum This attribute specifies the central position of interest in a dual sideband spectrum. Its sole use is to determine the local oscillator frequency (the frequency which marks the boundary between the lower and upper sidebands). See the description of the IFIF (intermediate frequency) attribute for details of how the local oscillator frequency is calculated. The sideband containing this central position is referred to as the " observed" sideband, and the other sideband as the " image" sideband.

The value is accessed as a position in the spectral system represented by the SpecFrameSpecFrame attributes inherited by this class, but is stored internally as topocentric frequency. Thus, if the SystemSystem attribute of the DSBSpecFrameDSBSpecFrame is set to " VRAD" , the Unit attribute set to " m/s" and the StdOfRestStdOfRest attribute set to " LSRK" , then values for the DSBCentre attribute should be supplied as radio velocity in units of " m/s" relative to the kinematic LSR (alternative units may be used by appending a suitable units string to the end of the value). This value is then converted to topocentric frequency and stored. If (say) the Unit attribute is subsequently changed to " km/s" before retrieving the current value of the DSBCentre attribute, the stored topocentric frequency will be converted back to LSRK radio velocity, this time in units of " km/s" , before being returned.

The default value for this attribute is 30 GHz. Floating point. DSBSpecFrame All DSBSpecFrames have this attribute. Note The attributes which define the transformation to or from topocentric frequency should be assigned their correct values before accessing this attribute. These potentially include System, Unit, StdOfRest, ObsLonObsLon, ObsLatObsLat, ObsAltObsAlt, EpochEpoch, RefRARefRA, RefDecRefDec and RestFreqRestFreq. DefB1950 Use FK4 B1950 as defaults? This attribute is a boolean value which specifies a default equinox and reference frame to use when reading a FrameSetFrameSet from a FitsChanFitsChan with a foreign (i.e. non-native) encoding. It is only used if the FITS header contains RA and DEC axes but contains no information about the reference frame or equinox. If this is the case, then values of FK4 and B1950 are assumed if the DefB1950 attribute has a non-zero value and ICRS is assumed if DefB1950 is zero. The default value for DefB1950 depends on the value of the EncodingEncoding attribute: for FITS-WCS encoding the default is zero, and for all other encodings it is one. Integer (boolean). FitsChan All FitsChans have this attribute. Digits/Digits(axis) Number of digits of precision This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a FrameFrame axis (e.g. using astFormatastFormat). 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 value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string " .34#34" , then the Digits attribute is used to determine the number of decimal places to produce. Integer. Frame The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead. FrameSetFrameSet The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the CurrentCurrent attribute). PlotPlot The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct. TimeFrameTimeFrame The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute). Direction(axis) Display axis in conventional direction? This attribute is a boolean value which suggests how the axes of a FrameFrame 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 set to zero, this attribute indicates that the direction should be reversed, as would often be done for an astronomical magnitude or a right ascension axis. Integer (boolean). Frame The default Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction. SkyFrameSkyFrame The SkyFrame class re-defines the default Direction value to suggest that certain axes (e.g. right ascension) should be plotted in reverse when appropriate. FrameSetFrameSet The Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the CurrentCurrent attribute). PlotPlot The 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. When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

The 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. Disco PcdMap pincushion/barrel distortion coefficient This attribute specifies the pincushion/barrel distortion coefficient used by a PcdMapPcdMap. This coefficient is set when the PcdMap is created, but may later be modified. If the attribute is cleared, its default value is zero, which gives no distortion. For pincushion distortion, the value should be positive. For barrel distortion, it should be negative.

Note that the forward transformation of a PcdMap applies the distortion specified by this attribute and the inverse transformation removes this distortion. If the PcdMap is inverted (e.g. using astInvertastInvert), then the forward transformation will remove the distortion and the inverse transformation will apply it. The distortion itself will still be given by the same value of Disco.

Note, the value of this attribute may changed only if the PcdMap has no more than one reference. That is, an error is reported if the PcdMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. PcdMap All PcdMaps have this attribute. Domain Coordinate system domain This attribute contains a string which identifies the physical domain of the coordinate system that a FrameFrame describes.

The Domain attribute also controls how a Frame behaves when it is used (by astFindFrameastFindFrame) as a template to match another (target) Frame. It does this by specifying the Domain that the target Frame should have in order to match the template. If the Domain value in the template Frame is set, then only targets with the same Domain value will be matched. If the template' s Domain value is not set, however, then the target' s Domain will be ignored. String. Frame The default Domain value supplied by the Frame class is an empty string. SkyFrameSkyFrame The SkyFrame class re-defines the default Domain value to be " SKY" . CmpFrameCmpFrame The CmpFrame class re-defines the default Domain value to be of the form " 1#1dom12#2-1#1dom22#2" , where 1#1dom12#2 and 1#1dom22#2 are the Domains of the two component Frames. If both these Domains are blank, then the string " CMP" is used as the default Domain name. FrameSetFrameSet The Domain attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). SpecFrameSpecFrame The SpecFrame class re-defines the default Domain value to be " SPECTRUM" . DSBSpecFrameDSBSpecFrame The DSBSpecFrame class re-defines the default Domain value to be " DSBSPECTRUM" . FluxFrameFluxFrame The FluxFrame class re-defines the default Domain value to be " FLUX" . SpecFluxFrameSpecFluxFrame The FluxFrame class re-defines the default Domain value to be " SPECTRUM-FLUX" . TimeFrameTimeFrame The TimeFrame class re-defines the default Domain value to be " TIME" . All Domain values are converted to upper case and white space is removed before use. DrawAxes(axis) Draw axes for a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether curves representing coordinate axes should be drawn. It takes a separate value for each physical axis of a PlotPlot so that, for instance, the setting " DrawAxes(2)=0" specifies that no axis should be drawn for the second axis.

If drawn, these axis lines will pass through any tick marks associated with numerical labels drawn to mark values on the axes. The location of these tick marks and labels (and hence the axis lines) is determined by the Plot' s LabelAt(axis)LabelAt(axis) attribute.

If the DrawAxes value of a Plot is non-zero (the default), then axis lines will be drawn, otherwise they will be omitted. Integer (boolean). Plot All Plots have this attribute. AxisAxis lines are drawn independently of any coordinate grid lines (see the GridGrid attribute) so grid lines may be used to substitute for axis lines if required.

In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the LabellingLabelling attribute). In this case, the value of the DrawAxes attribute is ignored.

If no axis is specified, (e.g. " DrawAxes" instead of " DrawAxes(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the DrawAxes(1) value. DrawTitle Draw a title for a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether a title is drawn.

If the DrawTitle value of a PlotPlot is non-zero (the default), then the title will be drawn, otherwise it will be omitted. Integer (boolean). Plot All Plots have this attribute. Plot3DPlot3D The Plot3D class ignores this attributes, assuming a value of zero. The text used for the title is obtained from the Plot' s TitleTitle attribute.

The vertical placement of the title can be controlled using the TitleGapTitleGap attribute. Dtai The TAI-UTC correction This attribute specifies the difference between TAI and UTC (i.e. the number of leap seconds) at the moment corresponding to the FrameFrame' s EpochEpoch value. The default value of AST__BAD causes the number of leap seconds to be determined from an internal look-up table, which is kept up-to-date manually by the AST development team. Therefore it is only necessary to assign a value to this attribute if the version of AST in use is so old that it does not include all leap seconds that occurred prior to the time represented by the Frame' s Epoch value. Floating point. Frame All Frames have this attribute. Dut1 The UT1-UTC correction This attribute is used when calculating the Local Apparent Sidereal Time corresponding to SkyFrameSkyFrame' s EpochEpoch 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 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. Floating point. FrameFrame All Frames have this attribute. Edge(axis) Which edges to label in a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining which edges of a PlotPlot are used for displaying numerical and descriptive axis labels. It takes a separate value for each physical axis of the Plot so that, for instance, the setting " Edge(2)=left" specifies which edge to use to display labels for the second axis.

The values " left" , " top" , " right" and " bottom" (or any abbreviation) can be supplied for this attribute. The default is usually " bottom" for the first axis and " left" for the second axis. However, if exterior labelling was requested (see the LabellingLabelling attribute) but cannot be produced using these default Edge values, then the default values will be swapped if this enables exterior labelling to be produced. String. Plot All Plots have this attribute. Plot3DPlot3D The Plot3D class ignores this attributes. Instead it uses its own RootCornerRootCorner attribute to determine which edges of the 3D plot to label. In some circumstances, numerical labels will be drawn along internal grid lines instead of at the edges of the plotting area (see the Labelling attribute). In this case, the Edge attribute only affects the placement of the descriptive labels (these are drawn at the edges of the plotting area, rather than along the axis lines). Encoding System for encoding Objects as FITS headers This attribute specifies the encoding system to use when AST Objects are stored as FITS header cards in a FitsChanFitsChan. It affects the behaviour of the astWriteastWrite and astReadastRead functions when they are used to transfer any AST ObjectObject to or from an external representation consisting of FITS header cards (i.e. whenever a write or read operation is performed using a FitsChan as the I/O ChannelChannel).

There are several ways (conventions) by which coordinate system information may be represented in the form of FITS headers and the Encoding attribute is used to specify which of these should be used. The encoding options available are outlined in the " Encodings Available" section below, and in more detail in the sections which follow.

Encoding systems differ in the range of possible Objects (e.g. classes) they can represent, in the restrictions they place on these Objects (e.g. compatibility with some externally-defined coordinate system model) and in the number of Objects that can be stored together in any particular set of FITS header cards (e.g. multiple Objects, or only a single Object). The choice of encoding also affects the range of external applications which can potentially read and interpret the FITS header cards produced.

The encoding options available are not necessarily mutually exclusive, and it may sometimes be possible to store multiple Objects (or the same Object several times) using different encodings within the same set of FITS header cards. This possibility increases the likelihood of other applications being able to read and interpret the information.

By default, a FitsChan will attempt to determine which encoding system is already in use, and will set the default Encoding value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical FITS keywords which only occur in particular encodings. For details of how this works, see the " Choice of Default Encoding" section below. If you wish to ensure that a particular encoding system is used, independently of any FITS cards already present, you should set an explicit Encoding value yourself. String. FitsChan All FitsChans have this attribute. Encodings Available The Encoding attribute can take any of the following (case insensitive) string values to select the corresponding encoding

system:

" DSS" : Encodes coordinate system information in FITS header cards using the convention developed at the Space Telescope Science Institute (STScI) for the Digitised Sky Survey (DSS) astrometric plate calibrations. The main advantages of this encoding are that FITS images which use it are widely available and it is understood by a number of important and well-established astronomy applications. For further details, see the section " The DSS Encoding" below.

" FITS-WCS" : Encodes coordinate system information in FITS header cards using the conventions described in the FITS world coordinate system (FITS-WCS) papers by E.W. Greisen, M. Calabretta, et al. The main advantages of this encoding are that it should be understood by any FITS-WCS compliant application and is likely to be adopted widely for FITS data in future. For further details, see the section " The FITS-WCS Encoding" below.

" FITS-PC" : Encodes coordinate system information in FITS header cards using the conventions described in an earlier draft of the FITS world coordinate system papers by E.W. Greisen and M. Calabretta. This encoding uses a combination of CDELTi and PCiiijjj keywords to describe the scale and rotation of the pixel axes. This encoding is included to support existing data and software which uses these now superceded conventions. In general, the " FITS-WCS" encoding (which uses CDi_j or PCi_j keywords to describe the scale and rotation) should be used in preference to " FITS-PC" .

" FITS-IRAF" : Encodes coordinate system information in FITS header cards using the conventions described in the document " World Coordinate Systems Representations Within the FITS Format" by R.J. Hanisch and D.G. Wells, 1988. This encoding is currently employed by the IRAF data analysis facility, so its use will facilitate data exchange with IRAF. Its main advantages are that it is a stable convention which approximates to a subset of the propsed FITS-WCS encoding (above). This makes it suitable as an interim method for storing coordinate system information in FITS headers until the FITS-WCS encoding becomes stable. Since many datasets currently use the FITS-IRAF encoding, conversion of data from FITS-IRAF to the final form of FITS-WCS is likely to be well supported.

" FITS-AIPS" : Encodes coordinate system information in FITS header cards using the conventions originally introduced by the AIPS data analysis facility. This is base on the use of CDELTi and CROTAi keuwords to desribe the scale and rotation of each axis. These conventions have been superceded but are still widely used.

" FITS-AIPS241#241 241#241" : Encodes coordinate system information in FITS header cards using the conventions used by the AIPS241#241 241#241 project. This is an extension of FITS-AIPS which includes some of the features of FITS-IRAF and FITS-PC.

" FITS-CLASS" : Encodes coordinate system information in FITS header cards using the conventions used by the CLASS project. CLASS is a software package for reducing single-dish radio and sub-mm spectroscopic data. See the section " CLASS FITS format" at http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/.

" NATIVE" : Encodes AST Objects in FITS header cards using a convention which is private to the AST library (but adheres to the general FITS standard) and which uses FITS keywords that will not clash with other encoding systems. The main advantages of this are that any class of AST Object may be encoded, and any (reasonable) number of Objects may be stored sequentially in the same FITS header. This makes FITS headers an almost loss-less communication path for passing AST Objects between applications (although all such applications must, of course, make use of the AST library to interpret the information). For further details, see the section " The NATIVE Encoding" below. Choice of Default Encoding If the Encoding attribute of a FitsChan is not set, the default value it takes is determined by the presence of certain critical FITS keywords within the FitsChan. The sequence of decisions

used to arrive at the default value is as follows:

If the FitsChan contains any keywords beginning with the string " BEGAST" , then NATIVE encoding is used,

Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV keyword and a keyword of the form VELO-xxx, where xxx indicates one of the rest frames used by class (e.g. " VELO-LSR" ), or " VLSR" .

Otherwise, if the FitsChan contains a CTYPE keyword which represents a spectral axis using the conventions of the AIPS and AIPS241#241 241#241 projects (e.g. " FELO-LSR" , etc), then one of FITS-AIPS or FITS-AIPS241#241 241#241 encoding is used. FITS-AIPS241#241 241#241 is used if any of the keywords CDi_j, PROJP, LONPOLE or LATPOLE are found in the FitsChan. Otherwise FITS-AIPS is used.

Otherwise, if the FitsChan contains a keyword of the form " PCiiijjj" , where " i" and " j" are single digits, then FITS-PC encoding is used,

Otherwise, if the FitsChan contains a keyword of the form " CDiiijjj" , where " i" and " j" are single digits, then FITS-IRAF encoding is used,

Otherwise, if the FitsChan contains a keyword of the form " CDi_j" , and at least one of RADECSYS, PROJPi, or CjVALi where " i" and " j" are single digits, then FITS-IRAF encoding is used.

Otherwise, if the FitsChan contains any keywords of the form PROJPi, CjVALi or RADECSYS, where " i" and " j" are single digits, then FITS-PC encoding is used.

Otherwise, if the FitsChan contains a keyword of the form CROTAi, where " i" is a single digit, then FITS-AIPS encoding is used.

Otherwise, if the FitsChan contains a keyword of the form CRVALi, where " i" is a single digit, then FITS-WCS encoding is used.

Otherwise, if the FitsChan contains the " PLTRAH" keyword, then DSS encoding is used,

Otherwise, if none of these conditions is met (as would be the case when using an empty FitsChan), then NATIVE encoding is used.

Except for the NATIVE and DSS encodings, all the above checks also require that the header contains at least one CTYPE, CRPIX and CRVAL keyword (otherwise the checking process continues to the next case).

Setting an explicit value for the Encoding attribute always over-rides this default behaviour.

Note that when writing information to a FitsChan, the choice of encoding will depend greatly on the type of application you expect to be reading the information in future. If you do not know this, there may sometimes be an advantage in writing the information several times, using a different encoding on each occasion. The DSS Encoding The DSS encoding uses FITS header cards to store a multi-term polynomial which relates pixel positions on a digitised photographic plate to celestial coordinates (right ascension and declination). This encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a FrameSetFrameSet which conforms to the STScI/DSS coordinate system model (this means the MappingMapping which relates its base and current Frames must include either a DssMapDssMap or a WcsMapWcsMap with type AST__TAN or AST__TPN).

When reading a DSS encoded Object (using astRead), the FitsChan concerned must initially be positioned at the first card (its CardCard attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base FrameFrame of this FrameSet represents DSS pixel coordinates, and the current Frame represents DSS celestial coordinates. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the " end-of-file" . A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound.

When astWrite is used to store a FrameSet using DSS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the DSS model. Specifically, the current Frame must be a FK5 SkyFrameSkyFrame; the projection must be a tangent plane (gnomonic) projection with polynomial corrections conforming to DSS requirements, and north must be parallel to the second base Frame axis.

If the simplification process succeeds, a description of the FrameSet is written to the FitsChan using appropriate DSS FITS header cards. The base Frame of the FrameSet is used to form the DSS pixel coordinate system and the current Frame gives the DSS celestial coordinate system. A successful write operation will over-write any existing DSS encoded data in the FitsChan, but will not affect other (non-DSS) header cards. If a destructive read of a DSS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations.

If an attempt to simplify a FrameSet to conform to the DSS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and astWrite will return zero. No error will result. The FITS-WCS Encoding The FITS-WCS convention uses FITS header cards to describe the relationship between pixels in an image (not necessarily 2-dimensional) and one or more related " world coordinate systems" . The FITS-WCS encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a FrameSet which conforms to the FITS-WCS model (the FrameSet may, however, contain multiple Frames which will be result in multiple FITS " alternate axis descriptions" ). Details of the use made by this Encoding of the conventions described in the FITS-WCS papers are given in the appendix " FITS-WCS Coverage" of this document. A few main points are described below.

The rotation and scaling of the intermediate world coordinate system can be specified using either " CDi_j" keywords, or " PCi_j" together with " CDELTi" keywords. When writing a FrameSet to a FitsChan, the the value of the CDMatrixCDMatrix attribute of the FitsChan determines which system is used.

In addition, this encoding supports the " TAN with polynomial correction terms" projection which was included in a draft of the FITS-WCS paper, but was not present in the final version. A " TAN with polynomial correction terms" projection is represented using a WcsMap with type AST__TPN (rather than AST__TAN which is used to represent simple TAN projections). When reading a FITS header, a CTYPE keyword value including a " -TAN" code results in an AST__TPN projection if there are any projection parameters (given by the PVi_mPVi_m keywords) associated with the latitude axis, or if there are projection parameters associated with the longitude axis for m greater than 4. When writing a FrameSet to a FITS header, an AST__TPN projection gives rise to a CTYPE value including the normal " -TAN" code, but the projection parameters are stored in keywords with names " QVi_m" , instead of the usual " PVi_m" . Since these QV parameters are not part of the FITS-WCS standard they will be ignored by other non-AST software, resulting in the WCS being interpreted as a simple TAN projection without any corrections. This should be seen as an interim solution until such time as an agreed method for describing projection distortions within FITS-WCS has been published.

AST extends the range of celestial coordinate systems which may be described using this encoding by allowing the inclusion of " AZ–" and " EL–" as the coordinate specification within CTYPE values. These form a longitude/latitude pair of axes which describe azimuth and elevation. The geographic position of the observer should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS paper III. Currently, a simple model is used which includes diurnal aberration, but ignores atmospheric refraction, polar motion, etc. These may be added in a later release.

If an AST SkyFrame that represents offset rather than absolute coordinates (see attribute SkyRefIsSkyRefIs) is written to a FitsChan using FITS-WCS encoding, two alternate axis descriptions will be created. One will describe the offset coordinates, and will use " OFLN" and " OFLT" as the axis codes in the CTYPE keywords. The other will describe absolute coordinates as specified by the SystemSystem attribute of the SkyFrame, using the usual CTYPE codes (" RA–" /" DEC-" , etc). In addition, the absolute coordinates description will contain AST-specific keywords (SREF1/2, SREFP1/2 and SREFIS) that allow the header to be read back into AST in order to reconstruct the original SkyFrame.

When reading a FITS-WCS encoded Object (using astRead), the FitsChan concerned must initially be positioned at the first card (its Card attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base Frame of this FrameSet represents FITS-WCS pixel coordinates, and the current Frame represents the physical coordinate system described by the FITS-WCS primary axis descriptions. If secondary axis descriptions are also present, then the FrameSet may contain additional (non-current) Frames which represent these. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the " end-of-file" . A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound.

When astWrite is used to store a FrameSet using FITS-WCS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the FITS-WCS model. If this simplification process succeeds (as it often should, as the model is reasonably flexible), a description of the FrameSet is written to the FitsChan using appropriate FITS header cards. The base Frame of the FrameSet is used to form the FITS-WCS pixel coordinate system and the current Frame gives the physical coordinate system to be described by the FITS-WCS primary axis descriptions. Any additional Frames in the FrameSet may be used to construct secondary axis descriptions, where appropriate.

A successful write operation will over-write any existing FITS-WCS encoded data in the FitsChan, but will not affect other (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations. Otherwise, the new cards will be inserted following any other FITS-WCS related header cards present or, failing that, in front of the current card (as given by the Card attribute).

If an attempt to simplify a FrameSet to conform to the FITS-WCS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and astWrite will return zero. No error will result. The FITS-IRAF Encoding The FITS-IRAF encoding can, for most purposes, be considered as a subset of the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the

addition of the following:

The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic,

Sky projections can be represented only if any associated projection parameters are set to their default values.

Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored.

Note that this encoding is provided mainly as an interim measure to provide a more stable alternative to the FITS-WCS encoding until the FITS standard for encoding WCS information is finalised. The name " FITS-IRAF" indicates the general keyword conventions used and does not imply that this encoding will necessarily support all features of the WCS scheme used by IRAF software. Nevertheless, an attempt has been made to support a few such features where they are known to be used by important sources of data.

When writing a FrameSet using the FITS-IRAF encoding, axis rotations are specified by a matrix of FITS keywords of the form " CDi_j" , where " i" and " j" are single digits. The alternative form " CDiiijjj" , which is also in use, is recognised when reading an Object, but is never written.

In addition, the experimental IRAF " ZPX" and " TNX" sky projections will be accepted when reading, but will never be written (the corresponding FITS " ZPN" or " distorted TAN" projection being used instead). However, there are restrictions on the use of these experimental projections. For " ZPX" , longitude and latitude correction surfaces (appearing as " lngcor" or " latcor" terms in the IRAF-specific " WAT" keywords) are not supported. For " TNX" projections, only cubic surfaces encoded as simple polynomials with " half cross-terms" are supported. If an un-usable " TNX" or " ZPX" projection is encountered while reading from a FitsChan, a simpler form of TAN or ZPN projection is used which ignores the unsupported features and may therefore be inaccurate. If this happens, a warning message is added to the contents of the FitsChan as a set of cards using the keyword " ASTWARN" .

You should not normally attempt to mix the foreign FITS encodings within the same FitsChan, since there is a risk that keyword clashes may occur. The FITS-PC Encoding The FITS-PC encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions. The FITS-AIPS Encoding The FITS-AIPS encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the

addition of the following:

The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic,

Spectral axes can only be represented if they represent frequency, radio velocity or optical velocity, and are linearly sampled in frequency. In addition, the standard of rest must be LSRK, LSRD, barycentric or geocentric.

Sky projections can be represented only if any associated projection parameters are set to their default values.

The AIT, SFL and MER projections can only be written if the CRVAL keywords are zero for both longitude and latitude axes.

Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored.

If there are more than 2 axes in the base and current Frames, any rotation must be restricted to the celestial plane, and must involve no shear. The FITS-AIPS241#241 241#241 Encoding The FITS-AIPS241#241 241#241 encoding is based on the FITS-AIPS encoding, but includes some features of the FITS-IRAF and FITS-PC encodings. Specifically, any celestial projections supported by FITS-PC may be used, including those which require parameterisation, and the axis rotation and scaling may be specified using CDi_j keywords. When writing a FITS header, rotation will be specified using CROTA/CDELT keywords if possible, otherwise CDi_j keywords will be used instead. The FITS-CLASS Encoding The FITS-CLASS encoding uses the conventions of the CLASS project. These are described in the section " Developer Manual" /" CLASS FITS

Format" contained in the CLASS documentation at:

http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html.

This encoding is similar to FITS-AIPS with the following restrictions:

When a SpecFrameSpecFrame is created by reading a FITS-CLASS header, the attributes describing the observer' s position (ObsLatObsLat, ObsLonObsLon and ObsAltObsAlt) are left unset because the CLASS encoding does not specify these values. Conversions to or from the topocentric standard of rest will therefore be inaccurate (typically by up to about 0.5 km/s) unless suitable values are assigned to these attributes after the FrameSet has been created.

When writing a FrameSet to a FITS-CLASS header, the current Frame in the FrameSet must have at least 3 WCS axes, of which one must be a linear spectral axis. The spectral axis in the created header will always describe frequency. If the spectral axis in the supplied FrameSet refers to some other system (e.g. radio velocity, etc), then it will be converted to frequency.

There must be a pair of celestial axes - either (RA,Dec) or (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000.

A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN) can be used. For AIT and SFL, the reference point must be at the origin of longitude and latitude. For SIN, the associated projection parameters must both be zero.

No rotation of the celestial axes is allowed, unless the spatial axes are degenerate (i.e. cover only a single pixel).

The frequency axis in the created header will always describe frequency in the source rest frame. If the supplied FrameSet uses some other standard of rest then suitable conversion will be applied.

The source velocity must be defined. In other words, the SpecFrame attributes SourceVelSourceVel and SourceVRFSourceVRF must have been assigned values.

The frequency axis in a FITS-CLASS header does not represent absolute frequency, but instead represents offsets from the rest frequency in the standard of rest of the source.

When writing a FrameSet out using FITS-CLASS encoding, the current Frame may be temporarily modified if this will allow the header to be produced. If this is done, the associated pixel-2#2WCS Mapping will also be modified to take account of the changes to the Frame. The modifications performed include re-ordering axes (WCS axes, not pixel axes), changing spectral coordinate system and standard of rest, changing the celestial coordinate system and reference equinox, and changing axis units. The NATIVE Encoding The NATIVE encoding may be used to store a description of any class of AST Object in the form of FITS header cards, and (for most practical purposes) any number of these Object descriptions may be stored within a single set of FITS cards. If multiple Object descriptions are stored, they are written and read sequentially. The NATIVE encoding makes use of unique FITS keywords which are designed not to clash with keywords that have already been used for other purposes (if a potential clash is detected, an alternative keyword is constructed to avoid the clash).

When reading a NATIVE encoded object from a FitsChan (using astRead), FITS header cards are read, starting at the current card (as determined by the Card attribute), until the start of the next Object description is found. This description is then read and converted into an AST Object, for which a pointer is returned. Such a read is always destructive and causes all the FITS header cards involved in the Object description to be removed from the FitsChan, which is left positioned at the following card.

The Object returned may be of any class, depending on the description that was read, and other AST routines may be used to validate it (for example, by examining its ClassClass or IDID attribute using astGetC). If further NATIVE encoded Object descriptions exist in the FitsChan, subsequent calls to astRead will return the Objects they describe in sequence (and destroy their descriptions) until no more remain between the current card and the " end-of-file" .

When astWrite is used to write an Object using NATIVE encoding, a description of the Object is inserted immediately before the current card (as determined by the Card attribute). Multiple Object descriptions may be written in this way and are stored separately (and sequentially if the Card attribute is not modified between the writes). A write operation using the NATIVE encoding does not over-write previously written Object descriptions. Note, however, that subsequent behaviour is undefined if an Object description is written inside a previously-written description, so this should be avoided.

When an Object is written to a FitsChan using NATIVE encoding, astWrite should (barring errors) always transfer data and return a value of 1. Epoch Epoch of observation This attribute is used to qualify the coordinate systems described by a FrameFrame, 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 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 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. Floating point. Frame All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the SystemSystem attribute). CmpFrameCmpFrame The default Epoch value for a CmpFrame is selected as follows; if the Epoch attribute has been set in the first component Frame then the Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch attribute has been set in the second component Frame then the Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames. FrameSetFrameSet The Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). SkyFrameSkyFrame The coordinates of sources within a SkyFrame can change 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 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 value, which relates to motion (or apparent motion) of the source, from the superficially similar EquinoxEquinox 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. TimeFrameTimeFrame A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch value. For this reason the TimeFrame class makes no use of the 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 value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame' s TimeOriginTimeOrigin attribute. If no value has been set for TimeOrigin, then the default Epoch value is J2000.0. Input Formats The formats accepted when setting an Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:

Besselian Epoch: Expressed in decimal years, with or without decimal places (" B1950" or " B1976.13" for example).

Julian 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 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 value to be obtained as either a character string or a floating point value. Equinox Epoch of the mean equinox This attribute is used to qualify those celestial coordinate systems described by a SkyFrameSkyFrame which are notionally based on the ecliptic (the plane of the Earth' s orbit around the Sun) and/or the Earth' s equator.

Both of these planes are in motion and their positions are difficult to specify precisely. In practice, therefore, a model ecliptic and/or equator are used instead. These, together with the point on the sky that defines the coordinate origin (the intersection of the two planes termed the " mean equinox" ) move with time according to some model which removes the more rapid fluctuations. The SkyFrame class supports both the FK4 and FK5 models.

The position of a fixed source expressed in any of these coordinate systems will appear to change with time due to movement of the coordinate system itself (rather than motion of the source). Such coordinate systems must therefore be qualified by a moment in time (the " epoch of the mean equinox" or " equinox" for short) which allows the position of the model coordinate system on the sky to be determined. This is the role of the Equinox attribute.

The Equinox attribute is stored as a Modified Julian Date, but when setting or getting its value you may use the same formats as for the EpochEpoch attribute (q.v.).

The default Equinox value is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the SystemSystem attribute) and J2000.0 (Julian) for all others. Floating point. SkyFrame All SkyFrames have this attribute. Care must be taken to distinguish the Equinox value, which relates to the definition of a time-dependent coordinate system (based on solar system reference planes which are in motion), from the superficially similar Epoch value. The latter is used to qualify coordinate systems where the positions of sources change with time (or appear to do so) for a variety of other reasons, such as aberration of light caused by the observer' s motion, etc.

See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system. Escape Allow changes of character attributes within strings? This attribute controls the appearance of text strings and numerical labels drawn by the astGridastGrid and (for the PlotPlot class) astTextastText functions, by determining if any escape sequences contained within the strings should be used to control the appearance of the text, or should be printed literally. Note, the Plot3DPlot3D class only interprets escape sequences within the astGrid function.

If the Escape value of a Plot is one (the default), then any escape sequences in text strings produce the effects described below when printed. Otherwise, they are printed literally.

See also the astEscapesastEscapes function. Integer (boolean). Plot All Plots have this attribute. Escape Sequences Escape sequences are introduced into the text string by a percent " %" character. Any unrecognised, illegal or incomplete escape sequences are printed literally. The following escape sequences are currently recognised (" ..." represents a string of one or more decimal digits):

%% - Print a literal " %" character.

%308#308...241#241 - Draw subsequent characters as super-scripts. The digits " ..." give the distance from the base-line of " normal" text to the base-line of the super-script text, scaled so that a value of " 100" corresponds to the height of " normal" text. %308#308 241#241 - Draw subsequent characters with the normal base-line.

%v...241#241 - Draw subsequent characters as sub-scripts. The digits " ..." give the distance from the base-line of " normal" text to the base-line of the sub-script text, scaled so that a value of " 100" corresponds to the height of " normal" text.

%v241#241 - Draw subsequent characters with the normal base-line (equivalent to %308#308 241#241).

%2#2...241#241 - Leave a gap before drawing subsequent characters. The digits " ..." give the size of the gap, scaled so that a value of " 100" corresponds to the height of " normal" text.

%1#1...241#241 - Move backwards before drawing subsequent characters. The digits " ..." give the size of the movement, scaled so that a value of " 100" corresponds to the height of " normal" text.

%s...241#241 - Change the Size attribute for subsequent characters. The digits " ..." give the new Size as a fraction of the " normal" Size, scaled so that a value of " 100" corresponds to 1.0;

%s241#241 - Reset the Size attribute to its " normal" value.

%w...241#241 - Change the Width attribute for subsequent characters. The digits " ..." give the new width as a fraction of the " normal" Width, scaled so that a value of " 100" corresponds to 1.0;

%w241#241 - Reset the Size attribute to its " normal" value.

%f...241#241 - Change the Font attribute for subsequent characters. The digits " ..." give the new Font value.

%f241#241 - Reset the Font attribute to its " normal" value.

%c...241#241 - Change the Colour attribute for subsequent characters. The digits " ..." give the new Colour value.

%c241#241 - Reset the Colour attribute to its " normal" value.

%t...241#241 - Change the Style attribute for subsequent characters. The digits " ..." give the new Style value.

%t241#241 - Reset the Style attribute to its " normal" value.

%h241#241 - Remember the current horizontal position (see " %g241#241" )

%g241#241 - Go to the horizontal position of the previous " %h241#241" (if any).

%- - Push the current graphics attribute values onto the top of the stack (see " %241#241" ).

%241#241 - Pop attributes values of the top the stack (see " %-" ). If the stack is empty, " normal" attribute values are restored. FillFactor Fraction of the Region which is of interest This attribute indicates the fraction of the RegionRegion which is of interest. AST does not use this attribute internally for any purpose. Typically, it could be used to indicate the fraction of the Region for which data is available.

The supplied value must be in the range 0.0 to 1.0, and the default value is 1.0 (except as noted below). Floating point. Region All Regions have this attribute. CmpRegionCmpRegion The default FillFactor for a CmpRegion is the FillFactor of its first component Region. PrismPrism The default FillFactor for a Prism is the product of the FillFactors of its two component Regions. StcStc The default FillFactor for an Stc is the FillFactor of its encapsulated Region. FitsAxisOrder Frame title This attribute specifies the order for the WCS axes in any new FITS-WCS headers created using the astWriteastWrite method.

The value of the FitsAxisOrder attribute can be either " 1#1auto2#2" (the default value), " 1#1copy2#2" or a space-separated list of axis symbols:

" 1#1auto2#2" : causes the WCS axis order to be chosen automatically so that the i' th WCS axis in the new FITS header is the WCS axis which is more nearly parallel to the i' th pixel axis.

" 1#1copy2#2" : causes the WCS axis order to be set so that the i' th WCS axis in the new FITS header is the i' th WCS axis in the current FrameFrame of the FrameSetFrameSet being written out to the header.

" Sym1 Sym2..." : the space-separated list is seached in turn for the Symbol attribute of each axis in the current Frame of the FrameSet. The order in which these Symbols occur within the space-separated list defines the order of the WCS axes in the new FITS header. An error is reported if Symbol for a current Frame axis is not present in the supplied list. However, no error is reported if the list contains extra words that do not correspond to the Symbol of any current Frame axis. String. FitsChanFitsChan All FitsChans have this attribute. FitsDigits Digits of precision for floating point FITS values This attribute gives the number of significant decimal digits to use when formatting floating point values for inclusion in the FITS header cards within a FitsChanFitsChan.

By default, a positive value is used which results in no loss of information, assuming that the value' s precision is double. Usually, this causes no problems.

However, to adhere strictly to the recommendations of the FITS standard, the width of the formatted value (including sign, decimal point and exponent) ought not to be more than 20 characters. If you are concerned about this, you should set FitsDigits to a negative value, such as -15. In this case, the absolute value (241#24115) indicates the maximum number of significant digits to use, but the actual number used may be fewer than this to ensure that the FITS recommendations are satisfied. When using this approach, the resulting number of significant digits may depend on the value being formatted and on the presence of any sign, decimal point or exponent.

The value of this attribute is effective when FITS header cards are output, either using astFindFitsastFindFits or by the action of the FitsChan' s sink function when it is finally deleted. Integer. FitsChan All FitsChans have this attribute. FitsRounding Controls rounding of floating-point FITS values This attribute controls how floating point values are rounded when formatted for inclusion in the FITS header cards within a FitsChanFitsChan.

The value is first formatted using the field width specified by attribute FitsDigitsFitsDigits. If this formatted value contains a sequence of 4 or more adjacent " 9" s or 4 or more adjacent " 0" s, the formatted value is truncated at the start of the sequence (rounding the final remaining digit up by one if the sequence contains " 9" s). However this truncation only occurs if the sequence extends beyond the digit specified by attribute FitsRounding. For instance, if FitsRounding is set to 10, then the rounding will only occur for sequences of 4 or more " 9" s or " 0" s that extend beyond the tenth significant figure in the formatted value.

The default value is 10. When setting a new value, negative values are converted to zero. Integer. FitsChan All FitsChans have this attribute. FitsTol Maximum non-linearity allowed when exporting to FITS-WCS This attribute is used when attempting to write a FrameSetFrameSet to a FitsChanFitsChan using a foreign encoding. It specifies the maximum departure from linearity allowed on any axis within the mapping from pixel coordinates to Intermediate World Coordinates. It is expressed in units of pixels. If an axis of the MappingMapping is found to deviate from linearity by more than this amount, the write operation fails. If the linearity test succeeds, a linear approximation to the mapping is used to determine the FITS keyword values to be placed in the FitsChan.

The default value is one tenth of a pixel. Floating point. FitsChan All FitsChans have this attribute. Font(element) Character font for a Plot element This attribute determines the character font index used when drawing each element of graphical output produced by a PlotPlot. It takes a separate value for each graphical element so that, for instance, the setting " Font(title)=2" causes the Plot title to be drawn using font number 2.

The range of integer font indices available and the appearance of the resulting text is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default font supplied by this graphics system. Integer. Plot All Plots have this attribute. For a list of the graphical elements available, see the description of the Plot class.

If no graphical element is specified, (e.g. " Font" instead of " Font(title)" ), then a " set" or " clear" operation will affect the attribute value of all graphical elements, while a " get" or " test" operation will use just the Font(TextLab) value. ForceTab Force the use of the -TAB algorithm when writing FITS-WCS headers? This attribute is a boolean value which indicates if the " -TAB" algorithm, defined in FITS-WCS paper III, should be used if at all possible when writing out a FrameSetFrameSet using the FITS-WCS encoding.

Note this attribute has no effect unless the TabOKTabOK attribute is set to a positive non-zero value. If, in addition to setting TabOK, ForceTab is set to non-zero value, astWriteastWrite will attempt to use the TAB algorithm even if another algorithm could have been used. If ForceTab is left at its default value of zero, then the -TAB algorithm will be used only if no other algorithm can be used. Integer (boolean). FitsChanFitsChan All FitsChans have this attribute. Format(axis) Format specification for axis values This attribute specifies the format to be used when displaying coordinate values associated with a particular FrameFrame axis (i.e. to convert values from binary to character form). It is interpreted by the astFormatastFormat function and determines the formatting which it applies.

If no 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), attribute and is chosen so that it displays the requested number of digits of precision. String. 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 (such as astSetastSet). You may need to double it (i.e. use " %%" ) to avoid this. SkyFrameSkyFrame The SkyFrame class re-defines the syntax and default value of the Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the " SkyFrame Formats" section. FrameSetFrameSet The Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the CurrentCurrent attribute). Note that the syntax of the Format string is also determined by the current Frame. TimeFrameTimeFrame The TimeFrame class extends the syntax of the Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format strings is described (below) in the " TimeFrame Formats" section. When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. SkyFrame Formats The 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:

" 241#241" : 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 PlotPlot 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 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. TimeFrame Formats The 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 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 TimeOriginTimeOrigin 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 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 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 string indicates the number of decimal places to use in the seconds field. For instance, a Format value of " iso.0" produces a time of day of the form " hh:mm:ss" , and a 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 attribute is ignored when using this " iso" format. Full Set level of output detail This attribute is a three-state flag and takes values of -1, 0 or 241#2411. It controls the amount of information included in the output generated by a ChannelChannel.

If Full is zero, then a modest amount of non-essential but useful information will be included in the output. If Full is negative, all non-essential information will be suppressed to minimise the amount of output, while if it is positive, the output will include the maximum amount of detailed information about the ObjectObject being written. Integer. Channel The default value is zero for a normal Channel. FitsChanFitsChan The default value is zero for a FitsChan. StcsChanStcsChan The default value is zero for an StcsChan. Set a positive value to cause default values to be included in STC-S descriptions. XmlChanXmlChan The default value is -1 for an XmlChan. YamlChanYamlChan This attribute is ignored by the YamlChan class. All positive values supplied for this attribute are converted to 241#2411 and all negative values are converted to -1. Gap(axis) Interval between linearly spaced major axis values of a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining the linear interval between the " major" axis values of a PlotPlot, at which (for example) major tick marks are drawn. It takes a separate value for each physical axis of the Plot so that, for instance, the setting " Gap(2)=3.0" specifies the difference between adjacent major values along the second axis. The Gap attribute is only used when the LogTicks attribute indicates that the spacing between major axis values is to be linear. If major axis values are logarithmically spaced then the gap is specified using attribute LogGap.

The Gap value supplied will usually be rounded to the nearest " nice" value, suitable (e.g.) for generating axis labels, before use. To avoid this " nicing" you should set an explicit format for the axis using the Format(axis)Format(axis) or Digits/Digits(axis)Digits/Digits(axis) attribute. The default behaviour is for the Plot to generate its own Gap value when required, based on the range of axis values to be represented. Floating point. Plot All Plots have this attribute. The Gap value should use the same units as are used internally for storing coordinate values on the corresponding axis. For example, with a celestial coordinate system, the Gap value should be in radians, not hours or degrees.

If no axis is specified, (e.g. " Gap" instead of " Gap(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the Gap(1) value. Grf Use Grf functions registered through astGrfSet? This attribute selects the functions which are used to draw graphics by the PlotPlot class. If it is zero, then the functions in the graphics interface selected at link-time are used (see the ast_linkast_link script). Otherwise, functions registered using astGrfSetastGrfSet are used. In this case, if a function is needed which has not been registered, then the function in the graphics interface selected at link-time is used.

The default is to use the graphics interface Integer (boolean). Plot All Plots have this attribute. Plot3DPlot3D The Plot3D class ignores this attributes, assuming a value of zero. The value of this attribute is not saved when the Plot is written out through a ChannelChannel to an external data store. On re-loading such a Plot using astReadastRead, the attribute will be cleared, resulting in the graphics interface selected at link-time being used. Grid Draw grid lines for a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether grid lines (a grid of curves marking the " major" values on each axis) are drawn across the plotting area.

If the Grid value of a PlotPlot is non-zero, then grid lines will be drawn. Otherwise, short tick marks on the axes are used to mark the major axis values. The default behaviour is to use tick marks if the entire plotting area is filled by valid physical coordinates, but to draw grid lines otherwise. Integer (boolean). Plot All Plots have this attribute. The spacing between major axis values, which determines the spacing of grid lines, may be set using the Gap(axis)Gap(axis) attribute. GrismAlpha The angle of incidence of the incoming light on the grating surface This attribute holds the angle between the incoming light and the normal to the grating surface, in radians. The default value is 0.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. GrismEps The angle between the normal and the dispersion plane This attribute holds the angle (in radians) between the normal to the grating or exit prism face, and the dispersion plane. The dispersion plane is the plane spanned by the incoming and outgoing ray. The default value is 0.0.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. GrismG The grating ruling density This attribute holds the number of grating rulings per unit length. The unit of length used should be consistent with the units used for attributes GrismWaveRGrismWaveR and GrismNRPGrismNRP. The default value is 0.0. (the appropriate value for a pure prism disperser with no grating).

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. GrismM The interference order This attribute holds the interference order being considered. The default value is 0.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Integer. GrismMap All GrismMaps have this attribute. GrismNR The refractive index at the reference wavelength This attribute holds refractive index of the grism material at the reference wavelength (given by attribute GrismWaveRGrismWaveR). The default value is 1.0.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. GrismNRP The rate of change of refractive index with wavelength This attribute holds the rate of change of the refractive index of the grism material with respect to wavelength at the reference wavelength (given by attribute GrismWaveRGrismWaveR). The default value is 0.0 (the appropriate value for a pure grating disperser with no prism). The units of this attribute should be consistent with those of attributes GrismWaveR and GrismGGrismG.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. GrismTheta Angle between normal to detector plane and reference ray This attribute gives the angle of incidence of light of the reference wavelength (given by attribute GrismWaveRGrismWaveR) onto the detector. Specifically, it holds the angle (in radians) between the normal to the detector plane and an incident ray at the reference wavelength. The default value is 0.0.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. GrismWaveR The reference wavelength This attribute holds reference wavelength. The default value is 5000 (Angstrom). The units of this attribute should be consistent with those of attributes GrismNRPGrismNRP and GrismGGrismG.

Note, the value of this attribute may changed only if the GrismMapGrismMap has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. GrismMap All GrismMaps have this attribute. ID Object identification string This attribute contains a string which may be used to identify the ObjectObject to which it is attached. There is no restriction on the contents of this string, which is not used internally by the AST library, and is simply returned without change when required. The default value is an empty string.

An identification string can be valuable when, for example, several Objects have been stored in a file (using astWriteastWrite) and are later retrieved (using astReadastRead). Consistent use of the ID attribute allows the retrieved Objects to be identified without depending simply on the order in which they were stored.

This attribute may also be useful during debugging, to distinguish similar Objects when using astShowastShow to display them. String. Object All Objects have this attribute. Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function. IF The intermediate frequency in a dual sideband spectrum This attribute specifies the (topocentric) intermediate frequency in a dual sideband spectrum. Its sole use is to determine the local oscillator (LO) frequency (the frequency which marks the boundary between the lower and upper sidebands). The LO frequency is equal to the sum of the centre frequency and the intermediate frequency. Here, the " centre frequency" is the topocentric frequency in Hz corresponding to the current value of the DSBCentreDSBCentre attribute. The value of the IF attribute may be positive or negative: a positive value results in the LO frequency being above the central frequency, whilst a negative IF value results in the LO frequency being below the central frequency. The sign of the IF attribute value determines the default value for the SideBandSideBand attribute.

When setting a new value for this attribute, the units in which the frequency value is supplied may be indicated by appending a suitable string to the end of the formatted value. If the units are not specified, then the supplied value is assumed to be in units of GHz. For instance, the following strings all result in an IF of 4 GHz being used: " 4.0" , " 4.0 GHz" , " 4.0E9 Hz" , etc.

When getting the value of this attribute, the returned value is always in units of GHz. The default value for this attribute is 4 GHz. Floating point. DSBSpecFrameDSBSpecFrame All DSBSpecFrames have this attribute. Ident Permanent Object identification string This attribute is like the IDID attribute, in that it contains a string which may be used to identify the ObjectObject to which it is attached. The only difference between ID and Ident is that Ident is transferred when an Object is copied, but ID is not. String. Object All Objects have this attribute. ImagFreq The image sideband equivalent of the rest frequency This is a read-only attribute giving the frequency which corresponds to the rest frequency but is in the opposite sideband.

The value is calculated by first transforming the rest frequency (given by the RestFreqRestFreq attribute) from the standard of rest of the source (given by the SourceVelSourceVel and SourceVRFSourceVRF attributes) to the standard of rest of the observer (i.e. the topocentric standard of rest). The resulting topocentric frequency is assumed to be in the same sideband as the value given for the DSBCentreDSBCentre attribute (the " observed" sideband), and is transformed to the other sideband (the " image" sideband). The new frequency is converted back to the standard of rest of the source, and the resulting value is returned as the attribute value, in units of GHz. Floating point, read-only. DSBSpecFrameDSBSpecFrame All DSBSpecFrames have this attribute. Indent Specifies the indentation to use in text produced by a Channel This attribute controls the indentation within the output text produced by the astWriteastWrite function. It gives the increase in the indentation for each level in the object heirarchy. If it is set to zero, no indentation will be used. [3] Integer (boolean). ChannelChannel The default value is zero for a basic Channel. FitsChanFitsChan The FitsChan class ignores this attribute. StcsChanStcsChan The default value for an StcsChan is zero, which causes the entire STC-S description is written out by a single invocation of the sink function. The text supplied to the sink function will not contain any linefeed characters, and each pair of adjacent words will be separated by a single space. The text may thus be arbitrarily large and the StcsLengthStcsLength attribute is ignored.

If Indent is non-zero, then the text is written out via multiple calls to the sink function, each call corresponding to a single " line" of text (although no line feed characters will be inserted by AST). The complete STC-S description is broken into lines so that:

the line length specified by attribute StcsLength is not exceeded

each sub-phrase (time, space, etc.) starts on a new line

each argument in a compound spatial region starts on a new line

If this causes a sub-phrase to extend to two or more lines, then the second and subsequent lines will be indented by three spaces compared to the first line. In addition, lines within a compound spatial region will have extra indentation to highlight the nesting produced by the parentheses. Each new level of nesting will be indented by a further three spaces. XmlChanXmlChan The default value for an XmlChan is zero, which results in no linefeeds or indentation strings being added to output text. If any non-zero value is assigned to Indent, then extra linefeed and space characters will be inserted as necessary to ensure that each XML tag starts on a new line, and each tag will be indented by a further 3 spaces to show its depth in the containment hierarchy. YamlChanYamlChan The default value for a YamlChan is two. Only non-zero values in the range 1-10 are allowed. InternalUnit(axis) Physical units for unformated axis values 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 FrameFrame, typically handled internally within application code. In most cases, the value of the 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 SkyFrameSkyFrame class, which represents unformatted axis values in radians, regardless of the current setting of the Unit attribute. String, read-only. Frame All Frames have this attribute. When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. IntraFlag IntraMap identification string This attribute allows an IntraMapIntraMap to be flagged so that it is distinguishable from other IntraMaps. The transformation function associated with the IntraMap may then enquire the value of this attribute and adapt the transformation it provides according to the particular IntraMap involved.

Although this is a string attribute, it may often be useful to store numerical values here, encoded as a character string, and to use these as data within the transformation function. Note, however, that this mechanism is not suitable for transferring large amounts of data (more than about 1000 characters) to an IntraMap. For that purpose, global variables are recommended, although the IntraFlag value can be used to supplement this approach. The default IntraFlag value is an empty string. String. IntraMap All IntraMaps have this attribute. A pair of IntraMaps whose transformations may potentially cancel cannot be simplified to produce a UnitMapUnitMap (e.g. using astSimplifyastSimplify) unless they have the same IntraFlag values. The test for equality is case-sensitive. Invert Mapping inversion flag This attribute controls which one of a MappingMapping' s two possible coordinate transformations is considered the " forward" transformation (the other being the " inverse" transformation). If the attribute value is zero (the default), the Mapping' s behaviour will be the same as when it was first created. However, if it is non-zero, its two transformations will be inter-changed, so that the Mapping displays the inverse of its original behaviour.

Inverting the boolean sense of the Invert attribute will cause the values of a Mapping' s NinNin and NoutNout attributes to be interchanged. The values of its TranForwardTranForward and TranInverseTranInverse attributes will also be interchanged. This operation may be performed with the astInvertastInvert function. Integer (boolean). Mapping All Mappings have this attribute. UnitMapUnitMap The value of the Invert attribute has no effect on the behaviour of a UnitMap. FrameSetFrameSet Inverting the boolean sense of the Invert attribute for a FrameSet will cause its base and current Frames (and its BaseBase and CurrentCurrent attributes) to be interchanged. This, in turn, may affect other properties and attributes of the FrameSet (such as Nin, Nout, NaxesNaxes, TranForward, TranInverse, etc.). The Invert attribute of a FrameSet is not itself affected by selecting a new base or current FrameFrame. Invisible Draw graphics using invisible ink? This attribute controls the appearance of all graphics produced by PlotPlot methods by determining whether graphics should be visible or invisible.

If the Invisible value of a Plot is non-zero, then all the Plot methods which normally generate graphical output do not do so (you can think of them drawing with " invisible ink" ). Such methods do, however, continue to do all the calculations which would be needed to produce the graphics. In particular, the bounding box enclosing the graphics is still calculated and can be retrieved as normal using astBoundingBoxastBoundingBox. The default value is zero, resulting in all methods drawing graphics as normal, using visible ink. Integer (boolean). Plot All Plots have this attribute. IsLatAxis(axis) Is the specified celestial axis a latitude axis? This is a read-only boolean attribute that indicates the nature of the specified axis. The attribute has a non-zero value if the specified axis is a celestial latitude axis (Declination, Galactic latitude, etc), and is zero otherwise. Integer (boolean), read-only. SkyFrameSkyFrame All SkyFrames have this attribute. When specifying this attribute by name, it should be subscripted with the number of the SkyFrame axis to be tested. IsLinear Is the Mapping linear? This attribute indicates whether a MappingMapping is an instance of a class that always represents a linear transformation. Note, some Mapping classes can represent linear or non-linear transformations (the MathMapMathMap class for instance). Such classes have a zero value for the IsLinear attribute. Specific instances of such classes can be tested for linearity using the astLinearApproxastLinearApprox function. AST_LINEARAPPROX routine. Integer (boolean), read-only. Mapping All Mappings have this attribute. CmpMapCmpMap The IsLinear value for a CmpMap is determined by the classes of the encapsulated Mappings. For instance, a CmpMap that combines a ZoomMapZoomMap and a ShiftMapShiftMap will have a non-zero value for its IsLinear attribute, but a CmpMap that contains a MathMap will have a value of zero for its IsLinear attribute. FrameFrame The IsLinear value for a Frame is 1 (since a Frame is equivalent to a UnitMapUnitMap). FrameSetFrameSet The IsLinear value for a FrameSet is obtained from the Mapping from the base Frame to the current Frame. IsLonAxis(axis) Is the specified celestial axis a longitude axis? This is a read-only boolean attribute that indicates the nature of the specified axis. The attribute has a non-zero value if the specified axis is a celestial longitude axis (Right Ascension, Galactic longitude, etc), and is zero otherwise. Integer (boolean), read-only. SkyFrameSkyFrame All SkyFrames have this attribute. When specifying this attribute by name, it should be subscripted with the number of the SkyFrame axis to be tested. IsSimple Has the Mapping been simplified? This attribute indicates whether a MappingMapping has been simplified by the astSimplifyastSimplify method. If the IsSimple value is non-zero, then the Mapping has been simplified and so there is nothing to be gained by simplifying it again. Indeed, the astSimplify method will immediately return the Mapping unchanged if the IsSimple attribute indicates that the Mapping has already been simplified. Integer (boolean), read-only. Mapping All Mappings have this attribute. FrameFrame All classes of Frame return zero for the IsSimple attribute. This is because changes can be made to a Frame which affect the Mapping represented by the Frame, and so there can be no guarantee that the Mapping may not need re-simplifying. Most non-Frame Mappings, on the other hand, are immutable and so when they are simplified it is certain that they weill remain in a simple state. IterInverse Provide an iterative inverse transformation? This attribute indicates whether the original inverse transformation of the PolyMapPolyMap should be implemented via an iterative Newton-Raphson approximation that uses the forward transformation to transform candidate input positions until an output position is found which is close to the required output position. By default, an iterative inverse is provided if, and only if, no inverse polynomial was supplied when the PolyMap was constructed.

Note, the term " inverse transformation" here refers to the inverse transformation of the original PolyMap, ignoring any subsequent inversions. Also, " input" and " output" refer to the inputs and outputs of the original PolyMap.

The NiterInverseNiterInverse and TolInverseTolInverse attributes provide parameters that control the behaviour of the inverse approximation method.

The iterative inverse returns AST__BAD axis values at positions for which the inverse transformation is undefined. For instance, if the forward transformation is y = x34#34x, the iterative inverse will return x = AST__BAD at y = -1. If the inverse transformation is multiply defined, the position returned by the iterative inverse will be the position of the solution that is closest to the supplied position. For instance, using the above example, y = x34#34x, the iterative inverse will return x = 241#2412 at y = 4, because x = 241#2412 is the closest solution to 4 (the other solution is x = -2). Integer (boolean). PolyMap All PolyMaps have this attribute. ChebyMapChebyMap The ChebyMap class does not currently provide an option for an iterative inverse, and so the IterInverse value is always zero. Setting or clearing the IterInverse attribute of a ChebyMap has no effect. The transformation replaced by the iterative algorithm is the transformation from the original PolyMap output space to the original PolyMap input space (i.e. the input and output spaces as defined by the arguments of the PolyMap constructor). This is still the case even if the PolyMap has subsequently been inverted. In other words if a PolyMap is created and then inverted, setting the IterInverse to a non-zero value will replace the forward transformation of the inverted PolyMap (i.e. the inverse transformation of the original PolyMap). It is not possible to replace the other transformation (i.e. from the original PolyMap input space to the original PolyMap output space) with an iterative algorithm.

If a PolyMap that has an iterative inverse transformation is subsequently inverted, the inverted PolyMap will have an iterative forward transformation.

An iterative inverse can only be used if the PolyMap has equal numbers of inputs and outputs, as given by the NinNin and NoutNout attributes. An error will be reported if IterInverse is set non-zero for a PolyMap that does not meet this requirement. Iwc Include a Frame representing FITS-WCS intermediate world coordinates? This attribute is a boolean value which is used when a FrameSetFrameSet is read from a FitsChanFitsChan with a foreign FITS encoding (e.g. FITS-WCS) using astReadastRead. If it has a non-zero value then the returned FrameSet will include Frames representing " intermediate world coordinates" (IWC). These Frames will have DomainDomain name " IWC" for primary axis descriptions, and " IWCa" for secondary axis descriptions, where " a" is replaced by the single alternate axis description character, as used in the FITS-WCS header. The default value for " Iwc" is zero.

FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one axis for each WCS axis, and is the coordinate system produced by the rotation matrix (represented by FITS keyword PCi_j, CDi_j, etc). For instance, for a 2-D FITS-WCS header describing projected celestial longitude and latitude, the intermediate world coordinates represent offsets in degrees from the reference point within the plane of projection. Integer (boolean). FitsChan All FitsChans have this attribute. KeyCase Are keys case sensitive? This attribute is a boolean value which controls how keys are used. If KeyCase is zero, then key strings supplied to any method are automatically converted to upper case before being used. If KeyCase is non-zero (the default), then supplied key strings are used without modification.

The value of this attribute can only be changed if the KeyMapKeyMap is empty. Its value can be set conveniently when creating the KeyMap. An error will be reported if an attempt is made to change the attribute value when the KeyMap contains any entries. Integer (boolean). KeyMap All KeyMaps have this attribute. TableTable The Table class over-rides this attribute by forcing it to zero. That is, keys within a Table are always case insensitive. KeyError Report an error when getting the value of a non-existant KeyMap entry? This attribute is a boolean value which controls how the astMapGet... functions behave if the requested key is not found in the KeyMapKeyMap. If KeyError is zero (the default), then these functions will return zero but no error will be reported. If KeyError is non-zero, then the same values are returned but an error is also reported. Integer (boolean). KeyMap All KeyMaps have this attribute. When setting a new value for KeyError, the supplied value is propagated to any KeyMaps contained within the supplied KeyMap.

When clearing the KeyError attribute, the attribute is also cleared in any KeyMaps contained within the supplied KeyMap. LTOffset The offset from UTC to Local Time, in hours This specifies the offset from UTC to Local Time, in hours (fractional hours can be supplied). It is positive for time zones east of Greenwich. AST uses the figure as given, without making any attempt to correct for daylight saving. The default value is zero. Floating point. TimeFrameTimeFrame All TimeFrames have this attribute. Label(axis) Axis label This attribute specifies a label to be attached to each axis of a FrameFrame when it is represented (e.g.) in graphical output.

If a Label value has not been set for a Frame axis, then a suitable default is supplied. String. Frame The default supplied by the Frame class is the string " AxisAxis 1#1n2#2" , where 1#1n2#2 is 1, 2, etc. for each successive axis. SkyFrameSkyFrame The SkyFrame class re-defines the default Label value (e.g. to " Right ascension" or " Galactic latitude" ) as appropriate for the particular celestial coordinate system being represented. TimeFrameTimeFrame The TimeFrame class re-defines the default Label value as appropriate for the particular time system being represented. FrameSetFrameSet The Label attribute of a FrameSet axis is the same as that of its current Frame (as specified by the CurrentCurrent attribute). Axis labels are intended purely for interpretation by human readers and not by software.

When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. LabelAt(axis) Where to place numerical labels for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining where numerical axis labels and associated tick marks are placed. It takes a separate value for each physical axis of a PlotPlot so that, for instance, the setting " LabelAt(2)=10.0" specifies where the numerical labels and tick marks for the second axis should be drawn.

For each axis, the LabelAt value gives the value on the other axis at which numerical labels and tick marks should be placed (remember that Plots suitable for use with astGrid may only have two axes). For example, in a celestial (RA,Dec) coordinate system, LabelAt(1) gives a Dec value which defines a line (of constant Dec) along which the numerical RA labels and their associated tick marks will be drawn. Similarly, LabelAt(2) gives the RA value at which the Dec labels and ticks will be drawn.

The default bahaviour is for the Plot to generate its own position for numerical labels and tick marks. Floating point. Plot All Plots have this attribute. The LabelAt value should use the same units as are used internally for storing coordinate values on the appropriate axis. For example, with a celestial coordinate system, the LabelAt value should be in radians, not hours or degrees.

Normally, the LabelAt value also determines where the lines representing coordinate axes will be drawn, so that the tick marks will lie on these lines (but also see the DrawAxes attribute).

In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the LabellingLabelling attribute). In this case, the value of the LabelAt attribute is ignored. LabelUnits(axis) Use axis unit descriptions in a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether the descriptive labels drawn for each axis of a PlotPlot should include a description of the units being used on the axis. It takes a separate value for each physical axis of a Plot so that, for instance, the setting " LabelUnits(2)=1" specifies that a unit description should be included in the label for the second axis.

If the LabelUnits value of a Plot axis is non-zero, a unit description will be included in the descriptive label for that axis, otherwise it will be omitted. The default behaviour is to include a unit description unless the current FrameFrame of the Plot is a SkyFrameSkyFrame representing equatorial, ecliptic, galactic or supergalactic coordinates, in which case it is omitted. Integer (boolean). Plot All Plots have this attribute. The text used for the unit description is obtained from the Plot' s Unit(axis)Unit(axis) attribute.

If no axis is specified, (e.g. " LabelUnits" instead of " LabelUnits(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the LabelUnits(1) value.

If the current Frame of the Plot is not a SkyFrame, but includes axes which were extracted from a SkyFrame, then the default behaviour is to include a unit description only for those axes which were not extracted from a SkyFrame. LabelUp(axis) Draw numerical Plot labels upright? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether the numerical labels for each axis of a PlotPlot should be drawn upright or not. It takes a separate value for each physical axis of a Plot so that, for instance, the setting " LabelUp(2)=1" specifies that numerical labels for the second axis should be drawn upright.

If the LabelUp value of a Plot axis is non-zero, it causes numerical labels for that axis to be plotted upright (i.e. as normal, horizontal text), otherwise labels are drawn parallel to the axis to which they apply.

The default is to produce upright labels if the labels are placed around the edge of the plot, and to produce labels that follow the axes if the labels are placed within the interior of the plot (see attribute LabellingLabelling). Integer (boolean). Plot All Plots have this attribute. In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the Labelling attribute). In this case, the value of the LabelUp attribute is ignored.

If no axis is specified, (e.g. " LabelUp" instead of " LabelUp(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the LabelUp(1) value. Labelling Label and tick placement option for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining the strategy for placing numerical labels and tick marks for a PlotPlot.

If the Labelling value of a Plot is " exterior" (the default), then numerical labels and their associated tick marks are placed around the edges of the plotting area, if possible. If this is not possible, or if the Labelling value is " interior" , then they are placed along grid lines inside the plotting area. String. Plot All Plots have this attribute. The LabelAt(axis)LabelAt(axis) attribute may be used to determine the exact placement of labels and tick marks that are drawn inside the plotting area. LatAxis Index of the latitude axis This read-only attribute gives the index (1 or 2) of the latitude axis within the SkyFrameSkyFrame (taking into account any current axis permutations). Integer. SkyFrame All SkyFrames have this attribute. ListSize Number of points in a PointList This is a read-only attribute giving the number of points in a PointListPointList. This value is determined when the PointList is created. Integer, read-only. PointList All PointLists have this attribute. LogGap(axis) Interval between major axis values of a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining the logarithmic interval between the " major" axis values of a PlotPlot, at which (for example) major tick marks are drawn. It takes a separate value for each physical axis of the Plot so that, for instance, the setting " LogGap(2)=100.0" specifies the ratio between adjacent major values along the second axis. The LogGap attribute is only used when the LogTicks attribute indicates that the spacing between major axis values is to be logarithmic. If major axis values are linearly spaced then the gap is specified using attribute Gap.

The LogGap value supplied will be rounded to the nearest power of 10. The reciprocal of the supplied value may be used if this is necessary to produce usable major axis values. If a zero or negative value is supplied, an error will be reported when the grid is drawn. The default behaviour is for the Plot to generate its own LogGap value when required, based on the range of axis values to be represented. Floating point. Plot All Plots have this attribute. The LogGap value is a ratio between axis values and is therefore dimensionless.

If no axis is specified, (e.g. " LogGap" instead of " LogGap(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the LogGap(1) value. LogLabel(axis) Use exponential format for numerical axis labels? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether the numerical axis labels should be in normal decimal form or should be represented as 10 raised to the appropriate power. That is, an axis value of 1000.0 will be drawn as " 1000.0" if LogLabel is zero, but as " 10308#3083" if LogLabel is non-zero. If graphical escape sequences are supported (see attribute EscapeEscape), the power in such exponential labels will be drawn as a small superscript instead of using a " 308#308" character to represent exponentiation.

The default is to produce exponential labels if the major tick marks are logarithmically spaced (see the LogTicks attribute). Integer (boolean). PlotPlot All Plots have this attribute. If no axis is specified, (e.g. " LogLabel" instead of " LogLabel(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the LogLabel(1) value. LogPlot(axis) Map the plot logarithmically onto the screen? This attribute controls the appearance of all graphics produced by the PlotPlot, by determining whether the axes of the plotting surface are mapped logarithmically or linearly onto the base FrameFrame of the FrameSetFrameSet supplied when the Plot was constructed. It takes a separate value for each axis of the graphics coordinate system (i.e. the base Frame in the Plot) so that, for instance, the setting " LogPlot(2)=1" specifies that the second axis of the graphics coordinate system (usually the vertical axis) should be mapped logarithmically onto the second axis of the base Frame of the FrameSet supplied when the Plot was constructed.

If the LogPlot value of a Plot axis is non-zero, it causes that axis to be mapped logarithmically, otherwise (the default) the axis is mapped linearly. Integer (boolean). Plot All Plots have this attribute. The setting of the LogPlot attribute provides the default value for the related LogTicks attribute. By selecting suitable values for LogPlot and LogTicks, it is possible to have tick marks which are evenly spaced in value but which are mapped logarithmically onto the screen (and vice-versa).

An axis may only be mapped logarithmically if the visible part of the axis does not include the value zero. The visible part of the axis is that part which is mapped onto the plotting area, and is measured within the base Frame of the FrameSet which was supplied when the Plot was constructed. Any attempt to set LogPlot to a non-zero value will be ignored (without error) if the visible part of the axis includes the value zero

If no axis is specified, (e.g. " LogPlot" instead of " LogPlot(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the LogPlot(1) value. LogTicks(axis) Space the major tick marks logarithmically? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether the major tick marks should be spaced logarithmically or linearly in axis value. It takes a separate value for each physical axis of the PlotPlot so that, for instance, the setting " LogTicks(2)=1" specifies that the major tick marks on the second axis should be spaced logarithmically.

If the LogTicks value for a physical axis is non-zero, the major tick marks on that axis will be spaced logarithmically (that is, there will be a constant ratio between the axis values at adjacent major tick marks). An error will be reported if the dynamic range of the axis (the ratio of the largest to smallest displayed axis value) is less than 10.0. If the LogTicks value is zero, the major tick marks will be evenly spaced (that is, there will be a constant difference between the axis values at adjacent major tick marks). The default is to produce logarithmically spaced tick marks if the corresponding LogPlot attribute is non-zero and the ratio of maximum axis value to minimum axis value is 100 or more. If either of these conditions is not met, the default is to produce linearly spaced tick marks. Integer (boolean). Plot All Plots have this attribute. The setting of the LogTicks attribute does not affect the mapping of the plot onto the screen, which is controlled by attribute LogPlot. By selecting suitable values for LogPlot and LogTicks, it is possible to have tick marks which are evenly spaced in value but which are mapped logarithmically onto the screen (and vica-versa).

An error will be reported when drawing an annotated axis grid if the visible part of the physical axis includes the value zero.

If no axis is specified, (e.g. " LogTicks" instead of " LogTicks(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the LogTicks(1) value. LonAxis Index of the longitude axis This read-only attribute gives the index (1 or 2) of the longitude axis within the SkyFrameSkyFrame (taking into account any current axis permutations). Integer. SkyFrame All SkyFrames have this attribute. LutEpsilon The relative error of the values held in the took-up table This attribute holds the relative error of the values held in the took-up table. It is used when simplifying a LutMapLutMap, to determine if the LutMap should be considered linear. Setting a larger value makes it more likely that a LutMap will be replaced by a WinMapWinMap (i.e. a linear MappingMapping) when simplified.

The default value is the value of the system constant DBL_EPSILON (typically around 1e-16 or 2E-16). If the values in the look-up table were derived from single precision data, it may be appropriate to set this attribute to a value around 1E-7.

Note, the value of this attribute may changed only if the LutMap has no more than one reference. That is, an error is reported if the LutMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. LutMap All LutMaps have this attribute. LutInterp Look-up table interpolation method This attribute indicates the method to be used when finding the output value of a LutMapLutMap for an input value part way between two table entries. If it is set to 0 (the default) then linear interpolation is used. Otherwise, nearest neighbour interpolation is used.

Using nearest neighbour interpolation causes AST__BAD to be returned for any point which falls outside the bounds of the table. Linear interpolation results in an extrapolated value being returned based on the two end entries in the table.

Note, the value of this attribute may changed only if the LutMap has no more than one reference. That is, an error is reported if the LutMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Integer. LutMap All LutMaps have this attribute. MajTickLen(axis) Length of major tick marks for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining the length of the major tick marks drawn on the axes of a PlotPlot. It takes a separate value for each physical axis of the Plot so that, for instance, the setting " MajTickLen(2)=0" specifies the length of the major tick marks drawn on the second axis.

The MajTickLen value should be given as a fraction of the minimum dimension of the plotting area. Negative values cause major tick marks to be placed on the outside of the corresponding grid line or axis (but subject to any clipping imposed by the underlying graphics system), while positive values cause them to be placed on the inside.

The default behaviour depends on whether a coordinate grid is drawn inside the plotting area (see the GridGrid attribute). If so, the default MajTickLen value is zero (so that major ticks are not drawn), otherwise the default is 241#2410.015. Floating point. Plot All Plots have this attribute. If no axis is specified, (e.g. " MajTickLen" instead of " MajTickLen(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the MajTickLen(1) value. MapLocked Prevent new entries being added to a KeyMap? If this boolean attribute is set to a non-zero value, an error will be reported if an attempt is made to add a new entry to the KeyMapKeyMap. Note, the value associated with any existing entries can still be changed, but no new entries can be stored in the KeyMap. The default value (zero) allows new entries to be added to the KeyMap. Integer (boolean). KeyMap All KeyMaps have this attribute. When setting a new value for MapLocked, the supplied value is propagated to any KeyMaps contained within the supplied KeyMap.

When clearing the MapLocked attribute, the attribute is also cleared in any KeyMaps contained within the supplied KeyMap. MatchEnd Match trailing axes? This attribute is a boolean value which controls how a FrameFrame behaves when it is used (by astFindFrameastFindFrame) 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 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 non-zero, the final axes in each Frame will be matched and any un-matched leading axes will be disregarded instead. Integer (boolean). Frame The default MatchEnd value for a Frame is zero, so that trailing axes are disregarded. FrameSetFrameSet The MatchEnd attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). MaxAxes Maximum number of Frame axes to match This attribute controls how a FrameFrame behaves when it is used (by astFindFrameastFindFrame) as a template to match another (target) Frame. It specifies the maximum 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. Integer. Frame The default MaxAxes value for a Frame is equal to the number of Frame axes (NaxesNaxes attribute). CmpFrameCmpFrame 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 MinAxesMinAxes 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. FrameSetFrameSet The MaxAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). When setting a MaxAxes value, the value of the MinAxes attribute may also be silently changed so that it remains consistent with (i.e. does not exceed) the new value. The default MaxAxes value may also be reduced to remain consistent with the MinAxes value.

If a template Frame is used to match a target with a different number of axes, the MatchEndMatchEnd attribute of the template is used to determine how the individual axes of each Frame should match. MaxOrder The highest HEALPix order used in the MOC This attribute gives the best resolution of the MOC expressed as a HEALPix order in the range zero to 27 (this class does not support orders greater than 27). It' s value can only be set once (for instance as an option when the MocMoc constructor is invoked). An error will be reported if a subsequent attempt to set or clear the attribute is made. If no value is supplied for MaxOrder before the first area of sky is added to the empty Moc, then a default value will be selected and set, depending on the method used to add the first area to the Moc:

astAddCellastAddCell: the order of the specified cell.

astAddRegionastAddRegion: if the added RegionRegion is a Moc, then the Moc' s MaxOrder value is used, Otherwise the value used corresponds to the resolution closest to 0.1% of the linear size of the Region being added (determined using method astGetRegionDiscastGetRegionDisc).

astAddPixelMask1#1X2#2astAddPixelMask1#1X2#2: the smallest order that results in the cells in the Moc being no larger than the size of the pixels in the centre of the pixel mask.

astAddMocDataastAddMocData: the largest order present in the supplied normalised MOC data array.

astAddMocStringastAddMocString: the largest order present in the supplied MOC.

A default value of -1 will be returned for the MaxOrder attribute prior to its value being set.

The MaxResMaxRes attribute is equivalent to MaxOrder but expresses the resolution as a number of arc-seconds rather than as a HEALPix order.

Increasing the HEALPix order by one roughly halves the resolution of the Moc. For instance, a value of 18 corresponds to a resolution of about 0.8 arc-second, and 19 corresponds to about 0.4 arc-seconds. Integer. Moc All Mocs have this attribute. MaxRes The best resolution of the MOC This attribute is an alternative to the MaxOrderMaxOrder attribute and gives the best resolution of the MOC expressed as a number of arc-seconds. It can be set only when the MocMoc is constructed - an error is reported if any subsequent attempt is made to set or clear the value of MaxRes. See attribute MaxOrder for more details.

A default value of zero will be returned for the MaxRes attribute prior to its value (or the value of MaxOrder) being set. Floating point, read-only. Moc All Mocs have this attribute. MeshSize Number of points used to represent the boundary of a Region This attribute controls how many points are used when creating a mesh of points covering the boundary or volume of a RegionRegion. Such a mesh is returned by the astGetRegionMeshastGetRegionMesh method. The boundary mesh is also used when testing for overlap between two Regions: each point in the bomdary mesh of the first Region is checked to see if it is inside or outside the second Region. Thus, the reliability of the overlap check depends on the value assigned to this attribute. If the value used is very low, it is possible for overlaps to go unnoticed. High values produce more reliable results, but can result in the overlap test being very slow. The default value is 200 for two dimensional Regions and 2000 for three or more dimensional Regions (this attribute is not used for 1-dimensional regions since the boundary of a simple 1-d Region can only ever have two points). A value of five is used if the supplied value is less than five. Integer. Region All Regions have this attribute. CmpRegionCmpRegion The default MeshSize for a CmpRegion is the MeshSize of its first component Region. MocMoc The MeshSize attribute is ignored when forming a mesh covering the boundary of a Moc. Instead, the mesh will include a point for the exterior corners of every HEALPix cell (at the order specified by attribute MaxOrderMaxOrder) that touches the boundary. Note, this applies only to meshes covering the boundary of the Moc - the MeshSize attribute is used as normal when forming a mesh covering the area of the Moc. StcStc The default MeshSize for an Stc is the MeshSize of its encapsulated Region. MinAxes Minimum number of Frame axes to match This attribute controls how a FrameFrame behaves when it is used (by astFindFrameastFindFrame) as a template to match another (target) Frame. It 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. Integer. Frame The default MinAxes value for a Frame is equal to the number of Frame axes (NaxesNaxes attribute). CmpFrameCmpFrame The MinAxes attribute of a CmpFrame defaults to zero. Combined with the MaxAxesMaxAxes 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. FrameSetFrameSet The MinAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). When setting a MinAxes value, the value of the MaxAxes attribute may also be silently changed so that it remains consistent with (i.e. is not less than) the new value. The default MinAxes value may also be reduced to remain consistent with the MaxAxes value.

If a template Frame is used to match a target with a different number of axes, the MatchEndMatchEnd attribute of the template is used to determine how the individual axes of each Frame should match. MinOrder The lowest HEALPix order used in the MOC This attribute controls the size of the largest hole or island that could be missed when adding Regions or pixel masks into a MocMoc using methods astAddRegionastAddRegion or astAddPixelMask. It gives the resolution of the initial grid used to identify areas that are inside or outside the RegionRegion or pixel mask, expressed as a HEALPix order in the range zero to 27 (this class does not support orders greater than 27). Unselected areas (i.e. bounded " holes" or or " islands" in the selection) that are smaller than one cell of this initial grid may be missed (i.e. such holes may be " filled in" and islands omitted in the resulting Moc).

The default value is (MaxOrderMaxOrder-4), with a lower limit of zero. For instance, if MaxOrder is 16 (a resolution of 3.2 arc-seconds), then MinOrder will be 12, meaning that bounded holes within selected areas may be filled in if the hole is smaller than 51 arc-seconds. Increase the value of this attribute to ensures that only holes smaller than this value can be missed. Note, doing so will increase the time spent creating the Moc.

To ensure no pixels are missed, set MinOrder to some very large value (larger than 27). If MinOrder is set greater than MaxOrder, the value of MaxOrder will be used whenever MinOrder is required.

The MinResMinRes attribute is equivalent to MinOrder but expresses the resolution as a number of arc-seconds rather than as a HEALPix order. Any change made to MinOrder will cause a corresponding change in the MinRes attribute. Integer. Moc All Mocs have this attribute. MinRes The worst resolution of the MOC This attribute gives the poorest resolution of the MOC expressed as a number of arc-seconds. When a new value is set for MinRes, the MinOrderMinOrder attribute will be set to the order that gives a resolution closest to the requested resolution. When the current value of MinRes is requested, the resolution corresponding to the current value of MinOrder will be returned. When MinRes is tested or cleared, the MinOrder attribute will be tested or cleared. Floating point. MocMoc All Mocs have this attribute. MinTick(axis) Density of minor tick marks for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining the density of minor tick marks which appear between the major axis values of a PlotPlot. It takes a separate value for each physical axis of a Plot so that, for instance, the setting " MinTick(2)=2" specifies the density of minor tick marks along the second axis.

The value supplied should be the number of minor divisions required between each pair of major axis values, this being one more than the number of minor tick marks to be drawn. By default, a value is chosen that depends on the gap between major axis values and the nature of the axis. Integer. Plot All Plots have this attribute. If no axis is specified, (e.g. " MinTick" instead of " MinTick(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the MinTick(1) value. MinTickLen(axis) Length of minor tick marks for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining the length of the minor tick marks drawn on the axes of a PlotPlot. It takes a separate value for each physical axis of the Plot so that, for instance, the setting " MinTickLen(2)=0" specifies the length of the minor tick marks drawn on the second axis.

The MinTickLen value should be given as a fraction of the minimum dimension of the plotting area. Negative values cause minor tick marks to be placed on the outside of the corresponding grid line or axis (but subject to any clipping imposed by the underlying graphics system), while positive values cause them to be placed on the inside.

The default value is 241#2410.007. Floating point. Plot All Plots have this attribute. The number of minor tick marks drawn is determined by the Plot' s MinTick(axis)MinTick(axis) attribute.

If no axis is specified, (e.g. " MinTickLen" instead of " MinTickLen(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the MinTickLen(1) value. MocArea The area covered by the Moc, in square arc-minutes This read-only attribute gives the area covered by the MocMoc, in square arc-minutes. Floating point, read-only. Moc All Mocs have this attribute. MocFormat Format for encoding Mocs as text This attribute specifies the format to use when AST MocMoc Objects are converted to text by a MocChanMocChan. There are currently two ways (conventions) by which MOCs may be represented in the form of text and the MocFormat attribute is used to specify which of these should be used:

" JSON" : Encodes a Moc ObjectObject as a JSON string using the JSON serialisation described in the MOC recommendation (version 1.1).

" STRING" : Encodes a Moc Object as using the string serialisation described in the MOC recommendation (version 1.1).

The value assigned to the MocFormat does not affect the behaviour of the astReadastRead method, which automatically identifies the format used by the external text and sets the MocFormat attribute to the corresponding value.

The astWriteastWrite method will create the external text using the format specified by the current value of the MocFormat attribute.

The initial default value of the attribute is " UNKNOWN" . String. MocChan All MocChans have this attribute. MocLength The table length used to describe a Moc in FITS This read-only attribute gives the length of the number of rows needed to describe the MocMoc in a FITS binary table. This is the number of cells in the normalised Moc. Integer, read-only. Moc All Mocs have this attribute. MocLineLen Controls output buffer length This attribute specifies the maximum length to use when writing out text through the sink function supplied when the MocChanMocChan was created.

The number of characters in each string written out through the sink function will not be greater than the value of this attribute (but may be less). The default value is 80. Integer. MocChan All MocChans have this attribute. MocType The data type used to describe a Moc in FITS This read-only attribute gives the data type to be used when writing out the MocMoc to a FITS binary table. The attribute takes the value 4 or 8. The binary table should contain a single column of signed integer values in which each integer has 4 or 8 bytes, as indicated by the value of this attribute. Integer, read-only. Moc All Mocs have this attribute. NatLat Native latitude of the reference point of a FITS-WCS projection This attribute gives the latitude of the reference point of the FITS-WCS projection implemented by a WcsMapWcsMap. The value is in radians in the " native spherical" coordinate system. This value is fixed for most projections, for instance it is PI/2 (90 degrees) for all zenithal projections. For some projections (e.g. the conics) the value is not fixed, but is specified by parameter one on the latitude axis.

FITS-WCS paper II introduces the concept of a " fiducial point" which is logical distinct from the projection reference point. It is easy to confuse the use of these two points. The fiducial point is the point which has celestial coordinates given by the CRVAL FITS keywords. The native spherical coordinates for this point default to the values of the NatLat and NatLonNatLon, but these defaults mey be over-ridden by values stored in the PVi_j keywords. Put another way, the CRVAL keywords will by default give the celestial coordinates of the projection reference point, but may refer to some other point if alternative native longitude and latitude values are provided through the PVi_j keywords.

The NatLat attribute is read-only. Floating point, read-only. WcsMap All WcsMaps have this attribute. A default value of AST__BAD is used if no latitude value is available. NatLon Native longitude of the reference point of a FITS-WCS projection This attribute gives the longitude of the reference point of the FITS-WCS projection implemented by a WcsMapWcsMap. The value is in radians in the " native spherical" coordinate system, and will usually be zero. See the description of attribute NatLatNatLat for further information.

The NatLon attribute is read-only. Floating point, read-only. WcsMap All WcsMaps have this attribute. Naxes Number of Frame axes This is a read-only attribute giving the number of axes in a FrameFrame (i.e. the number of dimensions of the coordinate space which the Frame describes). This value is determined when the Frame is created. Integer, read-only. Frame All Frames have this attribute. FrameSetFrameSet The Naxes attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). CmpFrameCmpFrame The Naxes attribute of a CmpFrame is equal to the sum of the Naxes values of its two component Frames. Ncard Number of FITS header cards in a FitsChan This attribute gives the total number of FITS header cards stored in a FitsChanFitsChan. It is updated as cards are added or deleted. Integer, read-only. FitsChan All FitsChans have this attribute. Ncolumn The number of columns in the table This attribute holds the number of columns currently in the table. Columns are added and removed using the astAddColumnastAddColumn and astRemoveColumnastRemoveColumn functions. Integer, read-only. TableTable All Tables have this attribute. NegLon Display negative longitude values? This attribute is a boolean value which controls how longitude values are normalized for display by astNormastNorm.

If the NegLon attribute is zero, then normalized longitude values will be in the range zero to 2.pi. If NegLon is non-zero, then normalized longitude values will be in the range -pi to pi.

The default value depends on the current value of the SkyRefIsSkyRefIs attribute, If SkyRefIs has a value of " Origin" , then the default for NegLon is one, otherwise the default is zero. Integer (boolean). SkyFrameSkyFrame All SkyFrames have this attribute. Negated Region negation flag This attribute controls whether a RegionRegion represents the " inside" or the " outside" of the area which was supplied when the Region was created. If the attribute value is zero (the default), the Region represents the inside of the original area. However, if it is non-zero, it represents the outside of the original area. The value of this attribute may be toggled using the astNegateastNegate function.

Note, whether the boundary is considered to be inside the Region or not is controlled by the ClosedClosed attribute. Changing the value of the Negated attribute does not change the value of the Closed attribute. Thus, if Region is closed, then the boundary of the Region will be inside the Region, whatever the setting of the Negated attribute. Integer (boolean). Region All Regions have this attribute. Nframe Number of Frames in a FrameSet This attribute gives the number of Frames in a FrameSetFrameSet. This value will change as Frames are added or removed, but will always be at least one. Integer, read-only. FrameSet All FrameSets have this attribute. Nin Number of input coordinates for a Mapping This attribute gives the number of coordinate values required to specify an input point for a MappingMapping (i.e. the number of dimensions of the space in which the Mapping' s input points reside). Integer, read-only. Mapping All Mappings have this attribute. CmpMapCmpMap If a CmpMap' s component Mappings are joined in series, then its Nin attribute is equal to the Nin attribute of the first component (or to the NoutNout attribute of the second component if the the CmpMap' s InvertInvert attribute is non-zero).

If a CmpMap' s component Mappings are joined in parallel, then its Nin attribute is given by the sum of the Nin attributes of each component (or to the sum of their Nout attributes if the CmpMap' s Invert attribute is non-zero). FrameFrame The Nin attribute for a Frame is always equal to the number of Frame axes (NaxesNaxes attribute). FrameSetFrameSet The Nin attribute of a FrameSet is equal to the number of axes (Naxes attribute) of its base Frame (as specified by the FrameSet' s BaseBase attribute). The Nin attribute value may therefore change if a new base Frame is selected. NiterInverse Maximum number of iterations for the iterative inverse transformation This attribute controls the iterative inverse transformation used if the IterInverseIterInverse attribute is non-zero.

Its value gives the maximum number of iterations of the Newton-Raphson algorithm to be used for each transformed position. The default value is 4. See also attribute TolInverseTolInverse. Integer. PolyMapPolyMap All PolyMaps have this attribute. Nkey Number of unique FITS keywords in a FitsChan This attribute gives the total number of unique FITS keywords stored in a FitsChanFitsChan. It is updated as cards are added or deleted. If no keyword occurrs more than once in the FitsChan, the NcardNcard and Nkey attributes will be equal. If any keyword occurrs more than once, the Nkey attribute value will be smaller than the Ncard attribute value. Integer, read-only. FitsChan All FitsChans have this attribute. Nobject Number of Objects in class This attribute gives the total number of Objects currently in existence in the same class as the ObjectObject whose attribute value is requested. This count does not include Objects which belong to derived (more specialised) classes.

This attribute is mainly intended for debugging. It can be used to detect whether Objects which should have been deleted have, in fact, been deleted. Integer, read-only. Object All Objects have this attribute. Norm(axis) Specifies the plane upon which a Plot3D draws text and markers This attribute controls the appearance of text and markers drawn by a Plot3DPlot3D. It specifies the orientation of the plane upon which text and markers will be drawn by all subsequent invocations of the astTextastText and astMarkastMark functions.

When setting or getting the Norm attribute, the attribute name must be qualified by an axis index in the range 1 to 3. The 3 elements of the Norm attribute are together interpreted as a vector in 3D graphics coordinates that is normal to the plane upon which text and marks should be drawn. When testing or clearing the attribute, the axis index is optional. If no index is supplied, then clearing the Norm attribute will clear all three elements, and testing the Norm attribute will return a non-zero value if any of the three elements are set.

The default value is 1.0 for each of the 3 elements. The length of the vector is insignificant, but an error will be reported when attempting to draw text or markers if the vector has zero length. Floating point. PlotPlot All Plot3Ds have this attribute. NormUnit(axis) Normalised physical units for formatted axis values 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 " s34#34(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. String, read-only. FrameFrame All Frames have this attribute. When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. Nout Number of output coordinates for a Mapping This attribute gives the number of coordinate values generated by a MappingMapping to specify each output point (i.e. the number of dimensions of the space in which the Mapping' s output points reside). Integer, read-only. Mapping All Mappings have this attribute. CmpMapCmpMap If a CmpMap' s component Mappings are joined in series, then its Nout attribute is equal to the Nout attribute of the second component (or to the NinNin attribute of the first component if the the CmpMap' s InvertInvert attribute is non-zero).

If a CmpMap' s component Mappings are joined in parallel, then its Nout attribute is given by the sum of the Nout attributes of each component (or to the sum of their Nin attributes if the CmpMap' s Invert attribute is non-zero). FrameFrame The Nout attribute for a Frame is always equal to the number of Frame axes (NaxesNaxes attribute). FrameSetFrameSet The Nout attribute of a FrameSet is equal to the number of FrameSet axes (Naxes attribute) which, in turn, is equal to the Naxes attribute of the FrameSet' s current Frame (as specified by the CurrentCurrent attribute). The Nout attribute value may therefore change if a new current Frame is selected. Nparameter The number of global parameters in the table This attribute holds the number of global parameters currently in the table. Parameters are added and removed using the astAddParameterastAddParameter and astRemoveParameterastRemoveParameter functions. Integer, read-only. TableTable All Tables have this attribute. Nrow The number of rows in the table This attribute holds the index of the last row to which any contents have been added using any of the astMapPut... AST_MAPPUT... functions. The first row has index 1. Integer, read-only. TableTable All Tables have this attribute. NumLab(axis) Draw numerical axis labels for a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether labels should be drawn to represent the numerical values along each axis of a PlotPlot. It takes a separate value for each physical axis of a Plot so that, for instance, the setting " NumLab(2)=1" specifies that numerical labels should be drawn for the second axis.

If the NumLab value of a Plot axis is non-zero (the default), then numerical labels will be drawn for that axis, otherwise they will be omitted. Integer (boolean). Plot All Plots have this attribute. The drawing of associated descriptive axis labels for a Plot (describing the quantity being plotted along each axis) is controlled by the TextLab(axis)TextLab(axis) attribute.

If no axis is specified, (e.g. " NumLab" instead of " NumLab(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the NumLab(1) value. NumLabGap(axis) Spacing of numerical labels for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining where numerical axis labels are placed relative to the axes they describe. It takes a separate value for each physical axis of a PlotPlot so that, for instance, the setting " NumLabGap(2)=-0.01" specifies where the numerical label for the second axis should be drawn.

For each axis, the NumLabGap value gives the spacing between the axis line (or edge of the plotting area, if appropriate) and the nearest edge of the corresponding numerical axis labels. Positive values cause the descriptive label to be placed on the opposite side of the line to the default tick marks, while negative values cause it to be placed on the same side.

The NumLabGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being 241#2410.01. Floating point. Plot All Plots have this attribute. If no axis is specified, (e.g. " NumLabGap" instead of " NumLabGap(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the NumLabGap(1) value. ObjSize The in-memory size of the Object This attribute gives the total number of bytes of memory used by the ObjectObject. This includes any Objects which are encapsulated within the supplied Object. Integer, read-only. Object All Objects have this attribute. ObsAlt The geodetic altitude of the observer This attribute specifies the geodetic altitude of the observer, in metres, relative to the IAU 1976 reference ellipsoid. The basic FrameFrame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrameSpecFrame, SkyFrameSkyFrame and TimeFrameTimeFrame classes use it. The default value is zero. Floating point. Frame All Frames have this attribute. SpecFrame Together with the ObsLonObsLon, EpochEpoch, RefRARefRA and RefDecRefDec 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 attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) ObsLat The geodetic latitude of the observer This attribute specifies the geodetic latitude of the observer, in degrees, relative to the IAU 1976 reference ellipsoid. The basic FrameFrame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrameSpecFrame, SkyFrameSkyFrame and TimeFrameTimeFrame 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 " 241#241" and " -" . When converting the stored value to a string, the format " [s]dd:mm:ss.ss" is used, when " [s]" is " N" or " S" . String. Frame All Frames have this attribute. SpecFrame Together with the ObsLonObsLon, EpochEpoch, RefRARefRA and RefDecRefDec 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 attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) ObsLon The geodetic longitude of the observer This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute ObsLatObsLat. The basic FrameFrame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrameSpecFrame, SkyFrameSkyFrame and TimeFrameTimeFrame 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 " 241#241" 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. String. Frame All Frames have this attribute. SpecFrame Together with the ObsLon, EpochEpoch, RefRARefRA and RefDecRefDec 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 attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) PVMax(i) Maximum number of FITS-WCS projection parameters This attribute specifies the largest legal index for a PV projection parameter attached to a specified axis of the WcsMapWcsMap (i.e. the largest legal value for " m" when accessing the " PVi_mPVi_m" attribute). The axis index is specified by i, and should be in the range 1 to 99. The value for each axis is determined by the projection type specified when the WcsMap is first created using astWcsMapastWcsMap and cannot subsequently be changed. Integer, read-only. WcsMap All WcsMaps have this attribute. PVi_m FITS-WCS projection parameters This attribute specifies the projection parameter values to be used by a WcsMapWcsMap when implementing a FITS-WCS sky projection. Each PV attribute name should include two integers, i and m, separated by an underscore. The axis index is specified by i, and should be in the range 1 to 99. The parameter number is specified by m, and should be in the range 0 to 99. For example, " PV2_1=45.0" would specify a value for projection parameter 1 of axis 2 in a WcsMap.

These projection parameters correspond exactly to the values stored using the FITS-WCS keywords " PV1_1" , " PV1_2" , etc. This means that projection parameters which correspond to angles must be given in degrees (despite the fact that the angular coordinates and other attributes used by a WcsMap are in radians).

The set of projection parameters used by a WcsMap depends on the type of projection, which is determined by its WcsTypeWcsType parameter. Most projections either do not require projection parameters, or use parameters 1 and 2 associated with the latitude axis. You should consult the FITS-WCS paper for details.

Some projection parameters have default values (as defined in the FITS-WCS paper) which apply if no explicit value is given. You may omit setting a value for these " optional" parameters and the default will apply. Some projection parameters, however, have no default and a value must be explicitly supplied. This is most conveniently done using the " options" argument of astWcsMapastWcsMap (q.v.) when a WcsMap is first created. An error will result when a WcsMap is used to transform coordinates if any of its required projection parameters has not been set and lacks a default value.

A " get" operation for a parameter which has not been assigned a value will return the default value defined in the FITS-WCS paper, or AST__BAD if the paper indicates that the parameter has no default. A default value of zero is returned for parameters which are not accessed by the projection.

Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude axis to hold the native longitude and latitude of the fiducial point of the projection, in degrees. The default values for these parameters are determined by the projection type. The AST-specific TPN projection does not use this convention - all projection parameters for both axes are used to represent polynomical correction terms, and the native longitude and latitude at the fiducial point may not be changed from the default values of zero and 90 degrees. Floating point. WcsMap All WcsMaps have this attribute. The value of this attribute may changed only if the WcsMap has no more than one reference. That is, an error is reported if the WcsMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function.

If the projection parameter values given for a WcsMap do not satisfy all the required constraints (as defined in the FITS-WCS paper), then an error will result when the WcsMap is used to transform coordinates. PcdCen(axis) Centre coordinates of pincushion/barrel distortion This attribute specifies the centre of the pincushion/barrel distortion implemented by a PcdMapPcdMap. It takes a separate value for each axis of the PcdMap so that, for instance, the settings " PcdCen(1)=345.0,PcdCen(2)=-104.4" specify that the pincushion distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2 respectively. This attribute is set when a PcdMap is created, but may later be modified. If the attribute is cleared, the default value for both axes is zero.

Note, the value of this attribute may changed only if the PcdMap has no more than one reference. That is, an error is reported if the PcdMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Floating point. PcdMap All PcdMaps have this attribute. If no axis is specified, (e.g. " PcdCen" instead of " PcdCen(2)" ), then a " set" or " clear" operation will affect the attribute value of both axes, while a " get" or " test" operation will use just the PcdCen(1) value. Permute Permute axis order? This attribute is a boolean value which controls how a FrameFrame behaves when it is used (by astFindFrameastFindFrame) 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 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. String. 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. SkyFrameSkyFrame Unlike a basic Frame, the SkyFrame class makes use of this attribute. FrameSetFrameSet The Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). PolarLong The longitude value to assign to either pole This attribute holds the longitude value, in radians, to be returned when a Cartesian position corresponding to either the north or south pole is transformed into spherical coordinates. The default value is zero.

Note, the value of this attribute may changed only if the SphMapSphMap has no more than one reference. That is, an error is reported if the SphMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Double precision. SphMap All SphMaps have this attribute. PolyTan Use PVi_m keywords to define distorted TAN projection? This attribute is a boolean value which specifies how FITS " TAN" projections should be treated when reading a FrameSetFrameSet from a foreign encoded FITS header. If zero, the projection is assumed to conform to the published FITS-WCS standard. If positive, the convention for a distorted TAN projection included in an early draft version of FITS-WCS paper II are assumed. In this convention the coefficients of a polynomial distortion to be applied to intermediate world coordinates are specified by the PVi_mPVi_m keywords. This convention was removed from the paper before publication and so does not form part of the standard. Indeed, it is incompatible with the published standard because it re-defines the meaning of the first five PVi_m keywords on the longitude axis, which are reserved by the published standard for other purposes. However, this scheme has now been added to the registry of FITS conventions (http://fits.gsfc.nasa.gov/registry/tpvwcs.html) and headers that use this convention are created by the SCAMP utility (http://www.astromatic.net/software/scamp) and the Dark Energy Camera at NOAO.

The default value for the PolyTan attribute is -1. A negative values causes the used convention to depend on the contents of the FitsChanFitsChan. If the FitsChan contains any PVi_m keywords for the latitude axis, or if it contains PVi_m keywords for the longitude axis with " m" greater than 4, then the distorted TAN convention is used. Otherwise, the standard convention is used. Integer. FitsChan All FitsChans have this attribute. PreserveAxes Preserve axes? This attribute controls how a FrameFrame behaves when it is used (by astFindFrameastFindFrame) 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 non-zero, 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. Integer (boolean). Frame All Frames have this attribute. FrameSetFrameSet The PreserveAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). PreserveName Save the ASDF name attributes as AST Ident values? This is a boolean attribute that controls how astReadastRead behaves. If PreserveName is non-zero, the value of the " name" property of each ASDF transform is stored as the value for the IdentIdent attribute of the corresponding AST MappingMapping. If PreserveName is zero, the " name" property is stored as the value for the IDID attribute of the corresponding AST Mapping. The main difference between the Ident and ID attributes is that the value of ID is not transferred to the new ObjectObject when an Object is copied, whereas the Ident value is transferred. However, a secondary difference is that a Mapping cannot be simplified (using astSimplifyastSimplify) if its Ident value is set (this is because the Ident value could be lost in the process). For this reason, the default for PreserveName is zero. Integer (boolean). All yamlchans have this attribute. ProjP(m) FITS-WCS projection parameters This attribute provides aliases for the PV attributes, which specifies the projection parameter values to be used by a WcsMapWcsMap when implementing a FITS-WCS sky projection. ProjP is retained for compatibility with previous versions of FITS-WCS and AST. New applications should use the PV attibute instead.

Attributes ProjP(0) to ProjP(9) correspond to attributes PV1#1axlat2#2_0 to PV1#1axlat2#2_9, where 1#1axlat2#2 is replaced by the index of the latitude axis (given by attribute WcsAxis(2)). See PV for further details.

Note, the value of this attribute may changed only if the WcsMap has no more than one reference. That is, an error is reported if the WcsMap has been cloned, either by including it within another object such as a CmpMapCmpMap or FrameSetFrameSet or by calling the astCloneastClone function. Floating point. WcsMap All WcsMaps have this attribute. Projection Sky projection description This attribute provides a place to store a description of the type of sky projection used when a SkyFrameSkyFrame is attached to a 2-dimensional object, such as an image or plotting surface. For example, typical values might be " orthographic" , " Hammer-Aitoff" or " cylindrical equal area" .

The Projection value is purely descriptive and does not affect the celestial coordinate system represented by the SkyFrame in any way. If it is set to a non-blank string, the description provided may be used when forming the default value for the SkyFrame' s TitleTitle attribute (so that typically it will appear in graphical output, for instance). The default value is an empty string. String. SkyFrame All SkyFrames have this attribute. RefCount Count of active Object pointers This attribute gives the number of active pointers associated with an ObjectObject. It is modified whenever pointers are created or annulled (by astCloneastClone, astAnnulastAnnul or astEndastEnd for example). The count includes the initial pointer issued when the Object was created.

If the reference count for an Object falls to zero as the result of annulling a pointer to it, then the Object will be deleted. Integer, read-only. Object All Objects have this attribute. RefDec The declination of the reference point This attribute specifies the FK5 J2000.0 declination of a reference point on the sky. See the description of attribute RefRARefRA for details. The default RefDec is " 0:0:0" . String. SpecFrameSpecFrame All SpecFrames have this attribute. RefRA The right ascension of the reference point This attribute, together with the RefDecRefDec attribute, specifies the FK5 J2000.0 coordinates of a reference point on the sky. For 1-dimensional spectra, this should normally be the position of the source. For spectral data with spatial coverage (spectral cubes, etc), this should be close to centre of the spatial coverage. It is used to define the correction for Doppler shift to be applied when using the astFindFrameastFindFrame or astConvertastConvert method to convert between different standards of rest.

The SpecFrameSpecFrame class assumes this velocity correction is spatially invariant. If a single SpecFrame is used (for instance, as a component of a CmpFrameCmpFrame) to describe spectral values at different points on the sky, then it is assumes that the doppler shift at any spatial position is the same as at the reference position. The maximum velocity error introduced by this assumption is of the order of V34#34SIN(FOV), where FOV is the angular field of view, and V is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of V is about 20 km/s, so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 km/s. As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 km/s over a 1 degree field of view.

The RefRA and RefDec attributes are stored internally in radians, but are converted to and from a string for access. The format " hh:mm:ss.ss" is used for RefRA, and " dd:mm:ss.s" is used for RefDec. The methods astSetRefPosastSetRefPos and astGetRefPosastGetRefPos may be used to access the values of these attributes directly as unformatted values in radians.

The default for RefRA is " 0:0:0" . String. SpecFrame All SpecFrames have this attribute. RegionClass The AST class name of the Region encapsulated within an Stc This is a read-only attribute giving the AST class name of the RegionRegion encapsulated within an StcStc (that is, the class of the Region which was supplied when the Stc was created). String, read-only. Stc All Stc objects this attribute. Report Report transformed coordinates? This attribute controls whether coordinate values are reported whenever a MappingMapping is used to transform a set of points. If its value is zero (the default), no report is made. However, if it is non-zero, the coordinates of each point are reported (both before and after transformation) by writing them to standard output.

This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs. Integer (boolean). Mapping All Mappings have this attribute. CmpMapCmpMap When applied to a compound Mapping (CmpMap), only the Report attribute of the CmpMap, and not those of its component Mappings, is used. Coordinate information is never reported for the component Mappings individually, only for the complete CmpMap. FrameFrame When applied to any Frame, the formatting capabilities of the Frame (as provided by the astFormatastFormat function) will be used to format the reported coordinates. FrameSetFrameSet When applied to any FrameSet, the formatting capabilities of the base and current Frames will be used (as above) to individually format the input and output coordinates, as appropriate. The Report attribute of a FrameSet is not itself affected by selecting a new base or current Frame, but the resulting formatting capabilities may be. Unlike most other attributes, the value of the Report attribute is not transferred when a Mapping is copied. Instead, its value is undefined (and therefore defaults to zero) in any copy. Similarly, it becomes undefined in any external representation of a Mapping produced by the astWriteastWrite function. ReportLevel Determines which read/write conditions are reported This attribute determines which, if any, of the conditions that occur whilst reading or writing an ObjectObject should be reported. These conditions will generate either a fatal error or a warning, as determined by attribute StrictStrict. ReportLevel can take any of the following values:

0 - Do not report any conditions.

1 - ReportReport only conditions where significant information content has been changed. For instance, an unsupported time-scale has been replaced by a supported near-equivalent time-scale. Another example is if a basic ChannelChannel encounters unexpected data items that may have been introduced by later versions of AST.

2 - Report the above, and in addition report significant default values. For instance, if no time-scale was specified when reading an Object from an external data source, report the default time-scale that is being used.

3 - Report the above, and in addition report any other potentially interesting conditions that have no significant effect on the conversion. For instance, report if a time-scale of " TT" (terrestrial time) is used in place of " ET" (ephemeris time). This change has no signficiant effect because ET is the predecessor of, and is continuous with, TT. Synonyms such as " IAT" and " TAI" are another example.

The default value is 1. Note, there are many other conditions that can occur whilst reading an Object that completely prevent the conversion taking place. Such conditions will always generate errors, irrespective of the ReportLevel and Strict attributes. Note, failure to write an Object to a Channel does not usually generate an error. Instead, astWriteastWrite returns a function value of zero. Integer. Channel All Channels have this attribute. FitsChanFitsChan All the conditions selected by the FitsChan WarningsWarnings attribute are reported at level 1. RestFreq The rest frequency This attribute specifies the frequency corresponding to zero velocity. It is used when converting between between velocity-based coordinate systems and and other coordinate systems (such as frequency, wavelength, energy, etc). The default value is 1.0E5 GHz.

When setting a new value for this attribute, the new value can be supplied either directly as a frequency, or indirectly as a wavelength or energy, in which case the supplied value is converted to a frequency before being stored. The nature of the supplied value is indicated by appending text to the end of the numerical value indicating the units in which the value is supplied. If the units are not specified, then the supplied value is assumed to be a frequency in units of GHz. If the supplied unit is a unit of frequency, the supplied value is assumed to be a frequency in the given units. If the supplied unit is a unit of length, the supplied value is assumed to be a (vacuum) wavelength. If the supplied unit is a unit of energy, the supplied value is assumed to be an energy. For instance, the following strings all result in a rest frequency of around 1.4E14 Hz being used: " 1.4E5" , " 1.4E14 Hz" , " 1.4E14 s34#34 34#34-1" , " 1.4E5 GHz" , " 2.14E-6 m" , " 21400 Angstrom" , " 9.28E-20 J" , " 9.28E-13 erg" , " 0.58 eV" , etc.

When getting the value of this attribute, the returned value is always a frequency in units of GHz. Floating point. SpecFrameSpecFrame All SpecFrames have this attribute. RootCorner Specifies which edges of the 3D box should be annotated This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining which edges of the cube enclosing the 3D graphics space are used for displaying numerical and descriptive axis labels. The attribute value identifies one of the eight corners of the cube within which graphics are being drawn (i.e. the cube specified by the " graphbox" parameter when astPlot3DastPlot3D was called tp create the Plot3DPlot3D). AxisAxis labels and tick marks will be placed on the three cube edges that meet at the given corner.

The attribute value should consist of three character, each of which must be either " U" or " L" . The first character in the string specifies the position of the corner on the first graphics axis. If the character is " U" then the corner is at the upper bound on the first graphics axis. If it is " L" , then the corner is at the lower bound on the first axis. Likewise, the second and third characters in the string specify the location of the corner on the second and third graphics axes.

For instance, corner " LLL" is the corner that is at the lower bound on all three graphics axes, and corner " ULU" is at the upper bound on axes 1 and 3 but at the lower bound on axis 2.

The default value is " LLL" . String. Plot3D All Plot3Ds have this attribute. Seed Random number seed for a MathMap This attribute, which may take any integer value, determines the sequence of random numbers produced by the random number functions in MathMapMathMap expressions. It is set to an unpredictable default value when a MathMap is created, so that by default each MathMap uses a different set of random numbers.

If required, you may set this Seed attribute to a value of your choosing in order to produce repeatable behaviour from the random number functions. You may also enquire the Seed value (e.g. if an initially unpredictable value has been used) and then use it to reproduce the resulting sequence of random numbers, either from the same MathMap or from another one.

Clearing the Seed attribute gives it a new unpredictable default value. Integer. MathMap All MathMaps have this attribute. SideBand Indicates which sideband a dual sideband spectrum represents This attribute indicates whether the DSBSpecFrameDSBSpecFrame currently represents its lower or upper sideband, or an offset from the local oscillator frequency. When querying the current value, the returned string is always one of " usb" (for upper sideband), " lsb" (for lower sideband), or " lo" (for offset from the local oscillator frequency). When setting a new value, any of the strings " lsb" , " usb" , " observed" , " image" or " lo" may be supplied (case insensitive). The " observed" sideband is which ever sideband (upper or lower) contains the central spectral position given by attribute DSBCentreDSBCentre, and the " image" sideband is the other sideband. It is the sign of the IFIF attribute which determines if the observed sideband is the upper or lower sideband. The default value for SideBand is the observed sideband. String. DSBSpecFrame All DSBSpecFrames have this attribute. SimpFI Forward-inverse MathMap pairs simplify? This attribute should be set to a non-zero value if applying a MathMapMathMap' s forward transformation, followed immediately by the matching inverse transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity MappingMapping (a UnitMapUnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplifyastSimplify).

By default, the SimpFI attribute is zero, so that AST will not perform this simplification unless you have set SimpFI to indicate that it is safe to do so. Integer (boolean). MathMap All MathMaps have this attribute. For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient.

The consent of both MathMaps is required before simplification can take place. If either has a SimpFI value of zero, then simplification will not occur.

The SimpFI attribute controls simplification only in the case where a MathMap' s forward transformation is followed by the matching inverse transformation. It does not apply if an inverse transformation is followed by a forward transformation. This latter case is controlled by the SimpIFSimpIF attribute.

The " forward" and " inverse" transformations referred to are those defined when the MathMap is created (corresponding to the " fwd" and " inv" parameters of its constructor function). If the MathMap is inverted (i.e. its InvertInvert attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged. SimpIF Inverse-forward MathMap pairs simplify? This attribute should be set to a non-zero value if applying a MathMapMathMap' s inverse transformation, followed immediately by the matching forward transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity MappingMapping (a UnitMapUnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplifyastSimplify).

By default, the SimpIF attribute is zero, so that AST will not perform this simplification unless you have set SimpIF to indicate that it is safe to do so. Integer (boolean). MathMap All MathMaps have this attribute. For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient.

The consent of both MathMaps is required before simplification can take place. If either has a SimpIF value of zero, then simplification will not occur.

The SimpIF attribute controls simplification only in the case where a MathMap' s inverse transformation is followed by the matching forward transformation. It does not apply if a forward transformation is followed by an inverse transformation. This latter case is controlled by the SimpFISimpFI attribute.

The " forward" and " inverse" transformations referred to are those defined when the MathMap is created (corresponding to the " fwd" and " inv" parameters of its constructor function). If the MathMap is inverted (i.e. its InvertInvert attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged. SimpVertices Simplify a Polygon by transforming its vertices? This attribute controls the behaviour of the astSimplifyastSimplify method when applied to a PolygonPolygon. The simplified Polygon is created by transforming the vertices from the FrameFrame in which the Polygon was originally defined into the Frame currently represented by the Polygon. If SimpVertices is non-zero (the default) then this simplified Polygon is returned without further checks. If SimpVertices is zero, a check is made that the edges of the new Polygon do not depart significantly from the edges of the original Polygon (as determined by the uncertainty associated with the Polygon). This could occur, for instance, if the MappingMapping frrm the original to the current Frame is highly non-linear. If this check fails, the original unsimplified Polygon is returned without change. Integer (boolean). Polygon All Polygons have this attribute. SinkFile Output file to which to data should be written This attribute specifies the name of a file to which the ChannelChannel should write data. If specified it is used in preference to any sink function specified when the Channel was created.

Assigning a new value to this attribute will cause any previously opened SinkFile to be closed. The first subsequent call to astWriteastWrite will attempt to open the new file (an error will be reported if the file cannot be opened), and write data to it. All subsequent call to astWrite will write data to the new file, until the SinkFile attribute is cleared or changed.

Clearing the attribute causes any open SinkFile to be closed. All subsequent data writes will use the sink function specified when the Channel was created, or will write to standard output if no sink function was specified.

If no value has been assigned to SinkFile, a null string will be returned if an attempt is made to get the attribute value. String. FitsChanFitsChan When the FitsChan is destroyed, any headers in the FitsChan will be written out to the sink file, if one is specified (if not, the sink function used when the FitsChan was created is used). The sink file is a text file (not a FITS file) containing one header per line. A new SinkFile will over-write any existing file with the same name unless the existing file is write protected, in which case an error will be reported.

Any open SinkFile is closed when the Channel is deleted.

If the Channel is copied or dumped (using astCopyastCopy or astShowastShow) the SinkFile attribute is left in a cleared state in the output Channel (i.e. the value of the SinkFile attribute is not copied). SipOK Use Spitzer Space Telescope keywords to define distortion? This attribute is a boolean value which specifies whether to include support for the " SIP" scheme, which can be used to add distortion to basic FITS-WCS projections. This scheme was first defined by the Spitzer Space Telescope and is described in the following document: http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf The default for SipOK is 1.

When using astReadastRead to read a FITS-WCS encoded header, a suitable PolyMapPolyMap will always be included in the returned FrameSetFrameSet if the header contains SIP keywords, regardless of the value of the SipOK attribute. The PolyMap will be immediately before the MatrixMapMatrixMap that corresponds to the FITS-WCS PC or CD matrix.

When using astWriteastWrite to write a FrameSet to a FITS-WCS encoded header, suitable SIP keywords will be included in the header if the FrameSet contains a PolyMap immediately before the MatrixMap that corresponds to the FITS-WCS PC or CD matrix, but only if the SipOK attribute is non-zero. If the FrameSet contains a PolyMap but SipOK is zero, then an attempt will be made to write out the FrameSet without SIP keywords using a linear approximation to the pixel-to-IWC mapping. If this fails because the MappingMapping exceeds the linearity requirement specified by attribute FitsTolFitsTol, astWrite will return zero, indicating that the FrameSet could not be written out. Note, SIP headers can only be produced for axes that form part of a SkyFrameSkyFrame.

Note, the SIP distortion scheme is independent of the TPV/TPN distortion schemes (see attribute PolyTanPolyTan). A FITS-WCS header could in principle, contain keywords for both schemes although this is unlikely. Integer (boolean). FitsChanFitsChan All FitsChans have this attribute. SipReplace Replace SIP inverse transformation? This attribute is a boolean value which specifies how SIP keywords should be handled when reading a FITS-WCS encoded header using the astReadastRead function. See http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf for more information about SIP headers. If SipReplace is non-zero, then any SIP keywords describing the inverse transformation (i.e. from WCS to pixel coordinates) are ignored. Instead a new inverse transformation is found by performing a fit to the forward transformation. The SipReplace attribute can be set to zero to prevent this happening. If SipReplace is zero, any SIP keywords describing the inverse transformation are used as supplied, rather than being replaced using a new fit. The default value is 1. Integer (boolean). FitsChanFitsChan All FitsChans have this attribute. Size(element) Character size for a Plot element This attribute determines the character size used when drawing each element of graphical output produced by a PlotPlot. It takes a separate value for each graphical element so that, for instance, the setting " Size(title)=2.0" causes the Plot title to be drawn using twice the default character size.

The range of character sizes available and the appearance of the resulting text is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default character size supplied by this graphics system. Floating Point. Plot All Plots have this attribute. For a list of the graphical elements available, see the description of the Plot class.

If no graphical element is specified, (e.g. " Size" instead of " Size(title)" ), then a " set" or " clear" operation will affect the attribute value of all graphical elements, while a " get" or " test" operation will use just the Size(TextLab) value. SizeGuess The expected size of the KeyMap This is attribute gives an estimate of the number of entries that will be stored in the KeyMapKeyMap. It is used to tune the internal properties of the KeyMap for speed and efficiency. A larger value will result in faster access at the expense of increased memory requirements. However if the SizeGuess value is much larger than the actual size of the KeyMap, then there will be little, if any, speed gained by making the SizeGuess even larger. The default value is 300.

The value of this attribute can only be changed if the KeyMap is empty. Its value can be set conveniently when creating the KeyMap. An error will be reported if an attempt is made to set or clear the attribute when the KeyMap contains any entries. Integer. KeyMap All KeyMaps have this attribute. Skip Skip irrelevant data? This is a boolean attribute which indicates whether the ObjectObject data being read through a ChannelChannel are inter-mixed with other, irrelevant, external data.

If Skip is zero (the default), then the source of input data is expected to contain descriptions of AST Objects and comments and nothing else (if anything else is read, an error will result). If Skip is non-zero, then any non-Object data encountered between Objects will be ignored and simply skipped over in order to reach the next Object. Integer (boolean). Channel All Channels have this attribute. FitsChanFitsChan The FitsChan class sets the default value of this attribute to 1, so that all irrelevant FITS headers will normally be ignored. YamlChanYamlChan The YamlChan class ignores this attribute. SkyRef(axis) Position defining the offset coordinate system This attribute allows a SkyFrameSkyFrame to represent offsets, rather than absolute axis values, within the coordinate system specified by the SystemSystem attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the SkyRefIsSkyRefIs attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute.

If an integer axis index is included in the attribute name (e.g. " SkyRef(1)" ) then the attribute value should be supplied as a single floating point axis value, in radians, when setting a value for the attribute, and will be returned in the same form when getting the value of the attribute. In this case the integer axis index should be " 1" or " 2" (the values to use for longitude and latitude axes are given by the LonAxisLonAxis and LatAxisLatAxis attributes).

If no axis index is included in the attribute name (e.g. " SkyRef" ) then the attribute value should be supplied as a character string containing two formatted axis values (an axis 1 value followed by a comma, followed by an axis 2 value). The same form will be used when getting the value of the attribute.

The default values for SkyRef are zero longitude and zero latitude. Floating point. SkyFrame All SkyFrames have this attribute. If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System.

If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending " offset" to the end, the default axis Symbols for the SkyFrame are modified by prepending the character " D" to the start, and the default title is modified by replacing the projection information by the origin information. Aligning SkyFrames with Offset Coordinate Systems The offset coordinate system within a SkyFrame should normally be considered as a superficial " re-badging" of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical " label" for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may " drift" with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the astConvertastConvert or astFindFrameastFindFrame routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the AlignSystemAlignSystem attribute. However, by setting the AlignOffsetAlignOffset attribute to a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames. SkyRefIs Selects the nature of the offset coordinate system This attribute controls how the values supplied for the SkyRef and SkyRefP attributes are used. These three attributes together allow a SkyFrameSkyFrame to represent offsets relative to some specified origin or pole within the coordinate system specified by the SystemSystem attribute, rather than absolute axis values. SkyRefIs can take one of the case-insensitive values " Origin" , " Pole" or " Ignored" .

If SkyRefIs is set to " Origin" , then the coordinate system represented by the SkyFrame is modified to put the origin of longitude and latitude at the position specified by the SkyRef attribute.

If SkyRefIs is set to " Pole" , then the coordinate system represented by the SkyFrame is modified to put the north pole at the position specified by the SkyRef attribute.

If SkyRefIs is set to " Ignored" (the default), then any value set for the SkyRef attribute is ignored, and the SkyFrame represents the coordinate system specified by the System attribute directly without any rotation. String. SkyFrame All SkyFrames have this attribute. SkyRefP(axis) Position on primary meridian of offset coordinate system This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and SkyRefIsSkyRefIs. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the SystemSystem attribute. The offset coordinate system represented by the SkyFrameSkyFrame will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of 241#24190 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute).

If an integer axis index is included in the attribute name (e.g. " SkyRefP(1)" ) then the attribute value should be supplied as a single floating point axis value, in radians, when setting a value for the attribute, and will be returned in the same form when getting the value of the attribute. In this case the integer axis index should be " 1" or " 2" (the values to use for longitude and latitude axes are given by the LonAxisLonAxis and LatAxisLatAxis attributes).

If no axis index is included in the attribute name (e.g. " SkyRefP" ) then the attribute value should be supplied as a character string containing two formatted axis values (an axis 1 value followed by a comma, followed by an axis 2 value). The same form will be used when getting the value of the attribute. Floating point. SkyFrame All SkyFrames have this attribute. If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to " origin" ), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude).

An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation.

If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System. SkyTol The smallest significant shift in sky coordinates This attribute indicates the accuracy of the axis values that will be represented by the SkyFrameSkyFrame. If the arc-distance between two positions within the SkyFrame is smaller than the value of SkyTol, then the two positions will (for the puposes indicated below) be considered to be co-incident.

This value is used only when constructing the MappingMapping between two different SkyFrames (for instance, when calling astConvertastConvert or astFindFrameastFindFrame). If the transformation between the two SkyFrames causes positions to shift by less than SkyTol arc-seconds, then the transformation is replaced by a UnitMapUnitMap. This could in certain circumatances allow major simplifications to be made to the transformation between any pixel grids associated with the two SkyFrames (for instance, if each SkyFrame is part of the WCS FrameSetFrameSet associated with an image).

A common case is when two SkyFrames use the FK5 system, but have slightly different EpochEpoch values. If the AlignSystemAlignSystem attribute has its default value of " ICRS" , then the transformation between the two SkyFrames will include a very small rotation (FK5 rotates with respect to ICRS as a rate of about 0.0005 arc-seconds per year). In most circumstances such a small rotation is insignificant. Setting SkyTol to some suitably small non-zero value will cause this rotation to be ignored, allowing much simpler transformations to be used.

The test to determine the shift introduced by transforming between the two SkyFrames is performed by transforming a set of 14 position spread evenly over the whole sky. The largest shift produced at any of these 14 positions is compared to the value of SkyTol.

The SkyTol value is in units of arc-seconds, and the default value is 0.001. Floating point. SkyFrame All SkyFrames have this attribute. SortBy Determines how keys are sorted in a KeyMap This attribute determines the order in which keys are returned by the astMapKeyastMapKey function. It may take the following values (the default is " None" ):

" None" : The keys are returned in an arbitrary order. This is the fastest method as it avoids the need for a sorted list of keys to be maintained and used.

" AgeDown" : The keys are returned in the order in which values were stored in the KeyMapKeyMap, with the key for the most recent value being returned last. If the value of an existing entry is changed, it goes to the end of the list.

" AgeUp" : The keys are returned in the order in which values were stored in the KeyMap, with the key for the most recent value being returned first. If the value of an existing entry is changed, it goes to the top of the list.

" KeyAgeDown" : The keys are returned in the order in which they were originally stored in the KeyMap, with the most recent key being returned last. If the value of an existing entry is changed, its position in the list does not change.

" KeyAgeUp" : The keys are returned in the order in which they were originally stored in the KeyMap, with the most recent key being returned first. If the value of an existing entry is changed, its position in the list does not change.

" KeyDown" : The keys are returned in alphabetical order, with " A..." being returned last.

" KeyUp" : The keys are returned in alphabetical order, with " A..." being returned first. String. KeyMap All KeyMaps have this attribute. If a new value is assigned to SortBy (or if SortBy is cleared), all entries currently in the KeyMap are re-sorted according to the new SortBy value. SourceFile Input file from which to read data This attribute specifies the name of a file from which the ChannelChannel should read data. If specified it is used in preference to any source function specified when the Channel was created.

Assigning a new value to this attribute will cause any previously opened SourceFile to be closed. The first subsequent call to astReadastRead will attempt to open the new file (an error will be reported if the file cannot be opened), and read data from it. All subsequent call to astRead will read data from the new file, until the SourceFile attribute is cleared or changed.

Clearing the attribute causes any open SourceFile to be closed. All subsequent data reads will use the source function specified when the Channel was created, or will read from standard input if no source function was specified.

If no value has been assigned to SourceFile, a null string will be returned if an attempt is made to get the attribute value. String. FitsChanFitsChan In the case of a FitsChan, the specified SourceFile supplements the source function specified when the FitsChan was created, rather than replacing the source function. The source file should be a text file (not a FITS file) containing one header per line. When a value is assigned to SourceFile, the file is opened and read immediately, and all headers read from the file are appended to the end of any header already in the FitsChan. The file is then closed. Clearing the SourceFile attribute has no further effect, other than nullifying the string (i.e. the file name) associated with the attribute. Any open SourceFile is closed when the Channel is deleted.

If the Channel is copied or dumped (using astCopyastCopy or astShowastShow) the SourceFile attribute is left in a cleared state in the output Channel (i.e. the value of the SourceFile attribute is not copied). SourceSys Spectral system in which the source velocity is stored This attribute identifies the spectral system in which the SourceVelSourceVel attribute value (the source velocity) is supplied and returned. It can be one of the following:

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

When setting a new value for the SourceVel attribute, the source velocity should be supplied in the spectral system indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity will be returned in this spectral system.

If the value of SourceSys is changed, the value stored for SourceVel will be converted from the old to the new spectral systems.

The default value is " VELO" (apparent radial velocity). String. SpecFrameSpecFrame All SpecFrames have this attribute. SourceVRF Rest frame in which the source velocity is stored This attribute identifies the rest frame in which the source velocity or redshift is stored (the source velocity or redshift is accessed using attribute SourceVelSourceVel). When setting a new value for the SourceVel attribute, the source velocity or redshift should be supplied in the rest frame indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity or redshift will be returned in this rest frame.

If the value of SourceVRF is changed, the value stored for SourceVel will be converted from the old to the new rest frame.

The values which can be supplied are the same as for the StdOfRestStdOfRest attribute (except that SourceVRF cannot be set to " Source" ). The default value is " Helio" . String. SpecFrameSpecFrame All SpecFrames have this attribute. SourceVel The source velocity This attribute (together with SourceSysSourceSys, SourceVRFSourceVRF, RefRARefRA and RefDecRefDec) defines the " Source" standard of rest (see attribute StdOfRestStdOfRest). This is a rest frame which is moving towards the position given by RefRA and RefDec at a velocity given by SourceVel. A positive value means the source is moving away from the observer. When a new value is assigned to this attribute, the supplied value is assumed to refer to the spectral system specified by the SourceSys attribute. For instance, the SourceVel value may be supplied as a radio velocity, a redshift, a beta factor, etc. Similarly, when the current value of the SourceVel attribute is obtained, the returned value will refer to the spectral system specified by the SourceSys value. If the SourceSys value is changed, any value previously stored for the SourceVel attribute will be changed automatically from the old spectral system to the new spectral system.

When setting a value for SourceVel, the value should be supplied in the rest frame specified by the SourceVRF attribute. Likewise, when getting the value of SourceVel, it will be returned in the rest frame specified by the SourceVRF attribute.

The default SourceVel value is zero. Floating point. SpecFrameSpecFrame All SpecFrames have this attribute. It is important to set an appropriate value for SourceVRF and SourceSys before setting a value for SourceVel. If a new value is later set for SourceVRF or SourceSys, the value stored for SourceVel will simultaneously be changed to the new standard of rest or spectral system. SpecOrigin The zero point for SpecFrame axis values This specifies the origin from which all spectral values are measured. The default value (zero) results in the SpecFrameSpecFrame describing absolute spectral values in the system given by the SystemSystem attribute (e.g. frequency, velocity, etc). If a SpecFrame is to be used to describe offset from some origin, the SpecOrigin attribute should be set to hold the required origin value. The SpecOrigin value stored inside the SpecFrame structure is modified whenever SpecFrame attribute values are changed so that it refers to the original spectral position.

When setting a new value for this attribute, the supplied value is assumed to be in the system, units and standard of rest described by the SpecFrame. Likewise, when getting the value of this attribute, the value is returned in the system, units and standard of rest described by the SpecFrame. If any of these attributes are changed, then any previously stored SpecOrigin value will also be changed so that refers to the new system, units or standard of rest. Floating point. SpecFrame All SpecFrames have this attribute. SpecVal The spectral position at which flux values are measured This attribute specifies the spectral position (frequency, wavelength, etc.), at which the values described by the FluxFrameFluxFrame are measured. It is used when determining the MappingMapping between between FluxFrames.

The default value and spectral system used for this attribute are both specified when the FluxFrame is created. Floating point. FluxFrame All FluxFrames have this attribute. StcsArea Return the CoordinateArea component when reading an STC-S document? This is a boolean attribute which controls what is returned by the astReadastRead function when it is used to read from an StcsChanStcsChan. If StcsArea is set non-zero (the default), then a RegionRegion representing the STC CoordinateArea will be returned by astRead. If StcsArea is set to zero, then the STC CoordinateArea will not be returned. Integer (boolean). StcsChan All StcsChans have this attribute. Other attributes such as StcsCoordsStcsCoords and StcsPropsStcsProps can be used to specify other Objects to be returned by astRead. If more than one of these attributes is set non-zero, then the actual ObjectObject returned by astRead will be a KeyMapKeyMap, containing the requested Objects. In this case, the Region representing the STC CoordinateArea will be stored in the returned KeyMap using the key " AREA" . If StcsArea is the only attribute to be set non-zero, then the Object returned by astRead will be the CoordinateArea Region itself.

The class of Region used to represent the CoordinateArea for each STC-S sub-phrase is determined by the first word in the sub-phrase (the " sub-phrase identifier" ). The individual sub-phrase Regions are combined into a single PrismPrism, which is then simplified using astSimplifyastSimplify to form the returned region.

Sub-phrases that represent a single value ( that is, have identifiers " Time" , " Position" , " Spectral" or " Redshift" ) are considered to be be part of the STC CoordinateArea component.

The TimeFrameTimeFrame used to represent a time STC-S sub-phrase will have its TimeOriginTimeOrigin attribute set to the sub-phrase start time. If no start time is specified by the sub-phrase, then the stop time will be used instead. If no stop time is specified by the sub-phrase, then the single time value specified in the sub-phrase will be used instead. Subsequently clearing the TimeOrigin attribute (or setting its value to zero) will cause the TimeFrame to reprsent absolute times.

The EpochEpoch attribute for the returned Region is set in the same way as the TimeOrigin attribute (see above). StcsCoords Return the Coordinates component when reading an STC-S document? This is a boolean attribute which controls what is returned by the astReadastRead function when it is used to read from an StcsChanStcsChan. If StcsCoords is set non-zero, then a PointListPointList representing the STC Coordinates will be returned by astRead. If StcsCoords is set to zero (the default), then the STC Coordinates will not be returned. Integer (boolean). StcsChan All StcsChans have this attribute. Other attributes such as StcsAreaStcsArea and StcsPropsStcsProps can be used to specify other Objects to be returned by astRead. If more than one of these attributes is set non-zero, then the actual ObjectObject returned by astRead will be a KeyMapKeyMap, containing the requested Objects. In this case, the PointList representing the STC Coordinates will be stored in the returned KeyMap using the key " COORDS" . If StcsCoords is the only attribute to be set non-zero, then the Object returned by astRead will be the Coordinates PointList itself.

The Coordinates component is specified by the additional axis values embedded within the body of each STC-S sub-phrase that represents an extended area. Sub-phrases that represent a single value ( that is, have identifiers " Time" , " Position" , " Spectral" or " Redshift" ) are not considered to be be part of the STC Coordinates component.

If the STC-S documents does not contain a Coordinates component, then a NULL object pointer will be returned by astRead if the Coordinates component is the only object being returned. If other objects are also being returned (see attributes StcsProps and StcsArea), then the returned KeyMap will contain a " COORDS" key only if the Coordinates component is read succesfully.

The TimeFrameTimeFrame used to represent a time STC-S sub-phrase will have its TimeOriginTimeOrigin attribute set to the sub-phrase start time. If no start time is specified by the sub-phrase, then the stop time will be used instead. If no stop time is specified by the sub-phrase, then the single time value specified in the sub-phrase will be used instead. Subsequently clearing the TimeOrigin attribute (or setting its value to zero) will cause the TimeFrame to reprsent absolute times.

The EpochEpoch attribute for the returned RegionRegion is set in the same way as the TimeOrigin attribute (see above). StcsLength Controls output line length This attribute specifies the maximum length to use when writing out text through the sink function supplied when the StcsChanStcsChan was created. It is ignored if the IndentIndent attribute is zero (in which case the text supplied to the sink function can be of any length). The default value is 70.

The number of characters in each string written out through the sink function will not usually be greater than the value of this attribute (but may be less). However, if any single word in the STC-S description exceeds the specified length, then the word will be written out as a single line. Integer. StcsChan All StcsChans have this attribute. StcsProps Return all properties when reading an STC-S document? This is a boolean attribute which controls what is returned by the astReadastRead function when it is used to read from an StcsChanStcsChan. If StcsProps is set non-zero, then a KeyMapKeyMap containing all the properties read from the STC-S document will be returned by astRead. If StcsProps is set to zero (the default), then the properties will not be returned. Integer (boolean). StcsChan All StcsChans have this attribute. Other attributes such as StcsCoordsStcsCoords and StcsAreaStcsArea can be used to specify other Objects to be returned by astRead. If more than one of these attributes is set non-zero, then the actual ObjectObject returned by astRead will be a KeyMap containing the requested Objects. In this case, the properties KeyMap will be stored in the returned KeyMap using the key " PROPS" . If StcsProps is the only attribute to be set non-zero, then the Object returned by astRead will be the properties KeyMap itself.

The KeyMap containing the properties will have entries for one or more of the following keys: " TIME_PROPS" , " SPACE_PROPS" , " SPECTRAL_PROPS" and " REDSHIFT_PROPS" . Each of these entries will be another KeyMap containing the properties of the corresponding STC-S sub-phrase. StdOfRest Standard of rest This attribute identifies the standard of rest to which the spectral axis values of a SpecFrameSpecFrame refer, and may take any of the values listed in the " Standards of Rest" section (below).

The default StdOfRest value is " Helio" . String. SpecFrame All SpecFrames have this attribute. Standards of Rest The SpecFrame class supports the following StdOfRest values (all are case-insensitive):

" Topocentric" , " Topocent" or " Topo" : The observers rest-frame (assumed to be on the surface of the earth). Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a day because of the rotation of the observer around the axis of the earth. This standard of rest must be qualified using the ObsLatObsLat, ObsLonObsLon, ObsAltObsAlt, EpochEpoch, RefRARefRA and RefDecRefDec attributes.

" Geocentric" , " Geocentr" or " Geo" : The rest-frame of the earth centre. Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a year because of the rotation of the earth around the Sun. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes.

" Barycentric" , " Barycent" or " Bary" : The rest-frame of the solar-system barycentre. Spectra recorded in this standard of rest suffer a Doppler shift which depends both on the velocity of the Sun through the Local Standard of Rest, and on the movement of the planets through the solar system. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes.

" Heliocentric" , " Heliocen" or " Helio" : The rest-frame of the Sun. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the Sun through the Local Standard of Rest. This standard of rest must be qualified using the RefRA and RefDec attributes.

" LSRK" , " LSR" : The rest-frame of the kinematical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the kinematical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes.

" LSRD" : The rest-frame of the dynamical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the dynamical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes.

" Galactic" , " Galactoc" or " Gal" : The rest-frame of the galactic centre. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the galactic centre through the local group. This standard of rest must be qualified using the RefRA and RefDec attributes.

" Local_group" , " Localgrp" or " LG" : The rest-frame of the local group. This standard of rest must be qualified using the RefRA and RefDec attributes.

" Source" , or " src" : The rest-frame of the source. This standard of rest must be qualified using the RefRA, RefDec and SourceVelSourceVel attributes.

Where more than one alternative SystemSystem value is shown above, the first of these will be returned when an enquiry is made. Strict Report an error if any unexpected data items are found? This is a boolean attribute which indicates whether a warning rather than an error should be issed for insignificant conversion problems. If it is set non-zero, then fatal errors are issued instead of warnings, resulting in the AST error status being set. If Strict is zero (the default), then execution continues after minor conversion problems, and a warning message is added to the ChannelChannel structure. Such messages can be retrieved using the astWarningsastWarnings function. Integer (boolean). YamlChanYamlChan The YamlChan class ignores this attribute. This attribute was introduced in AST version 5.0. Prior to this version of AST unexpected data items read by a basic Channel always caused an error to be reported. So applications linked against versions of AST prior to version 5.0 may not be able to read ObjectObject descriptions created by later versions of AST, if the Object' s class description has changed. Style(element) Line style for a Plot element This attribute determines the line style used when drawing each element of graphical output produced by a PlotPlot. It takes a separate value for each graphical element so that, for instance, the setting " Style(border)=2" causes the Plot border to be drawn using line style 2 (which might result in, say, a dashed line).

The range of integer line styles available and their appearance is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default line style supplied by this graphics system (normally, this is likely to give a solid line). Integer. Plot All Plots have this attribute. For a list of the graphical elements available, see the description of the Plot class.

If no graphical element is specified, (e.g. " Style" instead of " Style(border)" ), then a " set" or " clear" operation will affect the attribute value of all graphical elements, while a " get" or " test" operation will use just the Style(BorderBorder) value. Symbol(axis) Axis symbol This attribute specifies a short-form symbol to be used to represent coordinate values for a particular axis of a FrameFrame. 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. String. Frame The default Symbol value supplied by the Frame class is the string " 1#1DomainDomain2#2 1#1n2#2" , where 1#1n2#2 is 1, 2, etc. for successive axes, and 1#1Domain2#2 is the value of the Frame' s Domain attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain value has been set, " x" is used as the 1#1Domain2#2 value in constructing this default string. SkyFrameSkyFrame 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. TimeFrameTimeFrame The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented. FrameSetFrameSet The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the CurrentCurrent attribute). When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. System Coordinate system used to describe positions within the domain 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 SkyFrameSkyFrame class can use galactic coordinates, equatorial coordinates, etc, to describe positions on the sky. As another example, the SpecFrameSpecFrame 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 FrameFrame. 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. String. Frame The System attribute for a basic Frame always equals " Cartesian" , and may not be altered. CmpFrameCmpFrame 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. FrameSetFrameSet The System attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent 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 241#241PI/2 radians. The zenith has elevation 241#241PI/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 EpochEpoch 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 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 241#241 32.184 seconds.

" ECLIPTIC" : Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox specified by the qualifying EquinoxEquinox 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 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 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 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 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 MappingMapping 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 non-zero 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 astSetActiveUnitastSetActiveUnit function for further information). TimeFrameTimeFrame 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 non-zero 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). FluxFrameFluxFrame The FluxFrame class supports the following System values and associated systems for measuring observed value:

" FLXDN" : Flux per unit frequency (W/m308#3082/Hz)

" FLXDNW" : Flux per unit wavelength (W/m308#3082/Angstrom)

" SFCBR" : Surface brightness in frequency units (W/m308#3082/Hz/arcmin34#34 34#342)

" SFCBRW" : Surface brightness in wavelength units (W/m308#3082/Angstrom/arcmin34#34 34#342)

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/m308#3082/Hz are used. TabOK Should the FITS-WCS -TAB algorithm be recognised? This attribute is an integer value which indicates if the " -TAB" algorithm, defined in FITS-WCS paper III, should be supported by the FitsChanFitsChan. The default value is zero. A zero or negative value results in no support for -TAB axes (i.e. axes that have " -TAB" in their CTYPE keyword value). In this case, the astWriteastWrite method will return zero if the write operation would required the use of the -TAB algorithm, and the astReadastRead method will return a NULL pointer if any axis in the supplied header uses the -TAB algorithm.

If TabOK is set to a non-zero positive integer, these methods will recognise and convert axes described by the -TAB algorithm, as follows:

The astWrite method will generate headers that use the -TAB algorithm (if possible) if no other known FITS-WCS algorithm can be used to describe the supplied FrameSetFrameSet (but see the ForceTabForceTab attribute). This will result in a table of coordinate values and index vectors being stored in the FitsChan. After the write operation, the calling application should check to see if such a table has been stored in the FitsChan. If so, the table should be retrived from the FitsChan using the astGetTablesastGetTables method, and the data (and headers) within it copied into a new FITS binary table extension. See astGetTables for more information. The FitsChan uses a FitsTableFitsTable object to store the table data and headers. This FitsTable will contain the required columns and headers as described by FITS-WCS paper III - the coordinates array will be in a column named " COORDS" , and the index vector(s) will be in columns named " INDEX1#1i2#2" (where 1#1i2#2 is the index of the corresponding FITS WCS axis). Note, index vectors are only created if required. The EXTNAME value will be set to the value of the AST__TABEXTNAME constant (currently " WCS-TAB" ). The EXTVER header will be set to the positive integer value assigned to the TabOK attribute. No value will be stored for the EXTLEVEL header, and should therefore be considered to default to 1.

The astRead method will generate a FrameSet from headers that use the -TAB algorithm so long as the necessary FITS binary tables are made available. There are two ways to do this: firstly, if the application knows which FITS binary tables will be needed, then it can create a Fitstable describing each such table and store it in the FitsChan (using method astPutTablesastPutTables or astPutTableastPutTable) before invoking the astRead method. Secondly, if the application does not know which FITS binary tables will be needed by astRead, then it can register a call-back function with the FitsChan using method astTableSourceastTableSource. This call-back function will be called from within astRead if and when a -TAB header is encountered. When called, its arguments will give the name, version and level of the FITS extension containing a required table. The call-back function should read this table from an external FITS file, and create a corresponding FitsTable which it should then return to astRead. Note, currently astRead can only handle -TAB headers that describe 1-dimensional (i.e. separable) axes. Integer. FitsChan All FitsChans have this attribute. TextGapType Controls the interpretation of attributes TextLabGap and TitleGap This attribute controls how the values supplied for attributes TextLabGap and TitleGapTitleGap are used. If the TextGapType value is " box" (the default), then the gaps are measured from the nearest edge of the bounding box enclosing all other parts of the annotated grid (excluding other descriptive labels). If the TextGapType value is " plot" , then the gaps are measured from the nearest edge of the plotting area.

Note, this attribute only affects the position from which the gaps are measured - the size of the gap should always be given as a fraction of the minimum dimension of the plotting area. String. PlotPlot All Plots have this attribute. TextLab(axis) Draw descriptive axis labels for a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether textual labels should be drawn to describe the quantity being represented on each axis of a PlotPlot. It takes a separate value for each physical axis of a Plot so that, for instance, the setting " TextLab(2)=1" specifies that descriptive labels should be drawn for the second axis.

If the TextLab value of a Plot axis is non-zero, then descriptive labels will be drawn for that axis, otherwise they will be omitted. The default behaviour is to draw descriptive labels if tick marks and numerical labels are being drawn around the edges of the plotting area (see the LabellingLabelling attribute), but to omit them otherwise. Integer (boolean). Plot All Plots have this attribute. The text used for the descriptive labels is derived from the Plot' s Label(axis)Label(axis) attribute, together with its Unit(axis)Unit(axis) attribute if appropriate (see the LabelUnits(axis)LabelUnits(axis) attribute).

The drawing of numerical axis labels for a Plot (which indicate values on the axis) is controlled by the NumLab(axis)NumLab(axis) attribute.

If no axis is specified, (e.g. " TextLab" instead of " TextLab(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the TextLab(1) value. TextLabGap(axis) Spacing of descriptive axis labels for a Plot This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining where descriptive axis labels are placed relative to the axes they describe. It takes a separate value for each physical axis of a PlotPlot so that, for instance, the setting " TextLabGap(2)=0.01" specifies where the descriptive label for the second axis should be drawn.

For each axis, the TextLabGap value gives the spacing between the descriptive label and a reference point specified by the TextGapTypeTextGapType attribute (by default, the edge of a box enclosing all other parts of the annotated grid, excluding other descriptive labels). The gap is measured to the nearest edge of the label (i.e. the top or the bottom). Positive values cause the descriptive label to be placed outside the bounding box, while negative values cause it to be placed inside.

The TextLabGap value should be given as a fraction of the minimum dimension of the plotting area, the default value depends on the value of attribute TextGapType: if TextGapType is " box" , the default is 241#2410.01, otherwise the default is 241#2410.07. Floating point. Plot All Plots have this attribute. If drawn, descriptive labels are always placed at the edges of the plotting area, even although the corresponding numerical labels may be drawn along axis lines in the interior of the plotting area (see the LabellingLabelling attribute).

If no axis is specified, (e.g. " TextLabGap" instead of " TextLabGap(2)" ), then a " set" or " clear" operation will affect the attribute value of all the Plot axes, while a " get" or " test" operation will use just the TextLabGap(1) value. TickAll Draw tick marks on all edges of a Plot? This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining whether tick marks should be drawn on all edges of a PlotPlot.

If the TickAll value of a Plot is non-zero (the default), then tick marks will be drawn on all edges of the Plot. Otherwise, they will be drawn only on those edges where the numerical and descriptive axis labels are drawn (see the Edge(axis)Edge(axis) attribute). Integer (boolean). Plot All Plots have this attribute. In some circumstances, numerical labels and tick marks are drawn along grid lines inside the plotting area, rather than around its edges (see the LabellingLabelling attribute). In this case, the value of the TickAll attribute is ignored. TimeOrigin The zero point for TimeFrame axis values This specifies the origin from which all time values are measured. The default value (zero) results in the TimeFrameTimeFrame describing absolute time values in the system given by the SystemSystem attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time. Floating point. TimeFrame All TimeFrames have this attribute. Input Formats The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:

Besselian EpochEpoch: Expressed in decimal years, with or without decimal places (" B1950" or " B1976.13" for example).

Julian Epoch: Expressed in decimal years, with or without decimal places (" J2000" or " J2100.9" for example).

Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame' s System attribute, in the units given by the TimeFrame' s Unit attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value (" 123.4 d" for example), in which case the supplied value is scaled into the units specified by the Unit attribute.

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 TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame' s System, in the unit specified by the TimeFrame' s Unit attribute. TimeScale Time scale This attribute identifies the time scale to which the time axis values of a TimeFrameTimeFrame refer, and may take any of the values listed in the " Time Scales" section (below).

The default TimeScale value depends on the current SystemSystem value; if the current TimeFrame system is " Besselian epoch" the default is " TT" , otherwise it is " TAI" . Note, if the System attribute is set so that the TimeFrame represents Besselian EpochEpoch, then an error will be reported if an attempt is made to set the TimeScale to anything other than TT.

Note, the supported time scales fall into two groups. The first group containing UT1, GMST, LAST and LMST define time in terms of the orientation of the earth. The second group (containing all the remaining time scales) define time in terms of an atomic process. Since the rate of rotation of the earth varies in an unpredictable way, conversion between two timescales in different groups relies on a value being supplied for the Dut1Dut1 attribute (defined by the parent FrameFrame class). This attribute specifies the difference between the UT1 and UTC time scales, in seconds, and defaults to zero. See the documentation for the Dut1 attribute for further details. String. TimeFrame All TimeFrames have this attribute. Time Scales The TimeFrame class supports the following TimeScale values (all are case-insensitive):

" TAI" - International Atomic Time

" UTC" - Coordinated Universal Time

" UT1" - Universal Time

" GMST" - Greenwich Mean Sidereal Time

" LAST" - Local Apparent Sidereal Time

" LMST" - Local Mean Sidereal Time

" TT" - Terrestrial Time

" TDB" - Barycentric Dynamical Time

" TCB" - Barycentric Coordinate Time

" TCG" - Geocentric Coordinate Time

" LT" - Local Time (the offset from UTC is given by attribute LTOffsetLTOffset)

An very informative description of these and other time scales is available at http://www.ucolick.org/309#309sla/leapsecs/timescales.html. UTC WarningsWarnings UTC should ideally be expressed using separate hours, minutes and seconds fields (or at least in seconds for a given date) if leap seconds are to be taken into account. Since the TimeFrame class represents each moment in time using a single floating point number (the axis value) there will be an ambiguity during a leap second. Thus an error of up to 1 second can result when using AST to convert a UTC time to another time scale if the time occurs within a leap second. Leap seconds occur at most twice a year, and are introduced to take account of variation in the rotation of the earth. The most recent leap second occurred on 1st January 1999. Although in the vast majority of cases leap second ambiguities won' t matter, there are potential problems in on-line data acquisition systems and in critical applications involving taking the difference between two times. Title Frame title This attribute holds a string which is used as a title in (e.g.) graphical output to describe the coordinate system which a FrameFrame 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. String. Frame The default supplied by the Frame class is " 1#1n2#2-d coordinate system" , where 1#1n2#2 is the number of Frame axes (NaxesNaxes attribute). CmpFrameCmpFrame The CmpFrame class re-defines the default Title value to be " 1#1n2#2-d compound coordinate system" , where 1#1n2#2 is the number of CmpFrame axes (Naxes attribute). FrameSetFrameSet The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the CurrentCurrent attribute). A Frame' s Title is intended purely for interpretation by human readers and not by software. TitleGap Vertical spacing for a Plot title This attribute controls the appearance of an annotated coordinate grid (drawn with the astGridastGrid function) by determining where the title of a PlotPlot is drawn.

Its value gives the spacing between the bottom edge of the title and a reference point specified by the TextGapTypeTextGapType attribute (by default, the top edge of a box enclosing all other parts of the annotated grid). Positive values cause the title to be drawn outside the box, while negative values cause it to be drawn inside.

The TitleGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being 241#2410.05. Floating point. Plot All Plots have this attribute. Plot3DPlot3D The Plot3D class ignores this attributes since it does not draw a TitleTitle. The text used for the title is obtained from the Plot' s Title attribute. Tol Plotting tolerance This attribute specifies the plotting tolerance (or resolution) to be used for the graphical output produced by a PlotPlot. Smaller values will result in smoother and more accurate curves being drawn, but may slow down the plotting process. Conversely, larger values may speed up the plotting process in cases where high resolution is not required.

The Tol value should be given as a fraction of the minimum dimension of the plotting area, and should lie in the range from 1.0e-7 to 1.0. By default, a value of 0.01 is used. Floating point. Plot All Plots have this attribute. TolInverse Target relative error for the iterative inverse transformation This attribute controls the iterative inverse transformation used if the IterInverseIterInverse attribute is non-zero.

Its value gives the target relative error in the axis values of each transformed position. Further iterations will be performed until the target relative error is reached, or the maximum number of iterations given by attribute NiterInverseNiterInverse is reached.

The default value is 1.0E-6. Floating point. PolyMapPolyMap All PolyMaps have this attribute. Top(axis) Highest axis value to display This attribute gives the highest axis value to be displayed (for instance, by the astGridastGrid method). Floating point. FrameFrame The default supplied by the Frame class is to display all axis values, without any limit. SkyFrameSkyFrame The SkyFrame class re-defines the default Top value to 241#24190 degrees for latitude axes, and 180 degrees for co-latitude axes. The default for longitude axes is to display all axis values. When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. TranForward Forward transformation defined? This attribute indicates whether a MappingMapping is able to transform coordinates in the " forward" direction (i.e. converting input coordinates into output coordinates). If this attribute is non-zero, the forward transformation is available. Otherwise, it is not. Integer (boolean), read-only. Mapping All Mappings have this attribute. CmpMapCmpMap The TranForward attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping. FrameSetFrameSet The TranForward attribute of a FrameSet applies to the transformation which converts between the FrameSet' s base FrameFrame and its current Frame (as specified by the BaseBase and CurrentCurrent attributes). This value is given by the boolean AND of the TranForward values which apply to each of the individual sub-Mappings required to perform this conversion. The TranForward attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected. An error will result if a Mapping with a TranForward value of zero is used to transform coordinates in the forward direction. TranInverse Inverse transformation defined? This attribute indicates whether a MappingMapping is able to transform coordinates in the " inverse" direction (i.e. converting output coordinates back into input coordinates). If this attribute is non-zero, the inverse transformation is available. Otherwise, it is not. Integer (boolean), readonly. Mapping All Mappings have this attribute. CmpMapCmpMap The TranInverse attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping. FrameSetFrameSet The TranInverse attribute of a FrameSet applies to the transformation which converts between the FrameSet' s current FrameFrame and its base Frame (as specified by the CurrentCurrent and BaseBase attributes). This value is given by the boolean AND of the TranInverse values which apply to each of the individual sub-Mappings required to perform this conversion. The TranInverse attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected. An error will result if a Mapping with a TranInverse value of zero is used to transform coordinates in the inverse direction. Unit(axis) Physical units for formatted axis values This attribute contains a textual representation of the physical units used to represent formatted coordinate values on a particular axis of a FrameFrame. The astSetActiveUnitastSetActiveUnit function controls how the Unit values are used. String. Frame The default supplied by the Frame class is an empty string. SkyFrameSkyFrame The SkyFrame class re-defines the default Unit value (e.g. to " hh:mm:ss.sss" ) to describe the character string returned by the astFormatastFormat function when formatting coordinate values. SpecFrameSpecFrame The SpecFrame class re-defines the default Unit value so that it is appropriate for the current SystemSystem value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit. TimeFrameTimeFrame 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" ). FrameSetFrameSet The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the CurrentCurrent attribute). This attribute described the units used when an axis value is formatted into a string using astFormat. 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.

When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. UnitRadius SphMap input vectors lie on a unit sphere? This is a boolean attribute which indicates whether the 3-dimensional vectors which are supplied as input to a SphMapSphMap are known to always have unit length, so that they lie on a unit sphere centred on the origin.

If this condition is true (indicated by setting UnitRadius non-zero), it implies that a CmpMapCmpMap which is composed of a SphMap applied in the forward direction followed by a similar SphMap applied in the inverse direction may be simplified (e.g. by astSimplifyastSimplify) to become a UnitMapUnitMap. This is because the input and output vectors will both have unit length and will therefore have the same coordinate values.

If UnitRadius is zero (the default), then although the output vector produced by the CmpMap (above) will still have unit length, the input vector may not have. This will, in general, change the coordinate values, so it prevents the pair of SphMaps being simplified. Integer (boolean). SphMap All SphMaps have this attribute. This attribute is intended mainly for use when SphMaps are involved in a sequence of Mappings which project (e.g.) a dataset on to the celestial sphere. By regarding the celestial sphere as a unit sphere (and setting UnitRadius to be non-zero) it becomes possible to cancel the SphMaps present, along with associated sky projections, when two datasets are aligned using celestial coordinates. This often considerably improves performance.

Such a situations often arises when interpreting FITS data and is handled automatically by the FitsChanFitsChan class.

The value of the UnitRadius attribute is used only to control the simplification of Mappings and has no effect on the value of the coordinates transformed by a SphMap. The lengths of the input 3-dimensional Cartesian vectors supplied are always ignored, even if UnitRadius is non-zero.

The value of this attribute may changed only if the SphMap has no more than one reference. That is, an error is reported if the SphMap has been cloned, either by including it within another object such as a CmpMap or FrameSetFrameSet or by calling the astCloneastClone function. UseDefs Use default values for unspecified attributes? This attribute specifies whether default values should be used internally for object attributes which have not been assigned a value explicitly. If a non-zero value (the default) is supplied for UseDefs, then default values will be used for attributes which have not explicitly been assigned a value. If zero is supplied for UseDefs, then an error will be reported if an attribute for which no explicit value has been supplied is needed internally within AST.

Many attributes (including the UseDefs attribute itself) are unaffected by the setting of the UseDefs attribute, and default values will always be used without error for such attributes. The " Applicability:" section below lists the attributes which are affected by the setting of UseDefs.

Note, UseDefs only affects access to attributes internally within AST. The public accessor functions such as astGetC is unaffected by the UseDefs attribute - default values will always be returned if no value has been set. Application code should use the astTestastTest function if required to determine if a value has been set for an attribute. Integer (boolean). ObjectObject All Objects have this attribute, but ignore its setting except as described below for individual classes. FrameSetFrameSet The default value of UseDefs for a FrameSet is redefined to be the UseDefs value of its current FrameFrame. CmpFrameCmpFrame The default value of UseDefs for a CmpFrame is redefined to be the UseDefs value of its first component Frame. RegionRegion The default value of UseDefs for a Region is redefined to be the UseDefs value of its encapsulated Frame. Frame If UseDefs is zero, an error is reported when aligning Frames if the EpochEpoch, ObsLatObsLat or ObsLonObsLon attribute is required but has not been assigned a value explicitly. SkyFrameSkyFrame If UseDefs is zero, an error is reported when aligning SkyFrames if any of the following attributes are required but have not been assigned a value explicitly: Epoch, EquinoxEquinox. SpecFrameSpecFrame If UseDefs is zero, an error is reported when aligning SpecFrames if any of the following attributes are required but have not been assigned a value explicitly: Epoch, RefRARefRA, RefDecRefDec, RestFreqRestFreq, SourceVelSourceVel, StdOfRestStdOfRest. DSBSpecFrameDSBSpecFrame If UseDefs is zero, an error is reported when aligning DSBSpecFrames or when accessing the ImagFreqImagFreq attribute if any of the following attributes are required but have not been assigned a value explicitly: Epoch, DSBCentreDSBCentre, IFIF. Variant Indicates which variant of the current Frame is to be used This attribute can be used to change the MappingMapping that connects the current FrameFrame to the other Frames in the FrameSetFrameSet. By default, each Frame in a FrameSet is connected to the other Frames by a single Mapping that can only be changed by using the astRemapFrameastRemapFrame method. However, it is also possible to associate multiple Mappings with a Frame, each Mapping having an identifying name. If this is done, the " Variant" attribute can be set to indicate the name of the Mapping that is to be used with the current Frame.

A possible (if unlikely) use-case is to create a FrameSet that can be used to describe the WCS of an image formed by co-adding images of two different parts of the sky. In such an image, each pixel contains flux from two points on the sky.and so the WCS for the image should ideally contain one pixel Frame and two SkyFrames - one describing each of the two co-added images. There is nothing to prevent a FrameSet containing two explicit SkyFrames, but the problem then arises of how to distinguish between them. The two primary characteristics of a Frame that distinguishes it from other Frames are its class and its DomainDomain attribute value. The class of a Frame cannot be changed, but we could in principle use two different Domain values to distinguish the two SkyFrames. However, in practice it is not uncommon for application software to assume that SkyFrames will have the default Domain value of " SKY" . That is, instead of searching for Frames that have a class of " SkyFrameSkyFrame" , such software searches for Frames that have a Domain of " SKY" . To alleviate this problem, it is possible to add a single SkyFrame to the FrameSet, but specifying two alternate Mappings to use with the SkyFrame. Setting the " Variant" attribute to the name of one or the other of these alternate Mappings will cause the SkyFrame to be remapped within the FrameSet so that it uses the specified Mapping. The same facility can be used with any class of Frame, not just SkyFrames.

To use this facility, the Frame should first be added to the FrameSet in the usual manner using the astAddFrameastAddFrame method. By default, the Mapping supplied to astAddFrame is assigned a name equal to the Domain name of the Frame. To assign a different name to it, the astAddVariantastAddVariant method should then be called specifying the required name and a NULL Mapping. The astAddVariant method should then be called repeatedly to add each required extra Mapping to the current Frame, supplying a unique name for each one.

Each Frame in a FrameSet can have its own set of variant Mappings. To control the Mappings in use with a specific Frame, you need first to make it the current Frame in the FrameSet.

The astMirrorVariantsastMirrorVariants function allows the effects of variant Mappings associated with a nominated Frame to be propagated to other Frames in the FrameSet.

Once this has been done, setting a new value for the " Variant" attribute of a FrameSet will cause the current Frame in the FrameSet to be remapped to use the specified variant Mapping. An error will be reported if the current Frame has no variant Mapping with the supplied name.

Getting the value of the " Variant" attribute will return the name of the variant Mapping currently in use with the current Frame. If the Frame has no variant Mappings, the value will default to the Domain name of the current Frame.

Clearing the " Variant" attribute will have the effect of removing all variant Mappings (except for the currently selected Mapping) from the current Frame.

Testing the " Variant" attribute will return a non-zero value if the current Frame contains any variant Mappings, and zero otherwise.

A complete list of the names associated with all the available variant Mappings in the current Frame can be obtained from the AllVariantsAllVariants attribute.

If a Frame with variant Mappings is remapped using the astRemapFrame method, the currently selected variant Mapping is used by astRemapFrame and the other variant Mappings are removed from the Frame. String. FrameSet All FrameSets have this attribute. VerboseRead Echo YAML text to standard output as it is read? This is a boolean attribute which indicates whether YAML text should be displayed on standard output as it is read. Doing so can help to locate YAML syntax errors reported by libyaml. The default is zero (i.e. the text is not echoed by default). Integer (boolean). All yamlchans have this attribute. Warnings Controls the issuing of warnings about various conditions This attribute controls the issuing of warnings about selected conditions when an ObjectObject or keyword is read from or written to a FitsChanFitsChan. The value supplied for the Warnings attribute should consist of a space separated list of condition names (see the AllWarningsAllWarnings attribute for a list of the currently defined names). Each name indicates a condition which should be reported. The default value for Warnings is the string " BadKeyName BadKeyValue Tnx Zpx BadCel BadMat BadPV BadCTYPE" .

The text of any warning will be stored within the FitsChan in the form of one or more new header cards with keyword ASTWARN. If required, applications can check the FitsChan for ASTWARN cards (using astFindFitsastFindFits) after the call to astReadastRead or astWriteastWrite has been performed, and report the text of any such cards to the user. ASTWARN cards will be propagated to any output header unless they are deleted from the FitsChan using astDelFitsastDelFits. String FitsChan All FitsChans have this attribute. This attribute only controls the warnings that are to be stored as a set of header cards in the FitsChan as described above. It has no effect on the storage of warnings in the parent ChannelChannel structure. All warnings are stored in the parent Channel structure, from where they can be retrieved using the astWarningsastWarnings function. WcsAxis(lonlat) FITS-WCS projection axes This attribute gives the indices of the longitude and latitude coordinates of the FITS-WCS projection within the coordinate space used by a WcsMapWcsMap. These indices are defined when the WcsMap is first created using astWcsMapastWcsMap and cannot subsequently be altered.

If " lonlat" is 1, the index of the longitude axis is returned. Otherwise, if it is 2, the index of the latitude axis is returned. Integer, read-only. WcsMap All WcsMaps have this attribute. WcsType FITS-WCS projection type This attribute specifies which type of FITS-WCS projection will be performed by a WcsMapWcsMap. The value is specified when a WcsMap is first created using astWcsMapastWcsMap and cannot subsequently be changed.

The values used are represented by macros with names of the form " AST__XXX" , where " XXX" is the (upper case) 3-character code used by the FITS-WCS " CTYPEi" keyword to identify the projection. For example, possible values are AST__TAN (for the tangent plane or gnomonic projection) and AST__AIT (for the Hammer-Aitoff projection). AST__TPN is an exception in that it is not part of the FITS-WCS standard (it represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper). Integer, read-only. WcsMap All WcsMaps have this attribute. For a list of available projections, see the FITS-WCS paper. Width(element) Line width for a Plot element This attribute determines the line width used when drawing each element of graphical output produced by a PlotPlot. It takes a separate value for each graphical element so that, for instance, the setting " Width(border)=2.0" causes the Plot border to be drawn using a line width of 2.0. A value of 1.0 results in a line thickness which is approximately 0.0005 times the length of the diagonal of the entire display surface.

The actual appearance of lines drawn with any particular width, and the range of available widths, is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default line width supplied by this graphics system. This will not necessarily correspond to a Width value of 1.0. Floating point. Plot All Plots have this attribute. For a list of the graphical elements available, see the description of the Plot class.

If no graphical element is specified, (e.g. " Width" instead of " Width(border)" ), then a " set" or " clear" operation will affect the attribute value of all graphical elements, while a " get" or " test" operation will use just the Width(BorderBorder) value. XmlFormat System for formatting Objects as XML This attribute specifies the formatting system to use when AST Objects are written out as XML through an XmlChanXmlChan. It affects the behaviour of the astWriteastWrite function when they are used to transfer any AST ObjectObject to or from an external XML representation.

The XmlChan class allows AST objects to be represented in the form of XML in several ways (conventions) and the XmlFormat attribute is used to specify which of these should be used. The formatting options available are outlined in the " Formats Available" section below.

By default, an XmlChan will attempt to determine which format system is already in use, and will set the default XmlFormat value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical items which only occur in particular formats. For details of how this works, see the " Choice of Default Format" section below. If you wish to ensure that a particular format system is used, independently of any XML already read, you should set an explicit XmlFormat value yourself. String. XmlChan All XmlChans have this attribute. Formats Available The XmlFormat attribute can take any of the following (case insensitive) string values to select the corresponding formatting system:

" NATIVE" : This is a direct conversion to XML of the heirarchical format used by a standard XML channel (and also by the NATIVE encoding of a FitsChanFitsChan).

" QUOTED" : This is the same as NATIVE format except that extra information is included which allows client code to convert the XML into a form which can be read by a standard AST ChannelChannel. This extra information indicates which AST attribute values should be enclosed in quotes before being passed to a Channel.

" IVOA" : This is a format that uses an early draft of the STC-X schema developed by the International Virtual Observatory Alliance (IVOA - see " http://www.ivoa.net/" ) to describe coordinate systems, regions, mappings, etc. Support is limited to V1.20 described at " http://www.ivoa.net/Documents/WD/STC/STC-20050225.html" . Since the version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, this format is now mainly of historical interest. Note, the alternative " STC-S" format (a simpler non-XML encoding of the STC metadata) is supported by the StcsChanStcsChan class. Choice of Default Format; If the XmlFormat attribute of an XmlChan is not set, the default value it takes is determined by the presence of certain critical items within the document most recently read using astReadastRead. The sequence of decision used to arrive at the default value is as follows:

If the previous document read contained any elements in any of the STC namespaces (" urn:nvo-stc" , " urn:nvo-coords" or " urn:nvo-region" ), then the default value is IVOA.

If the previous document read contained any elements in the AST namespace which had an associated XML attribute called " quoted" , then the default value is QUOTED.

Otherwise, if none of these conditions is met (as would be the case if no document had yet been read), then NATIVE format is used.

Setting an explicit value for the XmlFormat attribute always over-rides this default behaviour. The IVOA Format The IVOA support caters only for certain parts of V1.20 of the draft Space-Time Coordinate (STC) schema (see http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this draft has now been superceded by an officially adopted version that differs in several significant respects from V1.20. Consequently, the " IVOA" XmlChan format is of historical interest only.

The following points should be noted when using an XmlChan to read or write STC information (note, this list is currently incomplete):

Objects can currently only be read using this format, not written.

The AST object generated by reading an 1#1STCMetadata2#2 element will be an instance of one of the AST " StcStc" classes: StcResourceProfileStcResourceProfile, StcSearchLocationStcSearchLocation, StcCatalogEntryLocationStcCatalogEntryLocation, StcObsDataLocationStcObsDataLocation.

When reading an 1#1STCMetadata2#2 element, the axes in the returned AST Object will be in the order space, time, spectral, redshift, irrespective of the order in which the axes occur in the 1#1STCMetadata2#2 element. If the supplied 1#1STCMetadata2#2 element does not contain all of these axes, the returned AST Object will also omit them, but the ordering of those axes which are present will be as stated above. If the spatial frame represents a celestial coordinate system the spatial axes will be in the order (longitude, latitude).

Until such time as the AST TimeFrameTimeFrame is complete, a simple 1-dimensional FrameFrame (with DomainDomain set to TIME) will be used to represent the STC 1#1TimeFrame2#2 element. Consequently, most of the information within a 1#1TimeFrame2#2 element is currently ignored.

1#1SpaceFrame2#2 elements can only be read if they describe a celestial longitude and latitude axes supported by the AST SkyFrameSkyFrame class. The space axes will be returned in the order (longitude, latitude).

Velocities associated with SpaceFrames cannot be read.

Any 1#1GenericCoordFrame2#2 elements within an 1#1AstroCoordSystem2#2 element are currently ignored.

Any second or subsequent 1#1AstroCoordSystem2#2 found within an STCMetaData element is ignored.

Any second or subsequent 1#1AstroCoordArea2#2 found within an STCMetaData element is ignored.

Any 1#1OffsetCenter2#2 found within a 1#1SpaceFrame2#2 is ignored.

Any CoordFlavor element found within a 1#1SpaceFrame2#2 is ignored.

1#1SpaceFrame2#2 elements can only be read if they refer to one of the following space reference frames: ICRS, GALACTIC_II, SUPER_GALACTIC, HEE, FK4, FK5, ECLIPTIC.

1#1SpaceFrame2#2 elements can only be read if the reference position is TOPOCENTER. Also, any planetary ephemeris is ignored.

Regions: there is currently no support for STC regions of type Sector, ConvexHull or SkyIndex.

The AST RegionRegion read from a CoordInterval element is considered to be open if either the lo_include or the hi_include attribute is set to false.

1#1RegionFile2#2 elements are not supported.

Vertices within 1#1PolygonPolygon2#2 elements are always considered to be joined using great circles (that is, 1#1SmallCircle2#2 elements are ignored). XmlLength Controls output buffer length This attribute specifies the maximum length to use when writing out text through the sink function supplied when the XmlChanXmlChan was created.

The number of characters in each string written out through the sink function will not be greater than the value of this attribute (but may be less). A value of zero (the default) means there is no limit - each string can be of any length. Integer. XmlChan All XmlChans have this attribute. XmlPrefix The namespace prefix to use when writing This attribute is a string which is to be used as the namespace prefix for all XML elements created as a result of writing an AST ObjectObject out through an XmlChanXmlChan. The URI associated with the namespace prefix is given by the symbolic constant AST__XMLNS defined in ast.h. A definition of the namespace prefix is included in each top-level element produced by the XmlChan.

The default value is a blank string which causes no prefix to be used. In this case each top-level element will set the default namespace to be the value of AST__XMLNS. String. Object All Objects have this attribute. YamlEncoding System for formatting Objects as YAML This attribute specifies the formatting system to use when AST Objects are written out as YAML through a YamlChanYamlChan. It affects the behaviour of the astWriteastWrite function when they are used to transfer any AST ObjectObject to or from an external XML representation. String. YamlChan All YamlChans have this attribute. Formats Available The YamlEncoding attribute can take any of the following (case insensitive) string values to select the corresponding formatting system:

" ASDF" : Currently, this is the only schema supported by the YamlChan class. It is defined by the Space Telescope Science Institute. (see http://asdf-standard.readthedocs.io). See below for details of the support this class provides for reading and writing ASDF objects. In future, the YamlChan class may allow AST objects to be represented in other ways (e.g. AST Native format). Notes on Reading ASDF WCS Information This class does not currently support the complete ASDF WCS schema. When reading an AST Object from an ASDF YAML file, the following restrictions on the ASDF file apply:

The ASDF spectral_frame, temporal_frame and composite_frame classes are not supported.

Only the following celestial coordinate frames are supported: icrs, fk4, fk4noeterms, fk5, galactic, supergalactic, altaz, barycentricmeanecliptic.

Earth locations must be specified using the WGS84 ellipsoid.

Times must be specified in one of the following formats: iso, byear, jyear, jd, mjd.

Only the following transform classes are supported: identity, scale, multiplyscale, remap_axes, shift, compose, concatenate, constant, fix_inputs, affine, rotate2d, rotate_sequence_3d, rotate3d, linear1d, ortho_polynomial (chebyshev only), planar2d, polynomial. In addition, all sky projections are supported. Notes on Writing ASDF WCS Information This class does not currently support the complete ASDF WCS schema. When writing an AST Object to an ASDF YAML file, the following restrictions on the AST object apply:

Only Frames, Mappings and FrameSets can be written.

Frames must be basic Frames or SkyFrames.

The following SkyFrameSkyFrame systems are not supported: GAPPT, HELIOECLIPTIC, J2000, UNKNOWN.

Only the following MappingMapping classes are supported: CmpMapCmpMap, TranMapTranMap, UnitMapUnitMap, ZoomMapZoomMap, ShiftMapShiftMap, WinMapWinMap, MatrixMapMatrixMap, PermMapPermMap, WcsMapWcsMap, PolyMapPolyMap, ChebyMapChebyMap. Zoom ZoomMap scale factor This attribute holds the ZoomMapZoomMap scale factor, by which coordinate values are multiplied. The default value is unity.

Note that the returned value describes the multiplication factor applied to the inputs by the forward transformation of the ZoomMap assuming the ZoomMap has not been inverted. If the ZoomMap has been inverted (e.g. by using astInvertastInvert), then the reciprocal of the returned factor will, in effect, be used by the forward transformation of the ZoomMap.

In general, MappingMapping attributes cannot be changed after the Mapping has been created (the exception to this is the InvertInvert attribute, which can be changed at any time). However, several of the oldest Mapping classes - including the ZoomMap class - were introduced into the AST library before this restriction was enforced. To reduce the chances of breaking existing software, the attributes of such Mappings may still be changed, but only for Mapping instances that have exactly one active reference. In other words, an error will be reported if an attempt is made to set or clear an attribute of a Mapping (other than the Invert attribute) if that Mapping has been cloned. Mappings are cloned when they are incorporated into another object such as a CmpMapCmpMap or FrameSetFrameSet, or when the astCloneastClone function is used. Double precision. ZoomMap All ZoomMaps have this attribute. The Zoom attribute may not be set to zero.