AST Function Descriptions

astSet Set attribute values for an Object This function assigns a set of attribute values to an ObjectObject, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form:

" attribute_1 = value_1, attribute_2 = value_2, ... "

where " attribute_n" specifies an attribute name, and the value to the right of each " =" sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute' s data type.

The string supplied may also contain " printf" -style format specifiers, identified by " %" signs in the usual way. If present, these will be substituted by values supplied as additional optional arguments (using the normal " printf" rules) before the string is used. Synopsis void astSet( AstObject $*$this, const char $*$settings, ... ) this Pointer to the Object. settings Pointer to a null-terminated character string containing a comma-separated list of attribute settings in the form described above. ... Optional additional arguments which supply values to be substituted for any " printf" -style format specifiers that appear in the " settings" string. Object This function applies to all Objects. astSet( map, " ReportReport = 1, ZoomZoom = 25.0" ); Sets the Report attribute for Object " map" to the value 1 and the Zoom attribute to 25.0. astSet( frame, " Label( %d ) =Offset along axis %d" , axis, axis ); Sets the Label(axis)Label(axis) attribute for Object " frame" to a suitable string, where the axis number is obtained from " axis" , a variable of type int. astSet( frame, " TitleTitle =%s" , mystring ); Sets the Title attribute for Object " frame" to the contents of the string " mystring" . Attribute names are not case sensitive and may be surrounded by white space.

White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned).

To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. Alternatively, you can use " %s" format and supply the value as a separate additional argument to astSet (or use the astSetC function instead).

The same procedure may be adopted if " %" signs are to be included and are not to be interpreted as format specifiers (alternatively, the " printf" convention of writing " %%" may be used).

An error will result if an attempt is made to set a value for a read-only attribute. astActiveObjects Return pointers for all active Objects This function returns a KeyMapKeyMap holding currently active AST ObjectObject pointers. Each entry in the KeyMap will have a key that is an AST class name such as " FrameSetFrameSet" , " SkyFrameSkyFrame" , " ZoomMapZoomMap" , etc. The value of the entry will be a 1-dimensional list of pointers for objects of the same class. Note, the returned pointers should NOT be annulled when they are no longer needed.

The pointers to return in the KeyMap may be restricted either by class or by context level using the function arguments. Synopsis AstKeyMap $*$astActiveObjects( const char $*$class, int subclass, int current ) class If NULL, then the returned KeyMap will contain pointers ofr Objects of all classes. If not NULL, then " class" should be a pointer to a null-terminated string holding the name of an AST class. The returned KeyMap will contain pointers only for the specified class. See also " subclass" . subclass A Boolean flag indicating if all subclasses of the class specified by " class" should be included in the returned KeyMap. If zero, then subclass objects are not returned. Otherwise they are returned. The supplied " subclass" value is ignored if " class" is NULL. current A Boolean flag indicating if the returned list of pointers should be restricted to pointers issued within the current AST object context (see astBeginastBegin and astEndastEnd). astActiveObjects() A pointer to a new KeyMap holding the required object pointers. They KeyMap pointer should be annulled when it is no longer needed, but the object pointers within the KeyMap should not be annulled. A NULL pointer is returned if an error has occurred prior to calling this function.

The values stored in the KeyMap should be accessed as generic C pointers using the KeyMap " P" data type (e.g. using function astMapGetlemP etc). This function will only return objects locked by the currently executing thread.

The KeyMap pointer returned by this function is not included in the list of active objects stored in the KeyMap.

Objects that were created using the Fortran interface will have a null " file" value and will have a routine name equal to the upper case Fortran routine that issued the pointer (e.g. " AST_CLONE" , " AST_FRAME" , etc). astAddCell Adds a single HEALPix cell into an existing Moc This function modifies a MocMoc by combining it with a single specified HEALPix cell. The way in which they are combined is determined by the " cmode" parameter. Synopsis void astAddCell( AstMoc $*$this, int cmode, int order, int64_t npix ) this Pointer to the Moc to be modified. cmode Indicates how the Moc and specified cell are to be combined. Any of the following values may be supplied: AST__AND: If the specified cell is included in the Moc, it is removed. Otherwise the Moc is left unchanged.

AST__OR: If the specified cell is not included in the Moc, it is added. Otherwise the Moc is left unchanged.

AST__XOR: The specified cell is toggled - it is removed from the Moc if originally present, and it is added to the Moc if not originally present. order The HEALPix order of the cell. An error is reported if this is higher than the maximum order allowed in the Moc (as given by its MaxOrderMaxOrder attribute). If no value has been set for the MaxOrder attribute, calling this method causes it to be set to the supplied order value. So the highest order cells should usually be added first. npix The " npix" value identifying the required cell (see the MOC recommendation for more details). astAddColumn Add a new column definition to a table Adds the definition of a new column to the supplied table. Initially, the column is empty. Values may be added subsequently using the methods of the KeyMapKeyMap class. Synopsis void astAddColumn( AstTable $*$this, const char $*$name, int type, int ndim, int $*$dims, const char $*$unit ) this Pointer to the TableTable. name The column name. Trailing spaces are ignored (all other spaces are significant). The supplied string is converted to upper case. type The data type associated with the column. See " Applicability:" below. ndim The number of dimensions spanned by the values stored in a single cell of the column. Zero if the column holds scalar values. dims An array holding the the lengths of each of the axes spanned by the values stored in a single cell of the column. Ignored if the column holds scalara values. unit A string specifying the units of the column. Supply a blank string if the column is unitless. Table Tables can hold columns with any of the following data types - 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). FitsTableFitsTable FitsTables can hold columns with any of the following data types - 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). This function returns without action if a column already exists in the Table with the supplied name and properties. However an error is reported if any of the properties differ. astAddFrame Add a Frame to a FrameSet to define a new coordinate system This function adds a new FrameFrame and an associated MappingMapping to a FrameSetFrameSet so as to define a new coordinate system, derived from one which already exists within the FrameSet. The new Frame then becomes the FrameSet' s current Frame.

This function may also be used to merge two FrameSets, or to append extra axes to every Frame in a FrameSet. Synopsis void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map, AstFrame $*$frame ) this Pointer to the FrameSet. iframe The index of the Frame within the FrameSet which describes the coordinate system upon which the new one is to be based. This value should lie in the range from 1 to the number of Frames already in the FrameSet (as given by its NframeNframe attribute). As a special case, AST__ALLFRAMES may be supplied, in which case the axes defined by the supplied Frame are appended to every Frame in the FrameSet (see the Notes section for details). map Pointer to a Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index " iframe" ) into coordinates in the new system. The Mapping' s forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction. The supplied Mapping is ignored if parameter " iframe" is equal to AST__ALLFRAMES. frame Pointer to a Frame that describes the new coordinate system. Any class of Frame may be supplied (including Regions and FrameSets).

This function may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this parameter (see the Notes section for details). Deep copies of the supplied " mapping" and " frame" objects are stored within the modified FrameSet. So any changes made to the FrameSet after calling this method will have no effect on the supplied Mapping and Frame objects.

A value of AST__BASE or AST__CURRENT may be given for the " iframe" parameter to specify the base Frame or the current Frame respectively.

This function sets the value of the CurrentCurrent attribute for the FrameSet so that the new Frame subsequently becomes the current Frame.

The number of input coordinate values accepted by the supplied Mapping (its NinNin attribute) must match the number of axes in the Frame identified by the " iframe" parameter. Similarly, the number of output coordinate values generated by this Mapping (its NoutNout attribute) must match the number of axes in the new Frame.

As a special case, if a pointer to a FrameSet is given for the " frame" parameter, this is treated as a request to merge a pair of FrameSets. This is done by appending all the new Frames (in the " frame" FrameSet) to the original FrameSet, while preserving their order and retaining all the inter-relationships (i.e. Mappings) between them. The two sets of Frames are inter-related within the merged FrameSet by using the Mapping supplied. This should convert between the Frame identified by the " iframe" parameter (in the original FrameSet) and the current Frame of the " frame" FrameSet. This latter Frame becomes the current Frame in the merged FrameSet.

As another special case, if a value of AST__ALLFRAMES is supplied for parameter " iframe" , then the supplied Mapping is ignored, and the axes defined by the supplied Frame are appended to each Frame in the FrameSet. In detail, each Frame in the FrameSet is replaced by a CmpFrameCmpFrame containing the original Frame and the Frame specified by parameter " frame" . In addition, each Mapping in the FrameSet is replaced by a CmpMapCmpMap containing the original Mapping and a UnitMapUnitMap in parallel. The Nin and Nout attributes of the UnitMap are set equal to the number of axes in the supplied Frame. Each new CmpMap is simplified using astSimplifyastSimplify before being stored in the FrameSet. astAddMocData Adds a FITS binary table into an existing Moc This function modifies a MocMoc by combining it with a binary data array describing a MOC read from a FITS binary table. The way in which they are combined is determined by the " cmode" parameter. Synopsis void astAddMocData( AstMoc $*$this, int cmode, int negate, int maxorder, int len, int nbyte, const void $*$data ); this Pointer to the Moc to be modified. cmode Indicates how the Moc and data are to be combined. Any of the following values may be supplied: AST__AND: The modified Moc is the intersection of the original Moc and the data.

AST__OR: The modified Moc is the union of the original Moc and the data.

AST__XOR: The modified Moc is the exclusive disjunction of the original Moc and the data. negate If non-zero, the cells added to the Moc will be those included in the supplied data array. If zero, the cells added to the Moc will be those not included in the supplied data array. maxorder The maximum HEALPix order to use. If a negative value is supplied, the maximum order will be determined by searching the data array (this will take extra time). In either case, if a value has already been set for the MaxOrderMaxOrder attribute in the Moc, then the attribute value is used in preference to the value supplied for this parameter. Any HEALPix cells in the data array that refer to an order greater than " maxorder" are ignored. len The length of the supplied array (i.e. the number of 4 or 8 byte integer values it contains). Note, this class only supports binary MOCs with lengths that can be represented in a 4 byte signed integer. nbyte The number of bytes in each integer value stored in the supplied array. Must be 4 or 8. data Pointer to the data array holding a description of a MOC in the form used by FITS binary tables. See the IVOA MOC recommendation for details. The values in this array are signed integers, each with the number of bytes specified by parameter " nbyte" . The number of bytes in this array should be at least " len$*$nbyte" . If no value has yet been set for attribute MaxOrder, then this function will automatically set it to the value supplied for " Maxorder" , or to the largest order present in the supplied binary MOC if " Maxorder" is negative. astAddMocString Adds a JSON or string-encoded MOC into an existing Moc This function modifies a MocMoc by combining it with the MOC described by the supplied string - assumed to be encoded using either the string or JSON serialisation described in the MOC recommendation. The way in which they are combined is determined by the " cmode" parameter. Synopsis void astAddMocString( AstMoc $*$this, int cmode, int negate, int maxorder, size_t len, const char$*$string, int $*$json ); this Pointer to the Moc to be modified. cmode Indicates how the supplied MOC is to be combined with the existing Moc. Any of the following values may be supplied: AST__AND: The modified Moc is the intersection of the original Moc and the sipplied MOC.

AST__OR: The modified Moc is the union of the original Moc and the supplied MOC.

AST__XOR: The modified Moc is the exclusive disjunction of the original Moc and the supplied MOC. negate If non-zero, the cells added to the existing Moc will be those included in the supplied MOC. If zero, the cells added to the existing Moc will be those not included in the supplied MOC. maxorder The maximum HEALPix order to use. If a negative value is supplied, the maximum order will be determined by searching the supplied MOC (this will take extra time). In either case, if a value has already been set for the MaxOrderMaxOrder attribute in the Moc, then the attribute value is used in preference to the value supplied for this parameter. Any HEALPix cells in the supplied MOC that refer to an order greater than " maxorder" are ignored. len The number of characters to read from the supplied string. If this is greater than the length of the string, it is ignored and the whole string is read. string Pointer to the array of characters holding the supplied MOC. It should be encoded using either the string or JSON serialisation described in the MOC recommendation. The used serialisation is determined from the first non-blank character, which should be either a curly brace (' {' - JSON serialisation) or a digit (string serialisation). json Pointer to an int in which to return a boolean flag indicating if the supplied string was interpreted using the JSON (non-zero) or string (zero) serialisation. If no value has yet been set for attribute MaxOrder, then this function will automatically set it to the value supplied for " Maxorder" , or to the largest order present in the supplied string MOC if " Maxorder" is negative. astAddParameter Add a new global parameter definition to a table Adds the definition of a new global parameter to the supplied table. Note, this does not store a value for the parameter. To get or set the parameter value, the methods of the paremt KeyMapKeyMap class should be used, using the name of the parameter as the key. Synopsis void astAddParameter( AstTable $*$this, const char $*$name ) this Pointer to the TableTable. name The parameter name. Trailing spaces are ignored (all other spaces are significant). The supplied string is converted to upper case. Unlike columns, the definition of a parameter does not specify its type, size or dimensionality. astAddPixelMask$<$X$>$ Add a set of pixels to a Moc This is a set of functions that modifies a MocMoc by combining it with a subset of the pixel positions contained within a supplied 2-dimensional array. A FrameSetFrameSet must be supplied describing the World Coordinate Systems associated with the array. The current FrameFrame of this FrameSet must be a SkyFrameSkyFrame or a CmpFrameCmpFrame containing a SkyFrame.

The subset of pixels to be combined with the Moc are selected using the " value" and " oper" parameters. The way in which the existing Moc and the selected pixels are combined together is determined by the " cmode" parameter.

An adaptive alogorithm is used to find the HEALPix cells that are inside the selected area in the pixel array. An initial grid, corresponding to the HEALPix cells at the order given by the Moc' s " MinOrderMinOrder" attribute, is placed over the pixel array. Each of these cells is tested at 9 positions (corners, edge-centres and cell-centre). If all 9 positions are inside the selected area of pixels, then the whole cell is assumed to be inside. If no positions are inside the selected area, then the whole cell is assumed to be outside. If there is a mix of inside and outside positions, the cell is divided into four sub-cells at HEALPix order " MinOrder$+$1" , and the same test is applied to each sub-cell in turn. When the HEALPix order reaches the value of the Moc' s " MaxOrderMaxOrder" attribute, each cell is tested only at the cell centre, and is assumed to be inside the selected area if the cell centre is inside the selected area.

This process means that contiguous " islands" or " holes" in the supplied pixel mask may be missed if they are smaller than the cell size associated with HEALPix order " MinOrder" .

If no value has yet been set for the MaxOrder attribute, then this function will automatically set it to the smallest value that results in the cells in the Moc being no larger than half the size of the pixels in the centre of the array. Note, if the value set for attribute MinOrder is greater than or equal to MaxOrder, a value of (MaxOrder-1) will be used in place of MinOrder.

You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astAddPixelMask$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are procesing data with type " float" , you should use the function astAddPixelMaskF (see the " Data Type Codes" section below for the codes appropriate to other numerical types). Synopsis void astAddPixelMask$<$X$>$( AstMoc $*$this, int cmode, AstFrameSet $*$wcs, $<$Xtype$>$ value, int oper, int flags, $<$Xtype$>$ badval, const $<$Xtype$>$ array[], const int dims[2] ) this Pointer to the Moc to be modified. cmode Indicates how the Moc and select pixels are to be combined. Any of the following values may be supplied: AST__AND: The modified Moc is the intersection of the original Moc and the selected pixels.

AST__OR: The modified Moc is the union of the original Moc and the selected pixels.

AST__XOR: The modified Moc is the exclusive disjunction of the original Moc and the selected pixels. wcs Pointer to a FrameSet defining the World Coordinate Systems associated with the image. The current Frame should be a SkyFrame or a CmpFrame containing a SkyFrame. The base Frame should have the same number of axes as the current Frame and should represent " grid" coordinates within a pixel array (i.e. the first pixel is centred at (1.0,1.0,...) and the distance between pixel centres is 1.0 on both axes). The array supplied for parameter " array" is assumed to be a 2-dimensional slice from this array, spanned by the grid axes corresponding to the SkyFrame axes. value A data value that specifies the selected pixels. See parameter " oper" . oper Indicates how the " value" parameter is used to select the required pixels. It can have any of the following values: AST__LT: select pixels with value less than " value" .

AST__LE: select pixels with value less than or equal to " value" .

AST__EQ: select pixels with value equal to " value" .

AST__NE: select pixels with value not equal to " value" .

AST__GE: select pixels with value greater than or equal to " value" .

AST__GT: select pixels with value greater than " value" . flags The bitwise OR of a set of flag values which may be used to provide additional control over the operation. See the " Control Flags" section below for a description of the options available. If no flag values are to be set, a value of zero should be given. badval This parameter should have the same type as the elements of the data array. It specifies the value used to flag missing data (bad pixels). Such pixels are never included in the Moc.

If the AST__USEBAD flag is set via the " flags" parameter, then this value is used to test for bad pixels in the supplied data array. array Pointer to the 2-dimensional data array. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astAddPixelMaskF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly (i.e. Fortran array indexing is used). dims Pointer to an array containing the length of each pixel axis, in pixels. Control Flags The following flags are defined in the " ast.h" header file and may be used to provide additional control over the process. Having selected a set of flags, you should supply the bitwise OR of their values via the " flags" parameter:

AST__USEBAD: Indicates that there may be bad pixels in the input array which must be recognised by comparing with the value given for " badval" . If this flag is not set, all input values are treated literally. Data Type Codes To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astAddPixelMask$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

L: long int

UL: unsigned long int

I: int

UI: unsigned int

S: short int

US: unsigned short int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astAddPixelMaskD would be used to process " double" data, while astAddPixelMaskS would be used to process " short int" data, etc. Handling of Huge Pixel Arrays If the input grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the argument " dims" is changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astAddPixelMask$<$X$>$ becomes astAddPixelMask8$<$X$>$. astAddRegion Add a Region into a Moc This function modifies a MocMoc by combining it with a supplied RegionRegion. The Region must be defined within a SkyFrameSkyFrame, or within a CmpFrameCmpFrame that contains a SkyFrame. The Region will be converted to ICRS before being combined with the Moc. The way in which they are combined is determined by the " cmode" parameter.

Note, since Moc is a subclass of Region this method can be used to add a Moc into another Moc. In such cases, the data is transferred from one Moc to another directly. For other classes of Region an adaptive algorithm is used to find the HEALPix cells that are inside the Region. An initial grid, corresponding to the HEALPix cells at the order given by the Moc' s " MinOrderMinOrder" attribute, is placed over the bounding box of the supplied Region. Each of these cells is tested at 9 positions (corners, edge-centres and cell-centre). If all 9 positions are inside the supplied Region, then the whole cell is assumed to be inside the Region. If no positions are inside the supplied Region, then the whole cell is assumed to be outside the Region. If there is a mix of inside and outside positions, the cell is divided into four sub-cells at HEALPix order " MinOrder$+$1" , and the same test is applied to each sub-cell in turn. When the HEALPix order reaches the value of the Moc' s " MaxOrderMaxOrder" attribute, each cell is tested only at the cell centre, and is assumed to be inside the Region if the cell centre is in the Region.

This process means that contiguous " islands" or " holes" in the supplied region may be missed if they are smaller than the cell size associated with HEALPix order " MinOrder" . Synopsis void astAddRegion( AstMoc $*$this, int cmode, AstRegion $*$region ) this Pointer to the Moc to be modified. cmode Indicates how the Moc and Region are to be combined. Any of the following values may be supplied: AST__AND: The modified Moc is the intersection of the original Moc and the Region.

AST__OR: The modified Moc is the union of the original Moc and the Region.

AST__XOR: The modified Moc is the exclusive disjunction of the original Moc and the Region. region Pointer to the Region to be combined with the Moc. When combining the Region with the Moc, it is assumed that the Moc has not been inverted (i.e. the current value of the Moc' s ' NegatedNegated' attribute is ignored).

If no value has yet been set for attribute MaxOrder, then this function will automatically set it to a value that depends on the class of Region being added. If the Region being added is another Moc, the MaxOrder attribute of the Moc is used. For other classes of Region, the value used corresponds to the resolution closest to 0.1% of the linear size of the Region being added (determined using method astGetRegionDiscastGetRegionDisc). astAddVariant Store a new variant Mapping for the current Frame in a FrameSet This function allows a new variant MappingMapping to be stored with the current FrameFrame in a FrameSetFrameSet. See the " VariantVariant" attribute for more details. It can also be used to rename the currently selected variant Mapping. Synopsis void astAddVariant( AstFrameSet $*$this, AstMapping $*$map, const char $*$name ) this Pointer to the FrameSet. map Pointer to a Mapping which describes how to convert coordinates from the current Frame to the new variant of the current Frame. If NULL is supplied, then the name associated with the currently selected variant of the current Frame is set to the value supplied for " name" , but no new variant is added. name The name to associate with the new variant Mapping (or the currently selected variant Mapping if " map" is NULL). The newly added Variant becomes the current variant on exit (this is equivalent to setting the Variant attribute to the value supplied for " name).

An error is reported if a variant with the supplied name already exists in the current Frame.

An error is reported if the current Frame is a mirror for the variant Mappings in another Frame. This is only the case if the astMirrorVariantsastMirrorVariants function has been called to make the current Frame act as a mirror. astAngle Calculate the angle subtended by two points at a third point This function finds the angle at point B between the line joining points A and B, and the line joining points C and B. These lines will in fact be geodesic curves appropriate to the FrameFrame in use. For instance, in SkyFrameSkyFrame, they will be great circles. Synopsis double astAngle( AstFrame $*$this, const double a[], const double b[], const double c[] ) this Pointer to the Frame. a An array of double, with one element for each Frame axis (NaxesNaxes attribute) containing the coordinates of the first point. b An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates of the second point. c An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates of the third point. astAngle The angle in radians, from the line AB to the line CB. If the Frame is 2-dimensional, it will be in the range $$\backslash$pm $\backslash$pi$, and positive rotation is in the same sense as rotation from the positive direction of axis 2 to the positive direction of axis 1. If the Frame has more than 2 axes, a positive value will always be returned in the range zero to $$\backslash$pi$. A value of AST__BAD will also be returned if points A and B are co-incident, or if points B and C are co-incident.

A value of AST__BAD will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astAnnul Annul a pointer to an Object This function annuls a pointer to an ObjectObject so that it is no longer recognised as a valid pointer by the AST library. Any resources associated with the pointer are released and made available for re-use.

This function also decrements the Object' s RefCountRefCount attribute by one. If this attribute reaches zero (which happens when the last pointer to the Object is annulled), then the Object is deleted. Synopsis AstObject $*$astAnnul( AstObject $*$this ) this The Object pointer to be annulled. Object This function applies to all Objects. astAnnul() A null Object pointer (AST__NULL) is always returned. This function will attempt to annul the pointer even if the Object is not currently locked by the calling thread (see astLockastLock).

This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. In particular, it will fail if the pointer suppled is not valid, but this will only be reported if the error status is clear on entry. astAxAngle Returns the angle from an axis, to a line through two points This function finds the angle, as seen from point A, between the positive direction of a specified axis, and the geodesic curve joining point A to point B. Synopsis double astAxAngle( AstFrame $*$this, const double a[], const double b[], int axis ) this Pointer to the FrameFrame. a An array of double, with one element for each Frame axis (NaxesNaxes attribute) containing the coordinates of the first point. b An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates of the second point. axis The number of the Frame axis from which the angle is to be measured (axis numbering starts at 1 for the first axis). astAxAngle The angle in radians, from the positive direction of the specified axis, to the line AB. If the Frame is 2-dimensional, it will be in the range [-PI/2,$+$PI/2], and positive rotation is in the same sense as rotation from the positive direction of axis 2 to the positive direction of axis 1. If the Frame has more than 2 axes, a positive value will always be returned in the range zero to PI. The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistanceastDistance function.

This function will return " bad" coordinate values (AST__BAD) if any of the input coordinates has this value, or if the require position angle is undefined. astAxDistance Find the distance between two axis values This function returns a signed value representing the axis increment from axis value v1 to axis value v2.

For a simple FrameFrame, this is a trivial operation returning the difference between the two axis values. But for other derived classes of Frame (such as a SkyFrameSkyFrame) this is not the case. Synopsis double astAxDistance( AstFrame $*$this, int axis, double v1, double v2 ) this Pointer to the Frame. axis The index of the axis to which the supplied values refer. The first axis has index 1. v1 The first axis value. v2 The second axis value. astAxDistance The distance from the first to the second axis value. This function will return a " bad" result value (AST__BAD) if any of the input values has this value.

A " bad" value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astAxNorm Normalise an array of axis values This function modifies a supplied array of axis values so that they are normalised in the manner indicated by parameter " oper" .

No normalisation is possible for a simple FrameFrame and so the supplied values are returned unchanged. However, this may not be the case for specialised sub-classes of Frame. For instance, a SkyFrameSkyFrame has a discontinuity at zero longitude and so a longitude value can be expressed in the range [-Pi,$+$PI] or the range [0,2$*$PI]. See the " Applicability:" section below for details. Synopsis void astAxNorm( AstFrame $*$this, int axis, int oper, int nval, double $*$values, int $*$status ) this Pointer to the Frame. axis The index of the axis to which the supplied values refer. The first axis has index 1. oper Indicates the type of normalisation to be applied. If zero is supplied, the normalisation will be the same as that performed by function astNormastNorm. If 1 is supplied, the normalisation will be chosen automatically so that the resulting list has the smallest range. nval The number of points in the values array. values On entry, the axis values to be normalised. Modified on exit to hold the normalised values. SkyFrame If " oper" is 0, longitude values are returned in the range [0,2$*$PI]. If " oper" is 1, longitude values are returned in either the range [0,2$*$PI] or [-PI,PI]. The choice is made so that that the resulting list has the smallest range. Latitude values are always returned in the range [-PI,PI]. All other classes of Frame The supplied axis values are returned unchanged. astAxOffset Add an increment onto a supplied axis value This function returns an axis value formed by adding a signed axis increment onto a supplied axis value.

For a simple FrameFrame, this is a trivial operation returning the sum of the two supplied values. But for other derived classes of Frame (such as a SkyFrameSkyFrame) this is not the case. Synopsis double astAxOffset( AstFrame $*$this, int axis, double v1, double dist ) this Pointer to the Frame. axis The index of the axis to which the supplied values refer. The first axis has index 1. v1 The original axis value. dist The axis increment to add to the original axis value. astAxOffset The incremented axis value. This function will return a " bad" result value (AST__BAD) if any of the input values has this value.

A " bad" value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astBBuf Begin a new graphical buffering context This function starts a new graphics buffering context. A matching call to the function astEBufastEBuf should be used to end the context. Synopsis void astBBuf( AstPlot $*$this ) this Pointer to the PlotPlot. The nature of the buffering is determined by the underlying graphics system (as defined by the current grf module). Each call to this function to this function simply invokes the astGBBuf function in the grf module. astBegin Begin a new AST context This macro invokes a function to begin a new AST context. Any ObjectObject pointers created within this context will be annulled when it is later ended using astEndastEnd (just as if astAnnulastAnnul had been invoked), unless they have first been exported using astExportastExport or rendered exempt using astExemptastExempt. If annulling a pointer causes an Object' s RefCountRefCount attribute to fall to zero (which happens when the last pointer to it is annulled), then the Object will be deleted. Synopsis void astBegin Object This macro applies to all Objects. astBegin attempts to execute even if the AST error status is set on entry.

Contexts delimited by astBegin and astEnd may be nested to any depth. astBorder Draw a border around valid regions of a Plot This function draws a (line) border around regions of the plotting area of a PlotPlot which correspond to valid, unclipped physical coordinates. For example, when plotting using an all-sky map projection, this function could be used to draw the boundary of the celestial sphere when it is projected on to the plotting surface.

If the entire plotting area contains valid, unclipped physical coordinates, then the boundary will just be a rectangular box around the edges of the plotting area.

If the Plot is a Plot3DPlot3D, this method is applied individually to each of the three 2D Plots encapsulated within the Plot3D (each of these Plots corresponds to a single 2D plane in the 3D graphics system). In addition, if the entire plotting volume has valid coordinates in the 3D current FrameFrame of the Plot3D, then additional lines are drawn along the edges of the 3D plotting volume so that the entire plotting volume is enclosed within a cuboid grid. Synopsis int astBorder( AstPlot $*$this ) this Pointer to the Plot. astBorder() Zero is returned if the plotting space is completely filled by valid, unclipped physical coordinates (so that only a rectangular box was drawn around the edge). Otherwise, one is returned. A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

An error results if either the current Frame or the base Frame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.

An error also results if the transformation between the base and current Frames of the Plot is not defined (i.e. the Plot' s TranForwardTranForward attribute is zero). astBoundingBox Return a bounding box for previously drawn graphics This function returns the bounds of a box which just encompasess the graphics produced by the previous call to any of the PlotPlot methods which produce graphical output. If no such previous call has yet been made, or if the call failed for any reason, then the bounding box returned by this function is undefined. Synopsis void astBoundingBox( AstPlot $*$this, float lbnd[2], float ubnd[2] ) this Pointer to the Plot. lbnd A two element array in which is returned the lower limits of the bounding box on each of the two axes of the graphics coordinate system (the base FrameFrame of the Plot). ubnd A two element array in which is returned the upper limits of the bounding box on each of the two axes of the graphics coordinate system (the base Frame of the Plot). An error results if the base Frame of the Plot is not 2-dimensional. astBox Create a Box This function creates a new BoxBox and optionally initialises its attributes.

The Box class implements a RegionRegion which represents a box with sides parallel to the axes of a FrameFrame (i.e. an area which encloses a given range of values on each axis). A Box is similar to an IntervalInterval, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a SkyFrameSkyFrame will look more like a fan than a box (the PolygonPolygon class can be used to create a box-like region close to a pole). Synopsis AstBox $*$astBox( AstFrame $*$frame, int form, const double point1[], const double point2[], AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. form Indicates how the box is described by the remaining parameters. A value of zero indicates that the box is specified by a centre position and a corner position. A value of one indicates that the box is specified by a two opposite corner positions. point1 An array of double, with one element for each Frame axis (NaxesNaxes attribute). If " form" is zero, this array should contain the coordinates at the centre of the box. If " form" is one, it should contain the coordinates at the corner of the box which is diagonally opposite the corner specified by " point2" . point2 An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates at any corner of the box. unc An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Box being created. The uncertainty in any point on the boundary of the Box is found by shifting the supplied " uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, CircleCircle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Box being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplifyastSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Box. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astBox() A pointer to the new Box. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astChannel Create a Channel This function creates a new ChannelChannel and optionally initialises its attributes.

A Channel implements low-level input/output for the AST library. Writing an ObjectObject to a Channel (using astWriteastWrite) will generate a textual representation of that Object, and reading from a Channel (using astReadastRead) will create a new Object from its textual representation.

Normally, when you use a Channel, you should provide " source" and " sink" functions which connect it to an external data store by reading and writing the resulting text. By default, however, a Channel will read from standard input and write to standard output. Alternatively, a Channel can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Synopsis AstChannel $*$astChannel( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) source Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the Channel to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read.

If " source" is NULL and no value has been set for the SourceFile attribute, the Channel will read from standard input instead. sink Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the Channel to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store.

If " sink" is NULL, and no value has been set for the SinkFile attribute, the Channel will write to standard output instead. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Channel. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astChannel() A pointer to the new Channel. Application code can pass arbitrary data (such as file descriptors, etc) to source and sink functions using the astPutChannelDataastPutChannelData function. The source or sink function should use the astChannelDataastChannelData macro to retrieve this data.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astChannelData Return a pointer to user-supplied data stored with a Channel This macro is intended to be used within the source or sink functions associated with a ChannelChannel. It returns any pointer previously stored in the Channel (that is, the Channel that has invoked the source or sink function) using astPutChannelDataastPutChannelData.

This mechanism is a thread-safe alternative to passing file descriptors, etc, via static global variables. Synopsis void $*$astChannelData Channel This macro applies to all Channels. astChannelData The pointer previously stored with the Channel using astPutChannelData. A NULL pointer will be returned if no such pointer has been stored with the Channel. This routine is not available in the Fortran 77 interface to the AST library. astChebyDomain Returns the bounding box of the domain of a ChebyMap This function returns the upper and lower limits of the box defining the domain of either the forward or inverse transformation of a ChebyMapChebyMap. These are the values that were supplied when the ChebyMap was created. Synopsis void astChebyDomain( AstChebyMap $*$this, int forward, double $*$lbnd, double $*$ubnd ) this Pointer to the ChebyMap. forward A non-zero value indicates that the domain of the ChebyMap' s forward transformation is to be returned, while a zero value indicates that the domain of the inverse transformation should be returned. lbnd Pointer to an array in which to return the lower axis bounds of the ChebyMap domain. The number of elements should be at least equal to the number of ChebyMap inputs (if " forward" is non-zero), or outputs (if " forward" is zero). ubnd Pointer to an array in which to return the upper axis bounds of the ChebyMap domain. The number of elements should be at least equal to the number of ChebyMap inputs (if " forward" is non-zero), or outputs (if " forward" is zero). If the requested transformation is undefined (i.e. no transformation coefficients were specified when the ChebyMap was created), this method returns a box determined using the astMapBoxastMapBox method on the opposite transformation, if the opposite transformation is defined.

If the above procedure fails to determine a bounding box, the supplied arrays are filled with AST__BAD values but no error is reported. astChebyMap Create a ChebyMap This function creates a new ChebyMapChebyMap and optionally initialises its attributes.

A ChebyMap is a form of MappingMapping which performs a Chebyshev polynomial transformation. Each output coordinate is a linear combination of Chebyshev polynomials of the first kind, of order zero up to a specified maximum order, evaluated at the input coordinates. The coefficients to be used in the linear combination are specified separately for each output coordinate.

For a 1-dimensional ChebyMap, the forward transformation is defined as follows:

f(x) = c0.T0(x' ) $+$ c1.T1(x' ) $+$ c2.T2(x' ) $+$ ...

where: Tn(x' ) is the nth Chebyshev polynomial of the first kind:

T0(x' ) = 1

T1(x' ) = x'

Tn$+$1(x' ) = 2.x' .Tn(x' ) $+$ Tn-1(x' )

x' is the inpux axis value, x, offset and scaled to the range [-1, 1] as x ranges over a specified bounding box, given when the ChebyMap is created. The input positions, x, supplied to the forward transformation must fall within the bounding box - bad axis values (AST__BAD) are generated for points outside the bounding box.

For an N-dimensional ChebyMap, the forward transformation is a generalisation of the above form. Each output axis value is the sum of " ncoeff" terms, where each term is the product of a single coefficient value and N factors of the form Tn(x' _i), where " x' _i" is the normalised value of the i' th input axis value.

The forward and inverse transformations are defined independantly by separate sets of coefficients, supplied when the ChebyMap is created. If no coefficients are supplied to define the inverse transformation, the astPolyTranastPolyTran method of the parent PolyMapPolyMap class can instead be used to create an inverse transformation. The inverse transformation so generated will be a Chebyshev polynomial with coefficients chosen to minimise the residuals left by a round trip (forward transformation followed by inverse transformation). Synopsis AstChebyMap $*$astChebyMap( int nin, int nout, int ncoeff_f, const double coeff_f[], int ncoeff_i, const double coeff_i[], const double lbnd_f[], const double ubnd_f[], const double lbnd_i[], const double ubnd_i[], const char $*$options, ... ) nin The number of input coordinates. nout The number of output coordinates. ncoeff_f The number of non-zero coefficients necessary to define the forward transformation of the ChebyMap. If zero is supplied, the forward transformation will be undefined. coeff_f An array containing " ncoeff_f$*$( 2 $+$ nin )" elements. Each group of " 2 $+$ nin" adjacent elements describe a single coefficient of the forward transformation. Within each such group, the first element is the coefficient value; the next element is the integer index of the ChebyMap output which uses the coefficient within its defining expression (the first output has index 1); the remaining elements of the group give the integer powers to use with each input coordinate value (powers must not be negative, and floating point values are rounded to the nearest integer). If " ncoeff_f" is zero, a NULL pointer may be supplied for " coeff_f" .

For instance, if the ChebyMap has 3 inputs and 2 outputs, each group consisting of 5 elements, A groups such as " (1.2, 2.0, 1.0, 3.0, 0.0)" describes a coefficient with value 1.2 which is used within the definition of output 2. The output value is incremented by the product of the coefficient value, the value of the Chebyshev polynomial of power 1 evaluated at input coordinate 1, and the value of the Chebyshev polynomial of power 3 evaluated at input coordinate 2. Input coordinate 3 is not used since its power is specified as zero. As another example, the group " (-1.0, 1.0, 0.0, 0.0, 0.0 )" adds a constant value -1.0 onto output 1 (it is a constant value since the power for every input axis is given as zero).

Each final output coordinate value is the sum of the " ncoeff_f" terms described by the " ncoeff_f" groups within the supplied array. ncoeff_i The number of non-zero coefficients necessary to define the inverse transformation of the ChebyMap. If zero is supplied, the inverse transformation will be undefined. coeff_i An array containing " ncoeff_i$*$( 2 $+$ nout )" elements. Each group of " 2 $+$ nout" adjacent elements describe a single coefficient of the inverse transformation, using the same schame as " coeff_f" , except that " inputs" and " outputs" are transposed. If " ncoeff_i" is zero, a NULL pointer may be supplied for " coeff_i" . lbnd_f An array containing the lower bounds of the input bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_f is zero, and so a NULL pointer may be supplied. If supplied, the array should contain " nin" elements. ubnd_f An array containing the upper bounds of the input bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_f is zero, and so a NULL pointer may be supplied. If supplied, the array should contain " nin" elements. lbnd_i An array containing the lower bounds of the output bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_i is zero, and so a NULL pointer may be supplied. If supplied, the array should contain " nout" elements. ubnd_i An array containing the upper bounds of the output bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_i is zero, and so a NULL pointer may be supplied. If supplied, the array should contain " nout" elements. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new ChebyMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astChebyMap() A pointer to the new ChebyMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astCircle Create a Circle This function creates a new CircleCircle and optionally initialises its attributes.

A Circle is a RegionRegion which represents a circle or sphere within the supplied FrameFrame. Synopsis AstCircle $*$astCircle( AstFrame $*$frame, int form, const double centre[], const double point[], AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. form Indicates how the circle is described by the remaining parameters. A value of zero indicates that the circle is specified by a centre position and a position on the circumference. A value of one indicates that the circle is specified by a centre position and a scalar radius. centre An array of double, with one element for each Frame axis (NaxesNaxes attribute) containing the coordinates at the centre of the circle or sphere. point If " form" is zero, then this array should have one element for each Frame axis (Naxes attribute), and should be supplied holding the coordinates at a point on the circumference of the circle or sphere. If " form" is one, then this array should have one element only which should be supplied holding the scalar radius of the circle or sphere, as a geodesic distance within the Frame. unc An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Circle being created. The uncertainty in any point on the boundary of the Circle is found by shifting the supplied " uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. BoxBox, Circle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Circle. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Circle being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplifyastSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Circle. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astCircle() A pointer to the new Circle. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astCirclePars Returns the geometric parameters of an Circle This function returns the geometric parameters describing the supplied CircleCircle. Synopsis void astCirclePars( AstCircle $*$this, double $*$centre, double $*$radius, double $*$p1 ) this Pointer to the RegionRegion. centre Pointer to an array in which to return the coordinates of the Circle centre. The length of this array should be no less than the number of axes in the associated coordinate system. radius Returned holding the radius of the Circle, as an geodesic distance in the associated coordinate system. p1 Pointer to an array in which to return the coordinates of a point on the circumference of the Circle. The length of this array should be no less than the number of axes in the associated coordinate system. A NULL pointer can be supplied if the circumference position is not needed. If the coordinate system represented by the Circle has been changed since it was first created, the returned parameters refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape represented by the supplied Circle object may not be an accurate circle. astClear Clear attribute values for an Object This function clears the values of a specified set of attributes for an ObjectObject. Clearing an attribute cancels any value that has previously been explicitly set for it, so that the standard default attribute value will subsequently be used instead. This also causes the astTestastTest function to return the value zero for the attribute, indicating that no value has been set. Synopsis void astClear( AstObject $*$this, const char $*$attrib ) this Pointer to the Object. attrib Pointer to a null-terminated character string containing a comma-separated list of the names of the attributes to be cleared. Object This function applies to all Objects. Attribute names are not case sensitive and may be surrounded by white space.

It does no harm to clear an attribute whose value has not been set.

An error will result if an attempt is made to clear the value of a read-only attribute. astClearStatus Clear the AST error status This macro resets the AST error status to an OK value, indicating that an error condition (if any) has been cleared. Synopsis void astClearStatus If the AST error status is set to an error value (after an error), most AST functions will not execute and will simply return without action. Using astClearStatus will restore normal behaviour. astClip Set up or remove clipping for a Plot This function defines regions of a PlotPlot which are to be clipped. Any subsequent graphical output created using the Plot will then be visible only within the unclipped regions of the plotting area. See also the ClipClip attribute. Synopsis void astClip( AstPlot $*$this, int iframe, const double lbnd[], const double ubnd[] ) this Pointer to the Plot. iframe The index of the FrameFrame within the Plot to which the clipping limits supplied in " lbnd" and " ubnd" (below) refer. Clipping may be applied to any of the coordinate systems associated with a Plot (as defined by the Frames it contains), so this index may take any value from 1 to the number of Frames in the Plot (NframeNframe attribute). In addition, the values AST__BASE and AST__CURRENT may be used to specify the base and current Frames respectively.

For example, a value of AST__CURRENT causes clipping to be performed in physical coordinates, while a value of AST__BASE would clip in graphical coordinates. Clipping may also be removed completely by giving a value of AST__NOFRAME. In this case any clipping bounds supplied (below) are ignored. lbnd An array with one element for each axis of the clipping Frame (identified by the index " iframe" ). This should contain the lower bound, on each axis, of the region which is to remain visible (unclipped). ubnd An array with one element for each axis of the clipping Frame (identified by the index " iframe" ). This should contain the upper bound, on each axis, of the region which is to remain visible (unclipped). Only one clipping Frame may be active at a time. This function will deactivate any previously-established clipping Frame before setting up new clipping limits.

The clipping produced by this function is in addition to that specified by the Clip attribute which occurs at the edges of the plotting area established when the Plot is created (see astPlotastPlot). The underlying graphics system may also impose further clipping.

When testing a graphical position for clipping, it is first transformed into the clipping Frame. The resulting coordinate on each axis is then checked against the clipping limits (given by " lbnd" and " ubnd" ). By default, a position is clipped if any coordinate lies outside these limits. However, if a non-zero value is assigned to the Plot' s ClipOpClipOp attribute, then a position is only clipped if the coordinates on all axes lie outside their clipping limits.

If the lower clipping limit exceeds the upper limit for any axis, then the sense of clipping for that axis is reversed (so that coordinate values lying between the limits are clipped instead of those lying outside the limits). To produce a " hole" in a coordinate space (that is, an internal region where nothing is plotted), you should supply all the bounds in reversed order, and set the ClipOp attribute for the Plot to a non-zero value.

Either clipping limit may be set to the value AST__BAD, which is equivalent to setting it to infinity (or minus infinity for a lower bound) so that it is not used.

If a graphical position results in any bad coordinate values (AST__BAD) when transformed into the clipping Frame, then it is treated (for the purposes of producing graphical output) as if it were clipped.

When a Plot is used as a MappingMapping to transform points (e.g. using astTran2astTran2), any clipped output points are assigned coordinate values of AST__BAD.

An error results if the base Frame of the Plot is not 2-dimensional. astClone Clone (duplicate) an Object pointer This function returns a duplicate pointer to an existing ObjectObject. It also increments the Object' s RefCountRefCount attribute to keep track of how many pointers have been issued.

Note that this function is NOT equivalent to an assignment statement, as in general the two pointers will not have the same value. Synopsis AstObject $*$astClone( AstObject $*$this ) this Original pointer to the Object. Object This function applies to all Objects. astClone() A duplicate pointer to the same Object. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astCmpFrame Create a CmpFrame This function creates a new CmpFrameCmpFrame and optionally initialises its attributes.

A CmpFrame is a compound FrameFrame which allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of the first Frame, followed by those of the second Frame).

Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way.

Also since a Frame is a MappingMapping, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a UnitMapUnitMap, but if either of the component Frames within a CmpFrame is a RegionRegion (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values. Synopsis AstCmpFrame $*$astCmpFrame( AstFrame $*$frame1, AstFrame $*$frame2, const char $*$options, ... ) frame1 Pointer to the first component Frame. frame2 Pointer to the second component Frame. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astCmpFrame() A pointer to the new CmpFrame. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astCmpMap Create a CmpMap This function creates a new CmpMapCmpMap and optionally initialises its attributes.

A CmpMap is a compound MappingMapping which allows two component Mappings (of any class) to be connected together to form a more complex Mapping. This connection may either be " in series" (where the first Mapping is used to transform the coordinates of each point and the second mapping is then applied to the result), or " in parallel" (where one Mapping transforms the earlier coordinates for each point and the second Mapping simultaneously transforms the later coordinates).

Since a CmpMap is itself a Mapping, it can be used as a component in forming further CmpMaps. Mappings of arbitrary complexity may be built from simple individual Mappings in this way. Synopsis AstCmpMap $*$astCmpMap( AstMapping $*$map1, AstMapping $*$map2, int series, const char $*$options, ... ) map1 Pointer to the first component Mapping. map2 Pointer to the second component Mapping. series If a non-zero value is given for this parameter, the two component Mappings will be connected in series. A zero value requests that they are connected in parallel. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astCmpMap() A pointer to the new CmpMap. If the component Mappings are connected in series, then using the resulting CmpMap to transform coordinates will cause the first Mapping to be applied, followed by the second Mapping. If the inverse CmpMap transformation is requested, the two component Mappings will be applied in both the reverse order and the reverse direction.

When connecting two component Mappings in series, the number of output coordinates generated by the first Mapping (its NoutNout attribute) must equal the number of input coordinates accepted by the second Mapping (its NinNin attribute).

If the component Mappings of a CmpMap are connected in parallel, then the first Mapping will be used to transform the earlier input coordinates for each point (and to produce the earlier output coordinates) and the second Mapping will be used simultaneously to transform the remaining input coordinates (to produce the remaining output coordinates for each point). If the inverse transformation is requested, each Mapping will still be applied to the same coordinates, but in the reverse direction.

When connecting two component Mappings in parallel, there is no restriction on the number of input and output coordinates for each Mapping.

Note that the component Mappings supplied are not copied by astCmpMap (the new CmpMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a CmpMap containing a copy of its component Mappings is required, then a copy of the CmpMap should be made using astCopyastCopy.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astCmpRegion Create a CmpRegion This function creates a new CmpRegionCmpRegion and optionally initialises its attributes.

A CmpRegion is a RegionRegion which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion.

The two component Region need not refer to the same coordinate FrameFrame, but it must be possible for the astConvertastConvert function to determine a MappingMapping between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS SkyFrameSkyFrame with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the astConvert function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region.

Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way. Synopsis AstCmpRegion $*$astCmpRegion( AstRegion $*$region1, AstRegion $*$region2, int oper, const char $*$options, ... ) region1 Pointer to the first component Region. region2 Pointer to the second component Region. This Region will be transformed into the coordinate Frame of the first region before use. An error will be reported if this is not possible. oper The boolean operator with which to combine the two Regions. This must be one of the symbolic constants AST__AND, AST__OR or AST__XOR. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpRegion. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astCmpRegion() A pointer to the new CmpRegion. If one of the supplied Regions has an associated uncertainty, that uncertainty will also be used for the returned CmpRegion. If both supplied Regions have associated uncertainties, the uncertainty associated with the first Region will be used for the returned CmpRegion.

Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the CmpRegion.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astColumnName Get the name of the column at a given index within the Table This function returns a string holding the name of the column with the given index within the TableTable.

This function is intended primarily as a means of iterating round all the columns in a Table. For this purpose, the number of columns in the Table is given by the NcolumnNcolumn attribute of the Table. This function could then be called in a loop, with the index value going from zero to one less than Ncolumn.

Note, the index associated with a column decreases monotonically with the age of the column: the oldest Column in the Table will have index one, and the Column added most recently to the Table will have the largest index. Synopsis const char $*$astColumnName( AstTable $*$this, int index ) this Pointer to the Table. index The index into the list of columns. The first column has index one, and the last has index " Ncolumn" . astColumnName() A pointer to a null-terminated string containing the upper case column name. The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this.

A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astColumnNull Get or set the null value for an integer column of a FITS table This function allows a null value to be stored with a named integer-valued column in a FitsTableFitsTable. The supplied null value is assigned to the TNULLn keyword in the FITS header associated with the FitsTable. A value in the named column is then considered to be null if 1) it equals the null value supplied to this function, or 2) no value has yet been stored in the cell.

As well as setting a new null value, this function also returns the previous null value. If no null value has been set previously, a default value will be returned. This default will be an integer value that does not currently occur anywhere within the named column. If no such value can be found, what happens depends on whether the column contains any cells in which no values have yet been stored. If so, an error will be reported. Otherwise (i.e. if there are no null values in the column), an arbitrary value of zero will be returned as the function value, and no TNULLn keyword will be stored in the FITS header.

A flag is returned indicating if the returned null value was set explicitly by a previous call to this function, or is a default value.

A second flag is returned indicating if the named column contains any null values (i.e. values equal to the supplied null value, or cells to which no value has yet been assigned). Synopsis int astColumnNull( AstFitsTable $*$this, const char $*$column, int set, int newval, int $*$wasset, int $*$hasnull ) this Pointer to the FitsTable. column The character string holding the name of the column. Trailing spaces are ignored. set If non-zero, the value supplied for parameter " newval" will be stored as the current null value, replacing any value set by a previous call to this function. If zero, the value supplied for parameter " newval" is ignored and the current null value is left unchanged. newval The new null value to use. Ignored if " set" is zero. An error will be reported if the supplied value is outside the range of values that can be stored in the integer data type associated with the column. wasset Pointer to an int that will be returned non-zero if the returned null value was set previously via an earlier invocation of this function. Zero is returned otherwise. If the named column does not exist, or an error occurs, a value of zero is returned. hasnull Pointer to an int that will be returned non-zero if and only if the named column currently contains any values equal to the null value on exit (i.e. " newval" if " set" is non-zero, or the returned function value otherwise), or contains any empty cells. If the named column does not exist, or an error occurs, a value of zero is returned. If a NULL pointer is supplied for " hasnull" , no check on the presence of null values will be performed. astColumnNull() The null value that was in use on entry to this function. If a null value has been set by a previous invocation of this function, it will be returned. Otherwise, if " set" is non-zero, the supplied " newval" value is returned. Otherwise, a default value is chosen (if possible) that does not currently occur in the named column. If all available values are in use in the column, an error is reported if and only if the column contains any empty cells. Otherwise, a value of zero is returned. A value of zero is also returned if the named column does not exist, or an error occurs. The FITS binary table definition allows only integer-valued columns to have an associated null value. This routine will return without action if the column is not integer-valued. astColumnShape Returns the shape of the values in a named column This function returns the number of dimensions spaned by each value in a named column of a TableTable, together with the length of each dimension. These are the values supplied when the column was created using astAddColumnastAddColumn. Synopsis void astColumnShape( AstTable $*$this, const char $*$column, int mxdim, int $*$ndim, int $*$dims ) this Pointer to the Table. column The character string holding the upper case name of the column. Trailing spaces are ignored. mxdim The length of the " dims" array. ndim Pointer to an int in which to return the number of dimensions spanned by values in the named column. This will be zero if the column contains scalar values. dims Pointer to an array in which to return the length of each dimension. Any excess trailing elements will be filled with the value 1. No error is reported if the requested column cannot be found in the given Table. A value of zero is returned for " ndim" and the supplied values in " dims" are left unchanged.

A value of zero is returned for " ndim" if an error occurs. astColumnSize Get the number of bytes needed to hold a full column of data This function returns the number of bytes of memory that must be allocated prior to retrieving the data from a column of a FitsTableFitsTable using astGetColumnDataastGetColumnData. Synopsis size_t astColumnSize( AstFitsTable $*$this, const char $*$column ) this Pointer to the FitsTable. column The character string holding the name of the column. Trailing spaces are ignored. astColumnSize() The number of bytes required to store the column data. An error will be reported if the named column does not exist in the FitsTable.

Zero will be returned as the function value in an error occurs. astConvert Determine how to convert between two coordinate systems This function compares two Frames and determines whether it is possible to convert between the coordinate systems which they represent. If conversion is possible, it returns a FrameSetFrameSet which describes the conversion and which may be used (as a MappingMapping) to transform coordinate values in either direction.

The same function may also be used to determine how to convert between two FrameSets (or between a FrameFrame and a FrameSet, or vice versa). This mode is intended for use when (for example) two images have been calibrated by attaching a FrameSet to each. astConvert might then be used to search for a celestial coordinate system that both images have in common, and the result could then be used to convert between the pixel coordinates of both images – having effectively used their celestial coordinate systems to align them.

When using FrameSets, there may be more than one possible intermediate coordinate system in which to perform the conversion (for instance, two FrameSets might both have celestial coordinates, detector coordinates, pixel coordinates, etc.). A comma-separated list of coordinate system domains may therefore be given which defines a priority order to use when selecting the intermediate coordinate system. The path used for conversion must go via an intermediate coordinate system whose DomainDomain attribute matches one of the domains given. If conversion cannot be achieved using the first domain, the next one is considered, and so on, until success is achieved. Synopsis AstFrameSet $*$astConvert( AstFrame $*$from, AstFrame $*$to, const char $*$domainlist ) from Pointer to a Frame which represents the " source" coordinate system. This is the coordinate system in which you already have coordinates available.

If a FrameSet is given, its current Frame (as determined by its CurrentCurrent attribute) is taken to describe the source coordinate system. Note that the BaseBase attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used (see under " FrameSets" in the " Applicability" section for details). to Pointer to a Frame which represents the " destination" coordinate system. This is the coordinate system into which you wish to convert your coordinates.

If a FrameSet is given, its current Frame (as determined by its Current attribute) is taken to describe the destination coordinate system. Note that the Base attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used (see under " FrameSets" in the " Applicability" section for details). domainlist Pointer to a null-terminated character string containing a comma-separated list of Frame domains. This may be used to define a priority order for the different intermediate coordinate systems that might be used to perform the conversion.

The function will first try to obtain a conversion by making use only of an intermediate coordinate system whose Domain attribute matches the first domain in this list. If this fails, the second domain in the list will be used, and so on, until conversion is achieved. A blank domain (e.g. two consecutive commas) indicates that all coordinate systems should be considered, regardless of their domains.

This list is case-insensitive and all white space is ignored. If you do not wish to restrict the domain in this way, you should supply an empty string. This is normally appropriate if either of the source or destination coordinate systems are described by Frames (rather than FrameSets), since there is then usually only one possible choice of intermediate coordinate system. DSBSpecFrameDSBSpecFrame If the AlignSideBandAlignSideBand attribute is non-zero, alignment occurs in the upper sideband expressed within the spectral system and standard of rest given by attributes AlignSystemAlignSystem and AlignStdOfRestAlignStdOfRest. If AlignSideBand is zero, the two DSBSpecFrames are aligned as if they were simple SpecFrames (i.e. the SideBandSideBand is ignored). Frame This function applies to all Frames. Alignment occurs within the coordinate system given by attribute AlignSystem. FrameSet If either of the " from" or " to" parameters is a pointer to a FrameSet, then astConvert will attempt to convert from the coordinate system described by the current Frame of the " from" FrameSet to that described by the current Frame of the " to" FrameSet.

To achieve this, it will consider all of the Frames within each FrameSet as a possible way of reaching an intermediate coordinate system that can be used for the conversion. There is then the possibility that more than one conversion path may exist and, unless the choice is sufficiently restricted by the " domainlist" string, the sequence in which the Frames are considered can be important. In this case, the search for a conversion path proceeds as follows: Each field in the " domainlist" string is considered in turn.

The Frames within each FrameSet are considered in a specific order: (1) the base Frame is always considered first, (2) after this come all the other Frames in Frame-index order (but omitting the base and current Frames), (3) the current Frame is always considered last. However, if either FrameSet' s InvertInvert attribute is set to a non-zero value (so that the FrameSet is inverted), then its Frames are considered in reverse order. (Note that this still means that the base Frame is considered first and the current Frame last, because the Invert value will also cause these Frames to swap places.)

All source Frames are first considered (in the appropriate order) for conversion to the first destination Frame. If no suitable intermediate coordinate system emerges, they are then considered again for conversion to the second destination Frame (in the appropriate order), and so on.

Generally, the first suitable intermediate coordinate system found is used. However, the overall Mapping between the source and destination coordinate systems is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the TranForwardTranForward and TranInverseTranInverse attributes). If only one transformation is defined, the forward one is preferred.

If the domain of the intermediate coordinate system matches the current " domainlist" field, the conversion path is accepted. Otherwise, the next " domainlist" field is considered and the process repeated.

If conversion is possible, the Base attributes of the two FrameSets will be modified on exit to identify the Frames used to access the intermediate coordinate system which was finally accepted.

Note that it is possible to force a particular Frame within a FrameSet to be used as the basis for the intermediate coordinate system, if it is suitable, by (a) focussing attention on it by specifying its domain in the " domainlist" string, or (b) making it the base Frame, since this is always considered first. SpecFrameSpecFrame Alignment occurs within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest. TimeFrameTimeFrame Alignment occurs within the time system and time scale given by attributes AlignSystem and AlignTimeScaleAlignTimeScale. astConvert() If the requested coordinate conversion is possible, the function returns a pointer to a FrameSet which describes the conversion. Otherwise, a null ObjectObject pointer (AST__NULL) is returned without error.

If a FrameSet is returned, it will contain two Frames. Frame number 1 (its base Frame) will describe the source coordinate system, corresponding to the " from" parameter. Frame number 2 (its current Frame) will describe the destination coordinate system, corresponding to the " to" parameter. The Mapping which inter-relates these two Frames will perform the required conversion between their respective coordinate systems.

Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with astTran2astTran2), then it provides a means of converting coordinates from the source to the destination coordinate system (or vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the destination coordinate system. cvt = astConvert( a, b, " " ); Attempts to convert between the coordinate systems represented by " a" and " b" (assumed to be Frames). If successful, a FrameSet is returned via the " cvt" pointer which may be used to apply the conversion to sets of coordinates (e.g. using astTran2). cvt = astConvert( astSkyFrameastSkyFrame(" " ), astSkyFrame(" EquinoxEquinox=2005" ), " " ); Creates a FrameSet which describes precession in the default FK5 celestial coordinate system between equinoxes J2000 (also the default) and J2005. The returned " cvt" pointer may then be passed to astTran2 to apply this precession correction to any number of coordinate values given in radians.

Note that the returned FrameSet also contains information about how to format coordinate values. This means that setting its ReportReport attribute to 1 is a simple way to obtain printed output (formatted in sexagesimal notation) to show the coordinate values before and after conversion. cvt = astConvert( a, b, " sky,detector," ); Attempts to convert between the coordinate systems represented by the current Frames of " a" and " b" (now assumed to be FrameSets), via the intermediate " SKY" coordinate system. This, by default, is the Domain associated with a celestial coordinate system represented by a SkyFrameSkyFrame.

If this fails (for example, because either FrameSet lacks celestial coordinate information), then the user-defined " DETECTOR" coordinate system is used instead. If this also fails, then all other possible ways of achieving conversion are considered before giving up.

The returned pointer " cvt" indicates whether conversion was possible and will have the value AST__NULL if it was not. If conversion was possible, " cvt" will point at a new FrameSet describing the conversion.

The Base attributes of the two FrameSets will be set by astConvert to indicate which of their Frames was used for the intermediate coordinate system. This means that you can subsequently determine which coordinate system was used by enquiring the Domain attribute of either base Frame. The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the " to" Frame. See the description of the AlignSystem attribute for further details.

When aligning (say) two images, which have been calibrated by attaching FrameSets to them, it is usually necessary to convert between the base Frames (representing " native" pixel coordinates) of both FrameSets. This may be achieved by inverting the FrameSets (e.g. using astInvertastInvert) so as to interchange their base and current Frames before using astConvert.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astConvex$<$X$>$ Create a new Polygon representing the convex hull of a 2D data grid This is a set of functions that create the shortest PolygonPolygon that encloses all pixels with a specified value within a gridded 2-dimensional data array (e.g. an image).

A basic 2-dimensional FrameFrame is used to represent the pixel coordinate system in the returned Polygon. The DomainDomain attribute is set to " PIXEL" , the TitleTitle attribute is set to " Pixel coordinates" , and the Unit attribute for each axis is set to " pixel" . All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter " starpix" .

You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astConvex$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are procesing data with type " float" , you should use the function astConvexF (see the " Data Type Codes" section below for the codes appropriate to other numerical types). Synopsis AstPolygon $*$astConvex$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[], const int lbnd[2], const int ubnd[2], int starpix ) value A data value that specifies the pixels to be included within the convex hull. oper Indicates how the " value" parameter is used to select the required pixels. It can have any of the following values: AST__LT: include pixels with value less than " value" .

AST__LE: include pixels with value less than or equal to " value" .

AST__EQ: include pixels with value equal to " value" .

AST__NE: include pixels with value not equal to " value" .

AST__GE: include pixels with value greater than or equal to " value" .

AST__GT: include pixels with value greater than " value" . array Pointer to a 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astConvexF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. Fortran array indexing is used). lbnd Pointer to an array of two integers containing the coordinates of the centre of the first pixel in the input grid along each dimension. ubnd Pointer to an array of two integers containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd" and " ubnd" together define the shape and size of the input grid, its extent along a particular (j' th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the index " j" to be zero-based). They also define the input grid' s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter " starpix" . starpix A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If non-zero, the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If zero, the definition of pixel coordinate used by other AST functions such as astResample, astMask, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates). astConvex$<$X$>$() A pointer to the required Polygon. NULL is returned without error if the array contains no pixels that satisfy the criterion specified by " value" and " oper" . NULL will be returned if this function is invoked with the global error status set, or if it should fail for any reason. Data Type Codes To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astConvex$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

L: long int

UL: unsigned long int

I: int

UI: unsigned int

S: short int

US: unsigned short int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astConvexD would be used to process " double" data, while astConvexS would be used to process " short int" data, etc. Handling of Huge Pixel Arrays If the input grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd" and " ubnd" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astConvex$<$X$>$ becomes astConvex8$<$X$>$. astCopy Copy an Object This function creates a copy of an ObjectObject and returns a pointer to the resulting new Object. It makes a " deep" copy, which contains no references to any other Object (i.e. if the original Object contains references to other Objects, then the actual data are copied, not simply the references). This means that modifications may safely be made to the copy without indirectly affecting any other Object. Synopsis AstObject $*$astCopy( const AstObject $*$this ) this Pointer to the Object to be copied. Object This function applies to all Objects. astCopy() Pointer to the new Object. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astCreatedAt Return the routine, file and line number at which an Object was created This function returns pointers to two strings containing the name of the routine or function within which the object was created and the name of the source file containing that routine. It also returns the number of the line within the file at which the object was created. It is intended for use in debugging memory leaks etc.

Precisely, the information returned identifies the point at which the ObjectObject' s public identifier (i.e. the supplied pointer) was first issued. This may not correspond to the actual creation of the Object if the object is contained within some higher level Object. For instance, if the astGetFrameastGetFrame method is used to get a pointer to a FrameFrame within a FrameSetFrameSet, the information returned by this function if supplied with the Frame pointer would identify the call to astGetFrame, rather than the line at which the FrameSet created its internal copy of the Frame. Likewise, if this function is used to get information from an Object pointer returned by astCloneastClone, the information will describe the call to astClone, not the call that created the original Object. Synopsis void astCreatedAt( AstObject $*$this, const char $*$$*$routine, const char $*$$*$file, int $*$line ) this Pointer to the Object. routine Address of a pointer to a null terminated C string in which to return the routine name (the string will reside in static memory). The pointer will be set to NULL on exit if no routine name is available. file Address of a pointer to a null terminated C string in which to return the file name (the string will reside in static memory). The pointer will be set to NULL on exit if no file name is available. line Address of an int in which to store the line number in the file. A line number of zero is returned if no line number is available. NULL pointers and a line number of zero are returned if an error has already occurred prior to calling this function. astCurrentTime Return the current system time This function returns the current system time, represented in the form specified by the supplied TimeFrameTimeFrame. That is, the returned floating point value should be interpreted using the attribute values of the TimeFrame. This includes SystemSystem, TimeOriginTimeOrigin, LTOffsetLTOffset, TimeScaleTimeScale, and Unit. Synopsis double astCurrentTime( AstTimeFrame $*$this ) this Pointer to the TimeFrame. astCurrentTime() A TimeFrame axis value representing the current system time. Values of AST__BAD will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

It is assumes that the system time (returned by the C time() function) follows the POSIX standard, representing a continuous monotonic increasing count of SI seconds since the epoch 00:00:00 UTC 1 January 1970 AD (equivalent to TAI with a constant offset). Resolution is one second.

An error will be reported if the TimeFrame has a TimeScale value which cannot be converted to TAI (e.g. " angular" systems such as UT1, GMST, LMST and LAST).

Any inaccuracy in the system clock will be reflected in the value returned by this function. astCurve Draw a geodesic curve This function draws a geodesic curve between two points in the physical coordinate system of a PlotPlot. The curve drawn is the path of shortest distance joining the two points (as defined by the astDistanceastDistance function for the current FrameFrame of the Plot). For example, if the current Frame is a basic Frame, then the curve joining the two points will be a straight line in physical coordinate space. If the current Frame is more specialised and describes, for instance, a sky coordinate system, then the geodesic curve would be a great circle in physical coordinate space passing through the two sky positions given.

Note that the geodesic curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the MappingMapping involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using astClipastClip.

If you need to draw many geodesic curves end-to-end, then the astPolyCurveastPolyCurve function is equivalent to repeatedly using astCurve, but will usually be more efficient.

If you need to draw curves which are not geodesics, see astGenCurveastGenCurve or astGridLineastGridLine. Synopsis void astCurve( AstPlot $*$this, const double start[], const double finish[] ) this Pointer to the Plot. start An array, with one element for each axis of the Plot, giving the physical coordinates of the first point on the geodesic curve. finish An array, with one element for each axis of the Plot, giving the physical coordinates of the second point on the geodesic curve. No curve is drawn if either of the " start" or " finish" arrays contains any coordinates with the value AST__BAD.

An error results if the base Frame of the Plot is not 2-dimensional.

An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot' s TranInverseTranInverse attribute is zero). astDSBSpecFrame Create a DSBSpecFrame This function creates a new DSBSpecFrameDSBSpecFrame and optionally initialises its attributes.

A DSBSpecFrame is a specialised form of SpecFrameSpecFrame which represents positions in a spectrum obtained using a dual sideband instrument. Such an instrument produces a spectrum in which each point contains contributions from two distinctly different frequencies, one from the " lower side band" (LSB) and one from the " upper side band" (USB). Corresponding LSB and USB frequencies are connected by the fact that they are an equal distance on either side of a fixed central frequency known as the " Local Oscillator" (LO) frequency.

When quoting a position within such a spectrum, it is necessary to indicate whether the quoted position is the USB position or the corresponding LSB position. The SideBandSideBand attribute provides this indication. Another option that the SideBand attribute provides is to represent a spectral position by its topocentric offset from the LO frequency.

In practice, the LO frequency is specified by giving the distance from the LO frequency to some " central" spectral position. Typically this central position is that of some interesting spectral feature. The distance from this central position to the LO frequency is known as the " intermediate frequency" (IFIF). The value supplied for IF can be a signed value in order to indicate whether the LO frequency is above or below the central position. Synopsis AstDSBSpecFrame $*$astDSBSpecFrame( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new DSBSpecFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astDSBSpecFrame() A pointer to the new DSBSpecFrame. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astDecompose Decompose a Mapping into two component Mappings This function returns pointers to two Mappings which, when applied either in series or parallel, are equivalent to the supplied MappingMapping.

Since the FrameFrame class inherits from the Mapping class, Frames can be considered as special types of Mappings and so this method can be used to decompose either CmpMaps or CmpFrames. Synopsis void astDecompose( AstMapping $*$this, AstMapping $*$$*$map1, AstMapping $*$$*$map2, int $*$series, int $*$invert1, int $*$invert2 ) this Pointer to the Mapping. map1 Address of a location to receive a pointer to first component Mapping. map2 Address of a location to receive a pointer to second component Mapping. series Address of a location to receive a value indicating if the component Mappings are applied in series or parallel. A non-zero value means that the supplied Mapping is equivalent to applying map1 followed by map2 in series. A zero value means that the supplied Mapping is equivalent to applying map1 to the lower numbered axes and map2 to the higher numbered axes, in parallel. invert1 The value of the InvertInvert attribute to be used with map1. invert2 The value of the Invert attribute to be used with map2. CmpMapCmpMap If the supplied Mapping is a CmpMap, then map1 and map2 will be returned holding pointers to the component Mappings used to create the CmpMap, either in series or parallel. Note, changing the Invert attribute of either of the component Mappings using the returned pointers will have no effect on the supplied CmpMap. This is because the CmpMap remembers and uses the original settings of the Invert attributes (that is, the values of the Invert attributes when the CmpMap was first created). These are the Invert values which are returned in invert1 and invert2. TranMapTranMap If the supplied Mapping is a TranMap, then map1 and map2 will be returned holding pointers to the forward and inverse Mappings represented by the TranMap (zero will be returned for series). Note, changing the Invert attribute of either of the component Mappings using the returned pointers will have no effect on the supplied TranMap. This is because the TranMap remembers and uses the original settings of the Invert attributes (that is, the values of the Invert attributes when the TranMap was first created). These are the Invert values which are returned in invert1 and invert2. Mapping For any class of Mapping other than a CmpMap, map1 will be returned holding a clone of the supplied Mapping pointer, and map2 will be returned holding a NULL pointer. Invert1 will be returned holding the current value of the Invert attribute for the supplied Mapping, and invert2 will be returned holding zero. CmpFrameCmpFrame If the supplied Mapping is a CmpFrame, then map1 and map2 will be returned holding pointers to the component Frames used to create the CmpFrame. The component Frames are considered to be in applied in parallel. Frame For any class of Frame other than a CmpFrame, map1 will be returned holding a clone of the supplied Frame pointer, and map2 will be returned holding a NULL pointer. The returned Invert values should be used in preference to the current values of the Invert attribute in map1 and map2. This is because the attributes may have changed value since the Mappings were combined.

Any changes made to the component Mappings using the returned pointers will be reflected in the supplied Mapping. astDelFits Delete the current FITS card in a FitsChan This function deletes the current FITS card from a FitsChanFitsChan. The current card may be selected using the CardCard attribute (if its index is known) or by using astFindFitsastFindFits (if only the FITS keyword is known).

After deletion, the following card becomes the current card. Synopsis void astDelFits( AstFitsChan $*$this ) this Pointer to the FitsChan. This function returns without action if the FitsChan is initially positioned at the " end-of-file" (i.e. if the Card attribute exceeds the number of cards in the FitsChan).

If there are no subsequent cards in the FitsChan, then the Card attribute is left pointing at the " end-of-file" after deletion (i.e. is set to one more than the number of cards in the FitsChan). astDelete Delete an Object This function deletes an ObjectObject, freeing all resources associated with it and rendering any remaining pointers to the Object invalid.

Note that deletion is unconditional, regardless of whether other pointers to the Object are still in use (possibly within other Objects). A safer approach is to defer deletion, until all references to an Object have expired, by using astBeginastBegin/astEndastEnd (together with astCloneastClone and astAnnulastAnnul if necessary). Synopsis AstObject $*$astDelete( AstObject $*$this ) this Pointer to the Object to be deleted. Object This function applies to all Objects. astDelete() A null Object pointer (AST__NULL) is always returned. This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. astDistance Calculate the distance between two points in a Frame This function finds the distance between two points whose FrameFrame coordinates are given. The distance calculated is that along the geodesic curve that joins the two points.

For example, in a basic Frame, the distance calculated will be the Cartesian distance along the straight line joining the two points. For a more specialised Frame describing a sky coordinate system, however, it would be the distance along the great circle passing through two sky positions. Synopsis double astDistance( AstFrame $*$this, const double point1[], const double point2[] ) this Pointer to the Frame. point1 An array of double, with one element for each Frame axis (NaxesNaxes attribute) containing the coordinates of the first point. point2 An array of double, with one element for each Frame axis containing the coordinates of the second point. astDistance The distance between the two points. This function will return a " bad" result value (AST__BAD) if any of the input coordinates has this value.

A " bad" value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astDownsize Reduce the number of vertices in a Polygon This function returns a pointer to a new PolygonPolygon that contains a subset of the vertices in the supplied Polygon. The subset is chosen so that the returned Polygon is a good approximation to the supplied Polygon, within the limits specified by the supplied parameter values. That is, the density of points in the returned Polygon is greater at points where the curvature of the boundary of the supplied Polygon is greater. Synopsis AstPolygon $*$astDownsize( AstPolygon $*$this, double maxerr, int maxvert ) this Pointer to the Polygon. maxerr The maximum allowed discrepancy between the supplied and returned Polygons, expressed as a geodesic distance within the Polygon' s coordinate frame. If this is zero or less, the returned Polygon will have the number of vertices specified by maxvert. maxvert The maximum allowed number of vertices in the returned Polygon. If this is less than 3, the number of vertices in the returned Polygon will be the minimum needed to achieve the maximum discrepancy specified by maxerr. astDownsize() Pointer to the new Polygon. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astEBuf End the current graphical buffering context This function ends the current graphics buffering context. It should match a corresponding call to the astBBufastBBuf function. Synopsis void astEBuf( AstPlot $*$this ) this Pointer to the PlotPlot. The nature of the buffering is determined by the underlying graphics system (as defined by the current grf module). Each call to this function simply invokes the astGEBuf function in the grf module. astEllipse Create a Ellipse This function creates a new EllipseEllipse and optionally initialises its attributes.

A Ellipse is a RegionRegion which represents a elliptical area within the supplied 2-dimensional FrameFrame. Synopsis AstEllipse $*$astEllipse( AstFrame $*$frame, int form, const double centre[2], const double point1[2], const double point2[2], AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. form Indicates how the ellipse is described by the remaining parameters. A value of zero indicates that the ellipse is specified by a centre position and two positions on the circumference. A value of one indicates that the ellipse is specified by its centre position, the half-lengths of its two axes, and the orientation of its first axis. centre An array of 2 doubles, containing the coordinates at the centre of the ellipse. point1 An array of 2 doubles. If " form" is zero, this array should contain the coordinates of one of the four points where an axis of the ellipse crosses the circumference of the ellipse. If " form" is one, it should contain the lengths of semi-major and semi-minor axes of the ellipse, given as geodesic distances within the Frame. point2 An array of 2 doubles. If " form" is zero, this array should containing the coordinates at some other point on the circumference of the ellipse, distinct from " point1" . If " form" is one, the first element of this array should hold the angle between the second axis of the Frame and the first ellipse axis (i.e. the ellipse axis which is specified first in the " point1" array), and the second element will be ignored. The angle should be given in radians, measured positive in the same sense as rotation from the positive direction of the second Frame axis to the positive direction of the first Frame axis. unc An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Ellipse being created. The uncertainty in any point on the boundary of the Ellipse is found by shifting the supplied " uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. BoxBox, CircleCircle, Ellipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Ellipse. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Ellipse being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplifyastSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Ellipse. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astEllipse() A pointer to the new Ellipse. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astEllipsePars Returns the geometric parameters of an Ellipse This function returns the geometric parameters describing the supplied ellipse. Synopsis void astEllipsePars( AstEllipse $*$this, double centre[2], double $*$a, double $*$b, double $*$angle, double p1[2], double p2[2] ) this Pointer to the RegionRegion. centre The coordinates of the EllipseEllipse centre are returned in this arrays. a Returned holding the half-length of the first axis of the ellipse. b Returned holding the half-length of the second axis of the ellipse. angle If the coordinate system in which the Ellipse is defined has axes (X,Y), then " $*$angle" is returned holding the angle from the positive direction of the Y axis to the first axis of the ellipse, in radians. Positive rotation is in the same sense as rotation from the positive direction of Y to the positive direction of X. p1 An array in which to return the coordinates at one of the two ends of the first axis of the ellipse. A NULL pointer can be supplied if these coordinates are not needed. p2 An array in which to return the coordinates at one of the two ends of the second axis of the ellipse. A NULL pointer can be supplied if these coordinates are not needed. If the coordinate system represented by the Ellipse has been changed since it was first created, the returned parameters refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape represented by the supplied Ellipse object may not be an accurate ellipse.

Values of AST__BAD are returned for the parameters without error if the ellipse is degenerate or undefined. astEmptyFits Delete all cards in a FitsChan This function deletes all cards and associated information from a FitsChanFitsChan. Synopsis void astEmptyFits( AstFitsChan $*$this ) this Pointer to the FitsChan. This method simply deletes the cards currently in the FitsChan. Unlike astWriteFitsastWriteFits, they are not first written out to the sink function or sink file.

Any Tables or warnings stored in the FitsChan are also deleted.

This method attempt to execute even if an error has occurred previously. astEnd End an AST context This macro invokes a function to end an AST context which was begun with a matching invocation of astBeginastBegin. Any ObjectObject pointers created within this context will be annulled (just as if astAnnulastAnnul had been invoked) and will cease to be valid afterwards, unless they have previously been exported using astExportastExport or rendered exempt using astExemptastExempt. If annulling a pointer causes an Object' s RefCountRefCount attribute to fall to zero (which happens when the last pointer to it is annulled), then the Object will be deleted. Synopsis void astEnd Object This macro applies to all Objects. astEnd attempts to execute even if the AST error status is set.

Contexts delimited by astBegin and astEnd may be nested to any depth. astEscapes Control whether graphical escape sequences are included in strings The PlotPlot class defines a set of escape sequences which can be included within a text string in order to control the appearance of sub-strings within the text. See the EscapeEscape attribute for a description of these escape sequences. It is usually inappropriate for AST to return strings containing such escape sequences when called by application code. For instance, an application which displays the value of the TitleTitle attribute of a FrameFrame usually does not want the displayed string to include potentially long escape sequences which a human read would have difficuly interpreting. Therefore the default behaviour is for AST to strip out such escape sequences when called by application code. This default behaviour can be changed using this function. Synopsis int astEscapes( int new_value ) new_value A flag which indicates if escapes sequences should be included in returned strings. If zero is supplied, escape sequences will be stripped out of all strings returned by any AST function. If a positive value is supplied, then any escape sequences will be retained in the value returned to the caller. If a negative value is supplied, the current value of the flag will be left unchanged. ObjectObject This macro applies to all Objects. astEscapes The value of the flag on entry to this function. This function also controls whether the astStripEscapesastStripEscapes function removes escape sequences from the supplied string, or returns the supplied string without change.

This function attempts to execute even if an error has already occurred. astExempt Exempt an Object pointer from AST context handling This function exempts an ObjectObject pointer from AST context handling, as implemented by astBeginastBegin and astEndastEnd. This means that the pointer will not be affected when astEnd is invoked and will remain active until the end of the program, or until explicitly annulled using astAnnulastAnnul.

If possible, you should avoid using this function when writing applications. It is provided mainly for developers of other libraries, who may wish to retain references to AST Objects in internal data structures, and who therefore need to avoid the effects of astBegin and astEnd. Synopsis void astExempt( AstObject $*$this ) this Object pointer to be exempted from context handling. Object This function applies to all Objects. astExport Export an Object pointer to an outer context This function exports an ObjectObject pointer from the current AST context into the context that encloses the current one. This means that the pointer will no longer be annulled when the current context is ended (with astEndastEnd), but only when the next outer context (if any) ends. Synopsis void astExport( AstObject $*$this ) this Object pointer to be exported. Object This function applies to all Objects. It is only sensible to apply this function to pointers that have been created within (or exported to) the current context and have not been rendered exempt using astExemptastExempt. Applying it to an unsuitable Object pointer has no effect. astFindFits Find a FITS card in a FitsChan by keyword This function searches for a card in a FitsChanFitsChan by keyword. The search commences at the current card (identified by the CardCard attribute) and ends when a card is found whose FITS keyword matches the template supplied, or when the last card in the FitsChan has been searched.

If the search is successful (i.e. a card is found which matches the template), the contents of the card are (optionally) returned and the Card attribute is adjusted to identify the card found or, if required, the one following it. If the search is not successful, the function returns zero and the Card attribute is set to the " end-of-file" . Synopsis int astFindFits( AstFitsChan $*$this, const char $*$name, char card[ 81 ], int inc ) this Pointer to the FitsChan. name Pointer to a null-terminated character string containing a template for the keyword to be found. In the simplest case, this should simply be the keyword name (the search is case insensitive and trailing spaces are ignored). However, this template may also contain " field specifiers" which are capable of matching a range of characters (see the " Keyword Templates" section for details). In this case, the first card with a keyword which matches the template will be found. To find the next FITS card regardless of its keyword, you should use the template " %f" . card An array of at least 81 characters (to allow room for a terminating null) in which the FITS card which is found will be returned. If the search is not successful (or a NULL pointer is given), a card will not be returned. inc If this value is zero (and the search is successful), the FitsChan' s Card attribute will be set to the index of the card that was found. If it is non-zero, however, the Card attribute will be incremented to identify the card which follows the one found. astFindFits() One if the search was successful, otherwise zero. result = astFindFits( fitschan, " %f" , card, 1 ); Returns the current card in a FitsChan and advances the Card attribute to identify the card that follows (the " %f" template matches any keyword). result = astFindFits( fitschan, " BITPIX" , card, 1 ); Searches a FitsChan for a FITS card with the " BITPIX" keyword and returns that card. The Card attribute is then incremented to identify the card that follows it. result = astFindFits( fitschan, " COMMENT" , NULL, 0 ); Sets the Card attribute of a FitsChan to identify the next COMMENT card (if any). The card itself is not returned. result = astFindFits( fitschan, " CRVAL%1d" , card, 1 ); Searches a FitsChan for the next card with a keyword of the form " CRVALi" (for example, any of the keywords " CRVAL1" , " CRVAL2" or " CRVAL3" would be matched). The card found (if any) is returned, and the Card attribute is then incremented to identify the following card (ready to search for another keyword with the same form, perhaps). The search always starts with the current card, as identified by the Card attribute. To ensure you search the entire contents of a FitsChan, you should first clear the Card attribute (using astClearastClear). This effectively " rewinds" the FitsChan.

If a search is unsuccessful, the Card attribute is set to the " end-of-file" (i.e. to one more than the number of cards in the FitsChan). No error occurs.

A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Keyword Templates The templates used to match FITS keywords are normally composed of literal characters, which must match the keyword exactly (apart from case). However, a template may also contain " field specifiers" which can match a range of possible characters. This allows you to search for keywords that contain (for example) numbers, where the digits comprising the number are not known in advance.

A field specifier starts with a " %" character. This is followed by an optional single digit (0 to 9) specifying a field width. Finally, there is a single character which specifies the

type of character to be matched, as follows:

" c" : matches all upper case letters,

" d" : matches all decimal digits,

" f" : matches all characters which are permitted within a FITS keyword (upper case letters, digits, underscores and hyphens).

If the field width is omitted, the field specifier matches one or more characters. If the field width is zero, it matches zero or more characters. Otherwise, it matches exactly the number of

characters specified. In addition to this:

The template " %f" will match a blank FITS keyword consisting of 8 spaces (as well as matching all other keywords).

A template consisting of 8 spaces will match a blank keyword (only).

For example:

The template " BitPix" will match the keyword " BITPIX" only.

The template " crpix%1d" will match keywords consisting of " CRPIX" followed by one decimal digit.

The template " P%c" will match any keyword starting with " P" and followed by one or more letters.

The template " E%0f" will match any keyword beginning with " E" .

The template " %f" will match any keyword at all (including a blank one). astFindFrame Find a coordinate system with specified characteristics This function uses a " template" FrameFrame to search another Frame (or FrameSetFrameSet) to identify a coordinate system which has a specified set of characteristics. If a suitable coordinate system can be found, the function returns a pointer to a FrameSet which describes the required coordinate system and how to convert coordinates to and from it.

This function is provided to help answer general questions about coordinate systems, such as typically arise when coordinate information is imported into a program as part of an initially unknown dataset. For example: Is there a wavelength scale?

Is there a 2-dimensional coordinate system?

Is there a celestial coordinate system?

Can I plot the data in ecliptic coordinates?

You can also use this function as a means of reconciling a user' s preference for a particular coordinate system (for example, what type of axes to draw) with what is actually possible given the coordinate information available.

To perform a search, you supply a " target" Frame (or FrameSet) which represents the set of coordinate systems to be searched. If a basic Frame is given as the target, this set of coordinate systems consists of the one described by this Frame, plus all other " virtual" coordinate systems which can potentially be reached from it by applying built-in conversions (for example, any of the celestial coordinate conversions known to the AST library would constitute a " built-in" conversion). If a FrameSet is given as the target, the set of coordinate systems to be searched consists of the union of those represented by all the individual Frames within it.

To select from this large set of possible coordinate systems, you supply a " template" Frame which is an instance of the type of Frame you are looking for. Effectively, you then ask the function to " find a coordinate system that looks like this" .

You can make your request more or less specific by setting attribute values for the template Frame. If a particular attribute is set in the template, then the function will only find coordinate systems which have exactly the same value for that attribute. If you leave a template attribute un-set, however, then the function has discretion about the value the attribute should have in any coordinate system it finds. The attribute will then take its value from one of the actual (rather than virtual) coordinate systems in the target. If the target is a FrameSet, its CurrentCurrent attribute will be modified to indicate which of its Frames was used for this purpose.

The result of this process is a coordinate system represented by a hybrid Frame which acquires some attributes from the template (but only if they were set) and the remainder from the target. This represents the " best compromise" between what you asked for and what was available. A MappingMapping is then generated which converts from the target coordinate system to this hybrid one, and the returned FrameSet encapsulates all of this information. Synopsis AstFrameSet $*$astFindFrame( AstFrame $*$target, AstFrame $*$template, const char $*$domainlist ) target Pointer to the target Frame (or FrameSet).

Note that if a FrameSet is supplied (and a suitable coordinate system is found), then its Current attribute will be modified to indicate which Frame was used to obtain attribute values which were not specified by the template. This Frame will, in some sense, represent the " closest" non-virtual coordinate system to the one you requested. template Pointer to the template Frame, which should be an instance of the type of Frame you wish to find. If you wanted to find a Frame describing a celestial coordinate system, for example, then you might use a SkyFrameSkyFrame here. See the " Examples" section for more ideas. domainlist Pointer to a null-terminated character string containing a comma-separated list of Frame domains. This may be used to establish a priority order for the different types of coordinate system that might be found.

The function will first try to find a suitable coordinate system whose DomainDomain attribute equals the first domain in this list. If this fails, the second domain in the list will be used, and so on, until a result is obtained. A blank domain (e.g. two consecutive commas) indicates that any coordinate system is acceptable (subject to the template) regardless of its domain.

This list is case-insensitive and all white space is ignored. If you do not wish to restrict the domain in this way, you should supply an empty string. Frame This function applies to all Frames. FrameSet If the target is a FrameSet, the possibility exists that several of the Frames within it might be matched by the template. Unless the choice is sufficiently restricted by the " domainlist" string, the sequence in which Frames are searched can then become important. In this case, the search proceeds as follows: Each field in the " domainlist" string is considered in turn.

An attempt is made to match the template to each of the target' s Frames in the order: (1) the current Frame, (2) the base Frame, (3) each remaining Frame in the order of being added to the target FrameSet.

Generally, the first match found is used. However, the Mapping between the target coordinate system and the resulting Frame is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the TranForwardTranForward and TranInverseTranInverse attributes). If only one transformation is defined, the forward one is preferred.

If a match is found and the domain of the resulting Frame also matches the current " domainlist" field, it is accepted. Otherwise, the next " domainlist" field is considered and the process repeated.

If a suitable coordinate system is found, the Current attribute of the target FrameSet will be modified on exit to identify the Frame whose match with the target was eventually accepted. astFindFrame() If the search is successful, the function returns a pointer to a FrameSet which contains the Frame found and a description of how to convert to (and from) the coordinate system it represents. Otherwise, a null ObjectObject pointer (AST__NULL) is returned without error.

If a FrameSet is returned, it will contain two Frames. Frame number 1 (its base Frame) represents the target coordinate system and will be the same as the (base Frame of the) target. Frame number 2 (its current Frame) will be a Frame representing the coordinate system which the function found. The Mapping which inter-relates these two Frames will describe how to convert between their respective coordinate systems.

Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with astTran2astTran2), then it provides a means of converting coordinates from the target coordinate system into the new coordinate system that was found (and vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the new coordinate system. result = astFindFrame( target, astFrameastFrame( 3, " " ), " " ); Searches for a 3-dimensional coordinate system in the target Frame (or FrameSet). No attributes have been set in the template Frame (created by astFrame), so no restriction has been placed on the required coordinate system, other than that it should have 3 dimensions. The first suitable Frame found will be returned as part of the " result" FrameSet. result = astFindFrame( target, astSkyFrameastSkyFrame( " " ), " " ); Searches for a celestial coordinate system in the target Frame (or FrameSet). The type of celestial coordinate system is unspecified, so astFindFrame will return the first one found as part of the " result" FrameSet. If the target is a FrameSet, then its Current attribute will be updated to identify the Frame that was used.

If no celestial coordinate system can be found, a value of AST__NULL will be returned without error. result = astFindFrame( target, astSkyFrame( " MaxAxesMaxAxes=100" ), " " ); This is like the last example, except that in the event of the target being a CmpFrameCmpFrame, the component Frames encapsulated by the CmpFrame will be searched for a SkyFrame. If found, the returned Mapping will included a PermMapPermMap which selects the required axes from the target CmpFrame.

This is acomplished by setting the MaxAxes attribute of the template SkyFrame to a large number (larger than or equal to the number of axes in the target CmpFrame). This allows the SkyFrame to be used as a match for Frames containing from 2 to 100 axes. result = astFindFrame( target, astSkyFrame( " SystemSystem=FK5" ), " " ); Searches for an equatorial (FK5) coordinate system in the target. The EquinoxEquinox value for the coordinate system has not been specified, so will be obtained from the target. If the target is a FrameSet, its Current attribute will be updated to indicate which SkyFrame was used to obtain this value. result = astFindFrame( target, astFrame( 2, " " ), " sky,pixel," ); Searches for a 2-dimensional coordinate system in the target. Initially, a search is made for a suitable coordinate system whose Domain attribute has the value " SKY" . If this search fails, a search is then made for one with the domain " PIXEL" . If this also fails, then any 2-dimensional coordinate system is returned as part of the " result" FrameSet.

Only if no 2-dimensional coordinate systems can be reached by applying built-in conversions to any of the Frames in the target will a value of AST__NULL be returned. result = astFindFrame( target, astFrame( 1, " Domain=WAVELENGTH" ), " " ); Searches for any 1-dimensional coordinate system in the target which has the domain " WAVELENGTH" . result = astFindFrame( target, astFrame( 1, " " ), " wavelength" ); This example has exactly the same effect as that above. It illustrates the equivalence of the template' s Domain attribute and the fields in the " domainlist" string. result = astFindFrame( target, astFrame( 1, " MaxAxes=3" ), " " ); This is a more advanced example which will search for any coordinate system in the target having 1, 2 or 3 dimensions. The Frame returned (as part of the " result" FrameSet) will always be 1-dimensional, but will be related to the coordinate system that was found by a suitable Mapping (e.g. a PermMap) which simply extracts the first axis.

If we had wanted a Frame representing the actual (1, 2 or 3-dimensional) coordinate system found, we could set the PreserveAxesPreserveAxes attribute to a non-zero value in the template. result = astFindFrame( target, astSkyFrame( " PermutePermute=0" ), " " ); Searches for any celestial coordinate system in the target, but only finds one if its axes are in the conventional (longitude,latitude) order and have not been permuted (e.g. with astPermAxesastPermAxes). The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystemAlignSystem attribute of the " template" Frame. See the description of the AlignSystem attribute for further details.

Beware of setting the Domain attribute of the template and then using a " domainlist" string which does not include the template' s domain (or a blank field). If you do so, no coordinate system will be found.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. More on Using Templates A Frame (describing a coordinate system) will be found by this function if (a) it is " matched" by the template you supply, and (b) the value of its Domain attribute appears in the " domainlist" string (except that a blank field in this string permits any domain). A successful match by the template depends on a number of criteria, as outlined below: In general, a template will only match another Frame which belongs to the same class as the template, or to a derived (more specialised) class. For example, a SkyFrame template will match any other SkyFrame, but will not match a basic Frame. Conversely, a basic Frame template will match any class of Frame.

The exception to this is that a Frame of any class can be used to match a CmpFrame, if that CmpFrame contains a Frame of the same class as the template. Note however, the MaxAxes and MinAxesMinAxes attributes of the template must be set to suitable values to allow it to match the CmpFrame. That is, the MinAxes attribute must be less than or equal to the number of axes in the target, and the MaxAxes attribute must be greater than or equal to the number of axes in the target.

If using a CmpFrame as a template frame, the MinAxes and MaxAxes for the template are determined by the MinAxes and MaxAxes values of the component Frames within the template. So if you want a template CmpFrame to be able to match Frames with different numbers of axes, then you must set the MaxAxes and/or MinAxes attributes in the component template Frames, before combining them together into the template CmpFrame.

If a template has a value set for any of its main attributes, then it will only match Frames which have an identical value for that attribute (or which can be transformed, using a built-in conversion, so that they have the required value for that attribute). If any attribute in the template is un-set, however, then Frames are matched regardless of the value they may have for that attribute. You may therefore make a template more or less specific by choosing the attributes for which you set values. This requirement does not apply to ' descriptive' attributes such as titles, labels, symbols, etc.

An important application of this principle involves the Domain attribute. Setting the Domain attribute of the template has the effect of restricting the search to a particular type of Frame (with the domain you specify). Conversely, if the Domain attribute is not set in the template, then the domain of the Frame found is not relevant, so all Frames are searched. Note that the " domainlist" string provides an alternative way of restricting the search in the same manner, but is a more convenient interface if you wish to search automatically for another domain if the first search fails.

Normally, a template will only match a Frame which has the same number of axes as itself. However, for some classes of template, this default behaviour may be changed by means of the MinAxes, MaxAxes and MatchEndMatchEnd attributes. In addition, the behaviour of a template may be influenced by its Permute and PreserveAxes attributes, which control whether it matches Frames whose axes have been permuted, and whether this permutation is retained in the Frame which is returned (as opposed to returning the axes in the order specified in the template, which is the default behaviour). You should consult the descriptions of these attributes for details of this more advanced use of templates. astFitsChan Create a FitsChan This function creates a new FitsChanFitsChan and optionally initialises its attributes.

A FitsChan is a specialised form of ChannelChannel which supports I/O operations involving the use of FITS (Flexible Image Transport SystemSystem) header cards. Writing an ObjectObject to a FitsChan (using astWriteastWrite) will, if the Object is suitable, generate a description of that Object composed of FITS header cards, and reading from a FitsChan will create a new Object from its FITS header card description.

While a FitsChan is active, it represents a buffer which may contain zero or more 80-character " header cards" conforming to FITS conventions. Any sequence of FITS-conforming header cards may be stored, apart from the " END" card whose existence is merely implied. The cards may be accessed in any order by using the FitsChan' s integer CardCard attribute, which identifies a " current" card, to which subsequent operations apply. Searches based on keyword may be performed (using astFindFitsastFindFits), new cards may be inserted (astPutFitsastPutFits, astPutCardsastPutCards, astSetFits$<$X$>$astSetFits$<$X$>$) and existing ones may be deleted (astDelFitsastDelFits) or changed (astSetFits$<$X$>$).

When you create a FitsChan, you have the option of specifying " source" and " sink" functions which connect it to external data stores by reading and writing FITS header cards. If you provide a source function, it is used to fill the FitsChan with header cards when it is accessed for the first time. If you do not provide a source function, the FitsChan remains empty until you explicitly enter data into it (e.g. using astPutFits, astPutCards, astWrite or by using the SourceFileSourceFile attribute to specifying a text file from which headers should be read). When the FitsChan is deleted, any remaining header cards in the FitsChan can be saved in either of two ways: 1) by specifying a value for the SinkFileSinkFile attribute (the name of a text file to which header cards should be written), or 2) by providing a sink function (used to to deliver header cards to an external data store). If you do not provide a sink function or a value for SinkFile, any header cards remaining when the FitsChan is deleted will be lost, so you should arrange to extract them first if necessary (e.g. using astFindFits or astReadastRead).

Coordinate system information may be described using FITS header cards using several different conventions, termed " encodings" . When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan' s EncodingEncoding attribute determines how the Object is converted to (or from) a description involving FITS header cards. In general, different encodings will result in different sets of header cards to describe the same Object. Examples of encodings include the DSS encoding (based on conventions used by the STScI Digitised Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard) and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS headers).

The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings.

The detailed behaviour of astRead and astWrite, when used with a FitsChan, depends on the encoding in use. In general, however, all use of astRead is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the astRetainFitsastRetainFits function).

If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using astWrite will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence. Synopsis AstFitsChan $*$astFitsChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) source Pointer to a source function which takes no arguments and returns a pointer to a null-terminated string. This function will be used by the FitsChan to obtain input FITS header cards. On each invocation, it should read the next input card from some external source (such as a FITS file), and return a pointer to the (null-terminated) contents of the card. It should return a NULL pointer when there are no more cards to be read.

If " source" is NULL, the FitsChan will remain empty until cards are explicitly stored in it (e.g. using astPutCards, astPutFits or via the SourceFile attribute). sink Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the FitsChan to deliver any FITS header cards it contains when it is finally deleted. On each invocation, it should deliver the contents of the character string passed to it as a FITS header card to some external data store (such as a FITS file).

If " sink" is NULL, and no value has been set for the SinkFile attribute, the contents of the FitsChan will be lost when it is deleted. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsChan. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function).

Note, the FITSCHAN_OPTIONS environment variable may be used to specify default options for all newly created FitsChans. astFitsChan() A pointer to the new FitsChan. No FITS " END" card will be written via the sink function. You should add this card yourself after the FitsChan has been deleted.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astFitsTable Create a FitsTable This function creates a new FitsTableFitsTable and optionally initialises its attributes.

The FitsTable class is a representation of a FITS binary table. It inherits from the TableTable class. The parent Table is used to hold the binary data of the main table, and a FitsChanFitsChan is used to hold the FITS header. Note, there is no provision for binary data following the main table (such data is referred to as a " heap" in the FITS standard).

Note - it is not recommended to use the FitsTable class to store very large tables. Synopsis AstFitsTable $*$astFitsTable( AstFitsChan $*$header, const char $*$options, ... ) header Pointer to an optional FitsChan containing headers to be stored in the FitsTable. NULL may be supplied if the new FitsTable is to be left empty. If supplied, and if the headers describe columns of a FITS binary table, then equivalent (empty) columns are added to the FitsTable. Each column has the same index in the FitsTable that it has in the supplied header. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsTable. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astFitsTable() A pointer to the new FitsTable. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astFluxFrame Create a FluxFrame This function creates a new FluxFrameFluxFrame and optionally initialises its attributes.

A FluxFrame is a specialised form of one-dimensional FrameFrame which represents various systems used to represent the signal level in an observation. The particular coordinate system to be used is specified by setting the FluxFrame' s SystemSystem attribute qualified, as necessary, by other attributes such as the units, etc (see the description of the System attribute for details).

All flux values are assumed to be measured at the same frequency or wavelength (as given by the SpecValSpecVal attribute). Thus this class is more appropriate for use with images rather than spectra. Synopsis AstFluxFrame $*$astFluxFrame( double specval, AstSpecFrame $*$specfrm, const char $*$options, ... ) specval The spectral value to which the flux values refer, given in the spectral coordinate system specified by " specfrm" . The value supplied for the " specval" parameter becomes the default value for the SpecVal attribute. A value of AST__BAD may be supplied if the spectral position is unknown, but this may result in it not being possible for the astConvertastConvert function to determine a MappingMapping between the new FluxFrame and some other FluxFrame. specfrm A pointer to a SpecFrameSpecFrame describing the spectral coordinate system in which the " specval" parameter is given. A deep copy of this object is taken, so any subsequent changes to the SpecFrame using the supplied pointer will have no effect on the new FluxFrame. A NULL pointer can be supplied if AST__BAD is supplied for " specval" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FluxFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astFluxFrame() A pointer to the new FluxFrame. When conversion between two FluxFrames is requested (as when supplying FluxFrames to astConvert), account will be taken of the nature of the flux coordinate systems they represent, together with any qualifying attribute values, including the AlignSystemAlignSystem attribute. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astFormat Format a coordinate value for a Frame axis This function returns a pointer to a string containing the formatted (character) version of a coordinate value for a FrameFrame axis. The formatting applied is determined by the Frame' s attributes and, in particular, by any Format attribute string that has been set for the axis. A suitable default format (based on the Digits attribute value) will be applied if necessary. Synopsis const char $*$astFormat( AstFrame $*$this, int axis, double value ) this Pointer to the Frame. axis The number of the Frame axis for which formatting is to be performed (axis numbering starts at 1 for the first axis). value The coordinate value to be formatted. astFormat() A pointer to a null-terminated string containing the formatted value. The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this.

A formatted value may be converted back into a numerical (double) value using astUnformatastUnformat.

A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astFrame Create a Frame This function creates a new FrameFrame and optionally initialises its attributes.

A Frame is used to represent a coordinate system. It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a TitleTitle (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two.

Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame.

Frames may also contain knowledge of how to transform to and from related coordinate systems. Synopsis AstFrame $*$astFrame( int naxes, const char $*$options, ... ) naxes The number of Frame axes (i.e. the number of dimensions of the coordinate space which the Frame describes). options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Frame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astFrame() A pointer to the new Frame. frame = astFrame( 2, " Title=Energy Spectrum: PlotPlot %d" , n ); Creates a new 2-dimensional Frame and initialises its Title attribute to the string " Energy Spectrum: Plot $<$n$>$" , where $<$n$>$ takes the value of the int variable " n" . frame = astFrame( 2, " Label(1)=Energy, Label(2)=Response" ); Creates a new 2-dimensional Frame and initialises its axis Label attributes to suitable string values. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astFrameSet Create a FrameSet This function creates a new FrameSetFrameSet and optionally initialises its attributes.

A FrameSet consists of a set of one or more Frames (which describe coordinate systems), connected together by Mappings (which describe how the coordinate systems are inter-related). A FrameSet makes it possible to obtain a MappingMapping between any pair of these Frames (i.e. to convert between any of the coordinate systems which it describes). The individual Frames are identified within the FrameSet by an integer index, with Frames being numbered consecutively from one as they are added to the FrameSet.

Every FrameSet has a " base" FrameFrame and a " current" Frame (which are allowed to be the same). Any of the Frames may be nominated to hold these positions, and the choice is determined by the values of the FrameSet' s BaseBase and CurrentCurrent attributes, which hold the indices of the relevant Frames. By default, the first Frame added to a FrameSet is its base Frame, and the last one added is its current Frame.

The base Frame describes the " native" coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the " apparent" coordinate system in which it should be viewed (e.g. displayed, etc.). Any further Frames represent a library of alternative coordinate systems, which may be selected by making them current.

When a FrameSet is used in a context that requires a Frame, (e.g. obtaining its TitleTitle value, or number of axes), the current Frame is used. A FrameSet may therefore be used in place of its current Frame in most situations.

When a FrameSet is used in a context that requires a Mapping, the Mapping used is the one between its base Frame and its current Frame. Thus, a FrameSet may be used to convert " native" coordinates into " apparent" ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see astInvertastInvert), which has the effect of interchanging its base and current Frames and hence of reversing the Mapping between them.

Regions may be added into a FrameSet (since a RegionRegion is a type of Frame), either explicitly or as components within CmpFrames. In this case the Mapping between a pair of Frames within a FrameSet will include the effects of the clipping produced by any Regions included in the path between the Frames. Synopsis AstFrameSet $*$astFrameSet( AstFrame $*$frame, const char $*$options, ... ) frame Pointer to the first Frame to be inserted into the FrameSet. This initially becomes both the base and the current Frame. (Further Frames may be added using the astAddFrameastAddFrame function.) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FrameSet. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astFrameSet() A pointer to the new FrameSet. If a pointer to an existing FrameSet is given for the " frame" parameter, then the new FrameSet will (as a special case) be initialised to contain the same Frames and Mappings, and to have the same attribute values, as the one supplied. This process is similar to making a copy of a FrameSet (see astCopyastCopy), except that the Frames and Mappings contained in the original are not themselves copied, but are shared by both FrameSets.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astFromString Re-create an Object from an in-memory serialisation This function returns a pointer to a new ObjectObject created from the supplied text string, which should have been created by astToStringastToString. Synopsis AstObject $*$astFromString( const char $*$string ) string Pointer to a text string holding an Object serialisation created previously by astToString. astFromString() Pointer to a new Object created from the supplied serialisation, or NULL if the serialisation was invalid, or an error occurred. astGenCurve Draw a generalized curve This function draws a general user-defined curve defined by the supplied MappingMapping. Note that the curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the Mapping involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using astClipastClip.

If you need to draw simple straight lines (geodesics), astCurveastCurve or astPolyCurveastPolyCurve will usually be easier to use and faster. Synopsis void astGenCurve( AstPlot $*$this, astMapping $*$map ) this Pointer to the PlotPlot. map Pointer to a Mapping. This Mapping should have 1 input coordinate representing offset along the required curve, normalized so that the start of the curve is at offset 0.0, and the end of the curve is at offset 1.0. Note, this offset does not need to be linearly related to distance along the curve. The number of output coordinates should equal the number of axes in the current FrameFrame of the Plot. The Mapping should map a specified offset along the curve, into the corresponding coordinates in the current Frame of the Plot. The inverse transformation need not be defined. An error results if the base Frame of the Plot is not 2-dimensional.

An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot' s TranInverseTranInverse attribute is zero). astGet$<$X$>$ Get an attribute value for an Object This is a family of functions which return a specified attribute value for an ObjectObject using one of several different data types. The type is selected by replacing $<$X$>$ in the function name by C, D, F, I or L, to obtain a result in const char$*$ (i.e. string), double, float, int, or long format, respectively.

If possible, the attribute value is converted to the type you request. If conversion is not possible, an error will result. Synopsis $<$X$>$type astGet$<$X$>$( AstObject $*$this, const char $*$attrib ) this Pointer to the Object. attrib Pointer to a null-terminated string containing the name of the attribute whose value is required. Object These functions apply to all Objects. astGet$<$X$>$() The attribute value, in the data type corresponding to $<$X$>$ (or, in the case of astGetC, a pointer to a constant null-terminated character string containing this value). printf( " RefCountRefCount = %d$\backslash$n" , astGetI( z, " RefCount" ) ); Prints the RefCount attribute value for Object " z" as an int. title = astGetC( axis, " TitleTitle" ); Obtains a pointer to a null-terminated character string containing the Title attribute of Object " axis" . Attribute names are not case sensitive and may be surrounded by white space.

An appropriate " null" value will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. This null value is zero for numeric values and NULL for pointer values.

The pointer returned by astGetC is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. astGetActiveUnit Determines how the Unit attribute will be used This function returns the current value of the ActiveUnit flag for a FrameFrame. See the description of the astSetActiveUnitastSetActiveUnit function for a description of the ActiveUnit flag. Synopsis int astGetActiveUnit( AstFrame $*$this ) this Pointer to the Frame. astGetActiveUnit The current value of the ActiveUnit flag. A zero value will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetCell Identify the next cell in a normalised Moc This function returns the order and " npix" value for the cell at a specified index in the normalised MocMoc. See the MOC recommendation for more information about " npix" values and MOC normalisation. Synopsis void astGetCell( AstMoc $*$this, int icell, int $*$order, int64_t $*$npix ) this Pointer to the Moc to be modified. icell The index of the cell for which information is required. The first cell has index zero. An error will be reported if the supplied value is greater than or equal to the value of the MocLengthMocLength attribute. order Returned holding the HEALPix order of the cell at the requested index. npix Returned holding the " npix" value of the cell at the requested index. astGetColumnData Retrieve all the data values stored in a column This function copies all data values from a named column into a supplied buffer Synopsis void astGetColumnData( AstFitsTable $*$this, const char $*$column, float fnull, double dnull, size_t mxsize, void $*$coldata, int $*$nelem ) this Pointer to the FitsTableFitsTable. column The character string holding the name of the column. Trailing spaces are ignored. fnull The value to return in " coldata" for any cells for which no value has been stored in the FitsTable. Ignored if the column' s data type is not AST__FLOATTYPE. Supplying AST__NANF will cause a single precision IEEE NaN value to be used. dnull The value to return in " coldata" for any cells for which no value has been stored in the FitsTable. Ignored if the column' s data type is not AST__DOUBLETYPE. Supplying AST__NAN will cause a double precision IEEE NaN value to be used. mxsize The size of the " coldata" array, in bytes. The amount of memory needed to hold the data from a column may be determined using astColumnSizeastColumnSize. If the supplied array is too small to hold all the column data, trailing column values will be omitted from the returned array, but no error will be reported. coldata A pointer to an area of memory in which to return the data values currently stored in the column. The values are stored in row order. If the column holds non-scalar values, the elements of each value are stored in " Fortran" order. No data type conversion is performed - the data type of each returned value is the data type associated with the column when the column was added to the table. If the column holds strings, the returned strings will be null terminated. Any excess room at the end of the array will be left unchanged. nelem The number of elements returned in the " coldata" array. This is the product of the number of rows returned and the number of elements in each column value. The " fnull" and " dnull" parameters specify the value to be returned for any empty cells within columns holding floating point values. For columns holding integer values, the value returned for empty cells is the value returned by the astColumNull function. For columns holding string values, the ASCII NULL character is returned for empty cells. astGetFits$<$X$>$ Get a named keyword value from a FitsChan This is a family of functions which gets a value for a named keyword, or the value of the current card, from a FitsChanFitsChan using one of several different data types. The data type of the returned value is selected by replacing $<$X$>$ in the function name by one of the following strings representing the recognised FITS data types:

CF - Complex floating point values.

CI - Complex integer values.

F - Floating point values.

I - Integer values.

L - Logical (i.e. boolean) values.

S - String values.

CN - A " CONTINUE" value, these are treated like string values, but are encoded without an equals sign.

The data type of the " value" parameter

depends on $<$X$>$ as follows:

CF - " double $*$" (a pointer to a 2 element array to hold the real and imaginary parts of the complex value).

CI - " int $*$" (a pointer to a 2 element array to hold the real and imaginary parts of the complex value).

F - " double $*$" .

I - " int $*$" .

L - " int $*$" .

S - " char $*$$*$" (a pointer to a static " char" array is returned at the location given by the " value" parameter, Note, the stored string may change on subsequent invocations of astGetFitsS so a permanent copy should be taken of the string if necessary).

CN - Like" S" . Synopsis int astGetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type $*$value ) this Pointer to the FitsChan. name Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. If NULL is supplied, the value of the current card is returned. value A pointer to a buffer to receive the keyword value. The data type depends on $<$X$>$ as described above. The conents of the buffer on entry are left unchanged if the keyword is not found. astGetFits$<$X$>$$<$X$>$() A value of zero is returned if the keyword was not found in the FitsChan (no error is reported). Otherwise, a value of one is returned. If a name is supplied, the card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards.

If the requested card is found, it becomes the current card, otherwise the current card is left pointing at the " end-of-file" .

If the stored keyword value is not of the requested type, it is converted into the requested type.

If the keyword is found in the FitsChan, but has no associated value, an error is reported. If necessary, the astTestFitsastTestFits function can be used to determine if the keyword has a defined value in the FitsChan prior to calling this function.

An error will be reported if the keyword name does not conform to FITS requirements.

Zero

.FALSE. is returned as the function value if an error has already occurred, or if this function should fail for any reason.

The FITS standard says that string keyword values should be padded with trailing spaces if they are shorter than 8 characters. For this reason, trailing spaces are removed from the string returned by astGetFitsS if the original string (including any trailing spaces) contains 8 or fewer characters. Trailing spaces are not removed from longer strings. astGetFrame Obtain a pointer to a specified Frame in a FrameSet This function returns a pointer to a specified FrameFrame in a FrameSetFrameSet. Synopsis AstFrame $*$astGetFrame( AstFrameSet $*$this, int iframe ) this Pointer to the FrameSet. iframe The index of the required Frame within the FrameSet. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). astGetFrame() A pointer to the requested Frame. A value of AST__BASE or AST__CURRENT may be given for the " iframe" parameter to specify the base Frame or the current Frame respectively.

This function increments the RefCountRefCount attribute of the selected Frame by one.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetGrfContext Return the KeyMap that describes a Plot' s graphics context This function returns a reference to a KeyMapKeyMap that will be passed to any drawing functions registered using astGrfSetastGrfSet. This KeyMap can be used by an application to pass information to the drawing functions about the context in which they are being called. The contents of the KeyMap are never accessed byt the PlotPlot class itself. Synopsis AstKeyMap $*$astGetGrfContext( AstPlot $*$this ) this Pointer to the Plot. astGetGrfContext() A pointer to the graphics context KeyMap. The returned pointer should be annulled when it is no longer needed. astGetMapping Obtain a Mapping that converts between two Frames in a FrameSet This function returns a pointer to a MappingMapping that will convert coordinates between the coordinate systems represented by two Frames in a FrameSetFrameSet. Synopsis AstMapping $*$astGetMapping( AstFrameSet $*$this, int iframe1, int iframe2 ) this Pointer to the FrameSet. iframe1 The index of the first FrameFrame in the FrameSet. This Frame describes the coordinate system for the " input" end of the Mapping. iframe2 The index of the second Frame in the FrameSet. This Frame describes the coordinate system for the " output" end of the Mapping. astGetMapping() Pointer to a Mapping whose forward transformation converts coordinates from the first coordinate system to the second one, and whose inverse transformation converts coordinates in the opposite direction. The returned Mapping will include the clipping effect of any Regions which occur on the path between the two supplied Frames (this includes the two supplied Frames themselves).

The values given for the " iframe1" and " iframe2" parameters should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). A value of AST__BASE or AST__CURRENT may also be given to identify the FrameSet' s base Frame or current Frame respectively. It is permissible for both these parameters to have the same value, in which case a unit Mapping (UnitMapUnitMap) is returned.

It should always be possible to generate the Mapping requested, but this does necessarily guarantee that it will be able to perform the required coordinate conversion. If necessary, the TranForwardTranForward and TranInverseTranInverse attributes of the returned Mapping should be inspected to determine if the required transformation is available.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetMocData Get the FITS binary table data describing a Moc This function retrieves the data values that form the FITS binary table representation of the MOC and stores them in a supplied array. Such a table contains a single scalar-valued column in which each row holds a signed integer identifier for a single HEALPix cell, following the scheme described in the MOC recommendation. Depending on the order of the MocMoc, these integers may be 4 bytes or 8 bytes.

The number of rows in the table and the required integer data type are available through the MocTypeMocType and MocLengthMocLength attributes of the Moc class.

The FITS headers to store in the FITS binary table can be obtained using function astGetMocHeaderastGetMocHeader. Synopsis void astGetMocData( AstMoc $*$this, size_t mxsize, void $*$data ) this Pointer to the Moc to be modified. mxsize The length of the supplied array in bytes. An error will be reported if this value is smaller than the number required to describe the Moc (the product of the MocType and MocLength attributes). data Pointer to the area of memory in which to return the signed integer cell identifiers. This area is assumed to contain at least " mxsize" bytes. astGetMocHeader Get the FITS binary table headers describing a Moc This function returns a FitsChanFitsChan holding the headers that should be stored in a FITS binary table extension describing the supplied MocMoc. The data values for the extension can be obtained using method astGetMocDataastGetMocData. Synopsis AstFitsCHan $*$astGetMocHeader( AstMoc $*$this ) this Pointer to the Moc to be modified. astGetMocString Get the JSON or string-encoded representation of a Moc This function stores the JSON or string-encoded representation of the supplied MocMoc in the supplied string buffer. Synopsis void astGetMocString( AstMoc $*$this, int json, size_t mxsize, char $*$string, size_t $*$size, int $*$status ) this Pointer to the Moc. json If non-zero, the Moc is encoded using JSON serialisation. Otherwise it is encoded using string-serialisation. mxsize The length of the supplied string buffer in bytes. An error will be reported if this value is smaller than the number required to describe the Moc. However, if zero is supplied, the buffer will be ignored - no string will be returned but the required size of the buffer will still be returned in ' size' . string Pointer to the area of memory in which to return the JSON or string-encoded representation of the Moc. This area is assumed to contain at least ' mxsize' bytes. Only used if ' mxsize' is greater than zero. Note, the string is not null-terminated. size Returned holding the number of bytes needed to store the complete JSON or string-encoded representation of the Moc. astGetRefPos Return the reference position in a specified celestial coordinate system This function returns the reference position (specified by attributes RefRARefRA and RefDecRefDec) converted to the celestial coordinate system represented by a supplied SkyFrameSkyFrame. The celestial longitude and latitude values are returned in radians. Synopsis void astGetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double $*$lon, double $*$lat ) this Pointer to the SpecFrameSpecFrame. frm Pointer to the SkyFrame which defines the required celestial coordinate system. If NULL is supplied, then the longitude and latitude values are returned as FK5 J2000 RA and Dec values. lon A pointer to a double in which to store the longitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). lat A pointer to a double in which to store the latitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). Values of AST__BAD will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetRegionBounds Returns the bounding box of Region This function returns the upper and lower limits of a box which just encompasses the supplied RegionRegion. The limits are returned as axis values within the FrameFrame represented by the Region. The value of the NegatedNegated attribute is ignored (i.e. it is assumed that the Region has not been negated). Synopsis void astGetRegionBounds( AstRegion $*$this, double $*$lbnd, double $*$ubnd ) this Pointer to the Region. lbnd Pointer to an array in which to return the lower axis bounds covered by the Region. It should have at least as many elements as there are axes in the Region. If an axis has no lower limit, the returned value will be the largest possible negative value. ubnd Pointer to an array in which to return the upper axis bounds covered by the Region. It should have at least as many elements as there are axes in the Region. If an axis has no upper limit, the returned value will be the largest possible positive value. The value of the Negated attribute is ignored (i.e. it is assumed that the Region has not been negated).

If an axis has no extent on an axis then the lower limit will be returned larger than the upper limit. Note, this is different to an axis which has a constant value (in which case both lower and upper limit will be returned set to the constant value).

If the bounds on an axis cannot be determined, AST__BAD is returned for both upper and lower bounds astGetRegionDisc Returns the centre and radius of a disc containing a 2D Region This function returns the centre and radius of a disc that just encloses the supplied 2-dimensional RegionRegion. The centre is returned as a pair of axis values within the FrameFrame represented by the Region. The value of the NegatedNegated attribute is ignored (i.e. it is assumed that the Region has not been negated). Synopsis void astGetRegionDisc( AstRegion $*$this, double centre[2], double $*$radius ) this Pointer to the Region. centre Pointer to a two-element array in which to return the axis values at the centre of the bounding disc. radius Pointer to a variable in which to return the radius of the bounding disc, as a geodesic distance within the Frame represented by the Region. It will be returned holding AST__BAD If the Region is unbounded. An error is reported if the Region is not 2-dimensional.

The value of the Negated attribute is ignored (i.e. it is assumed that the Region has not been negated).

If the Region is unbounded, the radius will be returned set to AST__BAD and the supplied centre axis values will be returned unchanged. astGetRegionFrame Obtain a pointer to the encapsulated Frame within a Region This function returns a pointer to the FrameFrame represented by a RegionRegion. Synopsis AstFrame $*$astGetRegionFrame( AstRegion $*$this ) this Pointer to the Region. astGetRegionFrame() A pointer to a deep copy of the Frame represented by the Region. Using this pointer to modify the Frame will have no effect on the Region. To modify the Region, use the Region pointer directly. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetRegionFrameSet Obtain a pointer to the encapsulated FrameSet within a Region This function returns a pointer to the FrameSetFrameSet encapsulated by a RegionRegion. The base FrameFrame is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by astGetRegionFrameastGetRegionFrame). Synopsis AstFrame $*$astGetRegionFrameSet( AstRegion $*$this ) this Pointer to the Region. astGetRegionFrameSet() A pointer to a deep copy of the FrameSet represented by the Region. Using this pointer to modify the FrameSet will have no effect on the Region. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetRegionMesh Return a mesh of points covering the surface or volume of a Region This function returns the axis values at a mesh of points either covering the surface (i.e. boundary) of the supplied RegionRegion, or filling the interior (i.e. volume) of the Region. The number of points in the mesh is determined by the MeshSizeMeshSize attribute. Synopsis void astGetRegionMesh( AstRegion $*$this, int surface, int maxpoint, int maxcoord, int $*$npoint, double $*$points ) this Pointer to the Region. surface If non-zero, the returned points will cover the surface or the Region. Otherwise, they will fill the interior of the Region. maxpoint If zero, the number of points in the mesh is returned in " $*$npoint" , but no axis values are returned and all other parameters are ignored. If not zero, the supplied value should be the length of the second dimension of the " points" array. An error is reported if the number of points in the mesh exceeds this number. maxcoord The length of the first dimension of the " points" array. An error is reported if the number of axes in the supplied Region exceeds this number. npoint A pointer to an integer in which to return the number of points in the returned mesh. points The address of the first element in a 2-dimensional array of shape " [maxcoord][maxpoint]" , in which to return the coordinate values at the mesh positions. These are stored such that the value of coordinate number " coord" for point number " point" is found in element " points[coord][point]" . An error is reported if the Region is unbounded.

If the coordinate system represented by the Region has been changed since it was first created, the returned axis values refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape within the new coordinate system may be distorted, and so may not match that implied by the name of the Region subclass (CircleCircle, BoxBox, etc).

If the Region defines an area within a SkyFrameSkyFrame that traverses zero longitude, the returned positions will be normalised to avoid jumps of 2.PI radians in longitude (i.e. it will include longitude values less than zero or greater than 2.PI). astGetRegionPoints Returns the positions that define the given Region This function returns the axis values at the points that define the supplied RegionRegion. The particular meaning of these points will depend on the type of class supplied, as listed below under " Applicability:" . Synopsis void astGetRegionPoints( AstRegion $*$this, int maxpoint, int maxcoord, int $*$npoint, double $*$points ) this Pointer to the Region. maxpoint If zero, the number of points needed to define the Region is returned in " $*$npoint" , but no axis values are returned and all other parameters are ignored. If not zero, the supplied value should be the length of the second dimension of the " points" array. An error is reported if the number of points needed to define the Region exceeds this number. maxcoord The length of the first dimension of the " points" array. An error is reported if the number of axes in the supplied Region exceeds this number. npoint A pointer to an integer in which to return the number of points defining the Region. points The address of the first element in a 2-dimensional array of shape " [maxcoord][maxpoint]" , in which to return the coordinate values at the positions that define the Region. These are stored such that the value of coordinate number " coord" for point number " point" is found in element " points[coord][point]" . Region All Regions have this attribute. BoxBox The first returned position is the Box centre, and the second is a Box corner. CircleCircle The first returned position is the Circle centre, and the second is a point on the circumference. CmpRegionCmpRegion Returns a value of zero for " $*$npoint" and leaves the supplied array contents unchanged. To find the points defining a CmpRegion, use this method on the component Regions, which can be accessed by invoking astDecomposeastDecompose on the CmpRegion. EllipseEllipse The first returned position is the Ellipse centre. The second is the end of one of the axes of the ellipse. The third is some other point on the circumference of the ellipse, distinct from the second point. IntervalInterval The first point corresponds to the lower bounds position, and the second point corresponds to the upper bounds position. These are reversed to indicate an extcluded interval rather than an included interval. See the Interval constructor for more information. NullRegionNullRegion Returns a value of zero for " $*$npoint" and leaves the supplied array contents unchanged. PointListPointList The positions returned are those that were supplied when the PointList was constructed. PolygonPolygon The positions returned are the vertex positions that were supplied when the Polygon was constructed. PrismPrism Returns a value of zero for " $*$npoint" and leaves the supplied array contents unchanged. To find the points defining a Prism, use this method on the component Regions, which can be accessed by invoking astDecompose on the CmpRegion. If the coordinate system represented by the Region has been changed since it was first created, the returned axis values refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape within the new coordinate system may be distorted, and so may not match that implied by the name of the Region subclass (Circle, Box, etc). astGetStcCoord Return information about an AstroCoords element stored in an Stc When any sub-class of StcStc is created, the constructor function allows one or more AstroCoords elements to be stored within the Stc. This function allows any one of these AstroCoords elements to be retrieved. The format of the returned information is the same as that used to pass the original information to the Stc constructor. That is, the information is returned in a KeyMapKeyMap structure containing elements with one or more of the keys given by symbolic constants AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE and AST__STCPIXSZ.

If the coordinate system represented by the Stc has been changed since it was created (for instance, by changing its SystemSystem attribute), then the sizes and positions in the returned KeyMap will reflect the change in coordinate system. Synopsis AstKeyMap $*$astGetStcCoord( AstStc $*$this, int icoord ) this Pointer to the Stc. icoord The index of the AstroCoords element required. The first has index one. The number of AstroCoords elements in the Stc can be found using function astGetStcNcoord. astGetStcCoord() A pointer to a new KeyMap containing the required information. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetStcNCoord Return the number of AstroCoords elements stored in an Stc This function returns the number of AstroCoords elements stored in an StcStc. Synopsis int astGetStcNCoord( AstStc $*$this ) this Pointer to the Stc. astGetStcNCoord() The number of AstroCoords elements stored in the Stc. Zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetStcRegion Obtain a copy of the encapsulated Region within a Stc This function returns a pointer to a deep copy of the RegionRegion supplied when the StcStc was created. Synopsis AstRegion $*$astGetStcRegion( AstStc $*$this ) this Pointer to the Stc. astGetStcRegion() A pointer to a deep copy of the Region encapsulated within the supplied Stc. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetTableHeader Get the FITS headers from a FitsTable This function returns a pointer to a FitsChanFitsChan holding copies of the FITS headers associated with a FitsTableFitsTable. Synopsis AstFitsChan $*$astGetTableHeader( AstFitsTable $*$this ) this Pointer to the FitsTable. astGetTableHeader() A pointer to a deep copy of the FitsChan stored within the FitsTable. The returned pointer should be annulled using astAnnulastAnnul when it is no longer needed.

Changing the contents of the returned FitsChan will have no effect on the FitsTable. To modify the FitsTable, the modified FitsChan must be stored in the FitsTable using astPutTableHeaderastPutTableHeader. astGetTables Retrieve any FitsTables currently in a FitsChan If the supplied FitsChanFitsChan currently contains any tables, then this function returns a pointer to a KeyMapKeyMap. Each entry in the KeyMap is a pointer to a FitsTableFitsTable holding the data for a FITS binary table. The key used to access each entry is the FITS extension name in which the table should be stored.

Tables can be present in a FitsChan as a result either of using the astPutTableastPutTable (or astPutTablesastPutTables) method to store existing tables in the FitsChan, or of using the astWriteastWrite method to write a FrameSetFrameSet to the FitsChan. For the later case, if the FitsChan " TabOKTabOK" attribute is positive and the FrameSet requires a look-up table to describe one or more axes, then the " -TAB" algorithm code described in FITS-WCS paper III is used and the table values are stored in the FitsChan in the form of a FitsTable object (see the documentation for the " TabOK" attribute). Synopsis AstKeyMap $*$astGetTables( AstFitsChan $*$this ) this Pointer to the FitsChan. astGetTables() A pointer to a deep copy of the KeyMap holding the tables currently in the FitsChan, or NULL if the FitsChan does not contain any tables. The returned pointer should be annulled using astAnnulastAnnul when no longer needed. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGetUnc Obtain uncertainty information from a Region This function returns a RegionRegion which represents the uncertainty associated with positions within the supplied Region. See astSetUncastSetUnc for more information about Region uncertainties and their use. Synopsis AstRegion $*$astGetUnc( AstRegion $*$this, int def ) this Pointer to the Region. def Controls what is returned if no uncertainty information has been associated explicitly with the supplied Region. If a non-zero value is supplied, then the default uncertainty Region used internally within AST is returned (see " Applicability" below). If zero is supplied, then NULL will be returned (without error). CmpRegionCmpRegion The default uncertainty for a CmpRegion is taken from one of the two component Regions. If the first component Region has a non-default uncertainty, then it is used as the default uncertainty for the parent CmpRegion. Otherwise, if the second component Region has a non-default uncertainty, then it is used as the default uncertainty for the parent CmpRegion. If neither of the component Regions has non-default uncertainty, then the default uncertainty for the CmpRegion is 1.0E-6 of the bounding box of the CmpRegion. PrismPrism The default uncertainty for a Prism is formed by combining the uncertainties from the two component Regions. If a component Region does not have a non-default uncertainty, then its default uncertainty will be used to form the default uncertainty of the parent Prism. Region For other classes of Region, the default uncertainty is 1.0E-6 of the bounding box of the Region. If the bounding box has zero width on any axis, then the uncertainty will be 1.0E-6 of the axis value. astGetUnc() A pointer to a Region describing the uncertainty in the supplied Region. If uncertainty information is associated with a Region, and the coordinate system described by the Region is subsequently changed (e.g. by changing the value of its SystemSystem attribute, or using the astMapRegionastMapRegion function), then the uncertainty information returned by this function will be modified so that it refers to the coordinate system currently described by the supplied Region.

A null ObjectObject pointer (NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astGrfPop Restore previously saved graphics functions used by a Plot This function restores a snapshot of the graphics functions stored previously by calling astGrfPushastGrfPush. The restored graphics functions become the current graphics functions used by the PlotPlot.

The astGrfPush and astGrfPop functions are intended for situations where it is necessary to make temporary changes to the graphics functions used by the Plot. The current functions should first be saved by calling astGrfPush. New functions should then be registered using astGrfSetastGrfSet. The required graphics should then be produced. Finally, astGrfPop should be called to restore the original graphics functions. Synopsis void astGrfPop( AstPlot $*$this ) this Pointer to the Plot. This function returns without action if there are no snapshots to restore. No error is reported in this case. astGrfPush Save the current graphics functions used by a Plot This function takes a snapshot of the graphics functions which are currently registered with the supplied PlotPlot, and saves the snapshot on a first-in-last-out stack within the Plot. The snapshot can be restored later using function astGrfPopastGrfPop.

The astGrfPush and astGrfPop functions are intended for situations where it is necessary to make temporary changes to the graphics functions used by the Plot. The current functions should first be saved by calling astGrfPush. New functions should then be registered using astGrfSetastGrfSet. The required graphics should then be produced. Finally, astGrfPop should be called to restore the original graphics functions. Synopsis void astGrfPush( AstPlot $*$this ) this Pointer to the Plot. astGrfSet Register a graphics function for use by a Plot This function can be used to select the underlying graphics functions to be used when the supplied PlotPlot produces graphical output. If this function is not called prior to producing graphical output, then the underlying graphics functions selected at link-time (using the ast_linkast_link command) will be used. To use alternative graphics functions, call this function before the graphical output is created, specifying the graphics functions to be used. This will register the function for future use, but the function will not actually be used until the GrfGrf attribute is given a non-zero value. Synopsis void astGrfSet( AstPlot $*$this, const char $*$name, AstGrfFun fun ) this Pointer to the Plot. name A name indicating the graphics function to be replaced. Various graphics functions are used by the Plot class, and any combination of them may be supplied by calling this function once for each function to be replaced. If any of the graphics functions are not replaced in this way, the corresponding functions in the graphics interface selected at link-time (using the ast_link command) are used. The allowed names are:

Attr - Enquire or set a graphics attribute value

BBuf - Start a new graphics buffering context

Cap - Inquire a capability

EBuf - End the current graphics buffering context

Flush - Flush all pending graphics to the output device

Line - Draw a polyline (i.e. a set of connected lines)

Mark - Draw a set of markers

Qch - Return the character height in world coordinates

Scales - Get the axis scales

Text - Draw a character string

TxExt - Get the extent of a character string

The string is case insensitive. For details of the interface required for each, see the sections below. fun A Pointer to the function to be used to provide the functionality indicated by parameter name. The interface for each function is described below, but the function pointer should be cast to a type of AstGrfFun when calling astGrfSet.

Once a function has been provided, a null pointer can be supplied in a subsequent call to astGrfSet to reset the function to the corresponding function in the graphics interface selected at link-time. Function Interfaces All the functions listed below (except for " Cap" ) should return an integer value of 0 if an error occurs, and 1 otherwise. All x and y values refer to " graphics cordinates" as defined by the graphbox parameter of the astPlotastPlot call which created the Plot.

The first parameter (" grfcon" ) for each function is an AST KeyMapKeyMap pointer that can be used by the called function to establish the context in which it is being called. The contents of the KeyMap are determined by the calling application, which should obtain a pointer to the KeyMap using the astGetGrfContextastGetGrfContext function, and then store any necessary information in the KeyMap using the methods of the KeyMap class. Note, the functions listed below should never annul or delete the supplied KeyMap pointer. Attr The " Attr" function returns the current value of a specified graphics attribute, and optionally establishes a new value. The supplied value is converted to an integer value if necessary before use. It requires the following interface:

int Attr( AstObject $*$grfcon, int attr, double value, double $*$old_value, int prim )

grfcon - A KeyMap containing information passed from the calling application.

attr - An integer value identifying the required attribute. The following symbolic values are defined in grf.h: GRF__STYLE (Line style), GRF__WIDTH (Line width), GRF__SIZE (Character and marker size scale factor), GRF__FONT (Character font), GRF__COLOUR (Colour index).

value - A new value to store for the attribute. If this is AST__BAD no value is stored.

old_value - A pointer to a double in which to return the attribute value. If this is NULL, no value is returned.

prim - The sort of graphics primitive to be drawn with the new attribute. Identified by the following values defined in grf.h: GRF__LINE, GRF__MARK, GRF__TEXT. BBuf The " BBuf" function should start a new graphics buffering context. A matching call to the function " EBuf" should be used to end the context. The nature of the buffering is determined by the underlying graphics system.

int BBuf( AstObject $*$grfcon )

grfcon - A KeyMap containing information passed from the calling application. Cap The " Cap" function is called to determine if the grf module has a given capability, as indicated by the " cap" argument:

int Cap( AstObject $*$grfcon, int cap, int value )

grfcon - A KeyMap containing information passed from the calling application.

cap - The capability being inquired about. This will be one of the following constants defined in grf.h:

GRF__SCALES: This function should return a non-zero value if the " Scales" function is implemented, and zero otherwise. The supplied " value" argument should be ignored.

GRF__MJUST: This function should return a non-zero value if the " Text" and " TxExt" functions recognise " M" as a character in the justification string. If the first character of a justification string is " M" , then the text should be justified with the given reference point at the bottom of the bounding box. This is different to " B" justification, which requests that the reference point be put on the baseline of the text, since some characters hang down below the baseline. If the " Text" or " TxExt" function cannot differentiate between " M" and " B" , then this function should return zero, in which case " M" justification will never be requested by Plot. The supplied " value" argument should be ignored.

GRF__ESC: This function should return a non-zero value if the " Text" and " TxExt" functions can recognise and interpret graphics escape sequences within the supplied string (see attribute EscapeEscape). Zero should be returned if escape sequences cannot be interpreted (in which case the Plot class will interpret them itself if needed). The supplied " value" argument should be ignored only if escape sequences cannot be interpreted by " Text" and " TxExt" . Otherwise, " value" indicates whether " Text" and " TxExt" should interpret escape sequences in subsequent calls. If " value" is non-zero then escape sequences should be interpreted by " Text" and " TxExt" . Otherwise, they should be drawn as literal text.

value - The use of this parameter depends on the value of " cap" as described above.

Returned Function Value: The value returned by the function depends on the value of " cap" as described above. Zero should be returned if the supplied capability is not recognised. EBuf The " EBuf" function should end the current graphics buffering context. See the description of " BBuf" above for further details. It requires the following interface:

int EBuf( AstObject $*$grfcon )

grfcon - A KeyMap containing information passed from the calling application. Flush The " Flush" function ensures that the display device is up-to-date, by flushing any pending graphics to the output device. It requires the following interface:

int Flush( AstObject $*$grfcon )

grfcon - A KeyMap containing information passed from the calling application. Line The " Line" function displays lines joining the given positions and requires the following interface:

int Line( AstObject $*$grfcon, int n, const float $*$x, const float $*$y )

grfcon - A KeyMap containing information passed from the calling application.

n - The number of positions to be joined together.

x - A pointer to an array holding the " n" x values.

y - A pointer to an array holding the " n" y values. Mark The " Mark" function displays markers at the given positions. It requires the following interface:

int Mark( AstObject $*$grfcon, int n, const float $*$x, const float $*$y, int type )

grfcon - A KeyMap containing information passed from the calling application.

n - The number of positions to be marked.

x - A pointer to an array holding the " n" x values.

y - A pointer to an array holding the " n" y values.

type - An integer which can be used to indicate the type of marker symbol required. Qch The " Qch" function returns the heights of characters drawn vertically and horizontally in graphics coordinates. It requires the following interface:

int Qch( AstObject $*$grfcon, float $*$chv, float $*$chh )

grfcon - A KeyMap containing information passed from the calling application.

chv - A pointer to the float which is to receive the height of characters drawn with a vertical baseline. This will be an increment in the X axis.

chh - A pointer to the float which is to receive the height of characters drawn with a horizontal baseline. This will be an increment in the Y axis. Scales The " Scales" function returns two values (one for each axis) which scale increments on the corresponding axis into a " normal" coordinate system in which: 1) the axes have equal scale in terms of (for instance) millimetres per unit distance, 2) X values increase from left to right, and 3) Y values increase from bottom to top. It requires the following interface:

int Scales( AstObject $*$grfcon, float $*$alpha, float $*$beta )

grfcon - A KeyMap containing information passed from the calling application.

alpha - A pointer to the float which is to receive the scale for the X axis (i.e. Xnorm = alpha$*$Xworld).

beta - A pointer to the float which is to receive the scale for the Y axis (i.e. Ynorm = beta$*$Yworld). Text The " Text" function displays a character string at a given position using a specified justification and up-vector. It requires the following interface:

int Text( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just, float upx, float upy )

grfcon - A KeyMap containing information passed from the calling application.

text - Pointer to a null-terminated character string to be displayed.

x - The reference x coordinate.

y - The reference y coordinate.

just - A character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be ' T' for " top" , ' C' for " centre" , or ' B' for " bottom" , and specifies the vertical location of the reference position. Note, " bottom" corresponds to the base-line of normal text. Some characters (eg " y" , " g" , " p" , etc) descend below the base-line. The second character may be ' L' for " left" , ' C' for " centre" , or ' R' for " right" , and specifies the horizontal location of the reference position. If the string has less than 2 characters then ' C' is used for the missing characters.

upx - The x component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.

upy - The y component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen. TxExt The " TxExt" function returns the corners of a box which would enclose the supplied character string if it were displayed using the Text function described above. The returned box includes any leading or trailing spaces. It requires the following interface:

int TxExt( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just, float upx, float upy, float $*$xb, float $*$yb )

grfcon - A KeyMap containing information passed from the calling application.

text - Pointer to a null-terminated character string to be displayed.

x - The reference x coordinate.

y - The reference y coordinate.

just - A character string which specifies the location within the text string which is to be placed at the reference position given by x and y. See " Text" above.

upx - The x component of the up-vector for the text. See " Text" above.

upy - The y component of the up-vector for the text. See " Text" above.

xb - An array of 4 elements in which to return the x coordinate of each corner of the bounding box.

yb - An array of 4 elements in which to return the y coordinate of each corner of the bounding box. astGrid Draw a set of labelled coordinate axes This function draws a complete annotated set of coordinate axes for a PlotPlot with (optionally) a coordinate grid superimposed. Details of the axes and grid can be controlled by setting values for the various attributes defined by the Plot class (q.v.). Synopsis void astGrid( AstPlot $*$this ) this Pointer to the Plot. If the supplied Plot is a Plot3DPlot3D, the axes will be annotated using three 2-dimensional Plots, one for each 2D plane in the 3D current coordinate system. The plots will be " pasted" onto 3 faces of the cuboid graphics volume specified when the Plot3D was constructed. The faces to be used can be controlled by the " RootCornerRootCorner" attribute.

An error results if either the current FrameFrame or the base Frame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.

An error also results if the transformation between the base and current Frames of the Plot is not defined in either direction (i.e. the Plot' s TranForwardTranForward or TranInverseTranInverse attribute is zero). astGridLine Draw a grid line (or axis) for a Plot This function draws a curve in the physical coordinate system of a PlotPlot by varying only one of the coordinates along the length of the curve. It is intended for drawing coordinate axes, coordinate grids, and tick marks on axes (but note that these are also available via the more comprehensive astGridastGrid function).

The curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the MappingMapping involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using astClipastClip. Synopsis void astGridLine( AstPlot $*$this, int axis, const double start[], double length ) this Pointer to the Plot. axis The index of the Plot axis whose physical coordinate value is to be varied along the length of the curve (all other coordinates will remain fixed). This value should lie in the range from 1 to the number of Plot axes (NaxesNaxes attribute). start An array, with one element for each axis of the Plot, giving the physical coordinates of the start of the curve. length The length of curve to be drawn, given as an increment along the selected physical axis. This may be positive or negative. No curve is drawn if the " start" array contains any coordinates with the value AST__BAD, nor if " length" has this value.

An error results if the base FrameFrame of the Plot is not 2-dimensional.

An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot' s TranInverseTranInverse attribute is zero). astGrismMap Create a GrismMap This function creates a new GrismMapGrismMap and optionally initialises its attributes.

A GrismMap is a specialised form of MappingMapping which transforms 1-dimensional coordinates using the spectral dispersion equation described in FITS-WCS paper III " Representation of spectral coordinates in FITS" . This describes the dispersion produced by gratings, prisms and grisms.

When initially created, the forward transformation of a GrismMap transforms input " grism parameter" values into output wavelength values. The " grism parameter" is a dimensionless value which is linearly related to position on the detector. It is defined in FITS-WCS paper III as " the offset on the detector from the point of intersection of the camera axis, measured in units of the effective local length" . The units in which wavelength values are expected or returned is determined by the values supplied for the GrismWaveRGrismWaveR, GrismNRPGrismNRP and GrismGGrismG attribute: whatever units are used for these attributes will also be used for the wavelength values. Synopsis AstGrismMap $*$astGrismMap( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new GrismMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astGrismMap() A pointer to the new GrismMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astHasAttribute Test if an Object has a named attribute This function returns a boolean result (0 or 1) to indicate whether the supplied ObjectObject has an attribute with the supplied name. Synopsis int astHasAttribute( AstObject $*$this, const char $*$attrib ) this Pointer to the first Object. attrib Pointer to a string holding the name of the attribute to be tested. Object This function applies to all Objects. astHasAttribute() One if the Object has the named attribute, otherwise zero. A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astHasColumn Returns a flag indicating if a column is present in a Table This function returns a flag indicating if a named column exists in a TableTable, for instance, by having been added to to the Table using astAddColumnastAddColumn. Synopsis int astHasColumn( AstTable $*$this, const char $*$column ) this Pointer to the Table. column The character string holding the upper case name of the column. Trailing spaces are ignored. A value of zero is returned for if an error occurs. astHasParameter Returns a flag indicating if a named global parameter is present in a Table This function returns a flag indicating if a named parameter exists in a TableTable, for instance, by having been added to to the Table using astAddParameterastAddParameter. Synopsis int astHasParameter( AstTable $*$this, const char $*$parameter ) this Pointer to the Table. parameter The character string holding the upper case name of the parameter. Trailing spaces are ignored. A value of zero is returned for if an error occurs. astImport Import an Object pointer to the current context This function imports an ObjectObject pointer that was created in a higher or lower level context, into the current AST context. This means that the pointer will be annulled when the current context is ended (with astEndastEnd). Synopsis void astImport( AstObject $*$this ) this Object pointer to be imported. Object This function applies to all Objects. astIntersect Find the point of intersection between two geodesic curves This function finds the coordinate values at the point of intersection between two geodesic curves. Each curve is specified by two points on the curve. It can only be used with 2-dimensional Frames.

For example, in a basic FrameFrame, it will find the point of intersection between two straight lines. But for a SkyFrameSkyFrame it will find an intersection of two great circles. Synopsis void astIntersect( AstFrame $*$this, const double a1[2], const double a2[2], const double b1[2], const double b2[2], double cross[2] ) this Pointer to the Frame. a1 An array of double, with one element for each Frame axis (NaxesNaxes attribute). This should contain the coordinates of the first point on the first geodesic curve. a2 An array of double, with one element for each Frame axis (Naxes attribute). This should contain the coordinates of a second point on the first geodesic curve. It should not be co-incident with the first point. b1 An array of double, with one element for each Frame axis (Naxes attribute). This should contain the coordinates of the first point on the second geodesic curve. b2 An array of double, with one element for each Frame axis (Naxes attribute). This should contain the coordinates of a second point on the second geodesic curve. It should not be co-incident with the first point. cross An array of double, with one element for each Frame axis in which the coordinates of the required intersection will be returned. For SkyFrames each curve will be a great circle, and in general each pair of curves will intersect at two diametrically opposite points on the sky. The returned position is the one which is closest to point " a1" .

This function will return " bad" coordinate values (AST__BAD) if any of the input coordinates has this value, or if the two points defining either geodesic are co-incident, or if the two curves do not intersect.

The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistanceastDistance function.

An error will be reported if the Frame is not 2-dimensional. astInterval Create a Interval This function creates a new IntervalInterval and optionally initialises its attributes.

A Interval is a RegionRegion which represents upper and/or lower limits on one or more axes of a FrameFrame. For a point to be within the region represented by the Interval, the point must satisfy all the restrictions placed on all the axes. The point is outside the region if it fails to satisfy any one of the restrictions. Each axis may have either an upper limit, a lower limit, both or neither. If both limits are supplied but are in reverse order (so that the lower limit is greater than the upper limit), then the interval is an excluded interval, rather than an included interval.

At least one axis limit must be supplied.

Note, The Interval class makes no allowances for cyclic nature of some coordinate systems (such as SkyFrameSkyFrame coordinates). A BoxBox should usually be used in these cases since this requires the user to think about suitable upper and lower limits, Synopsis AstInterval $*$astInterval( AstFrame $*$frame, const double lbnd[], const double ubnd[], AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. lbnd An array of double, with one element for each Frame axis (NaxesNaxes attribute) containing the lower limits on each axis. Set a value to AST__BAD to indicate that the axis has no lower limit. ubnd An array of double, with one element for each Frame axis (Naxes attribute) containing the upper limits on each axis. Set a value to AST__BAD to indicate that the axis has no upper limit. unc An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Interval being created. The uncertainty in any point on the boundary of the Interval is found by shifting the supplied " uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, CircleCircle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Interval. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Interval being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplifyastSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Interval. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astInterval() A pointer to the new Interval. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astIntraMap Create an IntraMap This function creates a new IntraMapIntraMap and optionally initialises its attributes.

An IntraMap is a specialised form of MappingMapping which encapsulates a privately-defined coordinate transformation function (e.g. written in C) so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation.

However, an IntraMap is intended for use within a single program or a private suite of software, where all programs have access to the same coordinate transformation functions (i.e. can be linked against them). IntraMaps should not normally be stored in datasets which may be exported for processing by other software, since that software will not have the necessary transformation functions available, resulting in an error.

You must register any coordinate transformation functions to be used using astIntraRegastIntraReg before creating an IntraMap. Synopsis AstIntraMap $*$astIntraMap( const char $*$name, int nin, int nout, const char $*$options, ... ) name Pointer to a null-terminated string containing the name of the transformation function to use (which should previously have been registered using astIntraReg). This name is case sensitive. All white space will be removed before use. nin The number of input coordinates. This must be compatible with the number of input coordinates accepted by the transformation function (as specified when this function was registered using astIntraReg). nout The number of output coordinates. This must be compatible with the number of output coordinates produced by the transformation function (as specified when this function was registered using astIntraReg). options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new IntraMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astIntraMap() A pointer to the new IntraMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astIntraReg Register a transformation function for use by an IntraMap This function registers a privately-defined coordinate transformation function written in C so that it may be used to create an IntraMapIntraMap. An IntraMap is a specialised form of MappingMapping which encapsulates the C function so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation.

Registration of relevant transformation functions is required before using the astIntraMapastIntraMap constructor function to create an IntraMap or reading an external representation of an IntraMap from a ChannelChannel. Synopsis astIntraReg( const char $*$name, int nin, int nout, void ($*$ tran)( AstMapping $*$, int, int, const double $*$[], int, int, double $*$[] ), unsigned int flags, const char $*$purpose, const char $*$author, const char $*$contact ) name Pointer to a null-terminated string containing a unique name to be associated with the transformation function in order to identify it. This name is case sensitive. All white space will be removed before use. nin The number of input coordinates accepted by the transformation function (i.e. the number of dimensions of the space in which the input points reside). A value of AST__ANY may be given if the function is able to accommodate a variable number of input coordinates. nout The number of output coordinates produced by the transformation function (i.e. the number of dimensions of the space in which the output points reside). A value of AST__ANY may be given if the function is able to produce a variable number of output coordinates. tran Pointer to the transformation function to be registered. This function should perform whatever coordinate transformations are required and should have an interface like astTranPastTranP (q.v.). flags This value may be used to supply a set of flags which describe the transformation function and which may affect the behaviour of any IntraMap which uses it. Often, a value of zero will be given here, but you may also supply the bitwise OR of a set of flags as described in the " Transformation Flags" section (below). purpose Pointer to a null-terminated string containing a short (one line) textual comment to describe the purpose of the transformation function. author Pointer to a null-terminated string containing the name of the author of the transformation function. contact Pointer to a null-terminated string containing contact details for the author of the transformation function (e.g. an e-mail or WWW address). If any IntraMap which uses this transformation function is exported as part of a dataset to an external user who does not have access to the function, then these contact details should allow them to obtain the necessary code. Beware that an external representation of an IntraMap (created by writing it to a Channel) will not include the coordinate transformation function which it uses, so will only refer to the function by its name (as assigned using astIntraReg). Consequently, the external representation cannot be utilised by another program unless that program has also registered the same transformation function with the same name using an identical invocation of astIntraReg. If no such registration has been performed, then attempting to read the external representation will result in an error.

You may use astIntraReg to register a transformation function with the same name more than once, but only if the arguments supplied are identical on each occasion (i.e there is no way of changing things once a function has been successfully registered under a given name, and attempting to do so will result in an error). This feature simply allows registration to be performed independently, but consistently, at several places within your program, without having to check whether it has already been done.

If an error occurs in the transformation function, this may be indicated by setting the AST error status to an error value (using astSetStatusastSetStatus) before it returns. This will immediately terminate the current AST operation. The error value AST__ITFER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). Transformation Flags The following flags are defined in the “ast.h' ' header file and allow you to provide further information about the nature of the transformation function. Having selected the set of flags which apply, you should supply the bitwise OR of their values as the “flags' ' argument to astIntraReg.

AST__NOFWD: If this flag is set, it indicates that the transformation function does not implement a forward coordinate transformation. In this case, any IntraMap which uses it will have a TranForwardTranForward attribute value of zero and the transformation function itself will not be invoked with its “forward' ' argument set to a non-zero value. By default, it is assumed that a forward transformation is provided.

AST__NOINV: If this flag is set, it indicates that the transformation function does not implement an inverse coordinate transformation. In this case, any IntraMap which uses it will have a TranInverseTranInverse attribute value of zero and the transformation function itself will not be invoked with its “forward' ' argument set to zero. By default, it is assumed that an inverse transformation is provided.

AST__SIMPFI: You may set this flag if applying the transformation function' s forward coordinate transformation, followed immediately by the matching inverse transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMapUnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplifyastSimplify). It is not necessary that both transformations have actually been implemented.

AST__SIMPIF: You may set this flag if applying the transformation function' s inverse coordinate transformation, followed immediately by the matching forward transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify). It is not necessary that both transformations have actually been implemented. astInvert Invert a Mapping This function inverts a MappingMapping by reversing the boolean sense of its InvertInvert attribute. If this attribute is zero (the default), the Mapping will transform coordinates in the way specified when it was created. If it is non-zero, the input and output coordinates will be inter-changed so that the direction of the Mapping is reversed. This will cause it to display the inverse of its original behaviour. Synopsis void astInvert( AstMapping $*$this ) this Pointer to the Mapping. astIsA$<$Class$>$ Test membership of a class by an Object This is a family of functions which test whether an ObjectObject is a member of the class called $<$ClassClass$>$, or of any class derived from it. Synopsis int astIsA$<$Class$>$( const Ast$<$Class$>$ $*$this ) this Pointer to the Object. Object These functions apply to all Objects. astIsA$<$Class$>$() One if the Object belongs to the class called $<$Class$>$ (or to a class derived from it), otherwise zero. member = astIsAFrame( obj ); Tests whether Object " obj" is a member of the FrameFrame class, or of any class derived from a Frame. Every AST class provides a function (astIsA$<$Class$>$) of this form, where $<$Class$>$ should be replaced by the class name.

This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances.

A value of zero will be returned if this function should fail for any reason. In particular, it will fail if the pointer supplied does not identify an Object of any sort. astKeyMap Create a KeyMap This function creates a new empty KeyMapKeyMap and optionally initialises its attributes. Entries can then be added to the KeyMap using the astMapPut0$<$X$>$astMapPut0$<$X$>$ and astMapPut1$<$X$>$astMapPut1$<$X$>$ functions.

The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the KeyCaseKeyCase attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), void pointer, character string or AST ObjectObject pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a MappingMapping in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap. Synopsis AstKeyMap $*$astKeyMap( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new KeyMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astKeyMap() A pointer to the new KeyMap. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astLinearApprox Obtain a linear approximation to a Mapping, if appropriate This function tests the forward coordinate transformation implemented by a MappingMapping over a given range of input coordinates. If the transformation is found to be linear to a specified level of accuracy, then an array of fit coefficients is returned. These may be used to implement a linear approximation to the Mapping' s forward transformation within the specified range of output coordinates. If the transformation is not sufficiently linear, no coefficients are returned. Synopsis int astLinearApprox( AstMapping $*$this, const double $*$lbnd, const double $*$ubnd, double tol, double $*$fit ) this Pointer to the Mapping. lbnd Pointer to an array of doubles containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping' s NinNin attribute. This box should specify the region over which linearity is required. ubnd Pointer to an array of doubles containing the upper bounds of the box specifying the region over which linearity is required. tol The maximum permitted deviation from linearity, expressed as a positive Cartesian displacement in the output coordinate space of the Mapping. If a linear fit to the forward transformation of the Mapping deviates from the true transformation by more than this amount at any point which is tested, then no fit coefficients will be returned. fit Pointer to an array of doubles in which to return the co-efficients of the linear approximation to the specified transformation. This array should have at least " ( Nin $+$ 1 ) $*$ NoutNout" , elements. The first Nout elements hold the constant offsets for the transformation outputs. The remaining elements hold the gradients. So if the Mapping has 2 inputs and 3 outputs the linear approximation to the forward transformation is:

X_out = fit[0] $+$ fit[3]$*$X_in $+$ fit[4]$*$Y_in

Y_out = fit[1] $+$ fit[5]$*$X_in $+$ fit[6]$*$Y_in

Z_out = fit[2] $+$ fit[7]$*$X_in $+$ fit[8]$*$Y_in astLinearApprox() If the forward transformation is sufficiently linear, a non-zero value is returned. Otherwise zero is returned and the fit co-efficients are set to AST__BAD. This function fits the Mapping' s forward transformation. To fit the inverse transformation, the Mapping should be inverted using astInvertastInvert before invoking this function.

If a Mapping output is found to have a bad value (AST__BAD) at one or more of the test points used in the linearity test, then all the values in the returned fit that correspond to that output are set to AST__BAD. However, this does not affect the linearity tests on the other Mapping outputs - if they are all found to be linear then usable coefficients will be returned for them in the fit, and the function will return a non-zero value. Consequently, it may be necessary to check that the values in the returned fit are not AST__BAD before using them. If all Mapping outputs generate bad values, then zero is returned as the function value.

A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason.

If all tested positions within the supplied box generate bad output positions, then the returned function value will be zero. However, the returned coefficients will represent a unit transformation, except that the constant term for each output will be set to AST__BAD. astLock Lock an Object for exclusive use by the calling thread The thread-safe public interface to AST is designed so that an error is reported if any thread attempts to use an ObjectObject that it has not previously locked for its own exclusive use using this function. When an Object is created, it is initially locked by the thread that creates it, so newly created objects do not need to be explicitly locked. However, if an Object pointer is passed to another thread, the original thread must first unlock it (using astUnlockastUnlock) and the new thread must then lock it (using astLock) before the new thread can use the Object.

The " wait" parameter determines what happens if the supplied Object is curently locked by another thread when this function is invoked. Synopsis void astLock( AstObject $*$this, int wait ) this Pointer to the Object to be locked. wait If the Object is curently locked by another thread then this function will either report an error or block. If a non-zero value is supplied for " wait" , the calling thread waits until the object is available for it to use. Otherwise, an error is reported and the function returns immediately without locking the Object. Object This function applies to all Objects. The astAnnulastAnnul function is exceptional in that it can be used on pointers for Objects that are not currently locked by the calling thread. All other AST functions will report an error.

The Locked object will belong to the current AST context.

This function returns without action if the Object is already locked by the calling thread.

If simultaneous use of the same object is required by two or more threads, astCopyastCopy should be used to to produce a deep copy of the Object for each thread. Each copy should then be unlocked by the parent thread (i.e. the thread that created the copy), and then locked by the child thread (i.e. the thread that wants to use the copy).

This function is only available in the C interface.

This function returns without action if the AST library has been built without POSIX thread support (i.e. the " -with-pthreads" option was not specified when running the " configure" script). astLutMap Create a LutMap This function creates a new LutMapLutMap and optionally initialises its attributes.

A LutMap is a specialised form of MappingMapping which transforms 1-dimensional coordinates by using linear interpolation in a lookup table. Each input coordinate value is first scaled to give the index of an entry in the table by subtracting a starting value (the input coordinate corresponding to the first table entry) and dividing by an increment (the difference in input coordinate value between adjacent table entries).

The resulting index will usually contain a fractional part, so the output coordinate value is then generated by interpolating linearly between the appropriate entries in the table. If the index lies outside the range of the table, linear extrapolation is used based on the two nearest entries (i.e. the two entries at the start or end of the table, as appropriate).

If the lookup table entries increase or decrease monotonically, then the inverse transformation may also be performed. Synopsis AstLutMap $*$astLutMap( int nlut, const double lut[], double start, double inc, const char $*$options, ... ) nlut The number of entries in the lookup table. This value must be at least 2. lut An array containing the " nlut" lookup table entries. start The input coordinate value which corresponds to the centre of the first lookup table entry. inc The lookup table spacing (the increment in input coordinate value between successive lookup table entries). This value may be positive or negative, but must not be zero. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new LutMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astLutMap() A pointer to the new LutMap. If the entries in the lookup table either increase or decrease monotonically, then the new LutMap' s TranInverseTranInverse attribute will have a value of one, indicating that the inverse transformation can be performed. Otherwise, it will have a value of zero, so that any attempt to use the inverse transformation will result in an error.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astMapBox Find a bounding box for a Mapping This function allows you to find the " bounding box" which just encloses another box after it has been transformed by a MappingMapping (using either its forward or inverse transformation). A typical use might be to calculate the size of an image after being transformed by a Mapping.

The function works on one dimension at a time. When supplied with the lower and upper bounds of a rectangular region (box) of input coordinate space, it finds the lowest and highest values taken by a nominated output coordinate within that region. Optionally, it also returns the input coordinates where these bounding values are attained. It should be used repeatedly to obtain the extent of the bounding box in more than one dimension. Synopsis void astMapBox( AstMapping $*$this, const double lbnd_in[], const double ubnd_in[], int forward, int coord_out, double $*$lbnd_out, double $*$ubnd_out, double xl[], double xu[] ); this Pointer to the Mapping. lbnd_in Pointer to an array of double, with one element for each Mapping input coordinate. This should contain the lower bound of the input box in each input dimension. ubnd_in Pointer to an array of double, with one element for each Mapping input coordinate. This should contain the upper bound of the input box in each input dimension.

Note that it is permissible for the upper bound to be less than the corresponding lower bound, as the values will simply be swapped before use. forward If this value is non-zero, then the Mapping' s forward transformation will be used to transform the input box. Otherwise, its inverse transformation will be used.

(If the inverse transformation is selected, then references to " input" and " output" coordinates in this description should be transposed. For example, the size of the " lbnd_in" and " ubnd_in" arrays should match the number of output coordinates, as given by the Mapping' s NoutNout attribute. Similarly, the " coord_out" parameter, below, should nominate one of the Mapping' s input coordinates.) coord_out The index of the output coordinate for which the lower and upper bounds are required. This value should be at least one, and no larger than the number of Mapping output coordinates. lbnd_out Pointer to a double in which to return the lowest value taken by the nominated output coordinate within the specified region of input coordinate space. ubnd_out Pointer to a double in which to return the highest value taken by the nominated output coordinate within the specified region of input coordinate space. xl An optional pointer to an array of double, with one element for each Mapping input coordinate. If given, this array will be filled with the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the lower bound value returned in " $*$lbnd_out" .

If these coordinates are not required, a NULL pointer may be supplied. xu An optional pointer to an array of double, with one element for each Mapping input coordinate. If given, this array will be filled with the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the upper bound value returned in " $*$ubnd_out" .

If these coordinates are not required, a NULL pointer may be supplied. Any input points which are transformed by the Mapping to give output coordinates containing the value AST__BAD are regarded as invalid and are ignored. They will make no contribution to determining the output bounds, even although the nominated output coordinate might still have a valid value at such points.

An error will occur if the required output bounds cannot be found. Typically, this might happen if all the input points which the function considers turn out to be invalid (see above). The number of points considered before generating such an error is quite large, so this is unlikely to occur by accident unless valid points are restricted to a very small subset of the input coordinate space.

The values returned via " lbnd_out" , " ubnd_out" , " xl" and " xu" will be set to the value AST__BAD if this function should fail for any reason. Their initial values on entry will not be altered if the function is invoked with the AST error status set. astMapCopy Copy all entries from one KeyMap into another This function copies all entries from one KeyMapKeyMap into another. Synopsis void astMapCopy( AstKeyMap $*$this, AstKeyMap $*$that ) this Pointer to the destination KeyMap. that Pointer to the source KeyMap. Entries from the source KeyMap will replace any existing entries in the destination KeyMap that have the same key.

The one exception to the above rule is that if a source entry contains a scalar KeyMap entry, and the destination contains a scalar KeyMap entry with the same key, then the source KeyMap entry will be copied into the destination KeyMap entry using this function, rather than simply replacing the destination KeyMap entry.

If the destination entry has a non-zero value for its MapLockedMapLocked attribute, then an error will be reported if the source KeyMap contains any keys that do not already exist within the destination KeyMap. astMapCopyEntry Copy a single entry from one KeyMap into another This function copies a single entry from one KeyMapKeyMap into another. Synopsis void astMapCopyEntry( AstKeyMap $*$this, const char $*$key, AstKeyMap $*$that, int merge ) this Pointer to the destination KeyMap. key The character string identifying the value to be copied. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. that Pointer to the source KeyMap. merge Indicates what to do if the named entry holds a KeyMap and a KeyMap entry with the same key already exists in the destination KeyMap. If zero, the existing destination KeyMap will be deleted and replaced by a copy of the source KeyMap. If non-zero, all entries in the source KeyMap will be copied into the existing destination KeyMap using function astMapCopyastMapCopy. This fuction returns without action if the named entry does not exist in the source KeyMap.

Entries from the source KeyMap will replace any existing entries in the destination KeyMap that have the same key.

If the destination entry has a non-zero value for its MapLockedMapLocked attribute, then an error will be reported if the source KeyMap contains any keys that do not already exist within the destination KeyMap. astMapDefined Check if a KeyMap contains a defined value for a key This function checks to see if a KeyMapKeyMap contains a defined value for a given key. If the key is present in the KeyMap but has an undefined value it returns zero (unlike astMapHasKeyastMapHasKey which would return non-zero). Synopsis int astMapDefined( AstKeyMap $*$this, const char $*$key ); this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. astMapDefined() A non-zero value is returned if the requested key name is present in the KeyMap and has a defined value. astMapGet0$<$X$>$ Get a scalar value from a KeyMap This is a set of functions for retrieving a scalar value from a KeyMapKeyMap. You should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$ by an appropriate 1-character type code (see the " Data Type Codes" section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Synopsis int astMapGet0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type $*$value ); this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. value A pointer to a buffer in which to return the requested value. If the requested key is not found, or if it is found but has an undefined value (see astMapPutUastMapPutU), then the contents of the buffer on entry to this function will be unchanged on exit. For pointer types (" A" and " C" ), the buffer should be a suitable pointer, and the address of this pointer should be supplied as the " value" parameter. astMapGet0$<$X$>$() A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. No error is reported if the requested key cannot be found in the given KeyMap, but a zero value will be returned as the function value. The supplied buffer will be returned unchanged.

If the stored value is a vector value, then the first value in the vector will be returned.

A string pointer returned by astMapGet0C is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. The calling code should never attempt to free the returned pointer (for instance, using astFreeastFree).

If the returned value is an AST ObjectObject pointer, the Object' s reference count is incremented by this call. Any subsequent changes made to the Object using the returned pointer will be reflected in any any other active pointers for the Object. The returned pointer should be annulled using astAnnulastAnnul when it is no longer needed. Data Type Codes To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: F: float

D: double

I: int

K: int64_t

C: " const" pointer to null terminated character string

A: Pointer to AstObject

P: Generic " void $*$" pointer

S: short int

B: Unsigned byte (i.e. word)

For example, astMapGet0D would be used to get a " double" value, while astMapGet0I would be used to get an " int" , etc. astMapGet1$<$X$>$ Get a vector value from a KeyMap This is a set of functions for retrieving a vector value from a KeyMapKeyMap. You should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$ by an appropriate 1-character type code (see the " Data Type Codes" section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Note, the astMapGet1C function has an extra parameter " l" which specifies the maximum length of each string to be stored in the " value" buffer (see the " astMapGet1C" section below). Synopsis int astMapGet1$<$X$>$( AstKeyMap $*$this, const char $*$key, int mxval, int $*$nval, $<$X$>$type $*$value ) int astMapGet1C( AstKeyMap $*$this, const char $*$key, int l, int mxval, int $*$nval, const char $*$value ) this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. mxval The number of elements in the " value" array. nval The address of an integer in which to put the number of elements stored in the " value" array. Any unused elements of the array are left unchanged. Zero is returned if the required KeyMap entry has an undefined value. value A pointer to an array in which to return the requested values. If the requested key is not found, or if it is found but has an undefined value (see astMapPutUastMapPutU), then the contents of the buffer on entry to this function will be unchanged on exit. astMapGet1$<$X$>$() A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. No error is reported if the requested key cannot be found in the given KeyMap, but a zero value will be returned as the function value. The supplied array will be returned unchanged.

If the stored value is a scalar value, then the value will be returned in the first element of the supplied array, and " nval" will be returned set to 1. astMapGet1C The " value" buffer supplied to the astMapGet1C function should be a pointer to a character array with " mxval$*$l" elements, where " l" is the maximum length of a string to be returned. The value of " l" should be supplied as an extra parameter following " key" when invoking astMapGet1C, and should include space for a terminating null character. Data Type Codes To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: D: double

F: float

I: int

K: int64_t

C: " const" pointer to null terminated character string

A: Pointer to AstObject

P: Generic " void $*$" pointer

S: short int

B: Unsigned byte (i.e. char)

For example, astMapGet1D would be used to get " double" values, while astMapGet1I would be used to get " int" values, etc. For D or I, the supplied " value" parameter should be a pointer to an array of doubles or ints, with " mxval" elements. For C, the supplied " value" parameter should be a pointer to a character string with " mxval$*$l" elements. For A, the supplied " value" parameter should be a pointer to an array of AstObject pointers. astMapGetC Get a scalar or vector value from a KeyMap as a single string This function gets a named value from a KeyMapKeyMap as a single string. For scalar values it is equivalent to astMapGet0C. If the value is a vector, the returned string is a comma-separated list of the vector elements, enclosed in parentheses. Synopsis int astMapGetC( AstKeyMap $*$this, const char $*$key, const char $*$$*$value ); this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. value Address at which to return a pointer to the required string value. If the requested key is not found, or if it is found but has an undefined value (see astMapPutUastMapPutU), then the contents of the supplied pointer are unchanged on exit. astMapGetC() A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. No error is reported if the requested key cannot be found in the given KeyMap, but a zero value will be returned as the function value. The supplied buffer will be returned unchanged.

The string pointer returned by astMapGetC is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. The calling code should never attempt to free the returned pointer (for instance, using astFreeastFree). astMapGetElem$<$X$>$ Get a single element of a vector value from a KeyMap This is a set of functions for retrieving a single element of a vector value from a KeyMapKeyMap. You should replace $<$X$>$ in the generic function name astMapGetElem$<$X$>$ by an appropriate 1-character type code (see the " Data Type Codes" section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Note, the astMapGetElemC function has an extra parameter " l" which specifies the maximum length of the string to be stored in the " value" buffer (see the " astMapGetElemC" section below). Synopsis int astMapGetElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, $<$X$>$type $*$value ) int astMapGetElemC( AstKeyMap $*$this, const char $*$key, int l, int elem, char $*$value ) this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. elem The index of the required vector element, starting at zero. An error will be reported if the value is outside the range of the vector. value A pointer to a buffer in which to return the requested value. If the requested key is not found, or if it is found but has an undefined value (see astMapPutUastMapPutU), then the contents of the buffer on entry to this function will be unchanged on exit. astMapGetElem$<$X$>$() A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. No error is reported if the requested key cannot be found in the given KeyMap, or if it has an undefined value, but a zero value will be returned as the function value. astMapGetElemC The " value" buffer supplied to the astMapGetElemC function should be a pointer to a character array with " l" elements, where " l" is the maximum length of the string to be returned. The value of " l" should be supplied as an extra parameter following " key" when invoking astMapGetElemC, and should include space for a terminating null character. Data Type Codes To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGetElem$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: D: double

F: float

I: int

K: int64_t

C: " const" pointer to null terminated character string

A: Pointer to AstObject

P: Generic " void $*$" pointer

S: short int

B: Unsigned byte (i.e. char)

For example, astMapGetElemD would be used to get a " double" value, while astMapGetElemI would be used to get an " int" value, etc. For D or I, the supplied " value" parameter should be a pointer to a double or int. For C, the supplied " value" parameter should be a pointer to a character string with " l" elements. For A, the supplied " value" parameter should be a pointer to an AstObject pointer. astMapHasKey Check if an entry with a given key exists in a KeyMap This function returns a flag indicating if the KeyMapKeyMap contains an entry with the given key. Synopsis int astMapHasKey( AstKeyMap $*$this, const char $*$key ) this Pointer to the KeyMap. key The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. astMapHasKey() Non-zero if the key was found, and zero otherwise. A non-zero function value is returned if the key exists but has an undefined value (that is, the returned value does not depend on whether the entry has a defined value or not). See also astMapDefinedastMapDefined, which returns zero in such a case.

A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. astMapKey Get the key at a given index within the KeyMap This function returns a string holding the key for the entry with the given index within the KeyMapKeyMap.

This function is intended primarily as a means of iterating round all the elements in a KeyMap. For this purpose, the number of entries in the KeyMap should first be found using astMapSizeastMapSize and this function should then be called in a loop, with the index value going from zero to one less than the size of the KeyMap. The index associated with a given entry is determined by the SortBySortBy attribute. Synopsis const char $*$astMapKey( AstKeyMap $*$this, int index ) this Pointer to the KeyMap. index The index into the KeyMap. The first entry has index zero, and the last has index " size-1" , where " size" is the value returned by the astMapSize function. astMapKey() A pointer to a null-terminated string containing the key. The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this.

A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astMapLenC Get the number of characters in a character entry in a KeyMap This function returns the minimum length that a character variable must have in order to be able to store a specified entry in the supplied KeyMapKeyMap. If the named entry is a vector entry, then the returned value is the length of the longest element of the vector value. Synopsis int astMapLenC( AstKeyMap $*$this, const char $*$key ) this Pointer to the KeyMap. key The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. astMapLenC() The length (i.e. number of characters) of the longest formatted value associated with the named entry. This does not include the trailing null character. A function value of zero will be returned without error if the named entry cannot be formatted as a character string.

A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. astMapLength Get the vector length of an entry in a KeyMap This function returns the vector length of a named entry in a KeyMapKeyMap, (that is, how many values are associated with the entry). Synopsis int astMapLength( AstKeyMap $*$this, const char $*$key ) this Pointer to the KeyMap. key The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. astMapLength() The length of the entry. One for a scalar, greater than one for a vector. A value of zero is returned if the KeyMap does not contain the named entry. A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. astMapPut0$<$X$>$ Add a scalar value to a KeyMap This is a set of functions for adding scalar values to a KeyMapKeyMap. You should use a function which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic function name astMapPut0$<$X$>$ by an appropriate 1-character type code (see the " Data Type Codes" section below for the code appropriate to each supported data type). Synopsis void astMapPut0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type value, const char $*$comment ); this Pointer to the KeyMap in which to store the supplied value. key A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. value The value to be stored. The data type of this value should match the 1-character type code appended to the function name (e.g. if you are using astMapPut0A, the type of this value should be " pointer to AstObject" ). comment A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored. If the supplied key is already in use in the KeyMap, the new value will replace the old value.

If the stored value is an AST ObjectObject pointer, the Object' s reference count is incremented by this call. Any subsequent changes made to the Object using the returned pointer will be reflected in any any other active pointers for the Object, including any obtained later using astMapget0A. The reference count for the Object will be decremented when the KeyMap is destroyed, or the entry is removed or over-written with a different pointer. Data Type Codes To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPut0$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: D: double

F: float

I: int

K: int64_t

C: " const" pointer to null terminated character string

A: Pointer to AstObject

P: Generic " void $*$" pointer

S: short int

B: unsigned byte (i.e. unsigned char)

For example, astMapPut0D would be used to store a " double" value, while astMapPut0I would be used to store an " int" , etc.

Note that KeyMaps containing generic " void $*$" pointers cannot be written out using astShowastShow or astWriteastWrite. An error will be reported if this is attempted. astMapPut1$<$X$>$ Add a vector value to a KeyMap This is a set of functions for adding vector values to a KeyMapKeyMap. You should use a function which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic function name astMapPut1$<$X$>$ by an appropriate 1-character type code (see the " Data Type Codes" section below for the code appropriate to each supported data type). Synopsis void astMapPut1$<$X$>$( AstKeyMap $*$this, const char $*$key, int size, const $<$X$>$type value[], const char $*$comment ); this Pointer to the KeyMap in which to store the supplied values. key A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. size The number of elements in the supplied array of values. value The array of values to be stored. The data type of this value should match the 1-character type code appended to the function name (e.g. if you are using astMapPut1A, the type of this value should be " array of pointers to AstObject" ). comment A pointer to a null-terminated comment string to be stored with the values. A NULL pointer may be supplied, in which case no comment is stored. If the supplied key is already in use in the KeyMap, the new values will replace the old values. Data Type Codes To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPut1$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: D: double

F: float

I: int

K: int64_t

C: " const" pointer to null terminated character string

A: Pointer to AstObject

P: Generic " void $*$" pointer

S: short int

B: Unsigned byte (i.e. char)

For example, astMapPut1D would be used to store " double" values, while astMapPut1I would be used to store " int" , etc.

Note that KeyMaps containing generic " void $*$" pointers cannot be written out using astShowastShow or astWriteastWrite. An error will be reported if this is attempted. astMapPutElem$<$X$>$ Put a value into an element of a vector value in a KeyMap This is a set of functions for storing a value in a single element of a vector value in a KeyMapKeyMap. You should replace $<$X$>$ in the generic function name astMapPutElem$<$X$>$ by an appropriate 1-character type code (see the " Data Type Codes" section below for the code appropriate to each supported data type). The supplied value is converted from the data type indicated by $<$X$>$ to the data type of the KeyMap entry before being stored (an error is reported if it is not possible to convert the value to the required data type). Synopsis void astMapPutElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, $<$X$>$type value ) this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. elem The index of the vector element to modify, starting at zero. value The value to store. KeyMap If the " elem" index is outside the range of the vector, the length of the vector will be increased by one element and the supplied value will be stored at the end of the vector in the new element. TableTable If the " elem" index is outside the range of the vector, an error will be reported. The number of elements in each cell of a column is specified when the column is created using astAddColumnastAddColumn. If the entry originally holds a scalar value, it will be treated like a vector entry of length 1.

If the specified key cannot be found in the given KeyMap, or is found but has an undefined value, a new vector entry with the given name, and data type implied by $<$X$>$, is created and the supplied value is stored in its first entry. Data Type Codes To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPutElem$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: D: double

F: float

I: int

K: int64_t

C: " const" pointer to null terminated character string

A: Pointer to AstObject

P: Generic " void $*$" pointer

S: short int

B: Unsigned byte (i.e. char)

For example, astMapPutElemD would be used to put a " double" value, while astMapPutElemI would be used to put an " int" value, etc. For D or I, the supplied " value" parameter should be a double or int. For C, the supplied " value" parameter should be a pointer to a character string. For A, the supplied " value" parameter should be an AstObject pointer. astMapPutU Add an entry to a KeyMap with an undefined value This function adds a new entry to a KeyMapKeyMap, but no value is stored with the entry. The entry therefore has a special data type represented by symbolic constant AST__UNDEFTYPE.

An example use is to add entries with undefined values to a KeyMap prior to locking them with the MapLockedMapLocked attribute. Such entries can act as placeholders for values that can be added to the KeyMap later. Synopsis void astMapPutU( AstKeyMap $*$this, const char $*$key, const char $*$comment ); this Pointer to the KeyMap in which to store the supplied value. key A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. comment A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored. If the supplied key is already in use in the KeyMap, the value associated with the key will be removed. astMapRegion Transform a Region into a new Frame using a given Mapping This function returns a pointer to a new RegionRegion which corresponds to supplied Region described by some other specified coordinate system. A MappingMapping is supplied which transforms positions between the old and new coordinate systems. The new Region may not be of the same class as the original region. Synopsis AstRegion $*$astMapRegion( AstRegion $*$this, AstMapping $*$map, AstFrame $*$frame ) this Pointer to the Region. map Pointer to a Mapping which transforms positions from the coordinate system represented by the supplied Region to the coordinate system specified by " frame" . The supplied Mapping should define both forward and inverse transformations, and these transformations should form a genuine inverse pair. That is, transforming a position using the forward transformation and then using the inverse transformation should produce the original input position. Some Mapping classes (such as PermMapPermMap, MathMapMathMap, SphMapSphMap) can result in Mappings for which this is not true. frame Pointer to a FrameFrame describing the coordinate system in which the new Region is required. astMapRegion() A pointer to a new Region. This Region will represent the area within the coordinate system specified by " frame" which corresponds to the supplied Region. The uncertainty associated with the supplied Region is modified using the supplied Mapping.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astMapRemove Removed a named entry from a KeyMap This function removes a named entry from a KeyMapKeyMap. It returns without action if the KeyMap does not contain the specified key. Synopsis void astMapRemove( AstKeyMap $*$this, const char $*$key ) this Pointer to the KeyMap. key The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. astMapRename Rename an existing KeyMap entry This function associated a new key with an existing entry in a KeyMapKeyMap. It returns without action if the oldkey does not exist in the KeyMap. Synopsis void astMapRename( AstKeyMap $*$this, const char $*$oldkey, const char $*$newkey ) this Pointer to the KeyMap. oldkey The character string identifying the entry to be renamed. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. newkey The new character string to associated with the renamed entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero. astMapSize Get the number of entries in a KeyMap This function returns the number of entries in a KeyMapKeyMap. Synopsis int astMapSize( AstKeyMap $*$this ) this Pointer to the KeyMap. astMapSize() The number of entries in the KeyMap. A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. astMapSplit Split a Mapping up into parallel component Mappings This function creates a new MappingMapping which connects specified inputs within a supplied Mapping to the corresponding outputs of the supplied Mapping. This is only possible if the specified inputs correspond to some subset of the Mapping outputs. That is, there must exist a subset of the Mapping outputs for which each output depends only on the selected Mapping inputs, and not on any of the inputs which have not been selected. Also, any output which is not in this subset must not depend on any of the selected inputs. If these conditions are not met by the supplied Mapping, then a NULL Mapping pointer is returned. Synopsis void astMapSplit( AstMapping $*$this, int nin, const int $*$in, int $*$out, AstMapping $*$$*$map ) this Pointer to the Mapping to be split. nin The number of inputs to pick from " this" . in Pointer to an array holding the indices within the supplied Mapping of the inputs which are to be picked from the Mapping. This array should have " nin" elements. If " NinNin" is the number of inputs of the supplied Mapping, then each element should have a value in the range 1 to Nin. out Pointer to an array in which to return the indices of the outputs of the supplied Mapping which are fed by the picked inputs. A value of one is used to refer to the first Mapping output. The supplied array should have a length at least equal to the number of outputs in the supplied Mapping. The number of values stored in the array on exit will equal the number of outputs in the returned Mapping. The i' th element in the returned array holds the index within the supplied Mapping which corresponds to the i' th output of the returned Mapping. map Address of a location at which to return a pointer to the returned Mapping. This Mapping will have " nin" inputs (the number of outputs may be different to " nin" ). NULL is returned if the supplied Mapping has no subset of outputs which depend only on the selected inputs. The returned Mapping is a deep copy of the required parts of the supplied Mapping. If this function is invoked with the global error status set, or if it should fail for any reason, then a NULL value will be returned for the " map" pointer. astMapType Get the data type of an entry in a KeyMap This function returns a value indicating the data type of a named entry in a KeyMapKeyMap. This is the data type which was used when the entry was added to the KeyMap. Synopsis int astMapType( AstKeyMap $*$this, const char $*$key ) this Pointer to the KeyMap. key The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero. astMapType() One of AST__INTTYPE (for integer), AST__SINTTYPE (for short int), AST__KINTTYPE (for int64_t), 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). AST__BADTYPE is returned if the supplied key is not found in the KeyMap. A function value of AST__BADTYPE will be returned if an error has already occurred, or if this function should fail for any reason. astMark Draw a set of markers for a Plot This function draws a set of markers (symbols) at positions specified in the physical coordinate system of a PlotPlot. The positions are transformed into graphical coordinates to determine where the markers should appear within the plotting area. Synopsis void astMark( AstPlot $*$this, int nmark, int ncoord, int indim, const double $*$in, int type ) this Pointer to the Plot. nmark The number of markers to draw. This may be zero, in which case nothing will be drawn. ncoord The number of coordinates being supplied for each mark (i.e. the number of axes in the current FrameFrame of the Plot, as given by its NaxesNaxes attribute). indim The number of elements along the second dimension of the " in" array (which contains the marker coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than " nmark" . in The address of the first element of a 2-dimensional array of shape " [ncoord][indim]" giving the physical coordinates of the points where markers are to be drawn. These should be stored such that the value of coordinate number " coord" for input mark number " mark" is found in element " in[coord][mark]" . type A value specifying the type (e.g. shape) of marker to be drawn. The set of values which may be used (and the shapes that will result) is determined by the underlying graphics system. Markers are not drawn at positions which have any coordinate equal to the value AST__BAD (or where the transformation into graphical coordinates yields coordinates containing the value AST__BAD).

If any marker position is clipped (see astClipastClip), then the entire marker is not drawn.

An error results if the base Frame of the Plot is not 2-dimensional.

An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot' s TranInverseTranInverse attribute is zero). astMask$<$X$>$ Mask a region of a data grid This is a set of functions for masking out regions within gridded data (e.g. an image). The functions modifies a given data grid by assigning a specified value to all samples which are inside (or outside if " inside" is zero) the specified RegionRegion.

You should use a masking function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astMask$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are masking data with type " float" , you should use the function astMaskF (see the " Data Type Codes" section below for the codes appropriate to other numerical types). Synopsis int astMask$<$X$>$( AstRegion $*$this, AstMapping $*$map, int inside, int ndim, const int lbnd[], const int ubnd[], $<$Xtype$>$ in[], $<$Xtype$>$ val ) this Pointer to a Region. map Pointer to a MappingMapping. The forward transformation should map positions in the coordinate system of the supplied Region into pixel coordinates as defined by the " lbnd" and " ubnd" parameters. A NULL pointer can be supplied if the coordinate system of the supplied Region corresponds to pixel coordinates. This is equivalent to supplying a UnitMapUnitMap.

The number of inputs for this Mapping (as given by its NinNin attribute) should match the number of axes in the supplied Region (as given by the NaxesNaxes attribute of the Region). The number of outputs for the Mapping (as given by its NoutNout attribute) should match the number of grid dimensions given by the value of " ndim" below. inside A boolean value which indicates which pixel are to be masked. If a non-zero value is supplied, then all grid pixels with centres inside the supplied Region are assigned the value given by " val" , and all other pixels are left unchanged. If zero is supplied, then all grid pixels with centres not inside the supplied Region are assigned the value given by " val" , and all other pixels are left unchanged. Note, the NegatedNegated attribute of the Region is used to determine which pixel are inside the Region and which are outside. So the inside of a Region which has not been negated is the same as the outside of the corresponding negated Region.

For types of Region such as PointListPointList which have zero volume, pixel centres will rarely fall exactly within the Region. For this reason, the inclusion criterion is changed for zero-volume Regions so that pixels are included (or excluded) if any part of the Region passes through the pixel. For a PointList, this means that pixels are included (or excluded) if they contain at least one of the points listed in the PointList. ndim The number of dimensions in the input grid. This should be at least one. lbnd Pointer to an array of integers, with " ndim" elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. ubnd Pointer to an array of integers, with " ndim" elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd" and " ubnd" together define the shape and size of the input grid, its extent along a particular (j' th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the index " j" to be zero-based). They also define the input grid' s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. in Pointer to an array, with one element for each pixel in the input grid, containing the data to be masked. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astMaskF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used).

On exit, the samples specified by " inside" are set to the value of " val" . All other samples are left unchanged. val This argument should have the same type as the elements of the " in" array. It specifies the value used to flag the masked data (see " inside" ). astMask$<$X$>$() The number of pixels to which a value of " badval" has been assigned. A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason.

An error will be reported if the overlap of the Region and the array cannot be determined. Data Type Codes To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astMask$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

L: long int

UL: unsigned long int

I: int

UI: unsigned int

S: short int

US: unsigned short int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astMaskD would be used to process " double" data, while astMaskS would be used to process " short int" data, etc. Handling of Huge Pixel Arrays If the input grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd" and " ubnd" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function return type is similarly changed to type int64_t. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astMask$<$X$>$ becomes astMask8$<$X$>$. astMatchAxes Find any corresponding axes in two Frames This function looks for corresponding axes within two supplied Frames. An array of integers is returned that contains an element for each axis in the second supplied FrameFrame. An element in this array will be set to zero if the associated axis within the second Frame has no corresponding axis within the first Frame. Otherwise, it will be set to the index (a non-zero positive integer) of the corresponding axis within the first supplied Frame. Synopsis void astMatchAxes( AstFrame $*$frm1, AstFrame $*$frm2, int $*$axes ) frm1 Pointer to the first Frame. frm2 Pointer to the second Frame. axes Pointer to an integer array in which to return the indices of the axes (within the first Frame) that correspond to each axis within the second Frame. AxisAxis indices start at 1. A value of zero will be stored in the returned array for each axis in the second Frame that has no corresponding axis in the first Frame.

The number of elements in this array must be greater than or equal to the number of axes in the second Frame. Frame This function applies to all Frames. Corresponding axes are identified by the fact that a MappingMapping can be found between them using astFindFrameastFindFrame or astConvertastConvert. Thus, " corresponding axes" are not necessarily identical. For instance, SkyFrameSkyFrame axes in two Frames will match even if they describe different celestial coordinate systems astMathMap Create a MathMap This function creates a new MathMapMathMap and optionally initialises its attributes.

A MathMap is a MappingMapping which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an IntraMapIntraMap), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs. Synopsis AstMathMap $*$astMathMap( int nin, int nout, int nfwd, const char $*$fwd[], int ninv, const char $*$inv[], const char $*$options, ... ) nin Number of input variables for the MathMap. This determines the value of its NinNin attribute. nout Number of output variables for the MathMap. This determines the value of its NoutNout attribute. nfwd The number of forward transformation functions being supplied. This must be at least equal to " nout" , but may be increased to accommodate any additional expressions which define intermediate variables for the forward transformation (see the " Calculating Intermediate Values" section below). fwd An array (with " nfwd" elements) of pointers to null terminated strings which contain the expressions defining the forward transformation. The syntax of these expressions is described below. ninv The number of inverse transformation functions being supplied. This must be at least equal to " nin" , but may be increased to accommodate any additional expressions which define intermediate variables for the inverse transformation (see the " Calculating Intermediate Values" section below). inv An array (with " ninv" elements) of pointers to null terminated strings which contain the expressions defining the inverse transformation. The syntax of these expressions is described below. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new MathMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astMathMap() A pointer to the new MathMap. The sequence of numbers produced by the random number functions available within a MathMap is normally unpredictable and different for each MathMap. However, this behaviour may be controlled by means of the MathMap' s SeedSeed attribute.

Normally, compound Mappings (CmpMaps) which involve MathMaps will not be subject to simplification (e.g. using astSimplifyastSimplify) because AST cannot know how different MathMaps will interact. However, in the special case where a MathMap occurs in series with its own inverse, then simplification may be possible. Whether simplification does, in fact, occur under these circumstances is controlled by the MathMap' s SimpFISimpFI and SimpIFSimpIF attributes.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Defining Transformation Functions A MathMap' s transformation functions are supplied as a set of expressions in an array of character strings. Normally you would supply the same number of expressions for the forward transformation, via the " fwd" parameter, as there are output variables (given by the MathMap' s Nout attribute). For instance, if Nout is 2 you might use: " r = sqrt( x $*$ x $+$ y $*$ y )"

" theta = atan2( y, x )"

which defines a transformation from Cartesian to polar coordinates. Here, the variables that appear on the left of each expression (" r" and " theta" ) provide names for the output variables and those that appear on the right (" x" and " y" ) are references to input variables.

To complement this, you must also supply expressions for the inverse transformation via the " inv" parameter. In this case, the number of expressions given would normally match the number of MathMap input coordinates (given by the Nin attribute). If Nin is 2, you might use: " x = r $*$ cos( theta )"

" y = r $*$ sin( theta )"

which expresses the transformation from polar to Cartesian coordinates. Note that here the input variables (" x" and " y" ) are named on the left of each expression, and the output variables (" r" and " theta" ) are referenced on the right.

Normally, you cannot refer to a variable on the right of an expression unless it is named on the left of an expression in the complementary set of functions. Therefore both sets of functions (forward and inverse) must be formulated using the same consistent set of variable names. This means that if you wish to leave one of the transformations undefined, you must supply dummy expressions which simply name each of the output (or input) variables. For example, you might use: " x"

" y"

for the inverse transformation above, which serves to name the input variables but without defining an inverse transformation. Calculating Intermediate Values It is sometimes useful to calculate intermediate values and then to use these in the final expressions for the output (or input) variables. This may be done by supplying additional expressions for the forward (or inverse) transformation functions. For instance, the following array of five expressions describes 2-dimensional pin-cushion distortion: " r = sqrt( xin $*$ xin $+$ yin $*$ yin )"

" rout = r $*$ ( 1 $+$ 0.1 $*$ r $*$ r )"

" theta = atan2( yin, xin )"

" xout = rout $*$ cos( theta )"

" yout = rout $*$ sin( theta )"

Here, we first calculate three intermediate results (" r" , " rout" and " theta" ) and then use these to calculate the final results (" xout" and " yout" ). The MathMap knows that only the final two results constitute values for the output variables because its Nout attribute is set to 2. You may define as many intermediate variables in this way as you choose. Having defined a variable, you may then refer to it on the right of any subsequent expressions.

Note that when defining the inverse transformation you may only refer to the output variables " xout" and " yout" . The intermediate variables " r" , " rout" and " theta" (above) are private to the forward transformation and may not be referenced by the inverse transformation. The inverse transformation may, however, define its own private intermediate variables. Expression Syntax The expressions given for the forward and inverse transformations closely follow the syntax of the C programming language (with some extensions for compatibility with Fortran). They may contain references to variables and literal constants, together with arithmetic, boolean, relational and bitwise operators, and function invocations. A set of symbolic constants is also available. Each of these is described in detail below. Parentheses may be used to over-ride the normal order of evaluation. There is no built-in limit to the length of expressions and they are insensitive to case or the presence of additional white space. Variables Variable names must begin with an alphabetic character and may contain only alphabetic characters, digits, and the underscore character " _" . There is no built-in limit to the length of variable names. Literal Constants Literal constants, such as " 0" , " 1" , " 0.007" or " 2.505e-16" may appear in expressions, with the decimal point and exponent being optional (a " D" may also be used as an exponent character for compatibility with Fortran). A unary minus " -" may be used as a prefix. Arithmetic Precision All arithmetic is floating point, performed in double precision. Propagation of Missing Data Unless indicated otherwise, if any argument of a function or operator has the value AST__BAD (indicating missing data), then the result of that function or operation is also AST__BAD, so that such values are propagated automatically through all operations performed by MathMap transformations. The special value AST__BAD can be represented in expressions by the symbolic constant " $<$bad$>$" .

A $<$bad$>$ result (i.e. equal to AST__BAD) is also produced in response to any numerical error (such as division by zero or numerical overflow), or if an invalid argument value is provided to a function or operator. Arithmetic Operators The following arithmetic operators are available: x1 $+$ x2: Sum of " x1" and " x2" .

x1 - x2: Difference of " x1" and " x2" .

x1 $*$ x2: Product of " x1" and " x1" .

x1 / x2: Ratio of " x1" and " x2" .

x1 $*$$*$ x2: " x1" raised to the power of " x2" .

$+$ x: Unary plus, has no effect on its argument.

- x: Unary minus, negates its argument. Boolean Operators Boolean values are represented using zero to indicate false and non-zero to indicate true. In addition, the value AST__BAD is taken to mean " unknown" . The values returned by boolean operators may therefore be 0, 1 or AST__BAD. Where appropriate, " tri-state" logic is implemented. For example, " a$\vert$$\vert$b" may evaluate to 1 if " a" is non-zero, even if " b" has the value AST__BAD. This is because the result of the operation would not be affected by the value of " b" , so long as " a" is non-zero.

The following boolean operators are available: x1 && x2: Boolean AND between " x1" and " x2" , returning 1 if both " x1" and " x2" are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym " .and." is also provided for compatibility with Fortran.)

x1 $\vert$$\vert$ x2: Boolean OR between " x1" and " x2" , returning 1 if either " x1" or " x2" are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym " .or." is also provided for compatibility with Fortran.)

x1 $\wedge$$\wedge$ x2: Boolean exclusive OR (XOR) between " x1" and " x2" , returning 1 if exactly one of " x1" and " x2" is non-zero, and 0 otherwise. Tri-state logic is not used with this operator. (The synonyms " .neqv." and " .xor." are also provided for compatibility with Fortran, although the second of these is not standard.)

x1 .eqv. x2: This is provided only for compatibility with Fortran and tests whether the boolean states of " x1" and " x2" (i.e. true/false) are equal. It is the negative of the exclusive OR (XOR) function. Tri-state logic is not used with this operator.

! x: Boolean unary NOT operation, returning 1 if " x" is zero, and 0 otherwise. (The synonym " .not." is also provided for compatibility with Fortran.) Relational Operators Relational operators return the boolean result (0 or 1) of comparing the values of two floating point values for equality or inequality. The value AST__BAD may also be returned if either argument is $<$bad$>$.

The following relational operators are available: x1 == x2: Tests whether " x1" equals " x1" . (The synonym " .eq." is also provided for compatibility with Fortran.)

x1 != x2: Tests whether " x1" is unequal to " x2" . (The synonym " .ne." is also provided for compatibility with Fortran.)

x1 $>$ x2: Tests whether " x1" is greater than " x2" . (The synonym " .gt." is also provided for compatibility with Fortran.)

x1 $>$= x2: Tests whether " x1" is greater than or equal to " x2" . (The synonym " .ge." is also provided for compatibility with Fortran.)

x1 $<$ x2: Tests whether " x1" is less than " x2" . (The synonym " .lt." is also provided for compatibility with Fortran.)

x1 $<$= x2: Tests whether " x1" is less than or equal to " x2" . (The synonym " .le." is also provided for compatibility with Fortran.)

Note that relational operators cannot usefully be used to compare values with the $<$bad$>$ value (representing missing data), because the result is always $<$bad$>$. The isbad() function should be used instead. Bitwise Operators The bitwise operators provided by C are often useful when operating on raw data (e.g. from instruments), so they are also provided for use in MathMap expressions. In this case, however, the values on which they operate are floating point values rather than pure integers. In order to produce results which match the pure integer case, the operands are regarded as fixed point binary numbers (i.e. with the binary equivalent of a decimal point) with negative numbers represented using twos-complement notation. For integer values, the resulting bit pattern corresponds to that of the equivalent signed integer (digits to the right of the point being zero). Operations on the bits representing the fractional part are also possible, however.

The following bitwise operators are available: x1 $>$$>$ x2: Rightward bit shift. The integer value of " x2" is taken (rounding towards zero) and the bits representing " x1" are then shifted this number of places to the right (or to the left if the number of places is negative). This is equivalent to dividing " x1" by the corresponding power of 2.

x1 $<$$<$ x2: Leftward bit shift. The integer value of " x2" is taken (rounding towards zero), and the bits representing " x1" are then shifted this number of places to the left (or to the right if the number of places is negative). This is equivalent to multiplying " x1" by the corresponding power of 2.

x1 & x2: Bitwise AND between the bits of " x1" and those of " x2" (equivalent to a boolean AND applied at each bit position in turn).

x1 $\vert$ x2: Bitwise OR between the bits of " x1" and those of " x2" (equivalent to a boolean OR applied at each bit position in turn).

x1 $\wedge$ x2: Bitwise exclusive OR (XOR) between the bits of " x1" and those of " x2" (equivalent to a boolean XOR applied at each bit position in turn).

Note that no bit inversion operator (" $\sim$" in C) is provided. This is because inverting the bits of a twos-complement fixed point binary number is equivalent to simply negating it. This differs from the pure integer case because bits to the right of the binary point are also inverted. To invert only those bits to the left of the binary point, use a bitwise exclusive OR with the value -1 (i.e. " x$\wedge$-1" ). Functions The following functions are available: abs(x): Absolute value of " x" (sign removal), same as fabs(x).

acos(x): Inverse cosine of " x" , in radians.

acosd(x): Inverse cosine of " x" , in degrees.

acosh(x): Inverse hyperbolic cosine of " x" .

acoth(x): Inverse hyperbolic cotangent of " x" .

acsch(x): Inverse hyperbolic cosecant of " x" .

aint(x): Integer part of " x" (round towards zero), same as int(x).

asech(x): Inverse hyperbolic secant of " x" .

asin(x): Inverse sine of " x" , in radians.

asind(x): Inverse sine of " x" , in degrees.

asinh(x): Inverse hyperbolic sine of " x" .

atan(x): Inverse tangent of " x" , in radians.

atand(x): Inverse tangent of " x" , in degrees.

atanh(x): Inverse hyperbolic tangent of " x" .

atan2(x1, x2): Inverse tangent of " x1/x2" , in radians.

atan2d(x1, x2): Inverse tangent of " x1/x2" , in degrees.

ceil(x): Smallest integer value not less then " x" (round towards plus infinity).

cos(x): Cosine of " x" in radians.

cosd(x): Cosine of " x" in degrees.

cosh(x): Hyperbolic cosine of " x" .

coth(x): Hyperbolic cotangent of " x" .

csch(x): Hyperbolic cosecant of " x" .

dim(x1, x2): Returns " x1-x2" if " x1" is greater than " x2" , otherwise 0.

exp(x): Exponential function of " x" .

fabs(x): Absolute value of " x" (sign removal), same as abs(x).

floor(x): Largest integer not greater than " x" (round towards minus infinity).

fmod(x1, x2): Remainder when " x1" is divided by " x2" , same as mod(x1, x2).

gauss(x1, x2): Random sample from a Gaussian distribution with mean " x1" and standard deviation " x2" .

int(x): Integer part of " x" (round towards zero), same as aint(x).

isbad(x): Returns 1 if " x" has the $<$bad$>$ value (AST__BAD), otherwise 0.

log(x): Natural logarithm of " x" .

log10(x): Logarithm of " x" to base 10.

max(x1, x2, ...): Maximum of two or more values.

min(x1, x2, ...): Minimum of two or more values.

mod(x1, x2): Remainder when " x1" is divided by " x2" , same as fmod(x1, x2).

nint(x): Nearest integer to " x" (round to nearest).

poisson(x): Random integer-valued sample from a Poisson distribution with mean " x" .

pow(x1, x2): " x1" raised to the power of " x2" .

qif(x1, x2, x3): Returns " x2" if " x1" is true, and " x3" otherwise.

rand(x1, x2): Random sample from a uniform distribution in the range " x1" to " x2" inclusive.

sech(x): Hyperbolic secant of " x" .

sign(x1, x2): Absolute value of " x1" with the sign of " x2" (transfer of sign).

sin(x): Sine of " x" in radians.

sinc(x): Sinc function of " x" [= " sin(x)/x" ].

sind(x): Sine of " x" in degrees.

sinh(x): Hyperbolic sine of " x" .

sqr(x): Square of " x" (= " x$*$x" ).

sqrt(x): Square root of " x" .

tan(x): Tangent of " x" in radians.

tand(x): Tangent of " x" in degrees.

tanh(x): Hyperbolic tangent of " x" . Symbolic Constants The following symbolic constants are available (the enclosing " $<$$>$" brackets must be included): $<$bad$>$: The " bad" value (AST__BAD) used to flag missing data. Note that you cannot usefully compare values with this constant because the result is always $<$bad$>$. The isbad() function should be used instead.

$<$dig$>$: Number of decimal digits of precision available in a floating point (double) value.

$<$e$>$: BaseBase of natural logarithms.

$<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is distinguishable from unity.

$<$mant_dig$>$: The number of base $<$radix$>$ digits stored in the mantissa of a floating point (double) value.

$<$max$>$: Maximum representable floating point (double) value.

$<$max_10_exp$>$: Maximum integer such that 10 raised to that power can be represented as a floating point (double) value.

$<$max_exp$>$: Maximum integer such that $<$radix$>$ raised to that power minus 1 can be represented as a floating point (double) value.

$<$min$>$: Smallest positive number which can be represented as a normalised floating point (double) value.

$<$min_10_exp$>$: Minimum negative integer such that 10 raised to that power can be represented as a normalised floating point (double) value.

$<$min_exp$>$: Minimum negative integer such that $<$radix$>$ raised to that power minus 1 can be represented as a normalised floating point (double) value.

$<$pi$>$: Ratio of the circumference of a circle to its diameter.

$<$radix$>$: The radix (number base) used to represent the mantissa of floating point (double) values.

$<$rounds$>$: The mode used for rounding floating point results after addition. Possible values include: -1 (indeterminate), 0 (toward zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus infinity). Other values indicate machine-dependent behaviour. Evaluation Precedence and Associativity Items appearing in expressions are evaluated in the following order (highest precedence first): Constants and variables

Function arguments and parenthesised expressions

Function invocations

Unary $+$ - ! .not.

$*$$*$

$*$ /

$+$ -

$<$$<$ $>$$>$

$<$ .lt. $<$= .le. $>$ .gt. $>$= .ge.

== .eq. != .ne.

&

$\wedge$

$\vert$

&& .and.

$\wedge$$\wedge$

$\vert$$\vert$ .or

.eqv. .neqv. .xor.

All operators associate from left-to-right, except for unary $+$, unary -, !, .not. and $*$$*$ which associate from right-to-left. astMatrixMap Create a MatrixMap This function creates a new MatrixMapMatrixMap and optionally initialises its attributes.

A MatrixMap is a form of MappingMapping which performs a general linear transformation. Each set of input coordinates, regarded as a column-vector, are pre-multiplied by a matrix (whose elements are specified when the MatrixMap is created) to give a new column-vector containing the output coordinates. If appropriate, the inverse transformation may also be performed. Synopsis AstMatrixMap $*$astMatrixMap( int nin, int nout, int form, const double matrix[], const char $*$options, ... ) nin The number of input coordinates, which determines the number of columns in the matrix. nout The number of output coordinates, which determines the number of rows in the matrix. form An integer which indicates the form in which the matrix elements will be supplied.

A value of zero indicates that a full " nout" x " nin" matrix of values will be supplied via the " matrix" parameter (below). In this case, the elements should be given in row order (the elements of the first row, followed by the elements of the second row, etc.).

A value of 1 indicates that only the diagonal elements of the matrix will be supplied, and that all others should be zero. In this case, the elements of " matrix" should contain only the diagonal elements, stored consecutively.

A value of 2 indicates that a " unit" matrix is required, whose diagonal elements are set to unity (with all other elements zero). In this case, the " matrix" parameter is ignored and a NULL pointer may be supplied. matrix The array of matrix elements to be used, stored according to the value of " form" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new MatrixMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astMatrixMap() A pointer to the new MatrixMap. In general, a MatrixMap' s forward transformation will always be available (as indicated by its TranForwardTranForward attribute), but its inverse transformation (TranInverseTranInverse attribute) will only be available if the associated matrix is square and non-singular.

As an exception to this, the inverse transformation is always available if a unit or diagonal matrix is specified. In this case, if the matrix is not square, one or more of the input coordinate values may not be recoverable from a set of output coordinates. Any coordinates affected in this way will simply be set to the value zero.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astMirrorVariants Make the current Frame mirror the variant Mappings in another Frame This function indicates that all access to the VariantVariant attribute of the current FrameFrame should should be forwarded to some other nominated Frame in the FrameSetFrameSet. For instance, if a value is set subsequently for the Variant attribute of the current Frame, the current Frame will be left unchanged and the setting is instead applied to the nominated Frame. Likewise, if the value of the Variant attribute is requested, the value returned is the value stored for the nominated Frame rather than the current Frame itself.

This provides a mechanism for propagating the effects of variant Mappings around a FrameSet. If a new Frame is added to a FrameSet by connecting it to an pre-existing Frame that has two or more variant Mappings, then it may be appropriate to set the new Frame so that it mirrors the variants Mappings of the pre-existing Frame. If this is done, then it will be possible to select a specific variant MappingMapping using either the pre-existing Frame or the new Frame. Synopsis void astMirrorVariants( AstFrameSet $*$this, int iframe ) this Pointer to the FrameSet. iframe The index of the Frame within the FrameSet which is to be mirrored by the current Frame. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). If AST__NOFRAME is supplied (or the current Frame is specified), then any mirroring established by a previous call to this function is disabled. Mirrors can be chained. That is, if Frame B is set to be a mirror of Frame A, and Frame C is set to be a mirror of Frame B, then Frame C will act as a mirror of Frame A.

Variant Mappings cannot be added to the current Frame if it is mirroring another Frame. So calls to the astAddVariantastAddVariant function will cause an error to be reported if the current Frame is mirroring another Frame.

A value of AST__BASE may be given for the " iframe" parameter to specify the base Frame.

Any variant Mappings explicitly added to the current Frame using astAddVariant will be ignored if the current Frame is mirroring another Frame. astMoc Create a Moc This function creates a new MocMoc object and optionally initialises its attributes.

The Moc class uses the IVOA MOC (Multi-Order Coverage) recommendation to describe a region on the sky. The region is made up of an arbitrary collection of cells from the HEALPix sky tessellation, and thus may represent any area on the sky, subject to the constraint that the edges of the area correspond to edges of the HEALPix cells. See the MOC recommendation for further information (http://www.ivoa.net/documents/MOC/).

The Moc class describes an arbitrary collection of cells on the sky, whereas other subclasses of RegionRegion describe exact geometric shapes in any arbitrary domain. This results in some differences between Mocs and other types of Region, the main one being that Mocs have no associated uncertainty.

The MOC recommendation requires that a MOC always describes a sky area using the ICRS coordinate system. However, the Moc class, like other subclasses of Region, allows its attributes to be changed so that it represents the equivalent area in any celestial coordinate system that can be mapped to ICRS. See attribute AdaptiveAdaptive.

In practice, to use this class an empty Moc object (i.e. a Moc describing a null area of the sky) should first be created using the astMoc constructor. Areas of the sky should then be added into the empty Moc using one or more of the class methods.

If it is required to write a Moc out to a FITS binary table, the data value and headers to put in the table can be obtained using methods astGetMocDataastGetMocData and astGetMocHeaderastGetMocHeader The MOC described by an existing FITS binary table can be added into a Moc object using the astAddMocDataastAddMocData method.

Note, this class is limited to MOCs for which the number of cells in the normalised MOC can be represented in a four byte signed integer. Synopsis AstMoc $*$astMoc( const char $*$options, ... ) maxorder options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Moc. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional parameters may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astMoc() A pointer to the new Moc. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astMocChan Create a MocChan This function creates a new MocChanMocChan and optionally initialises its attributes.

A MocChan is a specialised form of ChannelChannel which supports the reading and writing of AST MocMoc objects as text, using the conventions of the JSON and string encodings described in the IVOA' s MOC recommendation, version 1.1. Writing a Moc to a MocChan (using astWriteastWrite) will, if the Moc is suitable, generate a textual description of that Moc, and reading from a MocChan will create a new Moc from its textual description. See the Moc class for further information.

Normally, when you use a MocChan, you should provide " source" and " sink" functions which connect it to an external data store by reading and writing the resulting text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output.

Alternatively, a MocChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Synopsis AstMocChan $*$astMocChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) source Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the MocChan to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read.

If " source" is NULL and no value has been set for the SourceFile attribute, the MocChan will read from standard input instead. sink Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the MocChan to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store.

If " sink" is NULL, and no value has been set for the SinkFile attribute, the MocChan will write to standard output instead. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new MocChan. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astMocChan() A pointer to the new MocChan. If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astNegate Negate the area represented by a Region This function negates the area represented by a RegionRegion. That is, points which were previously inside the region will then be outside, and points which were outside will be inside. This is acomplished by toggling the state of the NegatedNegated attribute for the supplied region. Synopsis void astNegate( AstRegion $*$this ) this Pointer to the Region. astNorm Normalise a set of Frame coordinates representing one point This function normalises a set of FrameFrame coordinate values which might be unsuitable for display (e.g. may lie outside the expected range) into a set of acceptable values suitable for display. Synopsis void astNorm( AstFrame $*$this, double value[] ) this Pointer to the Frame. value An array of double, with one element for each Frame axis (NaxesNaxes attribute). Initially, this should contain a set of coordinate values representing a point in the space which the Frame describes. If these values lie outside the expected range for the Frame, they will be replaced with more acceptable (normalised) values. Otherwise, they will be returned unchanged. For some classes of Frame, whose coordinate values are not constrained, this function will never modify the values supplied. However, for Frames whose axes represent cyclic quantities (such as angles or positions on the sky), coordinates will typically be wrapped into an appropriate standard range, such as zero to 2$*$pi.

The NormMapNormMap class is a MappingMapping which can be used to normalise a set of points using the astNorm function of a specified Frame.

It is intended to be possible to put any set of coordinates into a form suitable for display by using this function to normalise them, followed by appropriate formatting (using astFormatastFormat). astNormMap Create a NormMap This function creates a new NormMapNormMap and optionally initialises its attributes.

A NormMap is a MappingMapping which normalises coordinate values using the astNormastNorm function of the supplied FrameFrame. The number of inputs and outputs of a NormMap are both equal to the number of axes in the supplied Frame.

The forward and inverse transformation of a NormMap are both defined but are identical (that is, they do not form a real inverse pair in that the inverse transformation does not undo the normalisation, instead it reapplies it). However, the astSimplifyastSimplify function will replace neighbouring pairs of forward and inverse NormMaps by a single UnitMapUnitMap (so long as the Frames encapsulated by the two NormMaps are equal - i.e. have the same class and the same attribute values). This means, for instance, that if a CmpMapCmpMap contains a NormMap, the CmpMap will still cancel with its own inverse. Synopsis AstNormMap $*$astNormMap( AstFrame $*$frame, const char $*$options, ... ) frame A pointer to the Frame which is to be used to normalise the supplied axis values. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new NormMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astNormMap() A pointer to the new NormMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astNormPoints Normalise a collection of points This function normalises the axis values representing a collection of points within a FrameFrame. The normalisation can be done in two ways - 1) to put the axis values into the range expected for display to human readers or 2) to put the axis values into which ever range avoids discontinuities within the collection of positions. Using method 1) is the same as using function astNormastNorm on each point in the collection. Using method 2) is useful when handling collections of points that may span some discontinuity in the coordinate system. Synopsis void astNormPoints( AstFrame $*$this, int npoint, int ncoord_in, int indim, const double $*$in, int contig, int ncoord_out, int outdim, double $*$out ) this Pointer to the Frame. npoint The number of points to be normalised. ncoord_in The number of coordinates being supplied for each input point. This should be the same as the number of axes in the Frame. indim The number of elements along the second dimension of the " in" array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than " npoint" . in The address of the first element in a 2-dimensional array of shape " [ncoord_in][indim]" , containing the coordinates of the input (unnormalised) points. These should be stored such that the value of coordinate number " coord" for input point number " point" is found in element " in[coord][point]" . contig Indicates the way in which the normalised axis values are to be calculated. A non-zero value causes the values to be normalised in such a way as to reduce the effects of any discontinuities in the coordinate system. For instance, points in a SkyFrameSkyFrame that span longitude zero will be normalized into a longitude range of -pi to $+$pi (otherwise they will be normalized into a range of 0 to 2.pi). A zero value causes each point to be normalised independently using astNorm. ncoord_out The number of coordinates being supplied for each output point. This should be the same as the number of axes in the Frame. outdim The number of elements along the second dimension of the " out" array (which will contain the output coordinates). This value is required so that the coordinate values can be correctly located if they will not entirely fill this array. The value given should not be less than " npoint" . out The address of the first element in a 2-dimensional array of shape " [ncoord_out][outdim]" , into which the coordinates of the output (normalised) points will be written. These will be stored such that the value of coordinate number " coord" for output point number " point" will be found in element " out[coord][point]" . For some classes of Frame, whose coordinate values are not constrained, this function will never modify the values supplied. However, for Frames whose axes represent cyclic quantities (such as angles or positions on the sky), coordinates will typically be wrapped into an appropriate standard range, such as zero to 2$*$pi or -pi to $+$pi (depending on the normalisation method used). Handling of Huge Pixel Arrays If the number of points to be normalised exceeds the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte). Specifically, the arguments " npoint" , " indim" and " outdim" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astNormPoints becomes astNormPoints8 astNullRegion Create a NullRegion This function creates a new NullRegionNullRegion and optionally initialises its attributes.

A NullRegion is a RegionRegion with no bounds. If the NegatedNegated attribute of a NullRegion is false, the NullRegion represents a Region containing no points. If the Negated attribute of a NullRegion is true, the NullRegion represents an infinite Region containing all points within the coordinate system. Synopsis AstNullRegion $*$astNullRegion( AstFrame $*$frame, AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the FrameFrame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. unc An optional pointer to an existing Region which specifies the uncertainties associated with positions in the supplied Frame. The uncertainty in any point in the Frame is found by shifting the supplied " uncertainty" Region so that it is centred at the point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. BoxBox, CircleCircle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created NullRegion. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty of zero is used. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new NullRegion. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astNullRegion() A pointer to the new NullRegion. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astOK Test whether AST functions have been successful This macro returns a boolean value (0 or 1) to indicate if preceding AST functions have completed successfully (i.e. without setting the AST error status). If the error status is set to an error value, a value of zero is returned, otherwise the result is one. Synopsis int astOK astOK One if the AST error status is OK, otherwise zero. If the AST error status is set to an error value (after an error), most AST functions will not execute and will simply return without action. To clear the error status and restore normal behaviour, use astClearStatusastClearStatus. astOffset Calculate an offset along a geodesic curve This function finds the FrameFrame coordinate values of a point which is offset a specified distance along the geodesic curve between two other points.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions. Synopsis void astOffset( AstFrame $*$this, const double point1[], const double point2[], double offset, double point3[] ) this Pointer to the Frame. point1 An array of double, with one element for each Frame axis (NaxesNaxes attribute). This should contain the coordinates of the point marking the start of the geodesic curve. point2 An array of double, with one element for each Frame axis This should contain the coordinates of the point marking the end of the geodesic curve. offset The required offset from the first point along the geodesic curve. If this is positive, it will be towards the second point. If it is negative, it will be in the opposite direction. This offset need not imply a position lying between the two points given, as the curve will be extrapolated if necessary. point3 An array of double, with one element for each Frame axis in which the coordinates of the required point will be returned. The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistanceastDistance function.

This function will return " bad" coordinate values (AST__BAD) if any of the input coordinates has this value.

" Bad" coordinate values will also be returned if the two points supplied are coincident (or otherwise fail to uniquely specify a geodesic curve) but the requested offset is non-zero. astOffset2 Calculate an offset along a geodesic curve in a 2D Frame This function finds the FrameFrame coordinate values of a point which is offset a specified distance along the geodesic curve at a given angle from a specified starting point. It can only be used with 2-dimensional Frames.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions. Synopsis double astOffset2( AstFrame $*$this, const double point1[2], double angle, double offset, double point2[2] ); this Pointer to the Frame. point1 An array of double, with one element for each Frame axis (NaxesNaxes attribute). This should contain the coordinates of the point marking the start of the geodesic curve. angle The angle (in radians) from the positive direction of the second axis, to the direction of the required position, as seen from the starting position. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1. offset The required offset from the first point along the geodesic curve. If this is positive, it will be in the direction of the given angle. If it is negative, it will be in the opposite direction. point2 An array of double, with one element for each Frame axis in which the coordinates of the required point will be returned. astOffset2 The direction of the geodesic curve at the end point. That is, the angle (in radians) between the positive direction of the second axis and the continuation of the geodesic curve at the requested end point. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1. The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistanceastDistance function.

An error will be reported if the Frame is not 2-dimensional.

This function will return " bad" coordinate values (AST__BAD) if any of the input coordinates has this value. astOutline$<$X$>$ Create a new Polygon outling values in a 2D data grid This is a set of functions that create a PolygonPolygon enclosing a single contiguous set of pixels that have a specified value within a gridded 2-dimensional data array (e.g. an image).

A basic 2-dimensional FrameFrame is used to represent the pixel coordinate system in the returned Polygon. The DomainDomain attribute is set to " PIXEL" , the TitleTitle attribute is set to " Pixel coordinates" , and the Unit attribute for each axis is set to " pixel" . All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter " starpix" .

The " maxerr" and " maxvert" parameters can be used to control how accurately the returned Polygon represents the required region in the data array. The number of vertices in the returned Polygon will be the minimum needed to achieve the required accuracy.

You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astOutline$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are procesing data with type " float" , you should use the function astOutlineF (see the " Data Type Codes" section below for the codes appropriate to other numerical types). Synopsis AstPolygon $*$astOutline$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[], const int lbnd[2], const int ubnd[2], double maxerr, int maxvert, const int inside[2], int starpix ) value A data value that specifies the pixels to be outlined. oper Indicates how the " value" parameter is used to select the outlined pixels. It can have any of the following values: AST__LT: outline pixels with value less than " value" .

AST__LE: outline pixels with value less than or equal to " value" .

AST__EQ: outline pixels with value equal to " value" .

AST__NE: outline pixels with value not equal to " value" .

AST__GE: outline pixels with value greater than or equal to " value" .

AST__GT: outline pixels with value greater than " value" . array Pointer to a 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astOutlineF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. Fortran array indexing is used). lbnd Pointer to an array of two integers containing the pixel index of the first pixel in the input grid along each dimension. ubnd Pointer to an array of two integers containing the pixel index of the last pixel in the input grid along each dimension.

Note that " lbnd" and " ubnd" together define the shape and size of the input pixel grid, its extent along a particular (j' th) dimension being ubnd[j]-lbnd[j]$+$1 pixels. For FITS images, the lbnd values will be 1 and the ubnd values will be equal to the NAXISi header values. Other data systems, such as the Starlink NDF system, allow an arbitrary pixel origin to be used (i.e. lbnd is not necessarily 1).

These bounds also define the input grid' s floating point coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter " starpix" . maxerr Together with " maxvert" , this determines how accurately the returned Polygon represents the required region of the data array. It gives the target discrepancy between the returned Polygon and the accurate outline in the data array, expressed as a number of pixels. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals " maxvert" , or the largest discrepancy between the accurate outline and the returned Polygon is greater than " maxerr" . If " maxerr" is zero or less, its value is ignored and the returned Polygon will have the number of vertices specified by " maxvert" . maxvert Together with " maxerr" , this determines how accurately the returned Polygon represents the required region of the data array. It gives the maximum allowed number of vertices in the returned Polygon. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals " maxvert" , or the largest discrepancy between the accurate outline and the returned Polygon is greater than " maxerr" . If " maxvert" is less than 3, its value is ignored and the number of vertices in the returned Polygon will be the minimum needed to ensure that the discrepancy between the accurate outline and the returned Polygon is less than " maxerr" . inside Pointer to an array of two integers containing the pixel indices of a pixel known to be inside the required region. This is needed because the supplied data array may contain several disjoint areas of pixels that satisfy the criterion specified by " value" and " oper" . In such cases, the area described by the returned Polygon will be the one that contains the pixel specified by " inside" . If the specified pixel is outside the bounds given by " lbnd" and " ubnd" , or has a value that does not meet the criterion specified by " value" and " oper" , then this function will search for a suitable pixel. The search starts at the central pixel and proceeds in a spiral manner until a pixel is found that meets the specified crierion. starpix A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If non-zero, the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If zero, the definition of pixel coordinate used by other AST functions such as astResample, astMask, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates). astOutline$<$X$>$() A pointer to the required Polygon. This function proceeds by first finding a very accurate polygon, and then removing insignificant vertices from this fine polygon using astDownsizeastDownsize.

The returned Polygon is the outer boundary of the contiguous set of pixels that includes ths specified " inside" point, and satisfy the specified value requirement. This set of pixels may potentially include " holes" where the pixel values fail to meet the specified value requirement. Such holes will be ignored by this function.

NULL will be returned if this function is invoked with the global error status set, or if it should fail for any reason. Data Type Codes To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astOutline$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

L: long int

UL: unsigned long int

I: int

UI: unsigned int

S: short int

US: unsigned short int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astOutlineD would be used to process " double" data, while astOutlineS would be used to process " short int" data, etc. Handling of Huge Pixel Arrays If the input grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd" , " ubnd" and " inside" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astOutline$<$X$>$ becomes astOutline8$<$X$>$. astOverlap Test if two regions overlap each other This function returns an integer value indicating if the two supplied Regions overlap. The two Regions are converted to a commnon coordinate system before performing the check. If this conversion is not possible (for instance because the two Regions represent areas in different domains), then the check cannot be performed and a zero value is returned to indicate this. Synopsis int astOverlap( AstRegion $*$this, AstRegion $*$that ) this Pointer to the first RegionRegion. that Pointer to the second Region. astOverlap() A value indicating if there is any overlap between the two Regions. Possible values are:

0 - The check could not be performed because the second Region could not be mapped into the coordinate system of the first Region.

1 - There is no overlap between the two Regions.

2 - The first Region is completely inside the second Region.

3 - The second Region is completely inside the first Region.

4 - There is partial overlap between the two Regions.

5 - The Regions are identical to within their uncertainties.

6 - The second Region is the exact negation of the first Region to within their uncertainties. The returned values 5 and 6 do not check the value of the ClosedClosed attribute in the two Regions.

A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astParameterName Get the name of the global parameter at a given index within the Table This function returns a string holding the name of the global parameter with the given index within the TableTable.

This function is intended primarily as a means of iterating round all the parameters in a Table. For this purpose, the number of parameters in the Table is given by the NparameterNparameter attribute of the Table. This function could then be called in a loop, with the index value going from zero to one less than Nparameter.

Note, the index associated with a parameter decreases monotonically with the age of the parameter: the oldest Parameter in the Table will have index one, and the Parameter added most recently to the Table will have the largest index. Synopsis const char $*$astParameterName( AstTable $*$this, int index ) this Pointer to the Table. index The index into the list of parameters. The first parameter has index one, and the last has index " Nparameter" . astParameterName() A pointer to a null-terminated string containing the upper case parameter name. The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this.

A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPcdMap Create a PcdMap This function creates a new PcdMapPcdMap and optionally initialises its attributes.

A PcdMap is a non-linear MappingMapping which transforms 2-dimensional positions to correct for the radial distortion introduced by some cameras and telescopes. This can take the form either of pincushion or barrel distortion, and is characterized by a single distortion coefficient.

A PcdMap is specified by giving this distortion coefficient and the coordinates of the centre of the radial distortion. The forward transformation of a PcdMap applies the distortion:

RD = R $*$ ( 1 $+$ C $*$ R $*$ R )

where R is the undistorted radial distance from the distortion centre (specified by attribute PcdCen), RD is the radial distance from the same centre in the presence of distortion, and C is the distortion coefficient (given by attribute DiscoDisco).

The inverse transformation of a PcdMap removes the distortion produced by the forward transformation. The expression used to derive R from RD is an approximate inverse of the expression above, obtained from two iterations of the Newton-Raphson method. The mismatch between the forward and inverse expressions is negligible for astrometric applications (to reach 1 milliarcsec at the edge of the Anglo-Australian Telescope triplet or a Schmidt field would require field diameters of 2.4 and 42 degrees respectively).

If a PcdMap is inverted (e.g. using astInvertastInvert) then the roles of the forward and inverse transformations are reversed; the forward transformation will remove the distortion, and the inverse transformation will apply it. Synopsis AstPcdMap $*$astPcdMap( double disco, const double pcdcen[2], const char $*$options, ... ) disco The distortion coefficient. Negative values give barrel distortion, positive values give pincushion distortion, and zero gives no distortion. pcdcen A 2-element array containing the coordinates of the centre of the distortion. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PcdMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPcdMap() A pointer to the new PcdMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astPermAxes Permute the axis order in a Frame This function permutes the order in which a FrameFrame' s axes occur. Synopsis void astPermAxes( AstFrame $*$this, const int perm[] ) this Pointer to the Frame. perm An array with one element for each axis of the Frame (NaxesNaxes attribute). This should list the axes in their new order, using the original axis numbering (which starts at 1 for the first axis). Only genuine permutations of the axis order are permitted, so each axis must be referenced exactly once in the " perm" array.

If successive axis permutations are applied to a Frame, then the effects are cumulative. astPermMap Create a PermMap This function creates a new PermMapPermMap and optionally initialises its attributes.

A PermMap is a MappingMapping which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output.

In addition to permuting the coordinate order, a PermMap may also assign constant values to coordinates. This is useful when the number of coordinates is being increased as it allows fixed values to be assigned to any new ones. Synopsis AstPermMap $*$astPermMap( int nin, const int inperm[], int nout, const int outperm[], double constant[], const char $*$options, ... ) nin The number of input coordinates. inperm An optional array with " nin" elements which, for each input coordinate, should contain the number of the output coordinate whose value is to be used (note that this array therefore defines the inverse coordinate transformation). Coordinates are numbered starting from 1.

For details of additional special values that may be used in this array, see the description of the " constant" parameter.

If a NULL pointer is supplied instead of an array, each input coordinate will obtain its value from the corresponding output coordinate (or will be assigned the value AST__BAD if there is no corresponding output coordinate). nout The number of output coordinates. outperm An optional array with " nout" elements which, for each output coordinate, should contain the number of the input coordinate whose value is to be used (note that this array therefore defines the forward coordinate transformation). Coordinates are numbered starting from 1.

For details of additional special values that may be used in this array, see the description of the " constant" parameter.

If a NULL pointer is supplied instead of an array, each output coordinate will obtain its value from the corresponding input coordinate (or will be assigned the value AST__BAD if there is no corresponding input coordinate). constant An optional array containing values which may be assigned to input and/or output coordinates instead of deriving them from other coordinate values. If either of the " inperm" or " outperm" arrays contains a negative value, it is used to address this " constant" array (such that -1 addresses the first element, -2 addresses the second element, etc.) and the value obtained is used as the corresponding coordinate value.

Care should be taken to ensure that locations lying outside the extent of this array are not accidentally addressed. The array is not used if the " inperm" and " outperm" arrays do not contain negative values.

If a NULL pointer is supplied instead of an array, the behaviour is as if the array were of infinite length and filled with the value AST__BAD. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PermMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPermMap() A pointer to the new PermMap. If either of the " inperm" or " outperm" arrays contains a zero value (or a positive value which does not identify a valid output/input coordinate, as appropriate), then the value AST__BAD is assigned as the new coordinate value.

This function does not attempt to ensure that the forward and inverse transformations performed by the PermMap are self-consistent in any way. You are therefore free to supply coordinate permutation arrays that achieve whatever effect is desired.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPickAxes Create a new Frame by picking axes from an existing one This function creates a new FrameFrame whose axes are copied from an existing Frame along with other Frame attributes, such as its TitleTitle. Any number (zero or more) of the original Frame' s axes may be copied, in any order, and additional axes with default attributes may also be included in the new Frame.

Optionally, a MappingMapping that converts between the coordinate systems described by the two Frames will also be returned. Synopsis AstFrame $*$astPickAxes( AstFrame $*$this, int naxes, const int axes[], AstMapping $*$$*$map ) this Pointer to the original Frame. naxes The number of axes required in the new Frame. axes An array, with " naxes" elements, which lists the axes to be copied. These should be given in the order required in the new Frame, using the axis numbering in the original Frame (which starts at 1 for the first axis). Axes may be selected in any order, but each may only be used once. If additional (default) axes are also to be included, the corresponding elements of this array should be set to zero. map Address of a location in which to return a pointer to a new Mapping. This will be a PermMapPermMap (or a UnitMapUnitMap as a special case) that describes the axis permutation that has taken place between the original and new Frames. The Mapping' s forward transformation will convert coordinates from the original Frame into the new one, and vice versa.

If this Mapping is not required, a NULL value may be supplied for this parameter. Frame This function applies to all Frames. The class of Frame returned may differ from that of the original Frame, depending on which axes are selected. For example, if a single axis is picked from a SkyFrameSkyFrame (which must always have two axes) then the resulting Frame cannot be a valid SkyFrame, so will revert to the parent class (Frame) instead. FrameSetFrameSet Using this function on a FrameSet is identical to using it on the current Frame in the FrameSet. The returned Frame will not be a FrameSet. RegionRegion If this function is used on a Region, an attempt is made to retain the bounds information on the selected axes. If succesful, the returned Frame will be a Region of some class. Otherwise, the returned Frame is obtained by calling this function on the Frame represented by the supplied Region (the returned Frame will then not be a Region). In order to be succesful, the selected axes in the Region must be independent of the others. For instance, a BoxBox can be split in this way but a CircleCircle cannot. Another requirement for success is that no default axes are added (that is, the " axes" array must not contain any zero values. astPickAxes() A pointer to the new Frame. The new Frame will contain a " deep" copy (c.f. astCopyastCopy) of all the data selected from the original Frame. Modifying any aspect of the new Frame will therefore not affect the original one.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPlot Create a Plot This function creates a new PlotPlot and optionally initialises its attributes.

A Plot is a specialised form of FrameSetFrameSet, in which the base FrameFrame describes a " graphical" coordinate system and is associated with a rectangular plotting area in the underlying graphics system. This plotting area is where graphical output appears. It is defined when the Plot is created.

The current Frame of a Plot describes a " physical" coordinate system, which is the coordinate system in which plotting operations are specified. The results of each plotting operation are automatically transformed into graphical coordinates so as to appear in the plotting area (subject to any clipping which may be in effect).

Because the MappingMapping between physical and graphical coordinates may often be non-linear, or even discontinuous, most plotting does not result in simple straight lines. The basic plotting element is therefore not a straight line, but a geodesic curve (see astCurveastCurve). A Plot also provides facilities for drawing markers or symbols (astMarkastMark), text (astTextastText) and grid lines (astGridLineastGridLine). It is also possible to draw curvilinear axes with optional coordinate grids (astGridastGrid). A range of Plot attributes is available to allow precise control over the appearance of graphical output produced by these functions.

You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot, using its CurrentCurrent attribute. You may also set up clipping (see astClipastClip) to limit the extent of any plotting you perform, and this may be done in any of the coordinate systems associated with the Plot, not necessarily the one you are plotting in.

Like any FrameSet, a Plot may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system.

When used as a Mapping, a Plot describes the inter-relation between graphical coordinates (its base Frame) and physical coordinates (its current Frame). It differs from a normal FrameSet, however, in that an attempt to transform points which lie in clipped areas of the Plot will result in bad coordinate values (AST__BAD). Synopsis AstPlot $*$astPlot( AstFrame $*$frame, const float graphbox[ 4 ], const double basebox[ 4 ], const char $*$options, ... ) frame Pointer to a Frame describing the physical coordinate system in which to plot. A pointer to a FrameSet may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below).

If a null ObjectObject pointer (AST__NULL) is given, a default 2-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. Label(axis)Label(axis)) for the Plot. graphbox An array giving the position and extent of the plotting area (on the plotting surface of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system.

The first pair of values should give the coordinates of the bottom left corner of the plotting area and the second pair should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations. basebox An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting area, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Plot. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPlot() A pointer to the new Plot. The base Frame of the returned Plot will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot. The choice of base Frame (BaseBase attribute) should not, in general, be changed once a Plot has been created (although you could use this as a way of moving the plotting area around on the plotting surface).

If a Frame is supplied (via the " frame" pointer), then it becomes the current Frame of the new Plot and is given a Frame index of 2.

If a FrameSet is supplied (via the " frame" pointer), then all the Frames within this FrameSet become part of the new Plot (where their Frame indices are increased by 1), with the FrameSet' s current Frame becoming the current Frame of the Plot.

If a null Object pointer (AST__NULL) is supplied (via the " frame" pointer), then the returned Plot will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot TitleTitle and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates.

An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 2-dimensional.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPlot3D Create a Plot3D This function creates a new Plot3DPlot3D and optionally initialises its attributes.

A Plot3D is a specialised form of PlotPlot that provides facilities for producing 3D graphical output. Synopsis AstPlot3D $*$astPlot3D( AstFrame $*$frame, const float graphbox[ 6 ], const double basebox[ 6 ], const char $*$options, ... ) frame Pointer to a FrameFrame describing the physical coordinate system in which to plot. A pointer to a FrameSetFrameSet may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below).

If a null ObjectObject pointer (AST__NULL) is given, a default 3-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. Label(axis)Label(axis)) for the Plot. graphbox An array giving the position and extent of the plotting volume (within the plotting space of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system.

The first triple of values should give the coordinates of the bottom left corner of the plotting volume and the second triple should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations. basebox An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting volume, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Plot3D. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPlot3D() A pointer to the new Plot3D. The base Frame of the returned Plot3D will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot3D. The choice of base Frame (BaseBase attribute) should not, in general, be changed once a Plot3D has been created (although you could use this as a way of moving the plotting area around on the plotting surface).

If a Frame is supplied (via the " frame" pointer), then it becomes the current Frame of the new Plot3D and is given a Frame index of 2.

If a FrameSet is supplied (via the " frame" pointer), then all the Frames within this FrameSet become part of the new Plot3D (where their Frame indices are increased by 1), with the FrameSet' s current Frame becoming the current Frame of the Plot3D.

At least one of the three axes of the current Frame must be independent of the other two current Frame axes.

If a null Object pointer (AST__NULL) is supplied (via the " frame" pointer), then the returned Plot3D will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot3D TitleTitle and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates.

An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 3-dimensional.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPointInRegion Tests if a single point is inside a Region This function returns a logical value indicating if a supplied point is inside a supplied RegionRegion. Synopsis int astPointInRegion( AstRegion $*$this, const double point[] ) this Pointer to the Region. point Pointer to an array holding the axis values of the point to be tested. The number of values in this array should match the number of axes in the supplied Region. astPointInRegion() Zero if the point is outside the Region, and non-zero otherwise. If the supplied value is AST__BAD on every axis, then 0 is always returned.

If many points need to be tested, then it is usually more efficient to use the Region as a MappingMapping to transform all the points. This can be done using one of the Mapping transformation methods (astTran$<$X$>$). If a transformed axis value is AST__BAD then the corresponding input point is outside the Region.

Zero will be returned if an error occurs. astPointList Create a PointList This function creates a new PointListPointList object and optionally initialises its attributes.

A PointList object is a specialised type of RegionRegion which represents a collection of points in a coordinate FrameFrame. Synopsis AstPointList $*$astPointList( AstFrame $*$frame, int npnt, int ncoord, int dim, const double $*$points, AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. npnt The number of points in the Region. ncoord The number of coordinates being supplied for each point. This must equal the number of axes in the supplied Frame, given by its NaxesNaxes attribute. dim The number of elements along the second dimension of the " points" array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than " npnt" . points The address of the first element of a 2-dimensional array of shape " [ncoord][dim]" giving the physical coordinates of the points. These should be stored such that the value of coordinate number " coord" for point number " pnt" is found in element " in[coord][pnt]" . unc An optional pointer to an existing Region which specifies the uncertainties associated with each point in the PointList being created. The uncertainty at any point in the PointList is found by shifting the supplied " uncertainty" Region so that it is centred at the point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. BoxBox, CircleCircle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the bounding box of the PointList being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplifyastSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PointList. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPointList() A pointer to the new PointList. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astPolyCoeffs Retrieve the coefficient values used by a PolyMap This function returns the coefficient values used by either the forward or inverse transformation of a PolyMapPolyMap, in the same form that they are supplied to the PolyMap constructor.

Usually, you should call this method first with " nel" set to zero to determine the number of coefficients used by the PolyMap. This allows you to allocate an array of the correct size to hold all coefficient data. You should then call this method a second time to get the coefficient data. Synopsis void astPolyCoeffs( AstPolyMap $*$this, int forward, int nel, double $*$coeffs, int $*$ncoeff ) this Pointer to the original MappingMapping. forward If non-zero, the coefficients of the forward PolyMap transformation are returned. Otherwise the inverse transformation coefficients are returned. nel The length of the supplied " coeffs" array. It should be at least " ncoeff$*$( nin $+$ 2 )" if " foward" is non-zero, and " ncoeff$*$( nout $+$ 2 )" otherwise, where " ncoeff" is the number of coefficients to be returned. If a value of zero is supplied, no coefficient values are returned, but the number of coefficients used by the transformation is still returned in " ncoeff" . coeffs An array in which to return the coefficients used by the requested transformation of the PolyMap. Ignored if " nel" is zero. The coefficient data is returned in the form in which it is supplied to the PolyMap constructor. That is, each group of " 2 $+$ nin" or " 2 $+$ nout" adjacent elements describe a single coefficient of the forward or inverse transformation. See the PolyMap constructor documentation for further details.

If the supplied array is too short to hold all the coefficients, trailing coefficients are excluded. If the supplied array is longer than needed to hold all the coefficients, trailing elements are filled with zeros. ncoeff The number of coefficients used by the requested transformation. A value of zero is returned if the transformation does not have any defining polynomials. A value is returned for this argument even if " nel" is zero. astPolyCurve Draw a series of connected geodesic curves This function joins a series of points specified in the physical coordinate system of a PlotPlot by drawing a sequence of geodesic curves. It is equivalent to making repeated use of the astCurveastCurve function (q.v.), except that astPolyCurve will generally be more efficient when drawing many geodesic curves end-to-end. A typical application of this might be in drawing contour lines.

As with astCurve, full account is taken of the MappingMapping between physical and graphical coordinate systems. This includes any discontinuities and clipping established using astClipastClip. Synopsis void astPolyCurve( AstPlot $*$this, int npoint, int ncoord, int indim, const double $*$in ) this Pointer to the Plot. npoint The number of points between which geodesic curves are to be drawn. ncoord The number of coordinates being supplied for each point (i.e. the number of axes in the current FrameFrame of the Plot, as given by its NaxesNaxes attribute). indim The number of elements along the second dimension of the " in" array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than " npoint" . in The address of the first element in a 2-dimensional array of shape " [ncoord][indim]" giving the physical coordinates of the points which are to be joined in sequence by geodesic curves. These should be stored such that the value of coordinate number " coord" for point number " point" is found in element " in[coord][point]" . No curve is drawn on either side of any point which has any coordinate equal to the value AST__BAD.

An error results if the base Frame of the Plot is not 2-dimensional.

An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot' s TranInverseTranInverse attribute is zero). astPolyMap Create a PolyMap This function creates a new PolyMapPolyMap and optionally initialises its attributes.

A PolyMap is a form of MappingMapping which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, the default behaviour is to use an iterative method to evaluate the inverse based only on the forward transformation (see attribute IterInverseIterInverse). Synopsis AstPolyMap $*$astPolyMap( int nin, int nout, int ncoeff_f, const double coeff_f[], int ncoeff_i, const double coeff_i[], const char $*$options, ... ) nin The number of input coordinates. nout The number of output coordinates. ncoeff_f The number of non-zero coefficients necessary to define the forward transformation of the PolyMap. If zero is supplied, the forward transformation will be undefined. coeff_f An array containing " ncoeff_f$*$( 2 $+$ nin )" elements. Each group of " 2 $+$ nin" adjacent elements describe a single coefficient of the forward transformation. Within each such group, the first element is the coefficient value; the next element is the integer index of the PolyMap output which uses the coefficient within its defining polynomial (the first output has index 1); the remaining elements of the group give the integer powers to use with each input coordinate value (powers must not be negative, and floating point values are rounded to the nearest integer). If " ncoeff_f" is zero, a NULL pointer may be supplied for " coeff_f" .

For instance, if the PolyMap has 3 inputs and 2 outputs, each group consisting of 5 elements, A groups such as " (1.2, 2.0, 1.0, 3.0, 0.0)" describes a coefficient with value 1.2 which is used within the definition of output 2. The output value is incremented by the product of the coefficient value, the value of input coordinate 1 raised to the power 1, and the value of input coordinate 2 raised to the power 3. Input coordinate 3 is not used since its power is specified as zero. As another example, the group " (-1.0, 1.0, 0.0, 0.0, 0.0 )" describes adds a constant value -1.0 onto output 1 (it is a constant value since the power for every input axis is given as zero).

Each final output coordinate value is the sum of the " ncoeff_f" terms described by the " ncoeff_f" groups within the supplied array. ncoeff_i The number of non-zero coefficients necessary to define the inverse transformation of the PolyMap. If zero is supplied, the default behaviour is to use an iterative method to evaluate the inverse based only on the forward transformation (see attribute IterInverse). coeff_i An array containing " ncoeff_i$*$( 2 $+$ nout )" elements. Each group of " 2 $+$ nout" adjacent elements describe a single coefficient of the inverse transformation, using the same schame as " coeff_f" , except that " inputs" and " outputs" are transposed. If " ncoeff_i" is zero, a NULL pointer may be supplied for " coeff_i" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PolyMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPolyMap() A pointer to the new PolyMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPolyTran Fit a PolyMap inverse or forward transformation This function creates a new PolyMapPolyMap which is a copy of the supplied PolyMap, in which a specified transformation (forward or inverse) has been replaced by a new polynomial transformation. The coefficients of the new transformation are estimated by sampling the other transformation and performing a least squares polynomial fit in the opposite direction to the sampled positions and values.

This method can only be used on (1-input,1-output) or (2-input,2-output) PolyMaps.

The transformation to create is specified by the " forward" parameter. In what follows " X" refers to the inputs of the PolyMap, and " Y" to the outputs of the PolyMap. The forward transformation transforms input values (X) into output values (Y), and the inverse transformation transforms output values (Y) into input values (X). Within a PolyMap, each transformation is represented by an independent set of polynomials, P_f or P_i: Y=P_f(X) for the forward transformation and X=P_i(Y) for the inverse transformation.

The " forward" parameter specifies the transformation to be replaced. If it is non-zero, a new forward transformation is created by first finding the input values (X) using the inverse transformation (which must be available) at a regular grid of points (Y) covering a rectangular region of the PolyMap' s output space. The coefficients of the required forward polynomial, Y=P_f(X), are chosen in order to minimise the sum of the squared residuals between the sampled values of Y and P_f(X).

If " forward" is zero (probably the most likely case), a new inverse transformation is created by first finding the output values (Y) using the forward transformation (which must be available) at a regular grid of points (X) covering a rectangular region of the PolyMap' s input space. The coefficients of the required inverse polynomial, X=P_i(Y), are chosen in order to minimise the sum of the squared residuals between the sampled values of X and P_i(Y).

This fitting process is performed repeatedly with increasing polynomial orders (starting with linear) until the target accuracy is achieved, or a specified maximum order is reached. If the target accuracy cannot be achieved even with this maximum-order polynomial, the best fitting maximum-order polynomial is returned so long as its accuracy is better than " maxacc" . If it is not, a NULL pointer is returned but no error is reported. Synopsis AstPolyMap $*$astPolyTran( AstPolyMap $*$this, int forward, double acc, double maxacc, int maxorder, const double $*$lbnd, const double $*$ubnd ) this Pointer to the original MappingMapping. forward If non-zero, the forward PolyMap transformation is replaced. Otherwise the inverse transformation is replaced. acc The target accuracy, expressed as a geodesic distance within the PolyMap' s input space (if " forward" is zero) or output space (if " forward" is non-zero). maxacc The maximum allowed accuracy for an acceptable polynomial, expressed as a geodesic distance within the PolyMap' s input space (if " forward" is zero) or output space (if " forward" is non-zero). maxorder The maximum allowed polynomial order. This is one more than the maximum power of either input axis. So for instance, a value of 3 refers to a quadratic polynomial. Note, cross terms with total powers greater than or equal to maxorder are not inlcuded in the fit. So the maximum number of terms in each of the fitted polynomials is maxorder$*$(maxorder$+$1)/2. lbnd Pointer to an array holding the lower bounds of a rectangular region within the PolyMap' s input space (if " forward" is zero) or output space (if " forward" is non-zero). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap' s NinNin or NoutNout attribute, depending on " forward" . ubnd Pointer to an array holding the upper bounds of a rectangular region within the PolyMap' s input space (if " forward" is zero) or output space (if " forward" is non-zero). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap' s Nin or Nout attribute, depending on " forward" . PolyMap All PolyMaps have this method. ChebyMapChebyMap The ChebyMap implementation of this method allows NULL pointers to be supplied for " lbnd" and/or " ubnd" , in which case the corresponding bounds supplied when the ChebyMap was created are used. The returned PolyMap will be a ChebyMap, and the new transformation will be defined as a weighted sum of Chebyshev functions of the first kind. astPolyTran() A pointer to the new PolyMap. A NULL pointer will be returned if the fit fails to achieve the accuracy specified by " maxacc" , but no error will be reported. The IterInverseIterInverse attribute is always cleared in the returned PolyMap. This means that the returned PolyMap will always use the new fit by default, rather than the iterative inverse, regardless of the setting of IterInverse in the supplied PolyMap.

This function can only be used on 1D or 2D PolyMaps which have the same number of inputs and outputs.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPolygon Create a Polygon This function creates a new PolygonPolygon object and optionally initialises its attributes.

The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional FrameFrame. The vertices are connected together by geodesic curves within the encapsulated Frame. For instance, if the encapsulated Frame is a simple Frame then the geodesics will be straight lines, but if the Frame is a SkyFrameSkyFrame then the geodesics will be great circles. Note, the vertices must be supplied in an order such that the inside of the polygon is to the left of the boundary as the vertices are traversed. Supplying them in the reverse order will effectively negate the polygon.

Within a SkyFrame, neighbouring vertices are always joined using the shortest path. Thus if an edge of 180 degrees or more in length is required, it should be split into section each of which is less than 180 degrees. The closed path joining all the vertices in order will divide the celestial sphere into two disjoint regions. The inside of the polygon is the region which is circled in an anti-clockwise manner (when viewed from the inside of the celestial sphere) when moving through the list of vertices in the order in which they were supplied when the Polygon was created (i.e. the inside is to the left of the boundary when moving through the vertices in the order supplied). Synopsis AstPolygon $*$astPolygon( AstFrame $*$frame, int npnt, int dim, const double $*$points, AstRegion $*$unc, const char $*$options, ... ) frame A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the RegionRegion. npnt The number of points in the Region. dim The number of elements along the second dimension of the " points" array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than " npnt" . points The address of the first element of a 2-dimensional array of shape " [2][dim]" giving the physical coordinates of the vertices. These should be stored such that the value of coordinate number " coord" for point number " pnt" is found in element " in[coord][pnt]" . unc An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Polygon being created. The uncertainty in any point on the boundary of the Polygon is found by shifting the supplied " uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. BoxBox, CircleCircle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Polygon. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Polygon being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplifyastSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Polygon. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPolygon() A pointer to the new Polygon. A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astPrism Create a Prism This function creates a new PrismPrism and optionally initialises its attributes.

A Prism is a RegionRegion which represents an extrusion of an existing Region into one or more orthogonal dimensions (specified by another Region). If the Region to be extruded has N axes, and the Region defining the extrusion has M axes, then the resulting Prism will have (M$+$N) axes. A point is inside the Prism if the first N axis values correspond to a point inside the Region being extruded, and the remaining M axis values correspond to a point inside the Region defining the extrusion.

As an example, a cylinder can be represented by extruding an existing CircleCircle, using an IntervalInterval to define the extrusion. Ih this case, the Interval would have a single axis and would specify the upper and lower limits of the cylinder along its length. Synopsis AstPrism $*$astPrism( AstRegion $*$region1, AstRegion $*$region2, const char $*$options, ... ) region1 Pointer to the Region to be extruded. region2 Pointer to the Region defining the extent of the extrusion. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Prism. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astPrism() A pointer to the new Prism. Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the Prism.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astPurgeRows Remove all empty rows from a table This function removes all empty rows from the TableTable, renaming the key associated with each table cell accordingly. Synopsis void astPurgeRows( AstTable $*$this ) this Pointer to the Table. astPurgeWCS Delete all cards in the FitsChan describing WCS information This function deletes all cards in a FitsChanFitsChan that relate to any of the recognised WCS encodings. On exit, the current card is the first remaining card in the FitsChan. Synopsis void astPurgeWCS( AstFitsChan $*$this ) this Pointer to the FitsChan. astPutCards Store a set of FITS header cards in a FitsChan This function stores a set of FITS header cards in a FitsChanFitsChan. The cards are supplied concatenated together into a single character string. Any existing cards in the FitsChan are removed before the new cards are added. The FitsChan is " re-wound" on exit by clearing its CardCard attribute. This means that a subsequent invocation of astReadastRead can be made immediately without the need to re-wind the FitsChan first. Synopsis void astPutCards( AstFitsChan $*$this, const char $*$cards ) this Pointer to the FitsChan. cards Pointer to a null-terminated character string containing the FITS cards to be stored. Each individual card should occupy 80 characters in this string, and there should be no delimiters, new lines, etc, between adjacent cards. The final card may be less than 80 characters long. This is the format produced by the fits_hdr2str function in the CFITSIO library. An error will result if the supplied string contains any cards which cannot be interpreted. astPutChannelData Store arbitrary data to be passed to a source or sink function This function stores a supplied arbitrary pointer in the ChannelChannel. When a source or sink function is invoked by the Channel, the invoked function can use the astChannelDataastChannelData macro to retrieve the pointer. This provides a thread-safe alternative to passing file descriptors, etc, via global static variables. Synopsis void astPutChannelData( AstChannel $*$this, void $*$data ) this Pointer to the Channel. data A pointer to be made available to the source and sink functions via the astChannelData macro. May be NULL. Channel All Channels have this function. This routine is not available in the Fortran 77 interface to the AST library. astPutColumnData Store new data values for all rows of a column This function copies data values from a supplied buffer into a named column. The first element in the buffer becomes the first element in the first row of the column. If the buffer does not completely fill the column, then any trailing rows are filled with null values. Synopsis void astPutColumnData( AstFitsTable $*$this, const char $*$column, int clen, size_t size, void $*$coldata ) this Pointer to the FitsTableFitsTable. column The character string holding the name of the column. Trailing spaces are ignored. clen If the column holds character strings, then this must be set to the length of each fixed length string in the supplied array. This is often determined by the appropriate TFORMn keyword in the binary table header. The supplied value is ignored if the column does not hold character data. size The size of the " coldata" array, in bytes. This should be an integer multiple of the number of bytes needed to hold the full vector value stored in a single cell of the column. An error is reported if this is not the case. coldata A pointer to an area of memory holding the data to copy into the column. The values should be stored in row order. If the column holds non-scalar values, the elements of each value should be stored in " Fortran" order. No data type conversion is performed. astPutFits Store a FITS header card in a FitsChan This function stores a FITS header card in a FitsChanFitsChan. The card is either inserted before the current card (identified by the CardCard attribute), or over-writes the current card, as required. Synopsis void astPutFits( AstFitsChan $*$this, const char card[ 80 ], int overwrite ) this Pointer to the FitsChan. card Pointer to a possibly null-terminated character string containing the FITS card to be stored. No more than 80 characters will be used from this string (or fewer if a null occurs earlier). overwrite If this value is zero, the new card is inserted in front of the current card in the FitsChan (as identified by the initial value of the Card attribute). If it is non-zero, the new card replaces the current card. In either case, the Card attribute is then incremented by one so that it subsequently identifies the card following the one stored. If the Card attribute initially points at the " end-of-file" (i.e. exceeds the number of cards in the FitsChan), then the new card is appended as the last card in the FitsChan.

An error will result if the supplied string cannot be interpreted as a FITS header card. astPutTable Store a single FitsTable in a FitsChan This function allows a representation of a single FITS binary table to be stored in a FitsChanFitsChan. For instance, this may provide the coordinate look-up tables needed subequently when reading FITS-WCS headers for axes described using the " -TAB" algorithm. Since, in general, the calling application may not know which tables will be needed - if any - prior to calling astReadastRead, the astTablesSource function provides an alternative mechanism in which a caller-supplied function is invoked to store a named table in the FitsChan. Synopsis void astPutTable( AstFitsChan $*$this, AstFitsTable $*$table, const char $*$extnam ) this Pointer to the FitsChan. table Pointer to a FitsTableFitsTable to be added to the FitsChan. If a FitsTable with the associated extension name already exists in the FitsChan, it is replaced with the new one. A deep copy of the FitsTable is stored in the FitsChan, so any subsequent changes made to the FitsTable will have no effect on the behaviour of the FitsChan. extnam The name of the FITS extension associated with the table. Tables stored in the FitsChan may be retrieved using astGetTablesastGetTables.

The astPutTablesastPutTables method can add multiple FitsTables in a single call. astPutTableHeader Store new FITS headers in a FitsTable This function stores new FITS headers in the supplied FitsTableFitsTable. Any existing headers are first deleted. Synopsis void astPutTableHeader( AstFitsTable $*$this, AstFitsChan $*$header ) this Pointer to the FitsTable. header Pointer to a FitsChanFitsChan holding the headers for the FitsTable. A deep copy of the supplied FitsChan is stored in the FitsTable, replacing the current FitsChan in the Fitstable. Keywords that are fixed either by the properties of the TableTable, or by the FITS standard, are removed from the copy (see " Notes:" below). The attributes of the supplied FitsChan, together with any source and sink functions associated with the FitsChan, are copied to the FitsTable.

Values for the following keywords are generated automatically by the FitsTable (any values for these keywords in the supplied FitsChan will be ignored): " XTENSION" , " BITPIX" , " NAXIS" , " NAXIS1" , " NAXIS2" , " PCOUNT" , " GCOUNT" , " TFIELDS" , " TFORM%d" , " TTYPE%d" , " TNULL%d" , " THEAP" , " TDIM%d" . astPutTables Store one or more FitsTables in a FitsChan This function allows representations of one or more FITS binary tables to be stored in a FitsChanFitsChan. For instance, these may provide the coordinate look-up tables needed subequently when reading FITS-WCS headers for axes described using the " -TAB" algorithm. Since, in general, the calling application may not know which tables will be needed - if any - prior to calling astReadastRead, the astTablesSource function provides an alternative mechanism in which a caller-supplied function is invoked to store a named table in the FitsChan. Synopsis void astPutTables( AstFitsChan $*$this, AstKeyMap $*$tables ) this Pointer to the FitsChan. tables Pointer to a KeyMapKeyMap holding the tables that are to be added to the FitsChan. Each entry should hold a scalar value which is a pointer to a FitsTableFitsTable to be added to the FitsChan. Any unusable entries are ignored. The key associated with each entry should be the name of the FITS binary extension from which the table was read. If a FitsTable with the associated key already exists in the FitsChan, it is replaced with the new one. A deep copy of each usable FitsTable is stored in the FitsChan, so any subsequent changes made to the FitsTables will have no effect on the behaviour of the FitsChan. Tables stored in the FitsChan may be retrieved using astGetTablesastGetTables.

The tables in the supplied KeyMap are added to any tables already in the FitsChan.

The astPutTableastPutTable method provides a simpler means of adding a single table to a FitsChan. astQuadApprox Obtain a quadratic approximation to a 2D Mapping This function returns the co-efficients of a quadratic fit to the supplied MappingMapping over the input area specified by " lbnd" and " ubnd" . The Mapping must have 2 inputs, but may have any number of outputs. The i' th Mapping output is modelled as a quadratic function of the 2 inputs (x,y):

output_i = a_i_0 $+$ a_i_1$*$x $+$ a_i_2$*$y $+$ a_i_3$*$x$*$y $+$ a_i_4$*$x$*$x $+$ a_i_5$*$y$*$y

The " fit" array is returned holding the values of the co-efficients a_0_0, a_0_1, etc. Synopsis int QuadApprox( AstMapping $*$this, const double lbnd[2], const double ubnd[2], int nx, int ny, double $*$fit, double $*$rms ) this Pointer to the Mapping. lbnd Pointer to an array of doubles containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping' s NinNin attribute. This box should specify the region over which the fit is to be performed. ubnd Pointer to an array of doubles containing the upper bounds of the box specifying the region over which the fit is to be performed. nx The number of points to place along the first Mapping input. The first point is at " lbnd[0]" and the last is at " ubnd[0]" . If a value less than three is supplied a value of three will be used. ny The number of points to place along the second Mapping input. The first point is at " lbnd[1]" and the last is at " ubnd[1]" . If a value less than three is supplied a value of three will be used. fit Pointer to an array of doubles in which to return the co-efficients of the quadratic approximation to the specified transformation. This array should have at least " 6$*$NoutNout" , elements. The first 6 elements hold the fit to the first Mapping output. The next 6 elements hold the fit to the second Mapping output, etc. So if the Mapping has 2 inputs and 2 outputs the quadratic approximation to the forward transformation is:

X_out = fit[0] $+$ fit[1]$*$X_in $+$ fit[2]$*$Y_in $+$ fit[3]$*$X_in$*$Y_in $+$ fit[4]$*$X_in$*$X_in $+$ fit[5]$*$Y_in$*$Y_in Y_out = fit[6] $+$ fit[7]$*$X_in $+$ fit[8]$*$Y_in $+$ fit[9]$*$X_in$*$Y_in $+$ fit[10]$*$X_in$*$X_in $+$ fit[11]$*$Y_in$*$Y_in rms Pointer to a double in which to return the RMS residual between the fit and the Mapping, summed over all Mapping outputs. astQuadApprox() If a quadratic approximation was created, a non-zero value is returned. Otherwise zero is returned and the fit co-efficients are set to AST__BAD. This function fits the Mapping' s forward transformation. To fit the inverse transformation, the Mapping should be inverted using astInvertastInvert before invoking this function.

A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason. astRate Calculate the rate of change of a Mapping output This function evaluates the rate of change of a specified output of the supplied MappingMapping with respect to a specified input, at a specified input position.

The result is estimated by interpolating the function using a fourth order polynomial in the neighbourhood of the specified position. The size of the neighbourhood used is chosen to minimise the RMS residual per unit length between the interpolating polynomial and the supplied Mapping function. This method produces good accuracy but can involve evaluating the Mapping 100 or more times. Synopsis double astRate( AstMapping $*$this, double $*$at, int ax1, int ax2 ) this Pointer to the Mapping to be applied. at The address of an array holding the axis values at the position at which the rate of change is to be evaluated. The number of elements in this array should equal the number of inputs to the Mapping. ax1 The index of the Mapping output for which the rate of change is to be found (output numbering starts at 1 for the first output). ax2 The index of the Mapping input which is to be varied in order to find the rate of change (input numbering starts at 1 for the first input). astRate() The rate of change of Mapping output " ax1" with respect to input " ax2" , evaluated at " at" , or AST__BAD if the value cannot be calculated. A value of AST__BAD will be returned if this function is invoked with the global error status set, or if it should fail for any reason. astRateMap Create a RateMap This function creates a new RateMapRateMap and optionally initialises its attributes.

A RateMap is a MappingMapping which represents a single element of the Jacobian matrix of another Mapping. The Mapping for which the Jacobian is required is specified when the new RateMap is created, and is referred to as the " encapsulated Mapping" below.

The number of inputs to a RateMap is the same as the number of inputs to its encapsulated Mapping. The number of outputs from a RateMap is always one. This one output equals the rate of change of a specified output of the encapsulated Mapping with respect to a specified input of the encapsulated Mapping (the input and output to use are specified when the RateMap is created).

A RateMap which has not been inverted does not define an inverse transformation. If a RateMap has been inverted then it will define an inverse transformation but not a forward transformation. Synopsis AstRateMap $*$astRateMap( AstMapping $*$map, int ax1, int ax2, const char $*$options, ... ) map Pointer to the encapsulated Mapping. ax1 Index of the output from the encapsulated Mapping for which the rate of change is required. This corresponds to the delta quantity forming the numerator of the required element of the Jacobian matrix. The first axis has index 1. ax2 Index of the input to the encapsulated Mapping which is to be varied. This corresponds to the delta quantity forming the denominator of the required element of the Jacobian matrix. The first axis has index 1. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new RateMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astRateMap() A pointer to the new RateMap. The forward transformation of the encapsulated Mapping must be defined.

Note that the component Mappings supplied are not copied by astRateMap (the new RateMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a RateMap containing a copy of its component Mappings is required, then a copy of the RateMap should be made using astCopyastCopy.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astRead Read an Object from a Channel This function reads the next ObjectObject from a ChannelChannel and returns a pointer to the new Object. Synopsis AstObject $*$astRead( AstChannel $*$this ) this Pointer to the Channel. FitsChanFitsChan All successful use of astRead on a FitsChan is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the FitsChan astRetainFitsastRetainFits function). An unsuccessful call of astRead (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged. StcsChanStcsChan The AST Object returned by a successful use of astRead on an StcsChan, will be either a RegionRegion or a KeyMapKeyMap, depending on the values of the StcsAreaStcsArea, StcsCoordsStcsCoords and StcsPropsStcsProps attributes. See the documentation for these attributes for further information. astRead() A pointer to the new Object. The class to which this will belong is determined by the input data, so is not known in advance. A null Object pointer (AST__NULL) will be returned, without error, if the Channel contains no further Objects to be read.

A null Object pointer will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astReadFits Read cards into a FitsChan from the source function This function reads cards from the source function that was specified when the FitsChanFitsChan was created, and stores them in the FitsChan. This normally happens once-only, when the FitsChan is accessed for the first time. This function provides a means of forcing a re-read of the external source, and may be useful if (say) new cards have been deposited into the external source. Any newcards read from the source are appended to the end of the current contents of the FitsChan. Synopsis void astReadFits( AstFitsChan $*$this ) this Pointer to the FitsChan. This function returns without action if no source function was specified when the FitsChan was created.

The SourceFileSourceFile attribute is ignored by this function. New cards are read from the source file whenever a new value is assigned to the SourceFile attribute. astRebin$<$X$>$ Rebin a region of a data grid This is a set of functions for rebinning gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a MappingMapping. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Rebinning may be restricted to a specified region of the input grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the rebined output data. Propagation of missing data (bad pixels) is supported.

Note, if you will be rebining a sequence of input arrays and then co-adding them into a single array, the alternative astRebinSeq$<$X$>$astRebinSeq$<$X$>$ functions will in general be more efficient.

You should use a rebinning function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astRebin$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are rebinning data with type " float" , you should use the function astRebinF (see the " Data Type Codes" section below for the codes appropriate to other numerical types).

Rebinning of the grid of input data is performed by transforming the coordinates of the centre of each input grid element (or pixel) into the coordinate system of the output grid. The input pixel value is then divided up and assigned to the output pixels in the neighbourhood of the central output coordinates. A choice of schemes are provided for determining how each input pixel value is divided up between the output pixels. In general, each output pixel may be assigned values from more than one input pixel. All contributions to a given output pixel are summed to produce the final output pixel value. Output pixels can be set to the supplied bad value if they receive contributions from an insufficient number of input pixels. This is controlled by the " wlim" parameter.

Input pixel coordinates are transformed into the coordinate system of the output grid using the forward transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping' s forward transformation as they are transferred from the input to the output grid.

In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel.

This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the input grid which is being used. If this proves to be insufficiently accurate, the input region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). Synopsis void astRebin$<$X$>$( AstMapping $*$this, double wlim, int ndim_in, const int lbnd_in[], const int ubnd_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in_var[], int spread, const double params[], int flags, double tol, int maxpix, $<$Xtype$>$ badval, int ndim_out, const int lbnd_out[], const int ubnd_out[], const int lbnd[], const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out_var[] ); this Pointer to a Mapping, whose forward transformation will be used to transform the coordinates of pixels in the input grid into the coordinate system of the output grid.

The number of input coordinates used by this Mapping (as given by its NinNin attribute) should match the number of input grid dimensions given by the value of " ndim_in" below. Similarly, the number of output coordinates (NoutNout attribute) should match the number of output grid dimensions given by " ndim_out" . wlim Gives the required number of input pixel values which must contribute to an output pixel in order for the output pixel value to be considered valid. If the sum of the input pixel weights contributing to an output pixel is less than the supplied " wlim" value, then the output pixel value is returned set to the supplied bad value. ndim_in The number of dimensions in the input grid. This should be at least one. lbnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. ubnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd_in" and " ubnd_in" together define the shape and size of the input grid, its extent along a particular (j' th) dimension being ubnd_in[j]-lbnd_in[j]$+$1 (assuming the index " j" to be zero-based). They also define the input grid' s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. in Pointer to an array, with one element for each pixel in the input grid, containing the input data to be rebined. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astRebinF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). in_var An optional pointer to a second array with the same size and type as the " in" array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the " in" array. If this array is supplied (together with the corresponding " out_var" array), then estimates of the variance of the rebined output data will be calculated.

If no input variance estimates are being provided, a NULL pointer should be given. spread This parameter specifies the scheme to be used for dividing each input data value up amongst the corresponding output pixels. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the " Pixel Spreading Schemes" section below. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST__LINEAR). params An optional pointer to an array of double which should contain any additional parameter values required by the pixel spreading scheme. If such parameters are required, this will be noted in the " Pixel Spreading Schemes" section below.

If no additional parameters are required, this array is not used and a NULL pointer may be given. flags The bitwise OR of a set of flag values which may be used to provide additional control over the rebinning operation. See the " Control Flags" section below for a description of the options available. If no flag values are to be set, a value of zero should be given. tol The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the output grid' s coordinate system.

If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.

If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used. maxpix A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region.

If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed " maxpix" pixels in any dimension. Only at this point will attempts at approximation commence.

This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal.

If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting " tol" to zero). Although this may degrade performance, accurate results will still be obtained. badval This argument should have the same type as the elements of the " in" array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays.

If the AST__USEBAD flag is set via the " flags" parameter, then this value is used to test for bad pixels in the " in" (and " in_var" ) array(s).

In all cases, this value is also used to flag any output elements in the " out" (and " out_var" ) array(s) for which rebined values could not be obtained (see the " Propagation of Missing Data" section below for details of the circumstances under which this may occur). ndim_out The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. lbnd_out Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. ubnd_out Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension.

Note that " lbnd_out" and " ubnd_out" together define the shape, size and coordinate system of the output grid in the same way as " lbnd_in" and " ubnd_in" define the shape, size and coordinate system of the input grid. lbnd Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. ubnd Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array.

Note that " lbnd" and " ubnd" together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the " lbnd_in" and " ubnd_in" arrays). Regions of the input grid lying outside this region will not be used. out Pointer to an array, with one element for each pixel in the output grid, in which the rebined data values will be returned. The numerical type of this array should match that of the " in" array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). out_var An optional pointer to an array with the same type and size as the " out" array. If given, this array will be used to return variance estimates for the rebined data values. This array will only be used if the " in_var" array has also been supplied.

The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the pixel spreading schemes employed.

If no output variance estimates are required, a NULL pointer should be given. Data Type Codes To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name astRebin$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

I: int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astRebinD would be used to process " double" data, while astRebinI would be used to process " int" data, etc.

Note that, unlike astResample$<$X$>$astResample$<$X$>$, the astRebin$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes. Pixel Spreading Schemes The pixel spreading scheme specifies the Point Spread Function (PSF) applied to each input pixel value as it is copied into the output array. It can be thought of as the inverse of the sub-pixel interpolation schemes used by the astResample$<$X$>$ group of functions. That is, in a sub-pixel interpolation scheme the kernel specifies the weight to assign to each input pixel when forming the weighted mean of the input pixels, whereas the kernel in a pixel spreading scheme specifies the fraction of the input data value which is to be assigned to each output pixel. As for interpolation, the choice of suitable pixel spreading scheme involves stricking a balance between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features but which often tend to introduce unwanted artifacts. See the astResample$<$X$>$ documentation for further discussion.

The binning algorithm used has the ability to introduce artifacts not seen when using a resampling algorithm. Particularly, when viewing the output image at high contrast, systems of curves lines covering the entire image may be visible. These are caused by a beating effect between the input pixel positions and the output pixels position, and their nature and strength depend critically upon the nature of the Mapping and the spreading function being used. In general, the nearest neighbour spreading function demonstrates this effect more clearly than the other functions, and for this reason should be used with caution.

The following values (defined in the " ast.h" header file) may be assigned to the " spread" parameter. See the astResample$<$X$>$ documentation for details of these schemes including the use of the " fspread" and " params" parameters:

AST__NEAREST

AST__LINEAR

AST__SINC

AST__SINCSINC

AST__SINCCOS

AST__SINCGAUSS

AST__SOMBCOS

In addition, the following schemes can be used with astRebin$<$X$>$ but not with astResample$<$X$>$:

AST__GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k a positive constant determined by the full-width at half-maximum (FWHM). The FWHM should be supplied in units of output pixels by means of the " params[1]" value and should be at least 0.1. The " params[0]" value should be used to specify at what point the Gaussian is truncated to zero. This should be given as a number of output pixels on either side of the central output point in each dimension (the nearest integer value is used). Control Flags The following flags are defined in the " ast.h" header file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the bitwise OR of their values via the " flags" parameter:

AST__USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for " badval" and propagated to the output array(s). If this flag is not set, all input values are treated literally and the " badval" value is only used for flagging output array values. Propagation of Missing Data Instances of missing data (bad pixels) in the output grid are identified by occurrences of the " badval" value in the " out" array. These are produced if the sum of the weights of the contributing input pixels is less than " wlim" .

An input pixel is considered bad (and is consequently ignored) if its data value is equal to " badval" and the AST__USEBAD flag is set via the " flags" parameter.

In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the " badval" value in the " out_var" array for similar reasons. Handling of Huge Pixel Arrays If the input or output grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd_in" , " ubnd_in" , " lbnd_out" , " ubnd_out" , " lbnd" , " ubnd" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function return type is similarly changed to type int64_t. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astRebin$<$X$>$ becomes astRebin8$<$X$>$. astRebinSeq$<$X$>$ Rebin a region of a sequence of data grids This set of functions is identical to astRebin$<$X$>$astRebin$<$X$>$ except that the rebinned input data is added into the supplied output arrays, rather than simply over-writing the contents of the output arrays. Thus, by calling this function repeatedly, a sequence of input arrays can be rebinned and accumulated into a single output array, effectively forming a mosaic of the input data arrays.

In addition, the weights associated with each output pixel are returned. The weight of an output pixel indicates the number of input pixels which have been accumulated in that output pixel. If the entire value of an input pixel is assigned to a single output pixel, then the weight of that output pixel is incremented by one. If some fraction of the value of an input pixel is assigned to an output pixel, then the weight of that output pixel is incremented by the fraction used.

The start of a new sequence is indicated by specifying the AST__REBININIT flag via the " flags" parameter. This causes the supplied arrays to be filled with zeros before the rebinned input data is added into them. Subsequenct invocations within the same sequence should omit the AST__REBININIT flag.

The last call in a sequence is indicated by specifying the AST__REBINEND flag. Depending on which flags are supplied, this may cause the output data and variance arrays to be normalised before being returned. This normalisation consists of dividing the data array by the weights array, and can eliminate artifacts which may be introduced into the rebinned data as a consequence of aliasing between the input and output grids. This results in each output pixel value being the weighted mean of the input pixel values that fall in the neighbourhood of the output pixel (rather like astResample$<$X$>$astResample$<$X$>$). Optionally, these normalised values can then be multiplied by a scaling factor to ensure that the total data sum in any small area is unchanged. This scaling factor is equivalent to the number of input pixel values that fall into each output pixel. In addition to normalisation of the output data values, any output variances are also appropriately normalised, and any output data values with weight less than " wlim" are set to " badval" .

Output variances can be generated in two ways; by rebinning the supplied input variances with appropriate weights, or by finding the spread of input data values contributing to each output pixel (see the AST__GENVAR and AST__USEVAR flags). Synopsis void astRebinSeq$<$X$>$( AstMapping $*$this, double wlim, int ndim_in, const int lbnd_in[], const int ubnd_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in_var[], int spread, const double params[], int flags, double tol, int maxpix, $<$Xtype$>$ badval, int ndim_out, const int lbnd_out[], const int ubnd_out[], const int lbnd[], const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out_var[], double weights[], int64_t $*$nused ); this Pointer to a MappingMapping, whose forward transformation will be used to transform the coordinates of pixels in the input grid into the coordinate system of the output grid.

The number of input coordinates used by this Mapping (as given by its NinNin attribute) should match the number of input grid dimensions given by the value of " ndim_in" below. Similarly, the number of output coordinates (NoutNout attribute) should match the number of output grid dimensions given by " ndim_out" . If " in" is NULL, the Mapping will not be used, but a valid Mapping must still be supplied. wlim This value is only used if the AST__REBINEND flag is specified via the " flags" parameter. It gives the required number of input pixel values which must contribute to an output pixel (i.e. the output pixel weight) in order for the output pixel value to be considered valid. If the sum of the input pixel weights contributing to an output pixel is less than the supplied " wlim" value, then the output pixel value is returned set to the supplied bad value. If the supplied value is less than 1.0E-10 then 1.0E-10 is used instead. ndim_in The number of dimensions in the input grid. This should be at least one. Not used if " in" is NULL. lbnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. Not used if " in" is NULL. ubnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd_in" and " ubnd_in" together define the shape and size of the input grid, its extent along a particular (j' th) dimension being ubnd_in[j]-lbnd_in[j]$+$1 (assuming the index " j" to be zero-based). They also define the input grid' s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. Not used if " in" is NULL. in Pointer to an array, with one element for each pixel in the input grid, containing the input data to be rebined. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astRebinSeqF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). If a NULL pointer is supplied for " in" , then no data is added to the output arrays, but any initialisation or normalisation requested by " flags" is still performed. in_var An optional pointer to a second array with the same size and type as the " in" array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the " in" array. If neither the AST__USEVAR nor the AST__VARWGT flag is set, no input variance estimates are required and this pointer will not be used. A NULL pointer may then be supplied. spread This parameter specifies the scheme to be used for dividing each input data value up amongst the corresponding output pixels. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the " Pixel Spreading Schemes" section in the description of the astRebin$<$X$>$ functions. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST__LINEAR). Not used if " in" is NULL. params An optional pointer to an array of double which should contain any additional parameter values required by the pixel spreading scheme. If such parameters are required, this will be noted in the " Pixel Spreading Schemes" section in the description of the astRebin$<$X$>$ functions.

If no additional parameters are required, this array is not used and a NULL pointer may be given. See also flag AST__PARWGT. Not used if " in" is NULL. flags The bitwise OR of a set of flag values which may be used to provide additional control over the rebinning operation. See the " Control Flags" section below for a description of the options available. If no flag values are to be set, a value of zero should be given. tol The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the output grid' s coordinate system.

If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.

If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used. Not used if " in" is NULL. maxpix A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region.

If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed " maxpix" pixels in any dimension. Only at this point will attempts at approximation commence.

This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal.

If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting " tol" to zero). Although this may degrade performance, accurate results will still be obtained. Not used if " in" is NULL. badval This argument should have the same type as the elements of the " in" array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays.

If the AST__USEBAD flag is set via the " flags" parameter, then this value is used to test for bad pixels in the " in" (and " in_var" ) array(s).

In all cases, this value is also used to flag any output elements in the " out" (and " out_var" ) array(s) for which rebined values could not be obtained (see the " Propagation of Missing Data" section below for details of the circumstances under which this may occur). ndim_out The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. lbnd_out Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. ubnd_out Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension.

Note that " lbnd_out" and " ubnd_out" together define the shape, size and coordinate system of the output grid in the same way as " lbnd_in" and " ubnd_in" define the shape, size and coordinate system of the input grid. lbnd Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. Not used if " in" is NULL. ubnd Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array.

Note that " lbnd" and " ubnd" together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the " lbnd_in" and " ubnd_in" arrays). Regions of the input grid lying outside this region will not be used. Not used if " in" is NULL. out Pointer to an array, with one element for each pixel in the output grid. The rebined data values will be added into the original contents of this array. The numerical type of this array should match that of the " in" array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). out_var A pointer to an array with the same type and size as the " out" array. This pointer will only be used if the AST__USEVAR or AST__GENVAR flag is set in which case variance estimates for the rebined data values will be added into the array. If neither the AST__USEVAR flag nor the AST__GENVAR flag is set, no output variance estimates will be calculated and this pointer will not be used. A NULL pointer may then be supplied. weights Pointer to an array of double, with one or two elements for each pixel in the output grid, depending on whether or not the AST__GENVAR flag has been supplied via the " flags" parameter. If AST__GENVAR has not been specified then the array should have one element for each output pixel, and it will be used to accumulate the weight associated with each output pixel. If AST__GENVAR has been specified then the array should have two elements for each output pixel. The first half of the array is again used to accumulate the weight associated with each output pixel, and the second half is used to accumulate the square of the weights. In each half, the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). nused A pointer to an int64_t containing the number of input data values that have been added into the output array so far. The supplied value is incremented on exit by the number of input values used. The value is initially set to zero if the AST__REBININIT flag is set in " flags" . Data Type Codes To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name astRebinSeq$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

I: int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astRebinSeqD would be used to process " double" data, while astRebinSeqI would be used to process " int" data, etc.

Note that, unlike astResample$<$X$>$, the astRebinSeq$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes. Control Flags The following flags are defined in the " ast.h" header file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the bitwise OR of their values via the " flags" parameter:

AST__REBININIT: Used to mark the first call in a sequence. It indicates that the supplied " out" , " out_var" and " weights" arrays should be filled with zeros (thus over-writing any supplied values) before adding the rebinned input data into them. This flag should be used when rebinning the first input array in a sequence.

AST__REBINEND: Used to mark the last call in a sequence. It causes each value in the " out" and " out_var" arrays to be divided by a normalisation factor before being returned. The normalisation factor for each output data value is just the corresponding value from the weights array. The normalisation factor for each output variance value is the square of the data value normalisation factor (see also AST__CONSERVEFLUX). It also causes output data values to be set bad if the corresponding weight is less than the value supplied for parameter " wlim" . It also causes any temporary values stored in the output variance array (see flag AST__GENVAR below) to be converted into usable variance values. Note, this flag is ignored if the AST__NONORM flag is set.

AST__USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for " badval" and propagated to the output array(s). If this flag is not set, all input values are treated literally and the " badval" value is only used for flagging output array values.

AST__USEVAR: Indicates that output variance estimates should be created by rebinning the supplied input variance estimates. An error will be reported if both this flag and the AST__GENVAR flag are supplied.

AST__GENVAR: Indicates that output variance estimates should be created based on the spread of input data values contributing to each output pixel. An error will be reported if both this flag and the AST__USEVAR flag are supplied. If the AST__GENVAR flag is specified, the supplied output variance array is first used as a work array to accumulate the temporary values needed to generate the output variances. When the sequence ends (as indicated by the AST__REBINEND flag), the contents of the output variance array are converted into the required variance estimates. If the generation of such output variances is required, this flag should be used on every invocation of this function within a sequence, and any supplied input variances will have no effect on the output variances (although input variances will still be used to weight the input data if the AST__VARWGT flag is also supplied). The statistical meaning of these output varianes is determined by the presence or absence of the AST__DISVAR flag (see below).

AST__DISVAR: This flag is ignored unless the AST__GENVAR flag has also been specified. It determines the statistical meaning of the generated output variances. If AST__DISVAR is not specified, generated variances represent variances on the output mean values. If AST__DISVAR is specified, the generated variances represent the variance of the distribution from which the input values were taken. Each output variance created with AST__DISVAR will be larger than that created without AST__DISVAR by a factor equal to the number of input samples that contribute to the output sample.

AST__VARWGT: Indicates that the input data should be weighted by the reciprocal of the input variances. Otherwise, all input data are given equal weight. If this flag is specified, the calculation of the output variances (if any) is modified to take account of the varying weights assigned to the input data values. See also AST__PARWGT.

AST__PARWGT: Indicates that a constant weight should be used when pasting each pixel of the supplied input array into the returned arrays. This extra weight value should be inserted at the start of the " params" array (which should consequently be one element longer than specified in the " Pixel Spreading Schemes" section in the description of the astRebin$<$X$>$ functions). If the AST__VARWGT flag is also specified, the total weight for each pixel is the product of the reciprocal of the pixel variance and the value supplied in the last element of the " params" array.

AST__NONORM: If the simple unnormalised sum of all input data falling in each output pixel is required, then this flag should be set on each call in the sequence and the AST__REBINEND should not be used on the last call. In this case NULL pointers can be supplied for " weights" and " nused" . This flag cannot be used with the AST__CONSERVEFLUX, AST__GENVAR, AST__PARWGT or AST__VARWGT flag.

AST__CONSERVEFLUX: Indicates that the normalized output pixel values generated by the AST__REBINEND flag should be scaled in such a way as to preserve the total data value in a feature on the sky. Without this flag, each normalised output pixel value represents a weighted mean of the input data values around the corresponding input position. is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST__CONSERVEFLUX flag could be of use. It causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size.

This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the " tol" parameter is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the " tol" parameter until the difference between adjacent panels is sufficiently small to be insignificant.

This flag should normally be supplied on each invocation of astRebinSeq$<$X$>$ within a given sequence.

Note, this flag cannot be used in conjunction with the AST__NOSCALE flag (an error will be reported if both flags are specified). Propagation of Missing Data Instances of missing data (bad pixels) in the output grid are identified by occurrences of the " badval" value in the " out" array. These are only produced if the AST__REBINEND flag is specified and a pixel has zero weight.

An input pixel is considered bad (and is consequently ignored) if its data value is equal to " badval" and the AST__USEBAD flag is set via the " flags" parameter.

In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the " badval" value in the " out_var" array for similar reasons. Handling of Huge Pixel Arrays If the input or output grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd_in" , " ubnd_in" , " lbnd_out" , " ubnd_out" , " lbnd" , " ubnd" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function return type is similarly changed to type int64_t. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astRebinSeq$<$X$>$ becomes astRebinSeq8$<$X$>$. astRegionOutline Draw the outline of an AST Region This function draws an outline around the supplied AST RegionRegion object. Synopsis void astRegionOutline( AstPlot $*$this, AstRegion $*$region ) this Pointer to the PlotPlot. region Pointer to the Region. astRemapFrame Modify a Frame' s relationship to other Frames in a FrameSet This function modifies the relationship (i.e. MappingMapping) between a specified FrameFrame in a FrameSetFrameSet and the other Frames in that FrameSet.

Typically, this might be required if the FrameSet has been used to calibrate (say) an image, and that image is re-binned. The Frame describing the image will then have undergone a coordinate transformation, and this should be communicated to the associated FrameSet using this function. Synopsis void astRemapFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map ) this Pointer to the FrameSet. iframe The index within the FrameSet of the Frame to be modified. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). map Pointer to a Mapping whose forward transformation converts coordinate values from the original coordinate system described by the Frame to the new one, and whose inverse transformation converts in the opposite direction. A value of AST__BASE or AST__CURRENT may be given for the " iframe" parameter to specify the base Frame or the current Frame respectively.

The relationship between the selected Frame and any other Frame within the FrameSet will be modified by this function, but the relationship between all other Frames in the FrameSet remains unchanged.

The number of input coordinate values accepted by the Mapping (its NinNin attribute) and the number of output coordinate values generated (its NoutNout attribute) must be equal and must match the number of axes in the Frame being modified.

If a simple change of axis order is required, then the astPermAxesastPermAxes function may provide a more straightforward method of making the required changes to the FrameSet.

This function cannot be used to change the number of Frame axes. To achieve this, a new Frame must be added to the FrameSet (astAddFrameastAddFrame) and the original one removed if necessary (astRemoveFrameastRemoveFrame).

Any variant Mappings associated with the remapped Frame (except for the current variant) will be lost as a consequence of calling this method (see attribute " VariantVariant" ). astRemoveColumn Remove a column from a table This function removes a specified column from the supplied table. The function returns without action if the named column does not exist in the TableTable (no error is reported). Synopsis void astRemoveColumn( AstTable $*$this, const char $*$name ) this Pointer to the Table. name The column name. Trailing spaces are ignored (all other spaces are significant). Case is significant. astRemoveFrame Remove a Frame from a FrameSet This function removes a FrameFrame from a FrameSetFrameSet. All other Frames in the FrameSet have their indices re-numbered from one (if necessary), but are otherwise unchanged. Synopsis void astRemoveFrame( AstFrameSet $*$this, int iframe ) this Pointer to the FrameSet. iframe The index within the FrameSet of the Frame to be removed. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). Removing a Frame from a FrameSet does not affect the relationship between other Frames in the FrameSet, even if they originally depended on the Frame being removed.

The number of Frames in a FrameSet cannot be reduced to zero. An error will result if an attempt is made to remove the only remaining Frame.

A value of AST__BASE or AST__CURRENT may be given for the " iframe" parameter to specify the base Frame or the current Frame respectively.

If a FrameSet' s base or current Frame is removed, the BaseBase or CurrentCurrent attribute (respectively) of the FrameSet will have its value cleared, so that another Frame will then assume its role by default.

If any other Frame is removed, the base and current Frames will remain the same. To ensure this, the Base and/or Current attributes of the FrameSet will be changed, if necessary, to reflect any change in the indices of these Frames. astRemoveParameter Remove a global parameter from a table This function removes a specified global parameter from the supplied table. The function returns without action if the named parameter does not exist in the TableTable (no error is reported). Synopsis void astRemoveParameter( AstTable $*$this, const char $*$name ) this Pointer to the Table. name The parameter name. Trailing spaces are ignored (all other spaces are significant). Case is significant. astRemoveRegions Remove any Regions from a Mapping This function searches the suppliedMapping (which may be a compound MappingMapping such as a CmpMapCmpMap) for any component Mappings that are instances of the AST RegionRegion class. It then creates a new Mapping from which all Regions have been removed. If a Region cannot simply be removed (for instance, if it is a component of a parallel CmpMap), then it is replaced with an equivalent UnitMapUnitMap in the returned Mapping. Synopsis AstMapping $*$astRemoveRegions( AstMapping $*$this ) this Pointer to the original Mapping. CmpFrameCmpFrame If the supplied Mapping is a CmpFrame, any component Frames that are instances of the Region class are replaced by the equivalent FrameFrame. FrameSetFrameSet If the supplied Mapping is a FrameSet, the returned Mapping will be a copy of the supplied FrameSet in which Regions have been removed from all the inter-Frame Mappings, and any Frames which are instances of the Region class are replaced by the equivalent Frame. Mapping This function applies to all Mappings. Region If the supplied Mapping is a Region, the returned Mapping will be the equivalent Frame. astRemoveRegions() A new pointer to the (possibly modified) Mapping. This function can safely be applied even to Mappings which contain no Regions. If no Regions are found, it behaves exactly like astCloneastClone and returns a pointer to the original Mapping.

The Mapping returned by this function may not be independent of the original (even if some Regions were removed), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using astCopyastCopy.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astRemoveRow Remove a row from a table This function removes a specified row from the supplied table. The function returns without action if the row does not exist in the TableTable (no error is reported). Synopsis void astRemoveRow( AstTable $*$this, int index ) this Pointer to the Table. index The index of the row to be removed. The first row has index 1. astRemoveTables Remove one or more tables from a FitsChan This function removes the named tables from the FitsChanFitsChan, it they exist (no error is reported if any the tables do not exist). Synopsis void astRemoveTables( AstFitsChan $*$this, const char $*$key ) this Pointer to the FitsChan. key The key indicating which tables to exist. A single key or a comma-separated list of keys can be supplied. If a blank string is supplied, all tables are removed. astResample$<$X$>$ Resample a region of a data grid This is a set of functions for resampling gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a MappingMapping. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Resampling may be restricted to a specified region of the output grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the resampled output data. Propagation of missing data (bad pixels) is supported.

You should use a resampling function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astResample$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are resampling data with type " float" , you should use the function astResampleF (see the " Data Type Codes" section below for the codes appropriate to other numerical types).

Resampling of the grid of input data is performed by transforming the coordinates of the centre of each output grid element (or pixel) into the coordinate system of the input grid. Since the resulting coordinates will not, in general, coincide with the centre of an input pixel, sub-pixel interpolation is performed between the neighbouring input pixels. This produces a resampled value which is then assigned to the output pixel. A choice of sub-pixel interpolation schemes is provided, but you may also implement your own.

This algorithm samples the input data value, it does not integrate it. Thus total data value in the input image will not, in general, be conserved. However, an option is provided (see the " Control Flags" section below) which can produce approximate flux conservation by scaling the output values using the ratio of the output pixel size to the input pixel size. However, if accurate flux conservation is important to you, consder using the astRebin$<$X$>$astRebin$<$X$>$ or astRebinSeq$<$X$>$astRebinSeq$<$X$>$ family of functions instead.

Output pixel coordinates are transformed into the coordinate system of the input grid using the inverse transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping' s forward transformation as they are transferred from the input to the output grid (although the Mapping' s forward transformation is not explicitly used).

In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel.

This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the output grid which is being used. If this proves to be insufficiently accurate, the output region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). Synopsis int astResample$<$X$>$( AstMapping $*$this, int ndim_in, const int lbnd_in[], const int ubnd_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in_var[], int interp, void ($*$ finterp)( void ), const double params[], int flags, double tol, int maxpix, $<$Xtype$>$ badval, int ndim_out, const int lbnd_out[], const int ubnd_out[], const int lbnd[], const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out_var[] ); this Pointer to a Mapping, whose inverse transformation will be used to transform the coordinates of pixels in the output grid into the coordinate system of the input grid. This yields the positions which are used to obtain resampled values by sub-pixel interpolation within the input grid.

The number of input coordinates used by this Mapping (as given by its NinNin attribute) should match the number of input grid dimensions given by the value of " ndim_in" below. Similarly, the number of output coordinates (NoutNout attribute) should match the number of output grid dimensions given by " ndim_out" . ndim_in The number of dimensions in the input grid. This should be at least one. lbnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. ubnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd_in" and " ubnd_in" together define the shape and size of the input grid, its extent along a particular (j' th) dimension being ubnd_in[j]-lbnd_in[j]$+$1 (assuming the index " j" to be zero-based). They also define the input grid' s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. in Pointer to an array, with one element for each pixel in the input grid, containing the input data to be resampled. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astResampleF, the type of each array element should be " float" ).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). in_var An optional pointer to a second array with the same size and type as the " in" array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the " in" array. If this array is supplied (together with the corresponding " out_var" array), then estimates of the variance of the resampled output data will be calculated.

If no input variance estimates are being provided, a NULL pointer should be given. interp This parameter specifies the scheme to be used for sub-pixel interpolation within the input grid. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the " Sub-Pixel Interpolation Schemes" section below. If a value of zero is supplied, then the default linear interpolation scheme is used (equivalent to supplying the value AST__LINEAR).

Alternatively, you may supply a value which indicates that you will provide your own function to perform sub-pixel interpolation by means of the " finterp " parameter. Again, see the " Sub-Pixel Interpolation Schemes" section below for details. finterp If the value given for the " interp" parameter indicates that you will provide your own function for sub-pixel interpolation, then a pointer to that function should be given here. For details of the interface which the function should have (several are possible, depending on the value of " interp" ), see the " Sub-Pixel Interpolation Schemes" section below.

If the " interp" parameter has any other value, corresponding to one of the pre-defined interpolation schemes, then this function will not be used and you may supply a NULL pointer. params An optional pointer to an array of double which should contain any additional parameter values required by the sub-pixel interpolation scheme. If such parameters are required, this will be noted in the " Sub-Pixel Interpolation Schemes" section below (you may also use this array to pass values to your own interpolation function).

If no additional parameters are required, this array is not used and a NULL pointer may be given. flags The bitwise OR of a set of flag values which may be used to provide additional control over the resampling operation. See the " Control Flags" section below for a description of the options available. If no flag values are to be set, a value of zero should be given. tol The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the input grid' s coordinate system.

If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. maxpix A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the output grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire output region.

If a smaller value is used, the output region will first be divided into sub-regions whose size does not exceed " maxpix" pixels in any dimension. Only at this point will attempts at approximation commence.

This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal.

If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting " tol" to zero). Although this may degrade performance, accurate results will still be obtained. badval This argument should have the same type as the elements of the " in" array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays.

If the AST__USEBAD flag is set via the " flags" parameter, then this value is used to test for bad pixels in the " in" (and " in_var" ) array(s).

Unless the AST__NOBAD flag is set via the " flags" parameter, this value is also used to flag any output elements in the " out" (and " out_var" ) array(s) for which resampled values could not be obtained (see the " Propagation of Missing Data" section below for details of the circumstances under which this may occur). The astResample$<$X$>$ function return value indicates whether any such values have been produced. If the AST__NOBAD flag is set. then output array elements for which no resampled value could be obtained are left set to the value they had on entry to this function. ndim_out The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. lbnd_out Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. ubnd_out Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension.

Note that " lbnd_out" and " ubnd_out" together define the shape, size and coordinate system of the output grid in the same way as " lbnd_in" and " ubnd_in" define the shape, size and coordinate system of the input grid. lbnd Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the first pixel in the region of the output grid for which a resampled value is to be calculated. ubnd Pointer to an array of integers, with " ndim_out" elements, containing the coordinates of the last pixel in the region of the output grid for which a resampled value is to be calculated.

Note that " lbnd" and " ubnd" together define the shape and position of a (hyper-)rectangular region of the output grid for which resampled values should be produced. This region should lie wholly within the extent of the output grid (as defined by the " lbnd_out" and " ubnd_out" arrays). Regions of the output grid lying outside this region will not be modified. out Pointer to an array, with one element for each pixel in the output grid, into which the resampled data values will be returned. The numerical type of this array should match that of the " in" array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). out_var An optional pointer to an array with the same type and size as the " out" array. If given, this array will be used to return variance estimates for the resampled data values. This array will only be used if the " in_var" array has also been supplied.

The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the sub-pixel interpolation schemes employed.

If no output variance estimates are required, a NULL pointer should be given. astResample$<$X$>$() The number of output pixels for which no valid resampled value could be obtained. Thus, in the absence of any error, a returned value of zero indicates that all the required output pixels received valid resampled data values (and variances). See the " badval" and " flags" parameters. A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason. Data Type Codes To select the appropriate resampling function, you should replace $<$X$>$ in the generic function name astResample$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: D: double

F: float

L: long int (may be 32 or 64 bit)

K: 64 bit int

UL: unsigned long int (may be 32 or 64 bit)

UK: unsigned 64 bit int

I: int

UI: unsigned int

S: short int

US: unsigned short int

B: byte (signed char)

UB: unsigned byte (unsigned char)

For example, astResampleD would be used to process " double" data, while astResampleS would be used to process " short int" data, etc. Sub-Pixel Interpolation Schemes There is no such thing as a perfect sub-pixel interpolation scheme and, in practice, all resampling will result in some degradation of gridded data. A range of schemes is therefore provided, from which you can choose the one which best suits your needs.

In general, a balance must be struck between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features. The latter will often tend to introduce unwanted oscillations, typically visible as " ringing" around sharp features and edges, especially if the data are under-sampled (i.e. if the sharpest features are less than about two pixels across). In practice, a good interpolation scheme is likely to be a compromise and may exhibit some aspects of both these features.

For under-sampled data, some interpolation schemes may appear to preserve data resolution because they transform single input pixels into single output pixels, rather than spreading their data between several output pixels. While this may look better cosmetically, it can result in a geometrical shift of sharp features in the data. You should beware of this if you plan to use such features (e.g.) for image alignment.

The following are two easy-to-use sub-pixel interpolation schemes which are generally applicable. They are selected by supplying the appropriate value (defined in the " ast.h" header file) via the " interp" parameter. In these cases, the " finterp" and " params" parameters are not used:

AST__NEAREST: This is the simplest possible scheme, in which the value of the input pixel with the nearest centre to the interpolation point is used. This is very quick to execute and will preserve single-pixel features in the data, but may displace them by up to half their width along each dimension. It often gives a good cosmetic result, so is useful for quick-look processing, but is unsuitable if accurate geometrical transformation is required.

AST__LINEAR: This is the default scheme, which uses linear interpolation between the nearest neighbouring pixels in the input grid (there are two neighbours in one dimension, four neighbours in two dimensions, eight in three dimensions, etc.). It is superior to the nearest-pixel scheme (above) in not displacing features in the data, yet it still executes fairly rapidly. It is generally a safe choice if you do not have any particular reason to favour another scheme, since it cannot introduce oscillations. However, it does introduce some spatial smoothing which varies according to the distance of the interpolation point from the neighbouring pixels. This can degrade the shape of sharp features in the data in a position-dependent way. It may also show in the output variance grid (if used) as a pattern of stripes or fringes.

An alternative set of interpolation schemes is based on forming the interpolated value from the weighted sum of a set of surrounding pixel values (not necessarily just the nearest neighbours). This approach has its origins in the theory of digital filtering, in which interpolated values are obtained by conceptually passing the sampled data (represented by a grid of delta functions) through a linear filter which implements a convolution. Because the convolution kernel is continuous, the convolution yields a continuous function which may then be evaluated at fractional pixel positions. The (possibly multi-dimensional) kernel is usually regarded as " separable" and formed from the product of a set of identical 1-dimensional kernel functions, evaluated along each dimension. Different interpolation schemes are then distinguished by the choice of this 1-dimensional interpolation kernel. The number of surrounding pixels which contribute to the result may also be varied.

From a practical standpoint, it is useful to divide the weighted sum of pixel values by the sum of the weights when determining the interpolated value. Strictly, this means that a true convolution is no longer being performed. However, the distinction is rarely important in practice because (for slightly subtle reasons) the sum of weights is always approximately constant for good interpolation kernels. The advantage of this technique, which is used here, is that it can easily accommodate missing data and tends to minimise unwanted oscillations at the edges of the data grid.

In the following schemes, which are based on a 1-dimensional interpolation kernel, the first element of the " params" array should be used to specify how many pixels are to contribute to the interpolated result on either side of the interpolation point in each dimension (the nearest integer value is used). Execution time increases rapidly with this number. Typically, a value of 2 is appropriate and the minimum value used will be 1 (i.e. two pixels altogether, one on either side of the interpolation point). A value of zero or less may be given for " params[0]" to indicate that a suitable number of pixels should be calculated automatically.

In each of these cases, the " finterp" parameter is not used:

AST__GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k a positive constant. The full-width at half-maximum (FWHM) is given by " params[1]" to zero will select the number of contributing pixels so as to utilise the width of the kernel out to where the envelope declines to 1% of its maximum value). This kernel suppresses noise at the expense of smoothing the output array.

AST__SINC: This scheme uses a sinc(pi$*$x) kernel, where x is the pixel offset from the interpolation point and sinc(z)=sin(z)/z. This sometimes features as an " optimal" interpolation kernel in books on image processing. Its supposed optimality depends on the assumption that the data are band-limited (i.e. have no spatial frequencies above a certain value) and are adequately sampled. In practice, astronomical data rarely meet these requirements. In addition, high spatial frequencies are often present due (e.g.) to image defects and cosmic ray events. Consequently, substantial ringing can be experienced with this kernel. The kernel also decays slowly with distance, so that many surrounding pixels are required, leading to poor performance. Abruptly truncating it, by using only a few neighbouring pixels, improves performance and may reduce ringing (if " params[0]" is set to zero, then only two pixels will be used on either side). However, a more gradual truncation, as implemented by other kernels, is generally to be preferred. This kernel is provided mainly so that you can convince yourself not to use it!

AST__SINCSINC: This scheme uses an improved kernel, of the form sinc(pi$*$x).sinc(k$*$pi$*$x), with k a constant, out to the point where sinc(k$*$pi$*$x) goes to zero, and zero beyond. The second sinc() factor provides an " envelope" which gradually rolls off the normal sinc(pi$*$x) kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the " params[1]" value, which should be at least 1.0 (in addition, setting " params[0]" to zero will select the number of contributing pixels so as to utilise the full width of the kernel, out to where it reaches zero). The case given by " params[0]=2, params[1]=2" is typically a good choice and is sometimes known as the Lanczos kernel. This is a valuable general-purpose interpolation scheme, intermediate in its visual effect on images between the AST__NEAREST and AST__LINEAR schemes. Although the kernel is slightly oscillatory, ringing is adequately suppressed if the data are well sampled.

AST__SINCCOS: This scheme uses a kernel of the form sinc(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where cos(k$*$pi$*$x) goes to zero, and zero beyond. As above, the cos() factor provides an envelope which gradually rolls off the sinc() kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the " params[1]" value, which should be at least 1.0 (in addition, setting " params[0]" to zero will select the number of contributing pixels so as to utilise the full width of the kernel, out to where it reaches zero). This scheme gives similar results to the AST__SINCSINC scheme, which it resembles.

AST__SINCGAUSS: This scheme uses a kernel of the form sinc(pi$*$x).exp(-k$*$x$*$x), with k a positive constant. Here, the sinc() kernel is rolled off using a Gaussian envelope which is specified by giving its full-width at half-maximum (FWHM) by means of the " params[1]" value, which should be at least 0.1 (in addition, setting " params[0]" to zero will select the number of contributing pixels so as to utilise the width of the kernel out to where the envelope declines to 1% of its maximum value). On astronomical images and spectra, good results are often obtained by approximately matching the FWHM of the envelope function, given by " params[1]" , to the point spread function of the input data. However, there does not seem to be any theoretical reason for this.

AST__SOMB: This scheme uses a somb(pi$*$x) kernel (a " sombrero" function), where x is the pixel offset from the interpolation point and somb(z)=2$*$J1(z)/z (J1 is a Bessel function of the first kind of order 1). It is similar to the AST__SINC kernel, and has the same parameter usage.

AST__SOMBCOS: This scheme uses a kernel of the form somb(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where cos(k$*$pi$*$x) goes to zero, and zero beyond. It is similar to the AST__SINCCOS kernel, and has the same parameter usage.

In addition, the following schemes are provided which are not based on a 1-dimensional kernel:

AST__BLOCKAVE: This scheme simply takes an average of all the pixels on the input grid in a cube centred on the interpolation point. The number of pixels in the cube is determined by the value of the first element of the " params" array, which gives the number of pixels in each dimension on either side of the central point. Hence a block of (2 $*$ params[0])$\wedge$ndim_in pixels in the input grid will be examined to determine the value of the output pixel. If the variance is not being used (var_in or var_out = NULL) then all valid pixels in this cube will be averaged in to the result with equal weight. If variances are being used, then each input pixel will be weighted proportionally to the reciprocal of its variance; any pixel without a valid variance will be discarded. This scheme is suitable where the output grid is much coarser than the input grid; if the ratio of pixel sizes is R then a suitable value of params[0] may be R/2.

Finally, supplying the following values for " interp" allows you to implement your own sub-pixel interpolation scheme by means of your own function. You should supply a pointer to this function via the " finterp" parameter:

AST__UKERN1: In this scheme, you supply a function to evaluate your own 1-dimensional interpolation kernel, which is then used to perform sub-pixel interpolation (as described above). The function you supply should have the same interface as the fictitious astUkern1astUkern1 function (q.v.). In addition, a value should be given via " params[0]" to specify the number of neighbouring pixels which are to contribute to each interpolated value (in the same way as for the pre-defined interpolation schemes described above). Other elements of the " params" array are available to pass values to your interpolation function.

AST__UINTERP: This is a completely general scheme, in which your interpolation function has access to all of the input data. This allows you to implement any interpolation algorithm you choose, which could (for example) be non-linear, or adaptive. In this case, the astResample$<$X$>$ functions play no role in the sub-pixel interpolation process and simply handle the geometrical transformation of coordinates and other housekeeping. The function you supply should have the same interface as the fictitious astUinterpastUinterp function (q.v.). In this case, the " params" parameter is not used by astResample$<$X$>$, but is available to pass values to your interpolation function. Control Flags The following flags are defined in the " ast.h" header file and may be used to provide additional control over the resampling process. Having selected a set of flags, you should supply the bitwise OR of their values via the " flags" parameter:

AST__NOBAD: Indicates that any output array elements for which no resampled value could be obtained should be left set to the value they had on entry to this function. If this flag is not supplied, such output array elements are set to the value supplied for parameter " badval" . Note, this flag cannot be used in conjunction with the AST__CONSERVEFLUX flag (an error will be reported if both flags are specified).

AST__URESAMP1, 2, 3 & 4: A set of four flags which are reserved for your own use. They may be used to pass private information to any sub-pixel interpolation function which you implement yourself. They are ignored by all the pre-defined interpolation schemes.

AST__USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for " badval" and propagated to the output array(s). If this flag is not set, all input values are treated literally and the " badval" value is only used for flagging output array values.

AST__CONSERVEFLUX: Indicates that the output pixel values should be scaled in such a way as to preserve (approximately) the total data value in a feature on the sky. Without this flag, each output pixel value represents an instantaneous sample of the input data values at the corresponding input position. This is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST__CONSERVEFLUX flag could be used. This causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size.

This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the " tol" parameter is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the " tol" parameter until the difference between adjacent panels is sufficiently small to be insignificant.

Note, this flag cannot be used in conjunction with the AST__NOBAD flag (an error will be reported if both flags are specified). Propagation of Missing Data Unless the AST__NOBAD flag is specified, instances of missing data (bad pixels) in the output grid are identified by occurrences of the " badval" value in the " out" array. These may be produced if any of the following happen:

The input position (the transformed position of the output pixel' s centre) lies outside the boundary of the grid of input pixels.

The input position lies inside the boundary of a bad input pixel. In this context, an input pixel is considered bad if its data value is equal to " badval" and the AST__USEBAD flag is set via the " flags" parameter. (Positions which have half-integral coordinate values, and therefore lie on a pixel boundary, are regarded as lying within the pixel with the larger, i.e. more positive, index.)

The set of neighbouring input pixels (excluding those which are bad) is unsuitable for calculating an interpolated value. Whether this is true may depend on the sub-pixel interpolation scheme in use.

The interpolated value lies outside the range which can be represented using the data type of the " out" array.

In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the " badval" value in the " out_var" array under any of the following circumstances:

The associated resampled data value (in the " out" array) is bad.

The set of neighbouring input pixels which contributed to the output data value do not all have valid variance estimates associated with them. In this context, an input variance estimate may be regarded as bad either because it has the value " badval" (and the AST__USEBAD flag is set), or because it is negative.

The set of neighbouring input pixels for which valid variance values are available is unsuitable for calculating an overall variance value. Whether this is true may depend on the sub-pixel interpolation scheme in use.

The variance value lies outside the range which can be represented using the data type of the " out_var" array.

If the AST__NOBAD flag is specified via parameter " flags" , then output array elements that would otherwise be set to " badval" are instead left holding the value they had on entry to this function. The number of such array elements is returned as the function value. Handling of Huge Pixel Arrays If the input or output grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd_in" , " ubnd_in" , " lbnd_out" , " ubnd_out" , " lbnd" , " ubnd" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function return type is similarly changed to type int64_t. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, astResample$<$X$>$ becomes astResample8$<$X$>$. astResolve Resolve a vector into two orthogonal components This function resolves a vector into two perpendicular components. The vector from point 1 to point 2 is used as the basis vector. The vector from point 1 to point 3 is resolved into components parallel and perpendicular to this basis vector. The lengths of the two components are returned, together with the position of closest aproach of the basis vector to point 3. Synopsis void astResolve( AstFrame $*$this, const double point1[], const double point2[], const double point3[], double point4[], double $*$d1, double $*$d2 ); this Pointer to the FrameFrame. point1 An array of double, with one element for each Frame axis (NaxesNaxes attribute). This marks the start of the basis vector, and of the vector to be resolved. point2 An array of double, with one element for each Frame axis (Naxes attribute). This marks the end of the basis vector. point3 An array of double, with one element for each Frame axis (Naxes attribute). This marks the end of the vector to be resolved. point4 An array of double, with one element for each Frame axis in which the coordinates of the point of closest approach of the basis vector to point 3 will be returned. d1 The address of a location at which to return the distance from point 1 to point 4 (that is, the length of the component parallel to the basis vector). Positive values are in the same sense as movement from point 1 to point 2. d2 The address of a location at which to return the distance from point 4 to point 3 (that is, the length of the component perpendicular to the basis vector). The value is always positive. Each vector used in this function is the path of shortest distance between two points, as defined by the astDistanceastDistance function.

This function will return " bad" coordinate values (AST__BAD) if any of the input coordinates has this value, or if the required output values are undefined. astRetainFits Indicate that the current card in a FitsChan should be retained This function stores a flag with the current card in the FitsChanFitsChan indicating that the card should not be removed from the FitsChan when an ObjectObject is read from the FitsChan using astReadastRead.

Cards that have not been flagged in this way are removed when a read operation completes succesfully, but only if the card was used in the process of creating the returned AST Object. Any cards that are irrelevant to the creation of the AST Object are retained whether or not they are flagged. Synopsis void astRetainFits( AstFitsChan $*$this ) this Pointer to the FitsChan. This function returns without action if the FitsChan is initially positioned at the " end-of-file" (i.e. if the CardCard attribute exceeds the number of cards in the FitsChan).

The current card is not changed by this function. astSame Test if two AST pointers refer to the same Object This function returns a boolean result (0 or 1) to indicate whether two pointers refer to the same ObjectObject. Synopsis int astSame( AstObject $*$this, AstObject $*$that ) this Pointer to the first Object. that Pointer to the second Object. Object This function applies to all Objects. astSame() One if the two pointers refer to the same Object, otherwise zero. Two independent Objects that happen to be identical are not considered to be the same Object by this function.

A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSelectorMap Create a SelectorMap This function creates a new SelectorMapSelectorMap and optionally initialises its attributes.

A SelectorMap is a MappingMapping that identifies which RegionRegion contains a given input position.

A SelectorMap encapsulates a number of Regions that all have the same number of axes and represent the same coordinate FrameFrame. The number of inputs (NinNin attribute) of the SelectorMap equals the number of axes spanned by one of the encapsulated Region. All SelectorMaps have only a single output. SelectorMaps do not define an inverse transformation.

For each input position, the forward transformation of a SelectorMap searches through the encapsulated Regions (in the order supplied when the SelectorMap was created) until a Region is found which contains the input position. The index associated with this Region is returned as the SelectorMap output value (the index value is the position of the Region within the list of Regions supplied when the SelectorMap was created, starting at 1 for the first Region). If an input position is not contained within any Region, a value of zero is returned by the forward transformation.

If a compound Mapping contains a SelectorMap in series with its own inverse, the combination of the two adjacent SelectorMaps will be replaced by a UnitMapUnitMap when the compound Mapping is simplified using astSimplifyastSimplify.

In practice, SelectorMaps are often used in conjunction with SwitchMaps. Synopsis AstSelectorMap $*$astSelectorMap( int nreg, AstRegion $*$regs[], double badval, const char $*$options, ... ) nreg The number of supplied Regions. regs An array of pointers to the Regions. All the supplied Regions must relate to the same coordinate Frame. The number of axes in this coordinate Frame defines the number of inputs for the SelectorMap. badval The value to be returned by the forward transformation of the SelectorMap for any input positions that have a bad (AST__BAD) value on any axis. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SelectorMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSelectorMap() A pointer to the new SelectorMap. Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the SelectorMap.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSet Set attribute values for an Object This function assigns a set of attribute values to an ObjectObject, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form:

" attribute_1 = value_1, attribute_2 = value_2, ... "

where " attribute_n" specifies an attribute name, and the value to the right of each " =" sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute' s data type.

The string supplied may also contain " printf" -style format specifiers, identified by " %" signs in the usual way. If present, these will be substituted by values supplied as additional optional arguments (using the normal " printf" rules) before the string is used. Synopsis void astSet( AstObject $*$this, const char $*$settings, ... ) this Pointer to the Object. settings Pointer to a null-terminated character string containing a comma-separated list of attribute settings in the form described above. ... Optional additional arguments which supply values to be substituted for any " printf" -style format specifiers that appear in the " settings" string. Object This function applies to all Objects. astSet( map, " ReportReport = 1, ZoomZoom = 25.0" ); Sets the Report attribute for Object " map" to the value 1 and the Zoom attribute to 25.0. astSet( frame, " Label( %d ) =Offset along axis %d" , axis, axis ); Sets the Label(axis)Label(axis) attribute for Object " frame" to a suitable string, where the axis number is obtained from " axis" , a variable of type int. astSet( frame, " TitleTitle =%s" , mystring ); Sets the Title attribute for Object " frame" to the contents of the string " mystring" . Attribute names are not case sensitive and may be surrounded by white space.

White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned).

To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. Alternatively, you can use " %s" format and supply the value as a separate additional argument to astSet (or use the astSetC function instead).

The same procedure may be adopted if " %" signs are to be included and are not to be interpreted as format specifiers (alternatively, the " printf" convention of writing " %%" may be used).

An error will result if an attempt is made to set a value for a read-only attribute. astSet$<$X$>$ Set an attribute value for an Object This is a family of functions which set a specified attribute value for an ObjectObject using one of several different data types. The type is selected by replacing $<$X$>$ in the function name by C, D, F, I or L, to supply a value in const char$*$ (i.e. string), double, float, int, or long format, respectively.

If possible, the value you supply is converted to the type of the attribute. If conversion is not possible, an error will result. Synopsis void astSet$<$X$>$( AstObject $*$this, const char $*$attrib, $<$X$>$type value ) this Pointer to the Object. attrib Pointer to a null-terminated character string containing the name of the attribute whose value is to be set. value The value to be set for the attribute, in the data type corresponding to $<$X$>$ (or, in the case of astSetC, a pointer to a null-terminated character string containing this value). Object These functions apply to all Objects. astSetI( frame, " Preserve" , 1 ); Sets the Preserve attribute value for Object " frame" to 1. astSetC( plot, " Format(1)" , " %.2g" ); Sets the Format(1) attribute value for Object " plot" to the character string " %.2g" . Attribute names are not case sensitive and may be surrounded by white space.

An error will result if an attempt is made to set a value for a read-only attribute. astSetActiveUnit Specify how the Unit attribute should be used This function sets the current value of the ActiveUnit flag for a FrameFrame, which controls how the Frame behaves when it is used (by astFindFrameastFindFrame or astConvertastConvert) to match another Frame. If the ActiveUnit flag is set in both template and target Frames then the returned MappingMapping takes into account any differences in axis units. The default value for simple Frames is zero, which preserves the behaviour of versions of AST prior to version 2.0.

If the ActiveUnit flag of either Frame is zero, then the Mapping will ignore any difference in the Unit attributes of corresponding template and target axes. In this mode, the Unit attributes are purely descriptive commentary for the benefit of human readers and do not influence the Mappings between Frames. This is the behaviour which all Frames had in older version of AST, prior to the introduction of this attribute.

If the ActiveUnit flag of both Frames is non-zero, then the Mapping from template to target will take account of any difference in the axis Unit attributes, where-ever possible. For instance, if corresponding target and template axes have Unit strings of " km" and " m" , then the FrameSetFrameSet class will use a ZoomMapZoomMap to connect them which introduces a scaling of 1000. If no Mapping can be found between the corresponding units string, then an error is reported. In this mode, it is assumed that values of the Unit attribute conform to the syntax for units strings described in the FITS WCS Paper I " Representations of world coordinates in FITS" (Greisen & Calabretta). Particularly, any of the named unit symbols, functions, operators or standard multiplier prefixes listed within that paper can be used within a units string. A units string may contain symbols for unit which are not listed in the FITS paper, but transformation to any other units will then not be possible (except to units which depend only on the same unknown units - thus " flops" can be transformed to " Mflops" even though " flops" is not a standard FITS unit symbol).

A range of common non-standard variations of unit names and multiplier prefixes are also allowed, such as adding an " s" to the end of Angstrom, using a lower case " a" at the start of " angstrom" , " micron" instead of " um" , " sec" instead of " s" , etc.

If the ActiveUnit flag is non-zero, setting a new Unit value for an axis may also change its Label and Symbol attributes. For instance, if an axis has Unit " Hz" and Label " frequency" , then changing its Unit to " log(Hz)" will change its Label to " log( frequency )" . In addition, the AxisAxis Format attribute will be cleared when-ever a new value is assigned to the Unit attribute.

Note, if a non-zero value is set for the ActiveUnit flag, then changing a Unit value for the current Frame within a FrameSet will result in the Frame being re-mapped (that is, the Mappings which define the relationships between Frames within the FrameSet will be modified to take into account the change in Units). Synopsis void astSetActiveUnit( AstFrame $*$this, int value ) this Pointer to the Frame. value The new value to use. SkyFrameSkyFrame The ActiveUnit flag for a SkyFrame is always 0 (any value supplied using this function is ignored). SpecFrameSpecFrame The ActiveUnit flag for a SpecFrame is always 1 (any value supplied using this function is ignored). FluxFrameFluxFrame The ActiveUnit flag for a FluxFrame is always 1 (any value supplied using this function is ignored). CmpFrameCmpFrame The default ActiveUnit flag for a CmpFrame is 1 if both of the component Frames are using active units, and zero otherwise. When a new value is set for the ActiveUnit flag, the flag value is propagated to the component Frames. This change will be reflected through all references to the component Frames, not just those encapsulated within the CmpFrame. RegionRegion: Regions always use active units if possible. The ActiveUnit flag resembles a Frame attribute, except that it cannot be tested or cleared, and it cannot be accessed using the generic astGet$<$X$>$astGet$<$X$>$ and astSet$<$X$>$astSet$<$X$>$ functions.

The astGetActiveUnitastGetActiveUnit function can be used to retrieve the current value of the ActiveUnit flag. astSetFits$<$X$>$ Store a keyword value in a FitsChan This is a family of functions which store values for named keywords within a FitsChanFitsChan at the current card position. The supplied keyword value can either over-write an existing keyword value, or can be inserted as a new header card into the FitsChan.

The keyword data type is selected by replacing $<$X$>$ in the function name by one of the following strings representing the recognised FITS data

types:

CF - Complex floating point values.

CI - Complex integer values.

F - Floating point values.

I - Integer values.

L - Logical (i.e. boolean) values.

S - String values.

CN - A " CONTINUE" value, these are treated like string values, but are encoded without an equals sign.

The data type of the " value" parameter depends on $<$X$>$ as follows:

CF - " double $*$" (a pointer to a 2 element array holding the real and imaginary parts of the complex value).

CI - " int $*$" (a pointer to a 2 element array holding the real and imaginary parts of the complex value).

F - " double" .

I - " int" .

L - " int" .

S - " const char $*$" .

CN - " const char $*$" . Synopsis void astSetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type value, const char $*$comment, int overwrite ) this Pointer to the FitsChan. name Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. value The keyword value to store with the named keyword. The data type of this parameter depends on $<$X$>$ as described above. comment A pointer to a null terminated string holding a comment to associated with the keyword. If a NULL pointer or a blank string is supplied, then any comment included in the string supplied for the " name" parameter is used instead. If " name" contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card. overwrite If non-zero, the new card formed from the supplied keyword name, value and comment string over-writes the current card, and the current card is incremented to refer to the next card (see the " CardCard" attribute). If zero, the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the " end-of-file" , the new card is appended to the end of the list. The function astSetFitsUastSetFitsU can be used to indicate that no value is associated with a keyword.

The function astSetFitsCMastSetFitsCM can be used to store a pure comment card (i.e. a card with a blank keyword).

To assign a new value for an existing keyword within a FitsChan, first find the card describing the keyword using astFindFitsastFindFits, and then use one of the astSetFits$<$X$>$ family to over-write the old value.

If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the " end-of-file" .

An error will be reported if the keyword name does not conform to FITS requirements. astSetFitsCM Store a comment card in a FitsChan This function stores a comment card ( i.e. a card with no keyword name or equals sign) within a FitsChanFitsChan at the current card position. The new card can either over-write an existing card, or can be inserted as a new card into the FitsChan. Synopsis void astSetFitsCM( AstFitsChan $*$this, const char $*$comment, int overwrite ) this Pointer to the FitsChan. comment A pointer to a null terminated string holding the text of the comment card. If a NULL pointer or a blank string is supplied, then a totally blank card is produced. overwrite If non-zero, the new card over-writes the current card, and the current card is incremented to refer to the next card (see the " CardCard" attribute). If zero, the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the " end-of-file" , the new card is appended to the end of the list. If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the " end-of-file" . astSetFitsU Store an undefined keyword value in a FitsChan This function stores an undefined value for a named keyword within a FitsChanFitsChan at the current card position. The new undefined value can either over-write an existing keyword value, or can be inserted as a new header card into the FitsChan. Synopsis void astSetFitsU( AstFitsChan $*$this, const char $*$name, const char $*$comment, int overwrite ) this Pointer to the FitsChan. name Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. comment A pointer to a null terminated string holding a comment to associated with the keyword. If a NULL pointer or a blank string is supplied, then any comment included in the string supplied for the " name" parameter is used instead. If " name" contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card. overwrite If non-zero, the new card formed from the supplied keyword name and comment string over-writes the current card, and the current card is incremented to refer to the next card (see the " CardCard" attribute). If zero, the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the " end-of-file" , the new card is appended to the end of the list. If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the " end-of-file" .

An error will be reported if the keyword name does not conform to FITS requirements. astSetPutErr Register an error handling function for use by the AST error model This function can be used to register an external function to be used to deliver an error message and (optionally) an accompanying status value to the user.

If this function is not called prior to the first error occuring within AST, then the external error handling function selected at link-time (using the ast_linkast_link command) will be used. To use an alternative error handler, call this function before using any other AST functions, specifying the external error handling function to be used. This will register the function for future use. Synopsis void astSetPutErr( void ($*$fun)(int,const char$*$) ) fun A Pointer to the function to be used to handle errors. The interface for this function is described below. Once a function has been provided, a NULL pointer can be supplied in a subsequent call to astSetPutErr to reset the function to the corresponding function selected at link-time. Function Interface The supplied external function should deliver the supplied error message and (optionally) the supplied status value to the user or to some underlying error system. It requires the following interface:

void PutErr( int status_value, const char $*$message )

status_value - The error status value.

message - Pointer to a null-terminated character string containing the error message to be delivered. astSetRefPos Set the reference position in a specified celestial coordinate system This function sets the reference position (see attributes RefRARefRA and RefDecRefDec) using axis values (in radians) supplied within the celestial coordinate system represented by a supplied SkyFrameSkyFrame. Synopsis void astSetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double lon, double lat ) this Pointer to the SpecFrameSpecFrame. frm Pointer to the SkyFrame which defines the celestial coordinate system in which the longitude and latitude values are supplied. If NULL is supplied, then the supplied longitude and latitude values are assumed to be FK5 J2000 RA and Dec values. lon The longitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). lat The latitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). astSetStatus Set the AST error status to an explicit value This function sets the AST error status to the value supplied. It does not cause any error message to be produced and should not be used as part of normal error reporting. Its purpose is simply to communicate to AST that an error has occurred in some other item of software.

For example, a source or sink function supplied as an argument to astChannelastChannel or astFitsChanastFitsChan might use this to signal that an input/output error has occurred. AST could then respond by terminating the current read or write operation. Synopsis void astSetStatus( int status_value ) status_value The new error status value to be set. If the AST error status is set to an error value, most AST functions will not execute and will simply return without action. To clear the error status and restore normal behaviour, use astClearStatusastClearStatus. astSetUnc Store uncertainty information in a Region Each RegionRegion (of any class) can have an " uncertainty" which specifies the uncertainties associated with the boundary of the Region. This information is supplied in the form of a second Region. The uncertainty in any point on the boundary of a Region is found by shifting the associated " uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

The uncertainty is usually specified when the Region is created, but this function allows it to be changed at any time. Synopsis void astSetUnc( AstRegion $*$this, AstRegion $*$unc ) this Pointer to the Region which is to be assigned a new uncertainty. unc Pointer to the new uncertainty Region. This must be of a class for which all instances are centro-symetric (e.g. BoxBox, CircleCircle, EllipseEllipse, etc.) or be a PrismPrism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the Region " this" . astShiftMap Create a ShiftMap This function creates a new ShiftMapShiftMap and optionally initialises its attributes.

A ShiftMap is a linear MappingMapping which shifts each axis by a specified constant value. Synopsis AstShiftMap $*$astShiftMap( int ncoord, const double shift[], const char $*$options, ... ) ncoord The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. shift An array containing the values to be added on to the input coordinates in order to create the output coordinates. A separate value should be supplied for each coordinate. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new ShiftMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astShiftMap() A pointer to the new ShiftMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astShow Display a textual representation of an Object on standard output This function displays a textual description of any AST ObjectObject on standard output. It is provided primarily as an aid to debugging. Synopsis void astShow( AstObject $*$this ) this Pointer to the Object to be displayed. Object This function applies to all Objects. astShowFits Display the contents of a FitsChan on standard output This function formats and displays all the cards in a FitsChanFitsChan on standard output. Synopsis void astShowFits( AstFitsChan $*$this ) this Pointer to the FitsChan. astShowMesh Display a mesh of points covering the surface of a Region This function writes a table to standard output containing the axis values at a mesh of points covering the surface of the supplied RegionRegion. Each row of output contains a tab-separated list of axis values, one for each axis in the FrameFrame encapsulated by the Region. The number of points in the mesh is determined by the MeshSizeMeshSize attribute.

The table is preceded by a given title string, and followed by a single line containing the word " ENDMESH" . Synopsis void astShowMesh( AstRegion $*$this, int format, const char $*$ttl ) this Pointer to the Region. format A boolean value indicating if the displayed axis values should be formatted according to the Format attribute associated with the Frame' s axis. Otherwise, they are displayed as simple floating point values. ttl A title to display before displaying the first position. astSimplify Simplify a Mapping This function simplifies a MappingMapping (which may be a compound Mapping such as a CmpMapCmpMap) to eliminate redundant computational steps, or to merge separate steps which can be performed more efficiently in a single operation.

As a simple example, a Mapping which multiplied coordinates by 5, and then multiplied the result by 10, could be simplified to a single step which multiplied by 50. Similarly, a Mapping which multiplied by 5, and then divided by 5, could be reduced to a simple copying operation.

This function should typically be applied to Mappings which have undergone substantial processing or have been formed by merging other Mappings. It is of potential benefit, for example, in reducing execution time if applied before using a Mapping to transform a large number of coordinates. Synopsis AstMapping $*$astSimplify( AstMapping $*$this ) this Pointer to the original Mapping. Mapping This function applies to all Mappings. FrameSetFrameSet If the supplied Mapping is a FrameSet, the returned Mapping will be a copy of the supplied FrameSet in which all the inter-FrameFrame Mappings have been simplified. astSimplify() A new pointer to the (possibly simplified) Mapping. Mappings that have a set value for their IdentIdent attribute are left unchanged after simplification. This is so that their individual identity is preserved. This restriction does not apply to the simplification of Frames.

This function can safely be applied even to Mappings which cannot be simplified. If no simplification is possible, it behaves exactly like astCloneastClone and returns a pointer to the original Mapping.

The Mapping returned by this function may not be independent of the original (even if simplification was possible), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using astCopyastCopy.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSkyFrame Create a SkyFrame This function creates a new SkyFrameSkyFrame and optionally initialises its attributes.

A SkyFrame is a specialised form of FrameFrame which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame' s SystemSystem attribute (currently, the default is ICRS) qualified, as necessary, by a mean EquinoxEquinox value and/or an EpochEpoch.

For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef, SkyRefIsSkyRefIs and SkyRefP

All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using astFormatastFormat. Synopsis AstSkyFrame $*$astSkyFrame( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SkyFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSkyFrame() A pointer to the new SkyFrame. frame = astSkyFrame( " " ); Creates a SkyFrame to describe the default ICRS celestial coordinate system. frame = astSkyFrame( " System = FK5, Equinox = J2005, Digits = 10" ); Creates a SkyFrame to describe the FK5 celestial coordinate system, with a mean Equinox of J2005.0. Because especially accurate coordinates will be used, additional precision (10 digits) has been requested. This will be used when coordinate values are formatted for display. frame = astSkyFrame( " System = FK4, Equinox = 1955-sep-2" ); Creates a SkyFrame to describe the old FK4 celestial coordinate system. A default Epoch value (B1950.0) is used, but the mean Equinox value is given explicitly as " 1955-sep-2" . frame = astSkyFrame( " System = GAPPT, Epoch = %s" , date ); Creates a SkyFrame to describe the Geocentric Apparent celestial coordinate system. The Epoch value, which specifies the date of observation, is obtained from a date/time string supplied via the string pointer " date" . Currently, the default celestial coordinate system 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 behaviour with future versions of this function). If you intend to use the ICRS system indefinitely, then you should specify it explicitly using an " options" value of " System=ICRS" .

Whichever celestial coordinate system is represented, it will have two axes. The first of these will be the longitude axis and the second will be the latitude axis. This order can be changed using astPermAxesastPermAxes if required.

When conversion between two SkyFrames is requested (as when supplying SkyFrames to astConvertastConvert), account will be taken of the nature of the celestial coordinate systems they represent, together with any qualifying mean Equinox or Epoch values, etc. The AlignSystemAlignSystem attribute will also be taken into account. The results will therefore fully reflect the relationship between positions on the sky measured in the two systems.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSkyOffsetMap Returns a Mapping which goes from absolute coordinates to offset coordinates This function returns a MappingMapping in which the forward transformation transforms a position in the coordinate system given by the SystemSystem attribute of the supplied SkyFrameSkyFrame, into the offset coordinate system specified by the SkyRef, SkyRefP and SkyRefIsSkyRefIs attributes of the supplied SkyFrame.

A UnitMapUnitMap is returned if the SkyFrame does not define an offset coordinate system. Synopsis AstMapping $*$astSkyOffsetMap( AstSkyFrame $*$this ) this Pointer to the SkyFrame. astSkyOffsetMap() Pointer to the returned Mapping. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSlaAdd Add a celestial coordinate conversion to an SlaMap This function adds one of the standard celestial coordinate system conversions provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67) to an existing SlaMapSlaMap.

When an SlaMap is first created (using astSlaMapastSlaMap), it simply performs a unit (null) MappingMapping. By using astSlaAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SlaMap will perform in sequence. This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB.

Normally, if an SlaMap' s InvertInvert attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astSlaAdd in the order given (i.e. with the most recently added conversion applied last).

This order is reversed if the SlaMap' s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SlaMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. Synopsis void astSlaAdd( AstSlaMap $*$this, const char $*$cvt, int narg, const double args[] ) this Pointer to the SlaMap. cvt Pointer to a null-terminated string which identifies the celestial coordinate conversion to be added to the SlaMap. See the " SLALIB Conversions" section for details of those available. narg The number of argument values supplied in the " args" array. args An array containing argument values for the celestial coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the " SLALIB Conversions" section). This array is ignored and a NULL pointer may be supplied if no arguments are needed. All coordinate values processed by an SlaMap are in radians. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude.

When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, converting to the standard FK5 coordinate system as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use astSimplifyastSimplify to simplify the resulting SlaMap. The simplification process will eliminate any steps which turn out not to be needed.

This function does not check to ensure that the sequence of coordinate conversions added to an SlaMap is physically meaningful. SLALIB Conversions The following strings (which are case-insensitive) may be supplied via the " cvt" parameter to indicate which celestial coordinate conversion is to be added to the SlaMap. Each string is derived from the name of the SLALIB routine that performs the conversion and the relevant documentation (SUN/67) should be consulted for details. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the " args" array, in the order indicated. The argument names match the corresponding SLALIB routine arguments and their values should be given using exactly the same units, time scale, calendar, etc. as described in SUN/67:

" ADDET" (EQ): Add E-terms of aberration.

" SUBET" (EQ): Subtract E-terms of aberration.

" PREBN" (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4) precession model.

" PREC" (EP0,EP1): Apply IAU 1975 (FK5) precession model.

" FK45Z" (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax).

" FK54Z" (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax).

" AMP" (DATE,EQ): Convert geocentric apparent to mean place.

" MAP" (EQ,DATE): Convert mean place to geocentric apparent.

" ECLEQ" (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial.

" EQECL" (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates.

" GALEQ" : Convert galactic coordinates to FK5 J2000.0 equatorial.

" EQGAL" : Convert FK5 J2000.0 equatorial to galactic coordinates.

" HFK5Z" (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial.

" FK5HZ" (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS.

" GALSUP" : Convert galactic to supergalactic coordinates.

" SUPGAL" : Convert supergalactic coordinates to galactic.

" J2000H" : Convert dynamical J2000.0 to ICRS.

" HJ2000" : Convert ICRS to dynamical J2000.0.

" R2H" (LAST): Convert RA to Hour Angle.

" H2R" (LAST): Convert Hour Angle to RA.

For example, to use the " ADDET" conversion, which takes a single argument EQ, you should consult the documentation for the SLALIB routine SLA_ADDET. This describes the conversion in detail and shows that EQ is the Besselian epoch of the mean equator and equinox. This value should then be supplied to astSlaAdd in args[0].

In addition the following strings may be supplied for more complex conversions which do not correspond to any one single SLALIB routine (DIURAB is the magnitude of the diurnal aberration vector in units of " day/(2.PI)" , DATE is the Modified Julian Date of the observation, and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian coordinates, in metres, of the observer):

" HPCEQ" (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial.

" EQHPC" (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian.

" HPREQ" (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial.

" EQHPR" (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial.

" HEEQ" (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial.

" EQHE" (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic.

" H2E" (LAT,DIRUAB): Convert horizon coordinates to equatorial.

" E2H" (LAT,DIURAB): Convert equatorial coordinates to horizon.

Note, the " H2E" and " E2H" conversions convert between topocentric horizon coordinates (azimuth,elevation), and apparent local equatorial coordinates (hour angle,declination). Thus, the effects of diurnal aberration are taken into account in the conversions but the effects of atmospheric refraction are not. astSlaMap Create an SlaMap This function creates a new SlaMapSlaMap and optionally initialises its attributes.

An SlaMap is a specialised form of MappingMapping which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems.

When an SlaMap is first created, it simply performs a unit (null) Mapping on a pair of coordinates. Using the astSlaAddastSlaAdd function, a series of coordinate conversion steps may then be added, selected from those provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67). This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB.

For details of the individual coordinate conversions available, see the description of the astSlaAdd function. Synopsis AstSlaMap $*$astSlaMap( int flags, const char $*$options, ... ) flags This parameter is reserved for future use and should currently always be set to zero. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SlaMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSlaMap() A pointer to the new SlaMap. The NinNin and NoutNout attributes (number of input and output coordinates) for an SlaMap are both equal to 2. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude. All coordinate values are in radians.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSpecAdd Add a spectral coordinate conversion to a SpecMap This function adds one of the standard spectral coordinate system conversions listed below to an existing SpecMapSpecMap.

When a SpecMap is first created (using astSpecMapastSpecMap), it simply performs a unit (null) MappingMapping. By using astSpecAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SpecMap will perform in sequence. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class.

Normally, if a SpecMap' s InvertInvert attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astSpecAdd in the order given (i.e. with the most recently added conversion applied last).

This order is reversed if the SpecMap' s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SpecMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. Synopsis void astSpecAdd( AstSpecMap $*$this, const char $*$cvt, int narg, const double args[] ) this Pointer to the SpecMap. cvt Pointer to a null-terminated string which identifies the spectral coordinate conversion to be added to the SpecMap. See the " Available Conversions" section for details of those available. narg The number of argument values supplied in the " args" array. args An array containing argument values for the spectral coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the " Available Conversions" section). This array is ignored and a NULL pointer may be supplied if no arguments are needed. When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, when converting between reference frames, converting first to the heliographic reference frame as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use astSimplifyastSimplify to simplify the resulting SpecMap. The simplification process will eliminate any steps which turn out not to be needed.

This function does not check to ensure that the sequence of coordinate conversions added to a SpecMap is physically meaningful. Available Conversions The following strings (which are case-insensitive) may be supplied via the " cvt" parameter to indicate which spectral coordinate conversion is to be added to the SpecMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the " args" array, in the order indicated. Units and argument names are described at the end of the list of conversions.

" FRTOVL" (RF): Convert frequency to relativistic velocity.

" VLTOFR" (RF): Convert relativistic velocity to Frequency.

" ENTOFR" : Convert energy to frequency.

" FRTOEN" : Convert frequency to energy.

" WNTOFR" : Convert wave number to frequency.

" FRTOWN" : Convert frequency to wave number.

" WVTOFR" : Convert wavelength (vacuum) to frequency.

" FRTOWV" : Convert frequency to wavelength (vacuum).

" AWTOFR" : Convert wavelength (air) to frequency.

" FRTOAW" : Convert frequency to wavelength (air).

" VRTOVL" : Convert radio to relativistic velocity.

" VLTOVR" : Convert relativistic to radio velocity.

" VOTOVL" : Convert optical to relativistic velocity.

" VLTOVO" : Convert relativistic to optical velocity.

" ZOTOVL" : Convert redshift to relativistic velocity.

" VLTOZO" : Convert relativistic velocity to redshift.

" BTTOVL" : Convert beta factor to relativistic velocity.

" VLTOBT" : Convert relativistic velocity to beta factor.

" USF2HL" (VOFF,RA,DEC): Convert frequency from a user-defined reference frame to heliocentric.

" HLF2US" (VOFF,RA,DEC): Convert frequency from heliocentric reference frame to user-defined.

" TPF2HL" (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from topocentric reference frame to heliocentric.

" HLF2TP" (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to topocentric.

" GEF2HL" (EPOCH,RA,DEC): Convert frequency from geocentric reference frame to heliocentric.

" HLF2GE" (EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to geocentric.

" BYF2HL" (EPOCH,RA,DEC): Convert frequency from barycentric reference frame to heliocentric.

" HLF2BY" (EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to barycentric.

" LKF2HL" (RA,DEC): Convert frequency from kinematic LSR reference frame to heliocentric.

" HLF2LK" (RA,DEC): Convert frequency from heliocentric reference frame to kinematic LSR.

" LDF2HL" (RA,DEC): Convert frequency from dynamical LSR reference frame to heliocentric.

" HLF2LD" (RA,DEC): Convert frequency from heliocentric reference frame to dynamical LSR.

" LGF2HL" (RA,DEC): Convert frequency from local group reference frame to heliocentric.

" HLF2LG" (RA,DEC): Convert frequency from heliocentric reference frame to local group.

" GLF2HL" (RA,DEC): Convert frequency from galactic reference frame to heliocentric.

" HLF2GL" (RA,DEC): Convert frequency from heliocentric reference frame to galactic.

The units for the values processed by the above conversions are as follows:

all velocities: metres per second (positive if the source receeds from the observer).

frequency: Hertz.

all wavelengths: metres.

energy: Joules.

wave number: cycles per metre.

The arguments used in the above conversions are as follows:

RF: Rest frequency (Hz).

OBSALT: Geodetic altitude of observer (IAU 1975, metres).

OBSLAT: Geodetic latitude of observer (IAU 1975, radians).

OBSLON: Longitude of observer (radians - positive eastwards).

EPOCH: EpochEpoch of observation (UT1 expressed as a Modified Julian Date).

RA: Right Ascension of source (radians, FK5 J2000).

DEC: Declination of source (radians, FK5 J2000).

VOFF: Velocity of the user-defined reference frame, towards the position given by RA and DEC, measured in the heliocentric reference frame.

If the SpecMap is 3-dimensional, source positions are provided by the values supplied to inputs 2 and 3 of the SpecMap (which are simply copied to outputs 2 and 3). Note, usable values are still required for the RA and DEC arguments in order to define the " user-defined" reference frame used by USF2HL and HLF2US. However, AST__BAD can be supplied for RA and DEC if the user-defined reference frame is not required. astSpecFluxFrame Create a SpecFluxFrame This function creates a new SpecFluxFrameSpecFluxFrame and optionally initialises its attributes.

A SpecFluxFrame combines a SpecFrameSpecFrame and a FluxFrameFluxFrame into a single 2-dimensional compound FrameFrame. Such a Frame can for instance be used to describe a PlotPlot of a spectrum in which the first axis represents spectral position and the second axis represents flux. Synopsis AstSpecFluxFrame $*$astSpecFluxFrame( AstSpecFrame $*$frame1, AstFluxFrame $*$frame2, const char $*$options, ... ) frame1 Pointer to the SpecFrame. This will form the first axis in the new SpecFluxFrame. frame2 Pointer to the FluxFrame. This will form the second axis in the new SpecFluxFrame. The " SpecValSpecVal" attribute of this FluxFrame is not used by the SpecFluxFrame class and so may be set to AST__BAD when the FluxFrame is created. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFluxFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSpecFluxFrame() A pointer to the new SpecFluxFrame. The supplied Frame pointers are stored directly, rather than being used to create deep copies of the supplied Frames. This means that any subsequent changes made to the Frames via the supplied pointers will result in equivalent changes being visible in the SpecFluxFrame.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astSpecFrame Create a SpecFrame This function creates a new SpecFrameSpecFrame and optionally initialises its attributes.

A SpecFrame is a specialised form of one-dimensional FrameFrame which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. The particular coordinate system to be used is specified by setting the SpecFrame' s SystemSystem attribute (the default is wavelength) qualified, as necessary, by other attributes such as the rest frequency, the standard of rest, the epoch of observation, etc (see the description of the System attribute for details).

By setting a value for thr SpecOriginSpecOrigin attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute Synopsis AstSpecFrame $*$astSpecFrame( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSpecFrame() A pointer to the new SpecFrame. frame = astSpecFrame( " " ); Creates a SpecFrame to describe the default wavelength spectral coordinate system. The RestFreqRestFreq attribute (rest frequency) is unspecified, so it will not be possible to align this SpecFrame with another SpecFrame on the basis of a velocity-based system. The standard of rest is also unspecified. This means that alignment will be possible with other SpecFrames, but no correction will be made for Doppler shift caused by change of rest frame during the alignment. frame = astSpecFrame( " System=VELO, RestFreq=1.0E15, StdOfRestStdOfRest=LSRK" ); Creates a SpecFrame describing a apparent radial velocity (" VELO" ) axis with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured in the kinematic Local Standard of Rest (" LSRK" ). Since the source position has not been specified (using attributes RefRARefRA and RefDecRefDec), it will only be possible to align this SpecFrame with other SpecFrames which are also measured in the LSRK standard of rest. When conversion between two SpecFrames is requested (as when supplying SpecFrames to astConvertastConvert), account will be taken of the nature of the spectral coordinate systems they represent, together with any qualifying rest frequency, standard of rest, epoch values, etc. The AlignSystemAlignSystem and AlignStdOfRestAlignStdOfRest attributes will also be taken into account. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSpecMap Create a SpecMap This function creates a new SpecMapSpecMap and optionally initialises its attributes.

An SpecMap is a specialised form of MappingMapping which can be used to represent a sequence of conversions between standard spectral coordinate systems. This includes conversions between frequency, wavelength, and various forms of velocity, as well as conversions between different standards of rest.

When a SpecMap is first created, it simply performs a unit (null) Mapping. Using the astSpecAddastSpecAdd function, a series of coordinate conversion steps may then be added, selected from the list of supported conversions. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class.

For details of the individual coordinate conversions available, see the description of the astSpecAdd function.

Conversions are available to transform between standards of rest. Such conversions need to know the source position as an RA and DEC. This information can be supplied in the form of parameters for the relevant conversions, in which case the SpecMap is 1-dimensional, simply transforming the spectral axis values. This means that the same source position will always be used by the SpecMap. However, this may not be appropriate for an accurate description of a 3-D spectral cube, where changes of spatial position can produce significant changes in the Doppler shift introduced when transforming between standards of rest. For this situation, a 3-dimensional SpecMap can be created in which axes 2 and 3 correspond to the source RA and DEC The SpecMap simply copies values for axes 2 and 3 from input to output). Synopsis AstSpecMap $*$astSpecMap( int nin, int flags, const char $*$options, ... ) nin The number of inputs to the Mapping (this will also equal the number of outputs). This value must be either 1 or 3. In either case, the first input and output correspoindis the spectral axis. For a 3-axis SpecMap, the second and third axes give the RA and DEC (J2000 FK5) of the source. This positional information is used by conversions which transform between standards of rest, and replaces the " RA" and " DEC" arguments for the individual conversions listed in description of the " SpecAdd" function. flags This parameter is reserved for future use and should currently always be set to zero. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSpecMap() A pointer to the new SpecMap. The nature and units of the coordinate values supplied for the first input (i.e. the spectral input) of a SpecMap must be appropriate to the first conversion step applied by the SpecMap. For instance, if the first conversion step is " FRTOVL" (frequency to relativistic velocity), then the coordinate values for the first input should be frequency in units of Hz. Similarly, the nature and units of the coordinate values returned by a SpecMap will be determined by the last conversion step applied by the SpecMap. For instance, if the last conversion step is " VLTOVO" (relativistic velocity to optical velocity), then the coordinate values for the first output will be optical velocity in units of metres per second. See the description of the astSpecAdd function for the units expected and returned by each conversion.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astSphMap Create a SphMap This function creates a new SphMapSphMap and optionally initialises its attributes.

A SphMap is a MappingMapping which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). It works by regarding the input coordinates as position vectors and finding their intersection with the sphere surface. The inverse transformation always produces points which are a unit distance from the origin (i.e. unit vectors). Synopsis AstSphMap $*$astSphMap( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SphMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSphMap() A pointer to the new SphMap. The spherical coordinates are longitude (positive anti-clockwise looking from the positive latitude pole) and latitude. The Cartesian coordinates are right-handed, with the x axis (axis 1) at zero longitude and latitude, and the z axis (axis 3) at the positive latitude pole.

At either pole, the longitude is set to the value of the PolarLongPolarLong attribute.

If the Cartesian coordinates are all zero, then the longitude and latitude are set to the value AST__BAD.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astStatus Obtain the current AST error status value This function returns the current value of the AST error status. Synopsis int astStatus astStatus The AST error status value. If the AST error status is set to an error value (after an error), most AST functions will not execute and will simply return without action. To clear the error status and restore normal behaviour, use astClearStatusastClearStatus. astStcCatalogEntryLocation Create a StcCatalogEntryLocation This function creates a new StcCatalogEntryLocationStcCatalogEntryLocation and optionally initialises its attributes.

The StcCatalogEntryLocation class is a sub-class of StcStc used to describe the coverage of the datasets contained in some VO resource.

See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html Synopsis AstStcCatalogEntryLocation $*$astStcCatalogEntryLocation( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) region Pointer to the encapsulated RegionRegion. ncoords The length of the " coords" array. Supply zero if " coords" is NULL. coords Pointer to an array holding " ncoords" AstKeyMap pointers (if " ncoords" is zero, the supplied value is ignored). Each supplied KeyMapKeyMap describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST__STCNAME element should be a vector of character string pointers holding the " Name" item for each axis in the coordinate system represented by " region" . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by " region" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcCatalogEntryLocation. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astStcCatalogEntryLocation() A pointer to the new StcCatalogEntryLocation. A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astStcObsDataLocation Create a StcObsDataLocation This function creates a new StcObsDataLocationStcObsDataLocation and optionally initialises its attributes.

The StcObsDataLocation class is a sub-class of StcStc used to describe the coverage of the datasets contained in some VO resource.

See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html Synopsis AstStcObsDataLocation $*$astStcObsDataLocation( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) region Pointer to the encapsulated RegionRegion. ncoords The length of the " coords" array. Supply zero if " coords" is NULL. coords Pointer to an array holding " ncoords" AstKeyMap pointers (if " ncoords" is zero, the supplied value is ignored). Each supplied KeyMapKeyMap describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST__STCNAME element should be a vector of character string pointers holding the " Name" item for each axis in the coordinate system represented by " region" . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by " region" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcObsDataLocation. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astStcObsDataLocation() A pointer to the new StcObsDataLocation. A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astStcResourceProfile Create a StcResourceProfile This function creates a new StcResourceProfileStcResourceProfile and optionally initialises its attributes.

The StcResourceProfile class is a sub-class of StcStc used to describe the coverage of the datasets contained in some VO resource.

See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html Synopsis AstStcResourceProfile $*$astStcResourceProfile( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) region Pointer to the encapsulated RegionRegion. ncoords The length of the " coords" array. Supply zero if " coords" is NULL. coords Pointer to an array holding " ncoords" AstKeyMap pointers (if " ncoords" is zero, the supplied value is ignored). Each supplied KeyMapKeyMap describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST__STCNAME element should be a vector of character string pointers holding the " Name" item for each axis in the coordinate system represented by " region" . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by " region" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcResourceProfile. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astStcResourceProfile() A pointer to the new StcResourceProfile. A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astStcSearchLocation Create a StcSearchLocation This function creates a new StcSearchLocationStcSearchLocation and optionally initialises its attributes.

The StcSearchLocation class is a sub-class of StcStc used to describe the coverage of a VO query.

See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html Synopsis AstStcResourceProfile $*$astStcSearchLocation( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) region Pointer to the encapsulated RegionRegion. ncoords The length of the " coords" array. Supply zero if " coords" is NULL. coords Pointer to an array holding " ncoords" AstKeyMap pointers (if " ncoords" is zero, the supplied value is ignored). Each supplied KeyMapKeyMap describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST__STCNAME element should be a vector of character string pointers holding the " Name" item for each axis in the coordinate system represented by " region" . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by " region" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcSearchLocation. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astStcSearchLocation() A pointer to the new StcSearchLocation. A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astStcsChan Create an StcsChan This function creates a new StcsChanStcsChan and optionally initialises its attributes.

A StcsChan is a specialised form of ChannelChannel which supports STC-S I/O operations. Writing an ObjectObject to an StcsChan (using astWriteastWrite) will, if the Object is suitable, generate an STC-S description of that Object, and reading from an StcsChan will create a new Object from its STC-S description.

Normally, when you use an StcsChan, you should provide " source" and " sink" functions which connect it to an external data store by reading and writing the resulting text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output.

Alternatively, an XmlChanXmlChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Synopsis AstStcsChan $*$astStcsChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) source Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the StcsChan to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read.

If " source" is NULL and no value has been set for the SourceFile attribute, the StcsChan will read from standard input instead. sink Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the StcsChan to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store.

If " sink" is NULL, and no value has been set for the SinkFile attribute, the StcsChan will write to standard output instead. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcsChan. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astStcsChan() A pointer to the new StcsChan. If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astStripEscapes Remove AST escape sequences from a string This function removes AST escape sequences from a supplied string, returning the resulting text as the function value. The behaviour of this function can be controlled by invoking the astEscapesastEscapes function, which can be used to supress or enable the removal of escape sequences by this function.

AST escape sequences are used by the PlotPlot class to modify the appearance and position of sub-strings within a plotted text string. See the " EscapeEscape" attribute for further information. Synopsis const char $*$astStripEscapes( const char $*$text ) text Pointer to the string to be checked. astStripEscapes() Pointer to the modified string. If no escape sequences were found in the supplied string, then a copy of the supplied pointer is returned. Otherwise, the pointer will point to a static buffer holding the modified text. This text will be over-written by subsequent invocations of this function. If the astEscapes function has been called indicating that escape sequences should not be stripped, then the supplied string is returned without change. astSwitchMap Create a SwitchMap This function creates a new SwitchMapSwitchMap and optionally initialises its attributes.

A SwitchMap is a MappingMapping which represents a set of alternate Mappings, each of which is used to transform positions within a particular region of the input or output coordinate system of the SwitchMap.

A SwitchMap can encapsulate any number of Mappings, but they must all have the same number of inputs (NinNin attribute value) and the same number of outputs (NoutNout attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a " route" through the switch, and are referred to as " route" Mappings below. Each route Mapping transforms positions between the input and output coordinate space of the entire SwitchMap, but only one Mapping will be used to transform any given position. The selection of the appropriate route Mapping to use with any given input position is made by another Mapping, called the " selector" Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap' s forward transformation (called the " forward selector Mapping" ), and one for use with the SwitchMap' s inverse transformation (called the " inverse selector Mapping" ). The forward selector Mapping must have the same number of inputs as the route Mappings, but should have only one output. Likewise, the inverse selector Mapping must have the same number of outputs as the route Mappings, but should have only one input.

When the SwitchMap is used to transform a position in the forward direction (from input to output), each supplied input position is first transformed by the forward transformation of the forward selector Mapping. This produces a single output value for each input position referred to as the selector value. The nearest integer to the selector value is found, and is used to index the array of route Mappings (the first supplied route Mapping has index 1, the second route Mapping has index 2, etc). If the nearest integer to the selector value is less than 1 or greater than the number of route Mappings, then the SwitchMap output position is set to a value of AST__BAD on every axis. Otherwise, the forward transformation of the selected route Mapping is used to transform the supplied input position to produce the SwitchMap output position.

When the SwitchMap is used to transform a position in the inverse direction (from " output" to " input" ), each supplied " output" position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each " output" position. Again, the nearest integer to the selector value is found, and is used to index the array of route Mappings. If this selector index value is within the bounds of the array of route Mappings, then the inverse transformation of the selected route Mapping is used to transform the supplied " output" position to produce the SwitchMap " input" position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap " input" position is set to a value of AST__BAD on every axis.

In practice, appropriate selector Mappings should be chosen to associate a different route Mapping with each region of coordinate space. Note that the SelectorMapSelectorMap class of Mapping is particularly appropriate for this purpose.

If a compound Mapping contains a SwitchMap in series with its own inverse, the combination of the two adjacent SwitchMaps will be replaced by a UnitMapUnitMap when the compound Mapping is simplified using astSimplifyastSimplify. Synopsis AstSwitchMap $*$astSwitchMap( AstMapping $*$fsmap, AstMapping $*$ismap, int nroute, AstMapping $*$routemaps[], const char $*$options, ... ) fsmap Pointer to the forward selector Mapping. This must have a defined forward transformation, but need not have a defined inverse transformation. It must have one output, and the number of inputs must match the number of inputs of each of the supplied route Mappings. NULL may be supplied, in which case the SwitchMap will have an undefined forward Mapping. ismap Pointer to the inverse selector Mapping. This must have a defined inverse transformation, but need not have a defined forward transformation. It must have one input, and the number of outputs must match the number of outputs of each of the supplied route Mappings. NULL may be supplied, in which case the SwitchMap will have an undefined inverse Mapping. nroute The number of supplied route Mappings. routemaps An array of pointers to the route Mappings. All the supplied route Mappings must have common values for the Nin and Nout attributes, and these values define the number of inputs and outputs of the SwitchMap. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SwitchMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astSwitchMap() A pointer to the new SwitchMap. Note that the component Mappings supplied are not copied by astSwitchMap (the new SwitchMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a SwitchMap containing a copy of its component Mappings is required, then a copy of the SwitchMap should be made using astCopyastCopy.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astTable Create a Table This function creates a new empty TableTable and optionally initialises its attributes.

The Table class is a type of KeyMapKeyMap that represents a two-dimensional table of values. The astMapGet... and astMapPut... methods provided by the KeyMap class should be used for storing and retrieving values from individual cells within a Table. Each entry in the KeyMap represents a single cell of the table and has an associated key of the form " $<$COL$>$(i)" where " $<$COL$>$" is the name of a table column and " i" is the row index (the first row is row 1). Keys of this form should always be used when using KeyMap methods to access entries within a Table.

Columns must be declared using the astAddColumnastAddColumn method before values can be stored within them. This also fixes the type and shape of the values that may be stored in any cell of the column. Cells may contain scalar or vector values of any data type supported by the KeyMap class. Multi-dimensional arrays may also be stored, but these must be vectorised when storing and retrieving them within a table cell. All cells within a single column must have the same type and shape (specified when the column is declared).

Tables may have parameters that describe global properties of the entire table. These are stored as entries in the parent KeyMap and can be access using the get and set method of the KeyMap class. However, parameters must be declared using the astAddParameterastAddParameter method before being accessed.

Note - since accessing entries within a KeyMap is a relatively slow process, it is not recommended to use the Table class to store very large tables. Synopsis AstTable $*$astTable( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Table. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astTable() A pointer to the new Table. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astTableSource Register a source function for accessing tables in FITS files This function can be used to register a call-back function with a FitsChanFitsChan. The registered function is called when-ever the FitsChan needs to read information from a binary table contained within a FITS file. This occurs if the astReadastRead function is invoked to read a FrameSetFrameSet from a set of FITS headers that use the " -TAB" algorithm to describe one or more axes. Such axes use a FITS binary table to store a look-up table of axis values. The FitsChan will fail to read such axes unless the " TabOKTabOK" attribute is set to a non-zero positive integer value. The table containing the axis values must be made available to the FitsChan either by storing the table contents in the FitsChan (using astPutTablesastPutTables or astPutTableastPutTable) prior to invoking astRead or by registering a call-back function using astTableSource. The first method is possibly simpler, but requires that the name of the extension containing the table be known in advance. Since the table name is embedded in the FITS headers, the name is often not known in advance. If a call-back is registered, the FitsChan will determine the name of the required table and invoke the call-back function to supply the table at the point where it is needed (i.e. within the astRead method). Synopsis void astTableSource( AstFitsChan $*$this, void ($*$ tabsource)( AstFitsChan $*$, const char $*$, int, int, int $*$ ) ) this Pointer to the FitsChan. tabsource Pointer to the table source function to use. It takes five arguments - the first is a pointer to the FitsChan, the second is a string holding the name of the FITS extension containing the required binary table (" EXTNAME" ), the third is the integer FITS " EXTVER" header value for the required extension, the fourth is the integer FITS " EXTLEVEL" header value for the required extension, and the fifth is a pointer to an integer status value.

The call-back should read the entire contents (header and data) of the binary table in the named extension of the external FITS file, storing the contents in a newly created FitsTableFitsTable object. It should then store this FitsTable in the FitsChan using the astPutTables or astPutTable method, and finally annull its local copy of the FitsTable pointer. If the table cannot be read for any reason, or if any other error occurs, it should return zero for the final (third) argument (otherwise any non-zero integer should be returned).

If " tabsource" is NULL, any registered call-back function will be removed. Application code can pass arbitrary data (such as file descriptors, etc) to the table source function using the astPutChannelDataastPutChannelData function. The source function should use the astChannelDataastChannelData macro to retrieve this data. astTest Test if an Object attribute value is set This function returns a boolean result (0 or 1) to indicate whether a value has been explicitly set for one of an ObjectObject' s attributes. Synopsis int astTest( AstObject $*$this, const char $*$attrib ) this Pointer to the Object. attrib Pointer to a null-terminated character string containing the name of the attribute to be tested. Object This function applies to all Objects. astTest() One if a value has previously been explicitly set for the attribute (and hasn' t been cleared), otherwise zero. Attribute names are not case sensitive and may be surrounded by white space.

A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

A value of zero will also be returned if this function is used to test a read-only attribute, although no error will result. astTestCell Tests if a single HEALPix cell is included in a Moc This function returns a non-zero value if the MocMoc includes the specified cell. Synopsis void astTestCell( AstMoc $*$this, int order, int64_t npix, int parent ) this Pointer to the Moc to be modified. order The HEALPix order of the cell to test. Zero is returned if this is higher than the maximum order allowed in the Moc (as given by its MaxOrderMaxOrder attribute). npix The " npix" value identifying the cell to test (see the MOC recommendation for more details). parent Indicates the value to return if the tested cell is not included at the specified order, but a parent cell (at a lower order) is included. astTestCell() One if the specified cell is included in the Moc at the specified order, of (if " parent" is non-zero) a parent cell is included in the Moc. Zero otherwise. astTestFits See if a named keyword has a defined value in a FitsChan This function serches for a named keyword in a FitsChanFitsChan. If found, and if the keyword has a value associated with it, a non-zero value is returned. If the keyword is not found, or if it does not have an associated value, a zero value is returned. Synopsis int astTestFits( AstFitsChan $*$this, const char $*$name, int $*$there ) this Pointer to the FitsChan. name Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. If NULL is supplied, the current card is tested. there Pointer to an integer which will be returned holding a non-zero value if the keyword was found in the header, and zero otherwise. This parameter allows a distinction to be made between the case where a keyword is not present, and the case where a keyword is present but has no associated value. A NULL pointer may be supplied if this information is not required. astTestFits() A value of zero is returned if the keyword was not found in the FitsChan or has no associated value. Otherwise, a value of one is returned. The current card is left unchanged by this function.

The card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards.

An error will be reported if the keyword name does not conform to FITS requirements.

Zero is returned as the function value if an error has already occurred, or if this function should fail for any reason. astText Draw a text string for a Plot This function draws a string of text at a position specified in the physical coordinate system of a PlotPlot. The physical position is transformed into graphical coordinates to determine where the text should appear within the plotting area. Synopsis void astText( AstPlot $*$this, const char $*$text, const double pos[], const float up[], const char $*$just ) this Pointer to the Plot. text Pointer to a null-terminated character string containing the text to be drawn. Trailing white space is ignored. pos An array, with one element for each axis of the Plot, giving the physical coordinates of the point where the reference position of the text string is to be placed. up An array holding the components of a vector in the " up" direction of the text (in graphical coordinates). For example, to get horizontal text, the vector {0.0f,1.0f} should be supplied. For a basic Plot, 2 values should be supplied. For a Plot3DPlot3D, 3 values should be supplied, and the actual up vector used is the projection of the supplied up vector onto the text plane specified by the current value of the Plot3D' s Norm attribute. just Pointer to a null-terminated character string identifying the reference point for the text being drawn. The first character in this string identifies the reference position in the " up" direction and may be " B" (baseline), " C" (centre), " T" (top) or " M" (bottom). The second character identifies the side-to-side reference position and may be " L" (left), " C" (centre) or " R" (right ). The string is case-insensitive, and only the first two characters are significant.

For example, a value of " BL" means that the left end of the baseline of the original (un-rotated) text is to be drawn at the position given by " pos" . The Plot3D class currently does not interpret graphical escape sequences contained within text displayed using this method.

Text is not drawn at positions which have any coordinate equal to the value AST__BAD (or where the transformation into graphical coordinates yields coordinates containing the value AST__BAD).

If the plotting position is clipped (see astClipastClip), then no text is drawn.

An error results if the base FrameFrame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.

An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot' s TranInverseTranInverse attribute is zero). astThread Determine the thread that owns an Object Returns an integer that indicates whether the supplied ObjectObject (or Object pointer) is currently unlocked, or is currently locked by the running thread, or another thread. Synopsis int astThread( AstObject $*$this, int ptr ) this Pointer to the Object to be checked. ptr If non-zero, returns information about the supplied Object pointer, rather than the Object structure itself. See " Object Pointers and Structures" below. astThread() A value of AST__UNLOCKED is returned if the Object (or pointer) is currently unlocked (i.e. has been unlocked using astUnlockastUnlock but has not yet been locked using astLockastLock). A value of AST__RUNNING is returned if the Object (or pointer) is currently locked by the running thread. A value of AST__OTHER is returned if the Object (or pointer) is currently locked by the another thread. This function attempts to execute even if the global error status is set, but no further error report will be made if it subsequently fails under these circumstances.

This function is only available in the C interface.

This function always returns AST__RUNNING if the AST library has been built without POSIX thread support (i.e. the " -with-pthreads" option was not specified when running the " configure" script). Object Pointers and Structures At any one time, an AST Object can have several distinct pointers, any one of which can be used to access the Object structure. For instance, the astCloneastClone function will produce a new distinct pointer for a given Object. In fact, an AST " pointer" is not a real pointer at all - it is an identifier for a " handle" structure, encoded to make it look like a pointer. Each handle contains (amongst othere things) a " real" pointer to the Object structure. This allows more than one handle to refer to the same Object structure. So when you call astClone (for instance) you get back an identifier for a new handle that refers to the same Object as the supplied handle.

In order to use an Object for anything useful, it must be locked for use by the running thread (either implicitly at creation or explicitly using astLock). The identity of the thread is stored in both the Object structure, and in the handle that was passed to astLock (or returned by the constructor function). Thus it is possible for a thread to have active pointers for Objects that are currently locked by another thread. In general, if such a pointer is passed to an AST function an error will be reported indicating that the Object is currently locked by another thread. The two exceptions to this is that astAnnulastAnnul can be used to annull such a pointer, and this function can be used to return information about the pointer.

The other practical consequence of this is that when astEndastEnd is called, all active pointers currently owned by the running thread (at the current context level) are annulled. This includes pointers for Objects that are currently locked by other threads.

If the " ptr" parameter is zero, then the returned value describes the Object structure itself. If " ptr" is non-zero, then the returned value describes the supplied Object pointer (i.e. handle), rather than the Object structure. astTimeAdd Add a time coordinate conversion to a TimeMap This function adds one of the standard time coordinate system conversions listed below to an existing TimeMapTimeMap.

When a TimeMap is first created (using astTimeMapastTimeMap), it simply performs a unit (null) MappingMapping. By using astTimeAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the TimeMap will perform in sequence. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of the building blocks provided by this class.

Normally, if a TimeMap' s InvertInvert attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astTimeAdd in the order given (i.e. with the most recently added conversion applied last).

This order is reversed if the TimeMap' s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the TimeMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. Synopsis void astTimeAdd( AstTimeMap $*$this, const char $*$cvt, int narg, const double args[] ) this Pointer to the TimeMap. cvt Pointer to a null-terminated string which identifies the time coordinate conversion to be added to the TimeMap. See the " Available Conversions" section for details of those available. narg The number of argument values supplied in the " args" array. args An array containing argument values for the time coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the " Available Conversions" section). This array is ignored and a NULL pointer may be supplied if no arguments are needed. When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. A solution to this is to include all the steps which are (logically) necessary, but then to use astSimplifyastSimplify to simplify the resulting TimeMap. The simplification process will eliminate any steps which turn out not to be needed.

This function does not check to ensure that the sequence of coordinate conversions added to a TimeMap is physically meaningful. Available Conversions The following strings (which are case-insensitive) may be supplied via the " cvt" parameter to indicate which time coordinate conversion is to be added to the TimeMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the " args" array, in the order indicated. Units and argument names are described at the end of the list of conversions, and " MJD" means Modified Julian Date.

" MJDTOMJD" (MJDOFF1,MJDOFF2): Convert MJD from one offset to another.

" MJDTOJD" (MJDOFF,JDOFF): Convert MJD to Julian Date.

" JDTOMJD" (JDOFF,MJDOFF): Convert Julian Date to MJD.

" MJDTOBEP" (MJDOFF,BEPOFF): Convert MJD to Besselian epoch.

" BEPTOMJD" (BEPOFF,MJDOFF): Convert Besselian epoch to MJD.

" MJDTOJEP" (MJDOFF,JEPOFF): Convert MJD to Julian epoch.

" JEPTOMJD" (JEPOFF,MJDOFF): Convert Julian epoch to MJD.

" TAITOUTC" (MJDOFF,DTAI): Convert a TAI MJD to a UTC MJD.

" UTCTOTAI" (MJDOFF,DTAI): Convert a UTC MJD to a TAI MJD.

" TAITOTT" (MJDOFF): Convert a TAI MJD to a TT MJD.

" TTTOTAI" (MJDOFF): Convert a TT MJD to a TAI MJD.

" TTTOTDB" (MJDOFF,OBSLON,OBSLAT,OBSALT,DTAI): Convert a TT MJD to a TDB MJD.

" TDBTOTT" (MJDOFF,OBSLON,OBSLAT,OBSALT,DTAI): Convert a TDB MJD to a TT MJD.

" TTTOTCG" (MJDOFF): Convert a TT MJD to a TCG MJD.

" TCGTOTT" (MJDOFF): Convert a TCG MJD to a TT MJD.

" TDBTOTCB" (MJDOFF): Convert a TDB MJD to a TCB MJD.

" TCBTOTDB" (MJDOFF): Convert a TCB MJD to a TDB MJD.

" UTTOGMST" (MJDOFF): Convert a UT MJD to a GMST MJD.

" GMSTTOUT" (MJDOFF): Convert a GMST MJD to a UT MJD.

" GMSTTOLMST" (MJDOFF,OBSLON,OBSLAT): Convert a GMST MJD to a LMST MJD.

" LMSTTOGMST" (MJDOFF,OBSLON,OBSLAT): Convert a LMST MJD to a GMST MJD.

" LASTTOLMST" (MJDOFF,OBSLON,OBSLAT): Convert a GMST MJD to a LMST MJD.

" LMSTTOLAST" (MJDOFF,OBSLON,OBSLAT): Convert a LMST MJD to a GMST MJD.

" UTTOUTC" (DUT1): Convert a UT1 MJD to a UTC MJD.

" UTCTOUT" (DUT1): Convert a UTC MJD to a UT1 MJD.

" LTTOUTC" (LTOFF): Convert a Local Time MJD to a UTC MJD.

" UTCTOLT" (LTOFF): Convert a UTC MJD to a Local Time MJD.

The units for the values processed by the above conversions are as follows:

Julian epochs and offsets: Julian years

Besselian epochs and offsets: Tropical years

Modified Julian Dates and offsets: days

Julian Dates and offsets: days

The arguments used in the above conversions are the zero-points used by the astTransform function. The axis values supplied and returned by astTransform are offsets away from these zero-points:

MJDOFF: The zero-point being used with MJD values.

JDOFF: The zero-point being used with Julian Date values.

BEPOFF: The zero-point being used with Besselian epoch values.

JEPOFF: The zero-point being used with Julian epoch values.

OBSLON: Observer longitude in radians ($+$ve westwards).

OBSLAT: Observer geodetic latitude (IAU 1975) in radians ($+$ve northwards).

OBSALT: Observer geodetic altitude (IAU 1975) in metres.

DTAI: The value of TAI-UTC (the value returned by astDat is used if DTAI is AST__BAD).

DUT1: The UT1-UTC value to use.

LTOFF: The offset between Local Time and UTC (in hours, positive for time zones east of Greenwich). astTimeFrame Create a TimeFrame This function creates a new TimeFrameTimeFrame and optionally initialises its attributes.

A TimeFrame is a specialised form of one-dimensional FrameFrame which represents various coordinate systems used to describe positions in time.

A TimeFrame represents a moment in time as either an Modified Julian Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, as determined by the SystemSystem attribute. Optionally, a zero point can be specified (using attribute TimeOriginTimeOrigin) which results in the TimeFrame representing time offsets from the specified zero point.

Even though JD and MJD are defined as being in units of days, the TimeFrame class allows other units to be used (via the Unit attribute) on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs can be described in units other than the usual years. Besselian epoch are always represented in units of (tropical) years.

The TimeScaleTimeScale attribute allows the time scale to be specified (that is, the physical proces used to define the rate of flow of time). MJD, JD and Julian epoch can be used to represent a time in any supported time scale. However, Besselian epoch may only be used with the " TT" (Terrestrial Time) time scale. The list of supported time scales includes universal time and siderial time. Strictly, these represent angles rather than time scales, but are included in the list since they are in common use and are often thought of as time scales.

When a time value is formatted it can be formated either as a simple floating point value, or as a Gregorian date (see the Format attribute). Synopsis AstTimeFrame $*$astTimeFrame( const char $*$options, ... ) options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new TimeFrame. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astTimeFrame() A pointer to the new TimeFrame. When conversion between two TimeFrames is requested (as when supplying TimeFrames to astConvertastConvert), account will be taken of the nature of the time coordinate systems they represent, together with any qualifying time scale, offset, unit, etc. The AlignSystemAlignSystem and AlignTimeScaleAlignTimeScale attributes will also be taken into account.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astTimeMap Create a TimeMap This function creates a new TimeMapTimeMap and optionally initialises its attributes.

A TimeMap is a specialised form of 1-dimensional MappingMapping which can be used to represent a sequence of conversions between standard time coordinate systems.

When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the astTimeAddastTimeAdd function, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks.

For details of the individual coordinate conversions available, see the description of the astTimeAdd function. Synopsis AstTimeMap $*$astTimeMap( int flags, const char $*$options, ... ) flags This parameter is reserved for future use and should currently always be set to zero. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new TimeMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astTimeMap() A pointer to the new TimeMap. The nature and units of the coordinate values supplied for the first input (i.e. the time input) of a TimeMap must be appropriate to the first conversion step applied by the TimeMap. For instance, if the first conversion step is " MJDTOBEP" (Modified Julian Date to Besselian epoch) then the coordinate values for the first input should be date in units of days. Similarly, the nature and units of the coordinate values returned by a TimeMap will be determined by the last conversion step applied by the TimeMap.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astToString Create an in-memory serialisation of an Object This function returns a string holding a minimal textual serialisation of the supplied AST ObjectObject. The Object can re re-created from the serialisation using astFromStringastFromString. Synopsis char $*$astToString( AstObject $*$this ) this Pointer to the Object to be serialised. astToString() Pointer to dynamically allocated memory holding the serialisation, or NULL if an error occurs. The pointer should be freed when no longer needed using astFreeastFree. astTran1 Transform 1-dimensional coordinates This function applies a MappingMapping to transform the coordinates of a set of points in one dimension. Synopsis void astTran1( AstMapping $*$this, int npoint, const double xin[], int forward, double xout[] ) this Pointer to the Mapping to be applied. npoint The number of points to be transformed. xin An array of " npoint" coordinate values for the input (untransformed) points. forward A non-zero value indicates that the Mapping' s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. xout An array (with " npoint" elements) into which the coordinates of the output (transformed) points will be written. The Mapping supplied must have the value 1 for both its NinNin and NoutNout attributes. Handling of Huge Pixel Arrays If the number of points to be transformed exceeds the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte). Specifically, the argument " npoint" , is changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astTran1 becomes astTran18 astTran2 Transform 2-dimensional coordinates This function applies a MappingMapping to transform the coordinates of a set of points in two dimensions. Synopsis void astTran2( AstMapping $*$this, int npoint, const double xin[], const double yin[], int forward, double xout[], double yout[] ) this Pointer to the Mapping to be applied. npoint The number of points to be transformed. xin An array of " npoint" X-coordinate values for the input (untransformed) points. yin An array of " npoint" Y-coordinate values for the input (untransformed) points. forward A non-zero value indicates that the Mapping' s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. xout An array (with " npoint" elements) into which the X-coordinates of the output (transformed) points will be written. yout An array (with " npoint" elements) into which the Y-coordinates of the output (transformed) points will be written. The Mapping supplied must have the value 2 for both its NinNin and NoutNout attributes. Handling of Huge Pixel Arrays If the number of points to be transformed exceeds the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte). Specifically, the argument " npoint" , is changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astTran2 becomes astTran28 astTranGrid Transform a grid of positions This function uses the supplied MappingMapping to transforms a regular square grid of points covering a specified box. It attempts to do this quickly by first approximating the Mapping with a linear transformation applied over the whole region of the input grid which is being used. If this proves to be insufficiently accurate, the input region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). Synopsis void astTranGrid( AstMapping $*$this, int ncoord_in, const int lbnd[], const int ubnd[], double tol, int maxpix, int forward, int ncoord_out, int outdim, double $*$out ); this Pointer to the Mapping to be applied. ncoord_in The number of coordinates being supplied for each box corner (i.e. the number of dimensions of the space in which the input points reside). lbnd Pointer to an array of integers, with " ncoord_in" elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. ubnd Pointer to an array of integers, with " ncoord_in" elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd" and " ubnd" together define the shape and size of the input grid, its extent along a particular (j' th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the index " j" to be zero-based). They also define the input grid' s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. tol The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement within the output coordinate system of the Mapping.

If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.

If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher. If this is a problem, reduce the tolerance value used. maxpix A value which specifies an initial scale size (in input grid points) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region.

If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed " maxpix" grid points in any dimension. Only at this point will attempts at approximation commence.

This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 grid points can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal.

If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting " tol" to zero). Although this may degrade performance, accurate results will still be obtained. forward A non-zero value indicates that the Mapping' s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. ncoord_out The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as " ncoord_in" . outdim The number of elements along the second dimension of the " out" array (which will contain the output coordinates). The value given should not be less than the number of points in the grid. out The address of the first element in a 2-dimensional array of shape " [ncoord_out][outdim]" , into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number " coord" for output point number " point" will be found in element " out[coord][point]" . The points are ordered such that the first axis of the input grid changes most rapidly. For example, if the input grid is 2-dimensional and extends from (2,-1) to (3,1), the output points will be stored in the order (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1). If the forward coordinate transformation is being applied, the Mapping supplied must have the value of " ncoord_in" for its NinNin attribute and the value of " ncoord_out" for its NoutNout attribute. If the inverse transformation is being applied, these values should be reversed. Handling of Huge Pixel Arrays If the output grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments " lbnd" , " ubnd" , " outdim" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astTranGrid becomes astTranGrid8. astTranMap Create a TranMap This function creates a new TranMapTranMap and optionally initialises its attributes.

A TranMap is a MappingMapping which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist).

When the forward transformation of the TranMap is referred to, the transformation actually used is the forward transformation of the first Mapping supplied when the TranMap was constructed. Likewise, when the inverse transformation of the TranMap is referred to, the transformation actually used is the inverse transformation of the second Mapping supplied when the TranMap was constructed. Synopsis AstTranMap $*$astTranMap( AstMapping $*$map1, AstMapping $*$map2, const char $*$options, ... ) map1 Pointer to the first component Mapping, which defines the forward transformation. map2 Pointer to the second component Mapping, which defines the inverse transformation. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new TranMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astTranMap() A pointer to the new TranMap. The number of output coordinates generated by the two Mappings (their NoutNout attribute) must be equal, as must the number of input coordinates accepted by each Mapping (their NinNin attribute).

The forward transformation of the first Mapping must exist.

The inverse transformation of the second Mapping must exist.

Note that the component Mappings supplied are not copied by astTranMap (the new TranMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a TranMap containing a copy of its component Mappings is required, then a copy of the TranMap should be made using astCopyastCopy.

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astTranN Transform N-dimensional coordinates This function applies a MappingMapping to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in a single array (which they need not fill completely).

If the coordinates are not stored in a single array, then the astTranPastTranP function might be more suitable. Synopsis void astTranN( AstMapping $*$this, int npoint, int ncoord_in, int indim, const double $*$in, int forward, int ncoord_out, int outdim, double $*$out ) this Pointer to the Mapping to be applied. npoint The number of points to be transformed. ncoord_in The number of coordinates being supplied for each input point (i.e. the number of dimensions of the space in which the input points reside). indim The number of elements along the second dimension of the " in" array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than " npoint" . in The address of the first element in a 2-dimensional array of shape " [ncoord_in][indim]" , containing the coordinates of the input (untransformed) points. These should be stored such that the value of coordinate number " coord" for input point number " point" is found in element " in[coord][point]" . forward A non-zero value indicates that the Mapping' s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. ncoord_out The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as " ncoord_in" . outdim The number of elements along the second dimension of the " out" array (which will contain the output coordinates). This value is required so that the coordinate values can be correctly located if they will not entirely fill this array. The value given should not be less than " npoint" . out The address of the first element in a 2-dimensional array of shape " [ncoord_out][outdim]" , into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number " coord" for output point number " point" will be found in element " out[coord][point]" . If the forward coordinate transformation is being applied, the Mapping supplied must have the value of " ncoord_in" for its NinNin attribute and the value of " ncoord_out" for its NoutNout attribute. If the inverse transformation is being applied, these values should be reversed. Handling of Huge Pixel Arrays If the number of points to be transformed exceeds the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte). Specifically, the arguments " npoint" , " indim" and " outdim" are changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astTranN becomes astTranN8 astTranP Transform N-dimensional coordinates held in separate arrays This function applies a MappingMapping to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in separate arrays, since each coordinate array is located by supplying a separate pointer to it.

If the coordinates are stored in a single (2-dimensional) array, then the astTranNastTranN function might be more suitable. Synopsis void astTranP( AstMapping $*$this, int npoint, int ncoord_in, const double $*$ptr_in[], int forward, int ncoord_out, double $*$ptr_out[] ) this Pointer to the Mapping to be applied. npoint The number of points to be transformed. ncoord_in The number of coordinates being supplied for each input point (i.e. the number of dimensions of the space in which the input points reside). ptr_in An array of pointers to double, with " ncoord_in" elements. Element " ptr_in[coord]" should point at the first element of an array of double (with " npoint" elements) which contain the values of coordinate number " coord" for each input (untransformed) point. The value of coordinate number " coord" for input point number " point" is therefore given by " ptr_in[coord][point]" (assuming both indices are zero-based). forward A non-zero value indicates that the Mapping' s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. ncoord_out The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as " ncoord_in" . ptr_out An array of pointers to double, with " ncoord_out" elements. Element " ptr_out[coord]" should point at the first element of an array of double (with " npoint" elements) into which the values of coordinate number " coord" for each output (transformed) point will be written. The value of coordinate number " coord" for output point number " point" will therefore be found in " ptr_out[coord][point]" . If the forward coordinate transformation is being applied, the Mapping supplied must have the value of " ncoord_in" for its NinNin attribute and the value of " ncoord_out" for its NoutNout attribute. If the inverse transformation is being applied, these values should be reversed.

This routine is not available in the Fortran 77 interface to the AST library. Handling of Huge Pixel Arrays If the number of points to be transformed exceeds the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte). Specifically, the argument " npoint" , is changed from type " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astTranP becomes astTranP8. astTune Set or get an integer-valued AST global tuning parameter This function returns the current value of an integer-valued AST global tuning parameter, optionally storing a new value for the parameter. For character-valued tuning parameters, see astTuneCastTuneC. Synopsis int astTune( const char $*$name, int value ) name The name of the tuning parameter (case-insensitive). value The new value for the tuning parameter. If this is AST__TUNULL, the existing current value will be retained. astTune() The original value of the tuning parameter. A default value will be returned if no value has been set for the parameter. This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances.

All threads in a process share the same AST tuning parameters values. Tuning Parameters ObjectCaching A boolean flag which indicates what should happen to the memory occupied by an AST ObjectObject when the Object is deleted (i.e. when its reference count falls to zero or it is deleted using astDeleteastDelete). If this is zero, the memory is simply freed using the systems " free" function. If it is non-zero, the memory is not freed. Instead a pointer to it is stored in a pool of such pointers, all of which refer to allocated but currently unused blocks of memory. This allows AST to speed up subsequent Object creation by re-using previously allocated memory blocks rather than allocating new memory using the systems malloc function. The default value for this parameter is zero. Setting it to a non-zero value will result in Object memory being cached in future. Setting it back to zero causes any memory blocks currently in the pool to be freed. Note, this tuning parameter only controls the caching of memory used to store AST Objects. To cache other memory blocks allocated by AST, use MemoryCaching. MemoryCaching A boolean flag similar to ObjectCaching except that it controls caching of all memory blocks of less than 300 bytes allocated by AST (whether for internal or external use), not just memory used to store AST Objects. astTuneC Set or get a character-valued AST global tuning parameter This function returns the current value of a character-valued AST global tuning parameter, optionally storing a new value for the parameter. For integer-valued tuning parameters, see astTuneastTune. Synopsis void astTuneC( const char $*$name, const char $*$value, char $*$buff, int bufflen ) name The name of the tuning parameter (case-insensitive). value The new value for the tuning parameter. If this is NULL, the existing current value will be retained. buff A character string in which to return the original value of the tuning parameter. An error will be reported if the buffer is too small to hold the value. NULL may be supplied if the old value is not required. bufflen The size of the supplied " buff" array. Ignored if " buff" is NULL. This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances.

All threads in a process share the same AST tuning parameters values. Tuning Parameters HRDel A string to be drawn following the hours field in a formatted sky axis value when " g" format is in use (see the Format attribute). This string may include escape sequences to produce super-scripts, etc. (see the Escapes attribute for details of the escape sequences allowed). The default value is " %-%$\wedge$50$+$%s70$+$h%$+$" which produces a super-script " h" . MNDel A string to be drawn following the minutes field in a formatted sky axis value when " g" format is in use. The default value is " %-%$\wedge$50$+$%s70$+$m%$+$" which produces a super-script " m" . SCDel A string to be drawn following the seconds field in a formatted sky axis value when " g" format is in use. The default value is " %-%$\wedge$50$+$%s70$+$s%$+$" which produces a super-script " s" . DGDel A string to be drawn following the degrees field in a formatted sky axis value when " g" format is in use. The default value is " %-%$\wedge$53$+$%s60$+$o%$+$" which produces a super-script " o" . AMDel A string to be drawn following the arc-minutes field in a formatted sky axis value when " g" format is in use. The default value is " %-%$\wedge$20$+$%s85$+$' %$+$" which produces a super-script " ' " (single quote). ASDel A string to be drawn following the arc-seconds field in a formatted sky axis value when " g" format is in use. The default value is " %-%$\wedge$20$+$%s85$+$$\backslash$" %$+$" which produces a super-script " " " (double quote). EXDel A string to be drawn to introduce the exponent in a value when " g" format is in use. The default value is " 10%-%$\wedge$50$+$%s70$+$" which produces " 10" followed by the exponent as a super-script. astUinterp Perform sub-pixel interpolation on a grid of data This is a fictitious function which does not actually exist. Instead, this description constitutes a template so that you may implement a function with this interface for yourself (and give it any name you wish). A pointer to such a function may be passed via the " finterp" parameter of the astResample$<$X$>$astResample$<$X$>$ functions (q.v.) in order to perform sub-pixel interpolation during resampling of gridded data (you must also set the " interp" parameter of astResample$<$X$>$ to the value AST__UINTERP). This allows you to use your own interpolation algorithm in addition to those which are pre-defined.

The function interpolates an input grid of data (and, optionally, processes associated statistical variance estimates) at a specified set of points. Synopsis void astUinterp( int ndim_in, const AstDim lbnd_in[], const AstDim ubnd_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in_var[], AstDim npoint, const AstDim offset[], const double $*$const coords[], const double params[], int flags, $<$Xtype$>$ badval, $<$Xtype$>$ out[], $<$Xtype$>$ out_var[], AstDim $*$nbad ) ndim_in The number of dimensions in the input grid. This will be at least one. lbnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. ubnd_in Pointer to an array of integers, with " ndim_in" elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that " lbnd_in" and " ubnd_in" together define the shape, size and coordinate system of the input grid in the same way as they do in astResample$<$X$>$. in Pointer to an array, with one element for each pixel in the input grid, containing the input data. This will be the same array as was passed to astResample$<$X$>$ via the " in" parameter. The numerical type of this array should match that of the data being processed. in_var Pointer to an optional second array with the same size and type as the " in" array. If given, this will contain the set of variance values associated with the input data and will be the same array as was passed to astResample$<$X$>$ via the " in_var" parameter.

If no variance values are being processed, this will be a NULL pointer. npoint The number of points at which the input grid is to be interpolated. This will be at least one. offset Pointer to an array of integers with " npoint" elements. For each interpolation point, this will contain the zero-based index in the " out" (and " out_var" ) array(s) at which the interpolated value (and its variance, if required) should be stored. For example, the interpolated value for point number " point" should be stored in " out[offset[point]]" (assuming the index " point" is zero-based). coords An array of pointers to double, with " ndim_in" elements. Element " coords[coord]" will point at the first element of an array of double (with " npoint" elements) which contains the values of coordinate number " coord" for each interpolation point. The value of coordinate number " coord" for interpolation point number " point" is therefore given by " coords[coord][point]" (assuming both indices are zero-based).

If any interpolation point has any of its coordinates equal to the value AST__BAD (as defined in the " ast.h" header file), then the corresponding output data (and variance) should either be set to the value given by " badval" , or left unchanged, depending on whether the AST__NOBAD flag is specified by " flags" . params This will be a pointer to the same array as was given via the " params" parameter of astResample$<$X$>$. You may use this to pass any additional parameter values required by your interpolation algorithm. flags This will be the same value as was given via the " flags" parameter of astResample$<$X$>$. You may test this value to provide additional control over the operation of your resampling algorithm. Note that the special flag values AST__URESAMP1, 2, 3 & 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see astResample$<$X$>$). badval This will be the same value as was given via the " badval" parameter of astResample$<$X$>$, and will have the same numerical type as the data being processed (i.e. as elements of the " in" array). It should be used to test for bad pixels in the input grid (but only if the AST__USEBAD flag is set via the " flags" parameter) and (unless the AST__NOBAD flag is set in " flags" ) for identifying bad output values in the " out" (and " out_var" ) array(s). out Pointer to an array with the same numerical type as the " in" array, into which the interpolated data values should be returned. Note that details of the storage order and number of dimensions of this array are not required, since the " offset" array contains all necessary information about where each returned value should be stored.

In general, not all elements of this array (or the " out_var" array below) may be used in any particular invocation of the function. Those which are not used should be returned unchanged. out_var Pointer to an optional array with the same type and size as the " out" array, into which variance estimates for the resampled values should be returned. This array will only be given if the " in_var" array has also been given.

If given, it is addressed in exactly the same way (via the " offset" array) as the " out" array. The values returned should be estimates of the statistical variance of the corresponding values in the " out" array, on the assumption that all errors in input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors).

If no output variance estimates are required, a NULL pointer will be given. nbad Pointer to an int in which to return the number of interpolation points at which no valid interpolated value could be obtained. The maximum value that should be returned is " npoint" , and the minimum is zero (indicating that all output values were successfully obtained). The data type $<$Xtype$>$ indicates the numerical type of the data being processed, as for astResample$<$X$>$.

This function will typically be invoked more than once for each invocation of astResample$<$X$>$.

If an error occurs within this function, it should use astSetStatusastSetStatus to set the AST error status to an error value. This will cause an immediate return from astResample$<$X$>$. The error value AST__UINER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). astUkern1 1-dimensional sub-pixel interpolation kernel This is a fictitious function which does not actually exist. Instead, this description constitutes a template so that you may implement a function with this interface for yourself (and give it any name you wish). A pointer to such a function may be passed via the " finterp" parameter of the astResample$<$X$>$astResample$<$X$>$ functions (q.v.) in order to supply a 1-dimensional interpolation kernel to the algorithm which performs sub-pixel interpolation during resampling of gridded data (you must also set the " interp" parameter of astResample$<$X$>$ to the value AST__UKERN1). This allows you to use your own interpolation kernel in addition to those which are pre-defined.

The function calculates the value of a 1-dimensional sub-pixel interpolation kernel. This determines how the weight given to neighbouring pixels in calculating an interpolated value depends on the pixel' s offset from the interpolation point. In more than one dimension, the weight assigned to a pixel is formed by evaluating this 1-dimensional kernel using the offset along each dimension in turn. The product of the returned values is then used as the pixel weight. Synopsis void astUkern1( double offset, const double params[], int flags, double $*$value ) offset This will be the offset of the pixel from the interpolation point, measured in pixels. This value may be positive or negative, but for most practical interpolation schemes its sign should be ignored. params This will be a pointer to the same array as was given via the " params" parameter of astResample$<$X$>$. You may use this to pass any additional parameter values required by your kernel, but note that " params[0]" will already have been used to specify the number of neighbouring pixels which contribute to the interpolated value. flags This will be the same value as was given via the " flags" parameter of astResample$<$X$>$. You may test this value to provide additional control over the operation of your function. Note that the special flag values AST__URESAMP1, 2, 3 & 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see astResample$<$X$>$). value Pointer to a double to receive the calculated kernel value, which may be positive or negative. Not all functions make good interpolation kernels. In general, acceptable kernels tend to be symmetrical about zero, to have a positive peak (usually unity) at zero, and to evaluate to zero whenever the pixel offset has any other integral value (this ensures that the interpolated values pass through the original data). An interpolation kernel may or may not have regions with negative values. You should consult a good book on image processing for more details.

If an error occurs within this function, it should use astSetStatusastSetStatus to set the AST error status to an error value. This will cause an immediate return from astResample$<$X$>$. The error value AST__UK1ER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). astUnformat Read a formatted coordinate value for a Frame axis This function reads a formatted coordinate value (given as a character string) for a FrameFrame axis and returns the equivalent numerical (double) value. It also returns the number of characters read from the string.

The principle use of this function is in decoding user-supplied input which contains formatted coordinate values. Free-format input is supported as far as possible. If input is ambiguous, it is interpreted with reference to the Frame' s attributes (in particular, the Format string associated with the Frame' s axis). This function is, in essence, the inverse of astFormatastFormat. Synopsis int astUnformat( AstFrame $*$this, int axis, const char $*$string, double $*$value ) this Pointer to the Frame. axis The number of the Frame axis for which a coordinate value is to be read (axis numbering starts at 1 for the first axis). string Pointer to a null-terminated character string containing the formatted coordinate value. This string may contain additional information following the value to be read, in which case reading stops at the first character which cannot be interpreted as part of the value. Any white space before or after the value is discarded. value Pointer to a double in which the coordinate value read will be returned. Frame This function applies to all Frames. See the " Frame Input Format" section below for details of the input formats accepted by a basic Frame. SkyFrameSkyFrame The SkyFrame class re-defines the input format to be suitable for representing angles and times, with the resulting coordinate value returned in radians. See the " SkyFrame Input Format" section below for details of the formats accepted. FrameSetFrameSet The input formats accepted by a FrameSet are determined by its current Frame (as specified by the CurrentCurrent attribute). astUnformat() The number of characters read from the string in order to obtain the coordinate value. This will include any white space which occurs before or after the value. A function value of zero (and no coordinate value) will be returned, without error, if the string supplied does not contain a suitably formatted value.

Beware that it is possible for a formatting error part-way through an input string to terminate input before it has been completely read, but to yield a coordinate value that appears valid. For example, if a user types " 1.5r6" instead of " 1.5e6" , the " r" will terminate input, giving an incorrect coordinate value of 1.5. It is therefore most important to check the return value of this function to ensure that the correct number of characters have been read.

An error will result if a value is read which appears to have the correct format, but which cannot be converted into a valid coordinate value (for instance, because the value of one or more of its fields is invalid).

The string " $<$bad$>$" is recognised as a special case and will yield the coordinate value AST__BAD without error. The test for this string is case-insensitive and also permits embedded white space.

A function result of zero will be returned and no coordinate value will be returned via the " value" pointer if this function is invoked with the AST error status set, or if it should fail for any reason. Frame Input Format The input format accepted for a basic Frame axis is as follows: An optional sign, followed by:

A sequence of one or more digits possibly containing a decimal point, followed by:

An optional exponent field.

The exponent field, if present, consists of " E" or " e" followed by a possibly signed integer.

Examples of acceptable Frame input formats include: 99

1.25

-1.6

1E8

-.99e-17

$<$bad$>$ SkyFrame Input Format The input format accepted for a SkyFrame axis is as follows: An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. " -12 42 03" ).

Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as " 124.707" , while degrees and decimal arc-minutes might be given as " -13 33.8" ).

The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. " 720 45 31" is valid, whereas " 11 45 61" is not).

Fields may be separated by white space or by " :" (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. " - 2: 04 : 7.1" ).

The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: " d" —degrees; " h" —hours; " m" —minutes of arc or time; " s" —seconds of arc or time; " ' " (single quote)—minutes of arc; " " " (double quote)—seconds of arc. Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. " -11D 3' 14.4" " or " 22h14m11.2s" ).

The presence of any of the field identification characters " d" , " ' " (single quote) or " " " (double quote) indicates that the value is to be interpreted as an angle. Conversely, the presence of " h" indicates that it is to be interpreted as a time (with 24 hours corresponding to 360 degrees). Incompatible angle/time identification characters may not be mixed (e.g. " 10h14' 3" " is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either.

If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by astFormat are correctly interpreted by astUnformat.

Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. " -05m13s" is equivalent to " -:05:13" ). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. " 14:25.4s" specifies minutes and seconds, while " 14::25.4s" specifies degrees and seconds).

If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. " 01:02" ), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that astFormat would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that astFormat would produce.

This final convention is intended to ensure that values formatted by astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters.

Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include: -14d 13m 22.2s (-14d 13' 22.2" )

$+$ 12:34:56.7 (12d 34' 56.7" or 12h 34m 56.7s)

001 : 02 : 03.4 (1d 02' 03.4" or 1h 02m 03.4s)

22h 30 (22h 30m 00s)

136::10" (136d 00' 10" or 136h 00m 10s)

-14M 27S (-0d 14' 27" or -0h 14m 27s)

-:14: (-0d 14' 00" or -0h 14m 00s)

-::4.1 (-0d 00' 04.1" or -0h 00m 04.1s)

.9" (0d 00' 00.9" )

d12m (0d 12' 00" )

H 12:22.3s (0h 12m 22.3s)

$<$bad$>$ (AST__BAD)

Where alternative interpretations are shown, the choice of angle or time depends on the associated Format(axis)Format(axis) attribute. astUnitMap Create a UnitMap This function creates a new UnitMapUnitMap and optionally initialises its attributes.

A UnitMap is a unit (null) MappingMapping that has no effect on the coordinates supplied to it. They are simply copied. This can be useful if a Mapping is required (e.g. to pass to another function) but you do not want it to have any effect. Synopsis AstUnitMap $*$astUnitMap( int ncoord, const char $*$options, ... ) ncoord The number of input and output coordinates (these numbers are necessarily the same). options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astUnitMap() A pointer to the new UnitMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astUnitNormMap Create a UnitNormMap This function creates a new UnitNormMapUnitNormMap and optionally initialises its attributes.

The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. The output contains one more coordinate than the input: the initial NinNin outputs are in the same order as the input; the final output is the norm. If the norm is 0, then the output of the forward transformation is AST__BAD for each component of the unit vector and 0 for the norm (the final value).

The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. If the provided norm is 0 then the other input values are ignored, and the output vector is the centre.

Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre; the norm is 5, so the output is [0.8, 0.6, 5].

UnitNormMap enables radially symmetric transformations, as follows: apply a UnitNormMap to produce a unit vector and norm (radius)

apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged

apply the same UnitNormMap in the inverse direction to produce the result Synopsis AstUnitNormMap $*$astUnitNormMap( int ncoord, const double centre[], const char $*$options, ... ) ncoord The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). Output will include one additional coordinate. centre An array containing the values to be subtracted from the input coordinates before computing unit vector and norm. A separate value must be supplied for each coordinate. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitNormMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astUnitNormMap() A pointer to the new UnitNormMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astUnlock Unlock an Object for use by other threads Unlocks an ObjectObject previously locked using astLockastLock, so that other threads can use the Object. See astLock for further details. Synopsis void astUnlock( AstObject $*$this, int report ) this Pointer to the Object to be unlocked. report If non-zero, an error will be reported if the supplied Object, or any Object contained within the supplied Object, is not currently locked by the running thread. If zero, such Objects will be left unchanged, and no error will be reported. Object This function applies to all Objects. This function attempts to execute even if the global error status is set, but no further error report will be made if it subsequently fails under these circumstances.

All unlocked Objects are excluded from AST context handling until they are re-locked using astLock.

This function is only available in the C interface.

This function returns without action if the Object is not currently locked by any thread. If it is locked by the running thread, it is unlocked. If it is locked by another thread, an error will be reported if " error" is non-zero.

This function returns without action if the AST library has been built without POSIX thread support (i.e. the " -with-pthreads" option was not specified when running the " configure" script). astVersion Return the version of the AST library being used This macro invokes a function which returns an integer representing the version of the AST library being used. The library version is formatted as a string such as " 2.0-7" which contains integers representing the " major version" (2), the " minor version" (0) and the " release" (7). The integer returned by this function combines all three integers together into a single integer using the expresion:

(major version)$*$1E6 $+$ (minor version)$*$1E3 $+$ (release) Synopsis int astVersion ObjectObject This macro applies to all Objects. astVersion The major version, minor version and release numbers for the AST library, encoded as a single integer. astWarnings Returns any warnings issued by the previous read or write operation This function returns an AST KeyMapKeyMap object holding the text of any warnings issued as a result of the previous invocation of the astReadastRead or astWriteastWrite function on the ChannelChannel. If no warnings were issued, a a NULL value will be returned.

Such warnings are non-fatal and will not prevent the read or write operation succeeding. However, the converted object may not be identical to the original object in all respects. Differences which would usually be deemed as insignificant in most usual cases will generate a warning, whereas more significant differences will generate an error.

The " StrictStrict" attribute allows this warning facility to be switched off, so that a fatal error is always reported for any conversion error. Synopsis AstKeyMap $*$astWarnings( AstChannel $*$this ) this Pointer to the Channel. Channel The basic Channel class generates a warning when ever an un-recognised item is encountered whilst reading an ObjectObject from an external data source. If Strict is zero (the default), then unexpected items in the Object description are simply ignored, and any remaining items are used to construct the returned Object. If Strict is non-zero, an error will be reported and a NULL Object pointer returned if any unexpected items are encountered.

As AST continues to be developed, new attributes are added occasionally to selected classes. If an older version of AST is used to read external Object descriptions created by a more recent version of AST, then the Channel class will, by default, ignore the new attributes, using the remaining attributes to construct the Object. This is usually a good thing. However, since external Object descriptions are often stored in plain text, it is possible to edit them using a text editor. This gives rise to the possibility of genuine errors in the description due to finger-slips, typos, or simple mis-understanding. Such inappropriate attributes will be ignored if Strict is left at its default zero value. This will cause the mis-spelled attribute to revert to its default value, potentially causing subtle changes in the behaviour of application software. If such an effect is suspected, the Strict attribute can be set non-zero, resulting in the erroneous attribute being identified in an error message. FitsChanFitsChan The returned KeyMap will contain warnings for all conditions listed in the WarningsWarnings attribute. XmlChanXmlChan Reports conversion errors that result in what are usally insignificant changes. astWarnings() A pointer to the KeyMap holding the warning messages, or NULL if no warnings were issued during the previous read operation. The returned KeyMap uses keys of the form " Warning_1" , " Warning_2" , etc.

A value of NULL will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astWatch Identify a new error status variable for the AST library This function allows a new error status variable to be accessed by the AST library when checking for and reporting error conditions.

By default, the library uses an internal integer error status which is set to an error value if an error occurs. Use of astWatch allows the internal error status to be replaced by an integer variable of your choosing, so that the AST library can share its error status directly with other code which uses the same error detection convention.

If an alternative error status variable is supplied, it is used by all related AST functions and macros (e.g. astOKastOK, astStatusastStatus and astClearStatusastClearStatus). Synopsis int $*$astWatch( int $*$status_ptr ) status_ptr Pointer to an int whose value is to be used subsequently as the AST inherited status value. If a NULL pointer is supplied, the AST library will revert to using its own internal error status. astWatch() Address of the previous error status variable. This may later be passed back to astWatch to restore the previous behaviour of the library. (Note that on the first invocation of astWatch the returned value will be the address of the internal error status variable.) This function is not available in the FORTRAN 77 interface to the AST library. astWcsMap Create a WcsMap This function creates a new WcsMapWcsMap and optionally initialises its attributes.

A WcsMap is used to represent sky coordinate projections as described in the (draft) FITS world coordinate system (FITS-WCS) paper by E.W. Griesen and M. Calabretta (A & A, in preparation). This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa).

A WcsMap is a specialised form of MappingMapping which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated " TAN with polynomial correction terms" projection which is refered to here by the code " TPN" . Using the FITS-WCS terminology, the transformation is between " native spherical" and " projection plane" coordinates. These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS).

The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the WcsTypeWcsType attribute and the coordinates on which it acts may be determined using the WcsAxis(lonlat)WcsAxis(lonlat) attribute.

Each WcsMap also allows up to 100 " projection parameters" to be associated with each axis. These specify the precise form of the projection, and are accessed using PVi_mPVi_m attribute, where " i" is the integer axis index (starting at 1), and m is an integer " parameter index" in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper. Synopsis AstWcsMap $*$astWcsMap( int ncoord, int type, int lonax, int latax, const char $*$options, ... ) ncoord The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). This must be at least 2. The same number is applicable to both input and output points. type The type of FITS-WCS projection to apply. This should be given using a macro value such as AST__TAN (for a tangent plane projection), where the characters following the double underscore give the projection type code (in upper case) as used in the FITS-WCS " CTYPEi" keyword. You should consult the FITS-WCS paper for a list of the available projections. The additional code of AST__TPN can be supplied which represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper. lonax The index of the longitude axis. This should lie in the range 1 to " ncoord" . latax The index of the latitude axis. This should lie in the range 1 to " ncoord" and be distinct from " lonax" . options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new WcsMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way.

If the sky projection to be implemented requires projection parameter values to be set, then this should normally be done here via the PVi_m attribute (see the " Examples" section). Setting values for these parameters is mandatory if they do not have default values (as defined in the FITS-WCS paper). ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astWcsMap() A pointer to the new WcsMap. wcsmap = astWcsMap( 2, AST__MER, 1, 2, " " ); Creates a WcsMap that implements a FITS-WCS Mercator projection on pairs of coordinates, with coordinates 1 and 2 representing the longitude and latitude respectively. Note that the FITS-WCS Mercator projection does not require any projection parameters. wcsmap = astWcsMap( 3, AST__COE, 2, 3, " PV3_1=40.0" ); Creates a WcsMap that implements a FITS-WCS conical equal area projection. The WcsMap acts on points in a 3-dimensional space; coordinates 2 and 3 represent longitude and latitude respectively, while the values of coordinate 1 are copied unchanged. ProjectionProjection parameter 1 associatyed with the latitude axis (corresponding to FITS keyword " PV3_1" ) is required and has no default, so is set explicitly to 40.0 degrees. Projection parameter 2 (corresponding to FITS keyword " PV3_2" ) is required but has a default of zero, so need not be specified. The forward transformation of a WcsMap converts between FITS-WCS " native spherical" and " relative physical" coordinates, while the inverse transformation converts in the opposite direction. This arrangement may be reversed, if required, by using astInvertastInvert or by setting the InvertInvert attribute to a non-zero value.

If any set of coordinates cannot be transformed (for example, many projections do not cover the entire celestial sphere), then a WcsMap will yield coordinate values of AST__BAD.

The validity of any projection parameters given via the PVi_m parameter in the " options" string is not checked by this function. However, their validity is checked when the resulting WcsMap is used to transform coordinates, and an error will result if the projection parameters do not satisfy all the required constraints (as defined in the FITS-WCS paper).

A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astWinMap Create a WinMap This function creates a new WinMapWinMap and optionally initialises its attributes.

A Winmap is a linear MappingMapping which transforms a rectangular window in one coordinate system into a similar window in another coordinate system by scaling and shifting each axis (the window edges being parallel to the coordinate axes).

A WinMap is specified by giving the coordinates of two opposite corners (A and B) of the window in both the input and output coordinate systems. Synopsis AstWinMap $*$astWinMap( int ncoord, const double ina[], const double inb[], const double outa[], const double outb[], const char $*$options, ... ) ncoord The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. ina An array containing the " ncoord" coordinates of corner A of the window in the input coordinate system. inb An array containing the " ncoord" coordinates of corner B of the window in the input coordinate system. outa An array containing the " ncoord" coordinates of corner A of the window in the output coordinate system. outb An array containing the " ncoord" coordinates of corner B of the window in the output coordinate system. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new WinMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astWinMap() A pointer to the new WinMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" . astWrite Write an Object to a Channel This function writes an ObjectObject to a ChannelChannel, appending it to any previous Objects written to that Channel. Synopsis int astWrite( AstChannel $*$this, AstObject $*$object ) this Pointer to the Channel. object Pointer to the Object which is to be written. FitsChanFitsChan If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather than the native AST encoding, then storing values in the FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking astWrite can help to produce a successful write. astWrite() The number of Objects written to the Channel by this invocation of astWrite (normally, this will be one). A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Invoking this function will usually cause the sink function associated with the channel to be called in order to transfer a textual description of the supplied object to some external data store. However, the FitsChan class behaves differently. Invoking this function on a FitsChan causes new FITS header cards to be added to an internal buffer (the sink function is not invoked). This buffer is written out through the sink function only when the FitsChan is deleted. astWriteFits Write out all cards in a FitsChan to the sink function This function writes out all cards currently in the FitsChanFitsChan. If the SinkFileSinkFile attribute is set, they will be written out to the specified sink file. Otherwise, they will be written out using the sink function specified when the FitsChan was created. All cards are then deleted from the FitsChan. Synopsis void astWriteFits( AstFitsChan $*$this ) this Pointer to the FitsChan. If the SinkFile is unset, and no sink function is available, this method simply empties the FitsChan, and is then equivalent to astEmptyFitsastEmptyFits.

This method attempt to execute even if an error has occurred previously. astXmlChan Create an XmlChan This function creates a new XmlChanXmlChan and optionally initialises its attributes.

A XmlChan is a specialised form of ChannelChannel which supports XML I/O operations. Writing an ObjectObject to an XmlChan (using astWriteastWrite) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description.

Normally, when you use an XmlChan, you should provide " source" and " sink" functions which connect it to an external data store by reading and writing the resulting XML text. By default, however, an XmlChan will read from standard input and write to standard output.

Alternatively, an XmlChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Synopsis AstXmlChan $*$astXmlChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) source Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the XmlChan to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read.

If " source" is NULL and no value has been set for the SourceFile attribute, the XmlChan will read from standard input instead. sink Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the XmlChan to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store.

If " sink" is NULL, and no value has been set for the SinkFile attribute, the XmlChan will write to standard output instead. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new XmlChan. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astXmlChan() A pointer to the new XmlChan. If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astYamlChan Create a YamlChan This function creates a new YamlChanYamlChan and optionally initialises its attributes.

A YamlChan is a specialised form of ChannelChannel which supports YAML I/O operations. Writing an ObjectObject to a YamlChan (using astWriteastWrite) will, if the Object is suitable, generate an YAML description of that Object, and reading from a YamlChan will create a new Object from its YAML description.

Normally, when you use a YamlChan, you should provide " source" and " sink" functions which connect it to an external data store by reading and writing the resulting text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output.

Alternatively, a YamlChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Synopsis AstYamlChan $*$astYamlChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) source Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the YamlChan to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read.

If " source" is NULL and no value has been set for the SourceFile attribute, the YamlChan will read from standard input instead. sink Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the YamlChan to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store.

If " sink" is NULL, and no value has been set for the SinkFile attribute, the YamlChan will write to standard output instead. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new YamlChan. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astYamlChan() A pointer to the new YamlChan. If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST.

A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. astZoomMap Create a ZoomMap This function creates a new ZoomMapZoomMap and optionally initialises its attributes.

A ZoomMap is a MappingMapping which " zooms" a set of points about the origin by multiplying all coordinate values by the same scale factor (the inverse transformation is performed by dividing by this scale factor). Synopsis AstZoomMap $*$astZoomMap( int ncoord, double zoom, const char $*$options, ... ) ncoord The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. zoom Initial scale factor by which coordinate values should be multiplied (by the forward transformation) or divided (by the inverse transformation). This factor may subsequently be changed via the ZoomMap' s ZoomZoom attribute. It may be positive or negative, but should not be zero. options Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new ZoomMap. The syntax used is identical to that for the astSetastSet function and may include " printf" format specifiers identified by " %" symbols in the normal way. ... If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function). astZoomMap() A pointer to the new ZoomMap. A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. Status Handling The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: " int $*$status" .