" 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
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.
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.
The pointers to return in the KeyMap may be restricted either by
class or by context level using the function arguments.
Synopsis
AstKeyMap
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
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 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.
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.
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 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
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
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, 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, 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.
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.
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 " MinOrder1" , 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
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
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,
astAddPixelMaskX
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.
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
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 " MinOrder1" , 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
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
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
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, 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.
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).
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 $
pm
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 $
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.
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
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 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.
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, 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.
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
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" .
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.
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
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
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.
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.
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.
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
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 )
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.
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
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 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.
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
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.
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.
This mechanism is a thread-safe alternative to passing file
descriptors, etc, via static global variables.
Synopsis
void
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.
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.
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'
Tn1(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
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_iastChebyMap( 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" .
( 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
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
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
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.
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.
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.
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.
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
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.
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.
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
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.
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.
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
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.
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.
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
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
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.
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.
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.
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
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.
astConvexastConvert( 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.
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
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]
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,
astConvexX
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" .
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
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
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.
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.
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
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.
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.
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
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).
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.
After deletion, the following card becomes the current card.
Synopsis
void astDelFits( AstFitsChan
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.
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).
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
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 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.
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
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
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
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.
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.
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.
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.
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
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, 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.
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
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.
astFindFrame( AstFrame
target, AstFrame
template,
const char
domainlist )
target
Pointer to the target Frame (or FrameSet).
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, astSetFitsX
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
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 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.
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
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
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.
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.
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 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
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 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.
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
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).
astGetthis, 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.
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
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 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
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.
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
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
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
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.
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.
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.
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 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
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
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
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, 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).
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.
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.
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
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.
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.
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
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.
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.
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
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 -
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 -
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 -
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 -
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 -
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 -
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 -
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 -
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 -
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
beta - A pointer to the float which is to receive the
scale for the Y axis (i.e. Ynorm = beta
int Text( AstObject
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 -
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
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).
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:
grfcon, int attr, double value, double
old_value, int prim )
grfcon )
grfcon, int cap, int value )
grfcon )
grfcon )
grfcon, int n, const float
x, const float
y )
grfcon, int n, const float
x, const float
y, int type )
grfcon, float
chv, float
chh )
grfcon, float
alpha, float
beta )
Xworld).
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:
grfcon, const char
text, float x, float y, const char
just,
float upx, float upy )
grfcon, const char
text, float x, float y, const char
just,
float upx, float upy, float
xb, float
yb )
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.
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
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.
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.
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 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.
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" .
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
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 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.
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
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 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
astMapPut0name, 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.
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.
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
X_out = fit[0]
Y_out = fit[1]
Z_out = fit[2]
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.
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:
fit[3]
X_in
fit[4]
Y_in
fit[5]
X_in
fit[6]
Y_in
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.
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
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.
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.
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
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 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.
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
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
"
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
"
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
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
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
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
D: double
I: int
K: int64_t
C: " const" pointer to null terminated character string
A: Pointer to AstObject
P: Generic " void
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
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
F: float
I: int
K: int64_t
C: " const" pointer to null terminated character string
A: Pointer to AstObject
P: Generic " void
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
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
F: float
I: int
K: int64_t
C: " const" pointer to null terminated character string
A: Pointer to AstObject
P: Generic " void
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
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,
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.
lbnd_out" .
ubnd_out" .
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.
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.
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.
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
" pointer
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.
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
" pointer
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.
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
" pointer
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.
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
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
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
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
F: float
I: int
K: int64_t
C: " const" pointer to null terminated character string
A: Pointer to AstObject
P: Generic " void
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
F: float
I: int
K: int64_t
C: " const" pointer to null terminated character string
A: Pointer to AstObject
P: Generic " void
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
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
F: float
I: int
K: int64_t
C: " const" pointer to null terminated character string
A: Pointer to AstObject
P: Generic " void
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.
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.
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.
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.
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
" pointer
" 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
" pointer
" 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.
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
" pointer
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
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
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).
astMaskthis, 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.
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).
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
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]
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
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
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
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.
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.
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" ).
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.
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
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.
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
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
" 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
" y = r
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
" rout = r
" theta = atan2( yin, xin )"
" xout = rout
" yout = rout
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 "
A
x1 - x2: Difference of " x1" and " x2" .
x1
x1 / x2: Ratio of " x1" and " x2" .
x1
- 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
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
x1
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
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
x1
x1
x1
Note that relational operators cannot usefully be used to compare
values with the
The following bitwise operators are available:
x1
x1
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
x1
Note that no bit inversion operator ("
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
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
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 "
Function arguments and parenthesised expressions
Function invocations
Unary
== .eq. != .ne.
&
&& .and.
.eqv. .neqv. .xor.
All operators associate from left-to-right, except for unary 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.
x
y
y )"
cos( theta )"
sin( theta )"
xin
yin
yin )"
( 1
0.1
r
r )"
cos( theta )"
sin( theta )"
bad
" .
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" .
x2: Product of " x1" and " x1" .
x2: " x1" raised to the power of " x2" .
x: Unary plus, has no effect on its argument.
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.
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.)
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.)
bad
.
x2: Tests whether " x1" is greater than " x2" . (The synonym
" .gt." is also provided for compatibility with Fortran.)
= x2: Tests whether " x1" is greater than or equal to " x2" . (The
synonym " .ge." is also provided for compatibility with Fortran.)
x2: Tests whether " x1" is less than " x2" . (The synonym " .lt."
is also provided for compatibility with Fortran.)
= x2: Tests whether " x1" is less than or equal to " x2" . (The
synonym " .le." is also provided for compatibility with Fortran.)
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.
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.
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.
x2: Bitwise OR between the bits of " x1" and those of " x2"
(equivalent to a boolean OR applied at each bit position in turn).
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).
" 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
-1" ).
Functions
The following functions are available:
abs(x): Absolute value of " x" (sign removal), same as fabs(x).
bad
value (AST__BAD), otherwise 0.
x" ).
"
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
- ! .not.
/
-
.lt.
= .le.
.gt.
= .ge.
.or
,
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
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 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.
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
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.
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.
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
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
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.
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.
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.
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
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.
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.
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 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.
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.
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
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.
astOutlinethis, 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.
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
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]
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
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
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
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.
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" .
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).
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.
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
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:
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
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.
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 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
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.
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.
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
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.
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.
Optionally, a MappingMapping that converts between the coordinate
systems described by the two Frames will also be returned.
Synopsis
AstFrame
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.
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.
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
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.
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).
A Plot3D is a specialised form of PlotPlot that provides facilities
for producing 3D graphical output.
Synopsis
AstPlot3D
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
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
Zero will be returned if an error occurs.
astPointList
Create a PointList
This function creates a new PointListPointList object and optionally initialises
its attributes.
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).
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.
X
).
If a transformed axis value is AST__BAD then the corresponding
input point is outside the Region.
A PointList object is a specialised type of RegionRegion which represents a
collection of points in a coordinate FrameFrame.
Synopsis
AstPointList
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 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.
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
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.
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.
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
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.
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.
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
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_iastPolyMap( 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" .
( 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
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.
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.
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
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 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.
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 (MN) 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
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
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
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
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
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):
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.
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.
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.
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.
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.
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
X_out = fit[0]
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.
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:
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.
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
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
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
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.
astRebinastRateMap( 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.
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.
this )
this
Pointer to the FitsChan.
This function returns without action if no source function was
specified when the FitsChan was created.
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
astRebinSeqX
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
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]
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
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
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
AST__NEAREST
AST__LINEAR
AST__SINC
AST__SINCSINC
AST__SINCCOS
AST__SINCGAUSS
AST__SOMBCOS
In addition, the following schemes can be used with
astRebin
AST__GAUSS: This scheme uses a kernel of the form exp(-k
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,
astRebinX
( 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.
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" ).
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
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.
X
documentation for details of these schemes including the use of the
" fspread" and " params" parameters:
X
but not with astResample
X
:
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:
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
astResampleX
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
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]
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
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
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
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
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
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,
astRebinSeqX
( 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.
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" ).
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.
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
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:
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.
X
within a given sequence.
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
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
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
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 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.
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.
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.
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
astRebinX
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
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]
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
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
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
AST__SINC: This scheme uses a sinc(pi
AST__SINCSINC: This scheme uses an improved kernel, of the form
sinc(pi
AST__SINCCOS: This scheme uses a kernel of the form
sinc(pi
AST__SINCGAUSS: This scheme uses a kernel of the form
sinc(pi
AST__SOMB: This scheme uses a somb(pi
AST__SOMBCOS: This scheme uses a kernel of the form
somb(pi
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
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
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
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.
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.
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" ).
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.
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
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.
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!
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.
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.
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.
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.
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.
params[0])
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.
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:
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.
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
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
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.
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).
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 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
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:
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.
" 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
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.
astSetthis, 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.
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
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.
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.
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
The astGetActiveUnitastGetActiveUnit function can be used to retrieve the current
value of the ActiveUnit flag.
astSetFitsthis, 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.
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
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
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
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.
" .
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.
X
family to over-write the old value.
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" .
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 (
void PutErr( int status_value, const char
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 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:
message )
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
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.
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.
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
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.
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" .
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
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.
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.
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
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.
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.
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 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.
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.
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
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 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.
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
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.
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.
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
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.
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 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
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 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.
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/
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.
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.
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/
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.
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.
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/
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 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.
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/
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 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.
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
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.
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.
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
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.
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.
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
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
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
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
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 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.
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.
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.
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.
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.
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.
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 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 (
OBSLAT: Observer geodetic latitude (IAU 1975) in radians (
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.
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.
ve westwards).
ve northwards).
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
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.
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 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
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
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]
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.
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.
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.
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.
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
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 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).
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 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
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
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
" %-%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.
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.
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.
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
" %-%
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
" %-%
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
" %-%
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
" %-%
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
" %-%
20
%s85
" %
" 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%-%
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
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
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
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
This function will typically be invoked more than once for each
invocation of astResample
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 astResampleXtype
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.
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.
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.
Xtype
indicates the numerical type of the data
being processed, as for astResample
X
.
X
.
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
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 astResamplevalue )
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.
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
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 "
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
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" )
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)
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.
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.
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.
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" ).
12:34:56.7 (12d 34' 56.7" or 12h 34m 56.7s)
bad
(AST__BAD)
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
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:
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.
(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
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.
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.
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
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 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.
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
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 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.
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.
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.
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
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.
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.
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
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.
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.
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" .