uk.ac.starlink.ast
Class Frame

java.lang.Object
  extended by uk.ac.starlink.ast.AstObject
      extended by uk.ac.starlink.ast.Mapping
          extended by uk.ac.starlink.ast.Frame
Direct Known Subclasses:
CmpFrame, FluxFrame, FrameSet, Region, SkyFrame, SpecFrame, TimeFrame

public class Frame
extends Mapping

Java interface to the AST Frame class - coordinate system description. This class is used to represent coordinate systems. 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 Title (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.

Notes


- When used as a Mapping, a Frame implements a unit (null) transformation in both the forward and inverse directions (equivalent to a UnitMap). The Nin and Nout attribute values are both equal to the number of Frame axes.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:
AST Frame

Nested Class Summary
 
Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping
Mapping.Interpolator, Mapping.Spreader
 
Field Summary
 
Fields inherited from class uk.ac.starlink.ast.Mapping
LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER
 
Fields inherited from class uk.ac.starlink.ast.AstObject
AST__BAD, AST__TUNULL, pointer
 
Constructor Summary
protected Frame()
          Dummy constructor.
  Frame(int naxes)
          Creates a new Frame.
 
Method Summary
 double angle(double[] a, double[] b, double[] c)
          Calculate the angle subtended by two points at a third point.
 double axAngle(double[] a, double[] b, int axis)
          Returns the angle from an axis, to a line through two points.
 double axDistance(int axis, double v1, double v2)
          Find the distance between two axis values.
 double axOffset(int axis, double v1, double dist)
          Add an increment onto a supplied axis value.
 FrameSet convert(Frame to, String domainlist)
          Determine how to convert between two coordinate systems.
 double distance(double[] point1, double[] point2)
          Calculate the distance between two points in a Frame.
 FrameSet findFrame(Frame template, String domainlist)
          Find a coordinate system with specified characteristics.
 String format(int axis, double value)
          Format a coordinate value for a Frame axis.
 boolean getActiveUnit()
          Determines how the Unit attribute will be used.
 String getAlignSystem()
          Get coordinate system in which to align the Frame.
 double getBottom(int axis)
          Get lowest axis value to display by axis.
 int getDigits()
          Get number of digits of precision.
 int getDigits(int axis)
          Get number of digits of precision by axis.
 boolean getDirection(int axis)
          Get display axis in conventional direction by axis.
 String getDomain()
          Get coordinate system domain.
 double getDut1()
          Get the UT1-UTC correction.
 double getEpoch()
          Get epoch of observation.
 String getFormat(int axis)
          Get format specification for axis values by axis.
 String getLabel(int axis)
          Get axis label by axis.
 boolean getMatchEnd()
          Get match trailing axes.
 int getMaxAxes()
          Get maximum number of Frame axes to match.
 int getMinAxes()
          Get minimum number of Frame axes to match.
 int getNaxes()
          Get number of Frame axes.
 String getNormUnit(int axis)
          Get normalised Axis physical units by axis.
 String getObsLat()
          Get the geodetic latitude of the observer.
 String getObsLon()
          Get the geodetic longitude of the observer.
 boolean getPermute()
          Get permute axis order.
 boolean getPreserveAxes()
          Get preserve axes.
 String getSymbol(int axis)
          Get axis symbol by axis.
 String getSystem()
          Get coordinate system used to describe positions within the domain.
 String getTitle()
          Get frame title.
 double getTop(int axis)
          Get highest axis value to display by axis.
 String getUnit(int axis)
          Get axis physical units by axis.
 double[] intersect(double[] a1, double[] a2, double[] b1, double[] b2)
          Find the point of intersection between two geodesic curves.
 void norm(double[] value)
          Normalise a set of Frame coordinates.
 double[] offset(double[] point1, double[] point2, double offset)
          Calculate an offset along a geodesic curve.
 double offset2(double[] point1, double angle, double offset, double[] point2)
          Calculate an offset along a geodesic curve in a 2D Frame.
 void permAxes(int[] perm)
          Permute the axis order in a Frame.
 Frame pickAxes(int naxes, int[] axes, Mapping[] map)
          Create a new Frame by picking axes from an existing one.
 double[] resolve(double[] point1, double[] point2, double[] point3, double[] point4)
          Resolve a vector into two orthogonal components.
 void setActiveUnit(boolean value)
          Specify how the Unit attribute should be used.
 void setAlignSystem(String alignSystem)
          Set coordinate system in which to align the Frame.
 void setBottom(int axis, double bottom)
          Set lowest axis value to display by axis.
 void setDigits(int digits)
          Set number of digits of precision.
 void setDigits(int axis, int digits)
          Set number of digits of precision by axis.
 void setDirection(int axis, boolean direction)
          Set display axis in conventional direction by axis.
 void setDomain(String domain)
          Set coordinate system domain.
 void setDut1(double dut1)
          Set the UT1-UTC correction.
 void setEpoch(double epoch)
          Set epoch of observation.
 void setEpoch(String epoch)
          Set epoch of observation.
 void setFormat(int axis, String format)
          Set format specification for axis values by axis.
 void setLabel(int axis, String label)
          Set axis label by axis.
 void setMatchEnd(boolean matchEnd)
          Set match trailing axes.
 void setMaxAxes(int maxAxes)
          Set maximum number of Frame axes to match.
 void setMinAxes(int minAxes)
          Set minimum number of Frame axes to match.
 void setObsLat(String obsLat)
          Set the geodetic latitude of the observer.
 void setObsLon(String obsLon)
          Set the geodetic longitude of the observer.
 void setPermute(boolean permute)
          Set permute axis order.
 void setPreserveAxes(boolean preserveAxes)
          Set preserve axes.
 void setSymbol(int axis, String symbol)
          Set axis symbol by axis.
 void setSystem(String system)
          Set coordinate system used to describe positions within the domain.
 void setTitle(String title)
          Set frame title.
 void setTop(int axis, double top)
          Set highest axis value to display by axis.
 void setUnit(int axis, String unit)
          Set axis physical units by axis.
 double unformat(int axis, String string)
          Read a formatted coordinate value for a Frame axis.
 
Methods inherited from class uk.ac.starlink.ast.Mapping
decompose, getInvert, getNin, getNout, getReport, getTranForward, getTranInverse, invert, linearApprox, mapBox, mapSplit, rate, rebin, rebinD, rebinF, rebinI, resample, resampleB, resampleD, resampleF, resampleI, resampleL, resampleS, setInvert, setReport, simplify, tran1, tran2, tranGrid, tranN, tranP
 
Methods inherited from class uk.ac.starlink.ast.AstObject
annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Frame

public Frame(int naxes)
Creates a new Frame.

Parameters:
naxes - The number of Frame axes (i.e. the number of dimensions of the coordinate space which the Frame describes).
Throws:
AstException - if an error occurred in the AST library

Frame

protected Frame()
Dummy constructor. This constructor does not create a valid Frame object, but is required for inheritance by Frame's subclasses.

Method Detail

angle

public double angle(double[] a,
                    double[] b,
                    double[] c)
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 Frame in use. For instance, in SkyFrame, they will be great circles.

Notes


- A value of AST__BAD will also be returned if points A and B are co-incident, or if points B and C are co-incident.
- A value of AST__BAD will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:
a - An array of double, with one element for each Frame axis (Naxes 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.
Returns:
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$.
Throws:
AstException - if an error occurred in the AST library

axAngle

public double axAngle(double[] a,
                      double[] b,
                      int axis)
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.

Notes


- The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistance function.
- This function will return "bad" coordinate values (AST__BAD) if any of the input coordinates has this value, or if the require position angle is undefined.

Parameters:
a - An array of double, with one element for each Frame axis (Naxes 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).
Returns:
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.
Throws:
AstException - if an error occurred in the AST library

axDistance

public double axDistance(int axis,
                         double v1,
                         double v2)
Find the distance between two axis values. This function returns a signed value representing the axis increment from axis value v1 to axis value v2.

For a simple Frame, this is a trivial operation returning the difference between the two axis values. But for other derived classes of Frame (such as a SkyFrame) this is not the case.

Notes


- This function will return a "bad" result value (AST__BAD) if any of the input values has this value.
- A "bad" value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:
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.
Returns:
The distance from the first to the second axis value.
Throws:
AstException - if an error occurred in the AST library

intersect

public double[] intersect(double[] a1,
                          double[] a2,
                          double[] b1,
                          double[] b2)
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 Frame, it will find the point of intersection between two straight lines. But for a SkyFrame it will find an intersection of two great circles.

Notes


- For SkyFrames each curve will be a great circle, and in general each pair of curves will intersect at two diametrically opposite points on the sky. The returned position is the one which is closest to point "a1".
- This function will return "bad" coordinate values (AST__BAD) if any of the input coordinates has this value, or if the two points defining either geodesic are co-incident, or if the two curves do not intersect.
- The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistance function.
- An error will be reported if the Frame is not 2-dimensional.

Parameters:
a1 - An array of double, with one element for each Frame axis (Naxes 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.
Returns:
An array of double, with one element for each Frame axis in which the coordinates of the required intersection will be returned.
Throws:
AstException - if an error occurred in the AST library

axOffset

public double axOffset(int axis,
                       double v1,
                       double dist)
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 Frame, this is a trivial operation returning the sum of the two supplied values. But for other derived classes of Frame (such as a SkyFrame) this is not the case.

Notes


- This function will return a "bad" result value (AST__BAD) if any of the input values has this value.
- A "bad" value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:
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.
Returns:
The incremented axis value.
Throws:
AstException - if an error occurred in the AST library

convert

public FrameSet convert(Frame to,
                        String domainlist)
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 FrameSet which describes the conversion and which may be used (as a Mapping) to transform coordinate values in either direction.

The same function may also be used to determine how to convert between two FrameSets (or between a Frame 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 Domain 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.

Notes


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

Parameters:
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.

Returns:
If the requested coordinate conversion is possible, the function returns a pointer to a FrameSet which describes the conversion. Otherwise, a null Object 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 astTran2), 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.

Throws:
AstException - if an error occurred in the AST library

distance

public double distance(double[] point1,
                       double[] point2)
Calculate the distance between two points in a Frame. This function finds the distance between two points whose Frame 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.

Notes


- This function will return a "bad" result value (AST__BAD) if any of the input coordinates has this value.
- A "bad" value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Returns:
The distance between the two points.
Throws:
AstException - if an error occurred in the AST library

findFrame

public FrameSet findFrame(Frame template,
                          String domainlist)
Find a coordinate system with specified characteristics. This function uses a "template" Frame to search another Frame (or FrameSet) to identify a coordinate system which has a specified set of characteristics. If a suitable coordinate system can be found, the function returns a pointer to a FrameSet which describes the required coordinate system and how to convert coordinates to and from it.

This function is provided to help answer general questions about coordinate systems, such as typically arise when coordinate information is imported into a program as part of an initially unknown dataset. For example:
- Is there a wavelength scale?
- Is there a 2-dimensional coordinate system?
- Is there a celestial coordinate system?
- Can I plot the data in ecliptic coordinates?

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

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

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

You can make your request more or less specific by setting attribute values for the template Frame. If a particular attribute is set in the template, then the function will only find coordinate systems which have exactly the same value for that attribute. If you leave a template attribute un-set, however, then the function has discretion about the value the attribute should have in any coordinate system it finds. The attribute will then take its value from one of the actual (rather than virtual) coordinate systems in the target. If the target is a FrameSet, its Current 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 Mapping is then generated which converts from the target coordinate system to this hybrid one, and the returned FrameSet encapsulates all of this information.

Notes


- The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem 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 MinAxes 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 MatchEnd 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.

Parameters:
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 SkyFrame 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 Domain 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.

Returns:
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 Object 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 astTran2), 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.

Throws:
AstException - if an error occurred in the AST library

format

public String format(int axis,
                     double value)
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 Frame 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.

Notes


- The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this.
- A formatted value may be converted back into a numerical (double) value using astUnformat.
- 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.

Parameters:
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.
Returns:
A pointer to a null-terminated string containing the formatted value.
Throws:
AstException - if an error occurred in the AST library

getActiveUnit

public boolean getActiveUnit()
Determines how the Unit attribute will be used. This function returns the current value of the ActiveUnit flag for a Frame. See the description of the astSetActiveUnit function for a description of the ActiveUnit flag.

Notes


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

Returns:
The current value of the ActiveUnit flag.
Throws:
AstException - if an error occurred in the AST library

norm

public void norm(double[] value)
Normalise a set of Frame coordinates. This function normalises a set of Frame 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.

Notes


- For some classes of Frame, whose coordinate values are not constrained, this function will never modify the values supplied. However, for Frames whose axes represent cyclic quantities (such as angles or positions on the sky), coordinates will typically be wrapped into an appropriate standard range, such as zero to 2*pi.
- The NormMap class is a Mapping 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 astFormat).

Parameters:
value - An array of double, with one element for each Frame axis (Naxes 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.
Throws:
AstException - if an error occurred in the AST library

offset

public double[] offset(double[] point1,
                       double[] point2,
                       double offset)
Calculate an offset along a geodesic curve. This function finds the Frame coordinate values of a point which is offset a specified distance along the geodesic curve between two other points.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions.

Notes


- The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistance function.
- This function will return "bad" coordinate values (AST__BAD) if any of the input coordinates has this value.
- "Bad" coordinate values will also be returned if the two points supplied are coincident (or otherwise fail to uniquely specify a geodesic curve) but the requested offset is non-zero.

Parameters:
point1 - An array of double, with one element for each Frame axis (Naxes 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.
Returns:
An array of double, with one element for each Frame axis in which the coordinates of the required point will be returned.
Throws:
AstException - if an error occurred in the AST library

offset2

public double offset2(double[] point1,
                      double angle,
                      double offset,
                      double[] point2)
Calculate an offset along a geodesic curve in a 2D Frame. This function finds the Frame coordinate values of a point which is offset a specified distance along the geodesic curve at a given angle from a specified starting point. It can only be used with 2-dimensional Frames.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions.

Notes


- The geodesic curve used by this function is the path of shortest distance between two points, as defined by the astDistance function.
- An error will be reported if the Frame is not 2-dimensional.
- This function will return "bad" coordinate values (AST__BAD) if any of the input coordinates has this value.

Parameters:
point1 - An array of double, with one element for each Frame axis (Naxes 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.
Returns:
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.
Throws:
AstException - if an error occurred in the AST library

permAxes

public void permAxes(int[] perm)
Permute the axis order in a Frame. This function permutes the order in which a Frame's axes occur.

Notes


- Only genuine permutations of the axis order are permitted, so each axis must be referenced exactly once in the "perm" array.
- If successive axis permutations are applied to a Frame, then the effects are cumulative.

Parameters:
perm - An array with one element for each axis of the Frame (Naxes attribute). This should list the axes in their new order, using the original axis numbering (which starts at 1 for the first axis).
Throws:
AstException - if an error occurred in the AST library

pickAxes

public Frame pickAxes(int naxes,
                      int[] axes,
                      Mapping[] map)
Create a new Frame by picking axes from an existing one. This function creates a new Frame whose axes are copied from an existing Frame along with other Frame attributes, such as its Title. Any number (zero or more) of the original Frame's axes may be copied, in any order, and additional axes with default attributes may also be included in the new Frame.

Optionally, a Mapping that converts between the coordinate systems described by the two Frames will also be returned.

Notes


- The new Frame will contain a "deep" copy (c.f. astCopy) 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 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.

Parameters:
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 PermMap (or a UnitMap as a special case) that describes the axis permutation that has taken place between the original and new Frames. The Mapping's forward transformation will convert coordinates from the original Frame into the new one, and vice versa.

If this Mapping is not required, a NULL value may be supplied for this parameter.

Returns:
A pointer to the new Frame.
Throws:
AstException - if an error occurred in the AST library

resolve

public double[] resolve(double[] point1,
                        double[] point2,
                        double[] point3,
                        double[] point4)
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.

Notes


- Each vector used in this function is the path of shortest distance between two points, as defined by the astDistance function.
- This function will return "bad" coordinate values (AST__BAD) if any of the input coordinates has this value, or if the required output values are undefined.

Parameters:
point1 - An array of double, with one element for each Frame axis (Naxes 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.
Returns:
a two element array in which to return the results. The first element is 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.

The second element is 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.

Throws:
AstException - if an error occurred in the AST library

setActiveUnit

public void setActiveUnit(boolean value)
Specify how the Unit attribute should be used. This function sets the current value of the ActiveUnit flag for a Frame, which controls how the Frame behaves when it is used (by astFindFrame or astConvert) to match another Frame. If the ActiveUnit flag is set in both template and target Frames then the returned Mapping takes into account any differences in axis units. The default value for simple Frames is zero, which preserves the behaviour of versions of AST prior to version 2.0.

If the ActiveUnit flag of either Frame is 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 FrameSet class will use a ZoomMap to connect them which introduces a scaling of 1000. If no Mapping can be found between the corresponding units string, then an error is reported. In this mode, it is assumed that values of the Unit attribute conform to the syntax for units strings described in the FITS WCS Paper I "Representations of world coordinates in FITS" (Greisen & Calabretta). Particularly, any of the named unit symbols, functions, operators or standard multiplier prefixes listed within that paper can be used within a units string. A units string may contain symbols for unit which are not listed in the FITS paper, but transformation to any other units will then not be possible (except to units which depend only on the same unknown units - thus "flops" can be transformed to "Mflops" even though "flops" is not a standard FITS unit symbol).

A range of common non-standard variations of unit names and multiplier prefixes are also allowed, such as adding an "s" to the end of Angstrom, using a lower case "a" at the start of "angstrom", "micron" instead of "um", "sec" instead of "s", etc.

If the ActiveUnit flag is 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 Axis 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).

Notes


- The ActiveUnit flag resembles a Frame attribute, except that it cannot be tested or cleared, and it cannot be accessed using the generic astGet and astSet functions.
- The astGetActiveUnit function can be used to retrieve the current value of the ActiveUnit flag.

Parameters:
value - The new value to use.
Throws:
AstException - if an error occurred in the AST library

unformat

public double unformat(int axis,
                       String string)
Read a formatted coordinate value for a Frame axis. This function reads a formatted coordinate value (given as a character string) for a Frame 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 astFormat.

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
-

SkyFrame Input Format

The input format accepted for a SkyFrame axis is as follows:
- An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. "-12 42 03").
- Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as "124.707", while degrees and decimal arc-minutes might be given as "-13 33.8").
- The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. "720 45 31" is valid, whereas "11 45 61" is not).
- Fields may be separated by white space or by ":" (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. "- 2: 04 : 7.1").
- The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: "d"---degrees; "h"---hours; "m"---minutes of arc or time; "s"---seconds of arc or time; "'" (single quote)---minutes of arc; """ (double quote)---seconds of arc. Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. "-11D 3' 14.4"" or "22h14m11.2s").
- The presence of any of the field identification characters "d", "'" (single quote) or """ (double quote) indicates that the value is to be interpreted as an angle. Conversely, the presence of "h" indicates that it is to be interpreted as a time (with 24 hours corresponding to 360 degrees). Incompatible angle/time identification characters may not be mixed (e.g. "10h14'3"" is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either.
- If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by astFormat are correctly interpreted by astUnformat.
- Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. "-05m13s" is equivalent to "-:05:13"). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. "14:25.4s" specifies minutes and seconds, while "14::25.4s" specifies degrees and seconds).
- If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. "01:02"), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that astFormat would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that astFormat would produce.

This final convention is intended to ensure that values formatted by astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters.

Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include:
- -14d 13m 22.2s (-14d 13' 22.2")
- + 12:34:56.7 (12d 34' 56.7" or 12h 34m 56.7s)
- 001 : 02 : 03.4 (1d 02' 03.4" or 1h 02m 03.4s)
- 22h 30 (22h 30m 00s)
- 136::10" (136d 00' 10" or 136h 00m 10s)
- -14M 27S (-0d 14' 27" or -0h 14m 27s)
- -:14: (-0d 14' 00" or -0h 14m 00s)
- -::4.1 (-0d 00' 04.1" or -0h 00m 04.1s)
- .9" (0d 00' 00.9")
- d12m (0d 12' 00")
- H 12:22.3s (0h 12m 22.3s)
- (AST__BAD)

Where alternative interpretations are shown, the choice of angle or time depends on the associated Format(axis) attribute.

Notes


- A function value of zero (and no coordinate value) will be returned, without error, if the string supplied does not contain a suitably formatted value.
- Beware that it is possible for a formatting error part-way through an input string to terminate input before it has been completely read, but to yield a coordinate value that appears valid. For example, if a user types "1.5r6" instead of "1.5e6", the "r" will terminate input, giving an incorrect coordinate value of 1.5. It is therefore most important to check the return value of this function to ensure that the correct number of characters have been read.
- An error will result if a value is read which appears to have the correct format, but which cannot be converted into a valid coordinate value (for instance, because the value of one or more of its fields is invalid).
- The string "" is recognised as a special case and will yield the coordinate value AST__BAD without error. The test for this string is case-insensitive and also permits embedded white space.
- A function result of zero will be returned and no coordinate value will be returned via the "value" pointer if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:
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.
Returns:
Pointer to a double in which the coordinate value read will be returned.
Throws:
AstException - if an error occurred in the AST library

getAlignSystem

public String getAlignSystem()
Get coordinate system in which to align the Frame. This attribute controls how a Frame behaves when it is used (by astFindFrame or astConvert) as a template to match another (target) Frame. It identifies the coordinate system in which the two Frames will be aligned by the match.

The values which may be assigned to this attribute, and its default value, depend on the class of Frame and are described in the "Applicability" section below. In general, the AlignSystem attribute will accept any of the values which may be assigned to the System attribute.

The Mapping returned by AST_FINDFRAME or AST_CONVERT will use the coordinate system specified by the AlignSystem attribute as an intermediate coordinate system. The total returned Mapping will first map positions from the first Frame into this intermediate coordinate system, using the attributes of the first Frame. It will then map these positions from the intermediate coordinate system into the second Frame, using the attributes of the second Frame.

Class Applicability

Frame
The AlignSystem attribute for a basic Frame always equals "Cartesian", and may not be altered.
CmpFrame
The AlignSystem attribute for a CmpFrame always equals "Compound", and may not be altered.
FrameSet
The AlignSystem attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The default AlignSystem attribute for a SkyFrame is "ICRS".
SpecFrame
The default AlignSystem attribute for a SpecFrame is "Wave" (wavelength).
TimeFrame
The default AlignSystem attribute for a TimeFrame is "MJD".

Returns:
this object's AlignSystem attribute

setAlignSystem

public void setAlignSystem(String alignSystem)
Set coordinate system in which to align the Frame. This attribute controls how a Frame behaves when it is used (by astFindFrame or astConvert) as a template to match another (target) Frame. It identifies the coordinate system in which the two Frames will be aligned by the match.

The values which may be assigned to this attribute, and its default value, depend on the class of Frame and are described in the "Applicability" section below. In general, the AlignSystem attribute will accept any of the values which may be assigned to the System attribute.

The Mapping returned by AST_FINDFRAME or AST_CONVERT will use the coordinate system specified by the AlignSystem attribute as an intermediate coordinate system. The total returned Mapping will first map positions from the first Frame into this intermediate coordinate system, using the attributes of the first Frame. It will then map these positions from the intermediate coordinate system into the second Frame, using the attributes of the second Frame.

Class Applicability

Frame
The AlignSystem attribute for a basic Frame always equals "Cartesian", and may not be altered.
CmpFrame
The AlignSystem attribute for a CmpFrame always equals "Compound", and may not be altered.
FrameSet
The AlignSystem attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The default AlignSystem attribute for a SkyFrame is "ICRS".
SpecFrame
The default AlignSystem attribute for a SpecFrame is "Wave" (wavelength).
TimeFrame
The default AlignSystem attribute for a TimeFrame is "MJD".

Parameters:
alignSystem - the AlignSystem attribute of this object

getBottom

public double getBottom(int axis)
Get lowest axis value to display by axis. This attribute gives the lowest axis value to be displayed (for instance, by the astGrid method).

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is to display all axis values, without any limit.
SkyFrame
The SkyFrame class re-defines the default Bottom value to -90 degrees for latitude axes, and 0 degrees for co-latitude axes. The default for longitude axes is to display all axis values.

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Bottom attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setBottom

public void setBottom(int axis,
                      double bottom)
Set lowest axis value to display by axis. This attribute gives the lowest axis value to be displayed (for instance, by the astGrid method).

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is to display all axis values, without any limit.
SkyFrame
The SkyFrame class re-defines the default Bottom value to -90 degrees for latitude axes, and 0 degrees for co-latitude axes. The default for longitude axes is to display all axis values.

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
bottom - the Bottom attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getDigits

public int getDigits()
Get number of digits of precision. This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a Frame axis (e.g. using astFormat). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole.

Note that the Digits value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string ".*", then the Digits attribute is used to determine the number of decimal places to produce.

Class Applicability

Frame
The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead.
FrameSet
The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the Current attribute).
Plot
The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct.
TimeFrame
The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute).

Returns:
this object's Digits attribute

setDigits

public void setDigits(int digits)
Set number of digits of precision. This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a Frame axis (e.g. using astFormat). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole.

Note that the Digits value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string ".*", then the Digits attribute is used to determine the number of decimal places to produce.

Class Applicability

Frame
The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead.
FrameSet
The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the Current attribute).
Plot
The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct.
TimeFrame
The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute).

Parameters:
digits - the Digits attribute of this object

getDigits

public int getDigits(int axis)
Get number of digits of precision by axis. This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a Frame axis (e.g. using astFormat). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole.

Note that the Digits value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string ".*", then the Digits attribute is used to determine the number of decimal places to produce.

Class Applicability

Frame
The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead.
FrameSet
The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the Current attribute).
Plot
The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct.
TimeFrame
The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute).

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Digits attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setDigits

public void setDigits(int axis,
                      int digits)
Set number of digits of precision by axis. This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a Frame axis (e.g. using astFormat). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole.

Note that the Digits value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string ".*", then the Digits attribute is used to determine the number of decimal places to produce.

Class Applicability

Frame
The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead.
FrameSet
The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the Current attribute).
Plot
The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct.
TimeFrame
The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute).

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
digits - the Digits attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getDirection

public boolean getDirection(int axis)
Get display axis in conventional direction by axis. This attribute is a boolean value which suggests how the axes of a Frame should be displayed (e.g.) in graphical output. By default, it has the value one, indicating that they should be shown in the conventional sense (increasing left to right for an abscissa, and bottom to top for an ordinate). If set to zero, this attribute indicates that the direction should be reversed, as would often be done for an astronomical magnitude or a right ascension axis.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.
- The Direction attribute does not directly affect the behaviour of the AST library. Instead, it serves as a hint to applications programs about the orientation in which they may wish to display any data associated with the Frame. Applications are free to ignore this hint if they wish.

Class Applicability

Frame
The default Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction.
SkyFrame
The SkyFrame class re-defines the default Direction value to suggest that certain axes (e.g. right ascension) should be plotted in reverse when appropriate.
FrameSet
The Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).
Plot
The Direction attribute of the base Frame in a Plot is set to indicate the sense of the two graphics axes, as implied by the graphics bounding box supplied when the Plot was created.

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Direction attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setDirection

public void setDirection(int axis,
                         boolean direction)
Set display axis in conventional direction by axis. This attribute is a boolean value which suggests how the axes of a Frame should be displayed (e.g.) in graphical output. By default, it has the value one, indicating that they should be shown in the conventional sense (increasing left to right for an abscissa, and bottom to top for an ordinate). If set to zero, this attribute indicates that the direction should be reversed, as would often be done for an astronomical magnitude or a right ascension axis.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.
- The Direction attribute does not directly affect the behaviour of the AST library. Instead, it serves as a hint to applications programs about the orientation in which they may wish to display any data associated with the Frame. Applications are free to ignore this hint if they wish.

Class Applicability

Frame
The default Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction.
SkyFrame
The SkyFrame class re-defines the default Direction value to suggest that certain axes (e.g. right ascension) should be plotted in reverse when appropriate.
FrameSet
The Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).
Plot
The Direction attribute of the base Frame in a Plot is set to indicate the sense of the two graphics axes, as implied by the graphics bounding box supplied when the Plot was created.

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
direction - the Direction attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getDomain

public String getDomain()
Get coordinate system domain. This attribute contains a string which identifies the physical domain of the coordinate system that a Frame describes.

The Domain attribute also controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It does this by specifying the Domain that the target Frame should have in order to match the template. If the Domain value in the template Frame is set, then only targets with the same Domain value will be matched. If the template's Domain value is not set, however, then the target's Domain will be ignored.

Notes


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

Class Applicability

Frame
The default Domain value supplied by the Frame class is an empty string.
SkyFrame
The SkyFrame class re-defines the default Domain value to be "SKY".
CmpFrame
The CmpFrame class re-defines the default Domain value to be of the form "-", where and are the Domains of the two component Frames. If both these Domains are blank, then the string "CMP" is used as the default Domain name.
FrameSet
The Domain attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SpecFrame
The SpecFrame class re-defines the default Domain value to be "SPECTRUM".
DSBSpecFrame
The DSBSpecFrame class re-defines the default Domain value to be "DSBSPECTRUM".
FluxFrame
The FluxFrame class re-defines the default Domain value to be "FLUX".
SpecFluxFrame
The FluxFrame class re-defines the default Domain value to be "SPECTRUM-FLUX".
TimeFrame
The TimeFrame class re-defines the default Domain value to be "TIME".

Returns:
this object's Domain attribute

setDomain

public void setDomain(String domain)
Set coordinate system domain. This attribute contains a string which identifies the physical domain of the coordinate system that a Frame describes.

The Domain attribute also controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It does this by specifying the Domain that the target Frame should have in order to match the template. If the Domain value in the template Frame is set, then only targets with the same Domain value will be matched. If the template's Domain value is not set, however, then the target's Domain will be ignored.

Notes


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

Class Applicability

Frame
The default Domain value supplied by the Frame class is an empty string.
SkyFrame
The SkyFrame class re-defines the default Domain value to be "SKY".
CmpFrame
The CmpFrame class re-defines the default Domain value to be of the form "-", where and are the Domains of the two component Frames. If both these Domains are blank, then the string "CMP" is used as the default Domain name.
FrameSet
The Domain attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SpecFrame
The SpecFrame class re-defines the default Domain value to be "SPECTRUM".
DSBSpecFrame
The DSBSpecFrame class re-defines the default Domain value to be "DSBSPECTRUM".
FluxFrame
The FluxFrame class re-defines the default Domain value to be "FLUX".
SpecFluxFrame
The FluxFrame class re-defines the default Domain value to be "SPECTRUM-FLUX".
TimeFrame
The TimeFrame class re-defines the default Domain value to be "TIME".

Parameters:
domain - the Domain attribute of this object

getDut1

public double getDut1()
Get the UT1-UTC correction. This attribute is used when calculating the Local Apparent Sidereal Time corresponding to SkyFrame's Epoch value (used when converting positions to or from the "AzEl" system). It should be set to the difference, in seconds, between the UT1 and UTC timescales at the moment in time represented by the SkyFrame's Epoch attribute. The value to use is unpredictable and depends on changes in the earth's rotation speed. Values for UT1-UTC can be obtained from the International Earth Rotation and Reference Systems Service (IERS) at http://www.iers.org/.

Currently, the correction is always less than 1 second. This is ensured by the occasional introduction of leap seconds into the UTC timescale. Therefore no great error will usually result if no value is assigned to this attribute (in which case a default value of zero is used). However, it is possible that a decision may be taken at some time in the future to abandon the introduction of leap seconds, in which case the DUT correction could grow to significant sizes.

Returns:
this object's Dut1 attribute

setDut1

public void setDut1(double dut1)
Set the UT1-UTC correction. This attribute is used when calculating the Local Apparent Sidereal Time corresponding to SkyFrame's Epoch value (used when converting positions to or from the "AzEl" system). It should be set to the difference, in seconds, between the UT1 and UTC timescales at the moment in time represented by the SkyFrame's Epoch attribute. The value to use is unpredictable and depends on changes in the earth's rotation speed. Values for UT1-UTC can be obtained from the International Earth Rotation and Reference Systems Service (IERS) at http://www.iers.org/.

Currently, the correction is always less than 1 second. This is ensured by the occasional introduction of leap seconds into the UTC timescale. Therefore no great error will usually result if no value is assigned to this attribute (in which case a default value of zero is used). However, it is possible that a decision may be taken at some time in the future to abandon the introduction of leap seconds, in which case the DUT correction could grow to significant sizes.

Parameters:
dut1 - the Dut1 attribute of this object

getEpoch

public double getEpoch()
Get epoch of observation. This attribute is used to qualify the coordinate systems described by a Frame, by giving the moment in time when the coordinates are known to be correct. Often, this will be the date of observation, and is important in cases where coordinates systems move with respect to each other over the course of time.

The Epoch attribute is stored as a Modified Julian Date, but when setting its value it may be given in a variety of formats. See the "Input Formats" section (below) for details. Strictly, the Epoch value should be supplied in the TDB timescale, but for some purposes (for instance, for converting sky positions between different types of equatorial system) the timescale is not significant, and UTC may be used.

Input Formats

The formats accepted when setting an Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:


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


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


- Year: Decimal years, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise.


- Julian Date: With or without decimal places ("JD 2454321.9" for example).


- Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).


- Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).


- Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

When enquiring Epoch values, the format used is the "Year" format described under "Input Formats". This is a value in decimal years which will be a Besselian epoch if less than 1984.0 and a Julian epoch otherwise. By omitting any character prefix, this format allows the Epoch value to be obtained as either a character string or a floating point value.

Class Applicability

Frame
All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the System attribute).
CmpFrame
The default Epoch value for a CmpFrame is selected as follows; if the Epoch attribute has been set in the first component Frame then the Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch attribute has been set in the second component Frame then the Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames.
FrameSet
The Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The coordinates of sources within a SkyFrame can changed with time for various reasons, including: (i) changing aberration of light caused by the observer's velocity (e.g. due to the Earth's motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer's position with time, (iii) fictitious motion due to rotation of non-inertial coordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame class because it affects individual sources rather than the coordinate system as a whole).

The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the System attribute) and J2000.0 (Julian) for all others.

Care must be taken to distinguish the Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar Equinox value. The latter is used to qualify a coordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator).

See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system.

TimeFrame
A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch value. For this reason the TimeFrame class makes no use of the Epoch attribute. However, user code can still make use of the attribute if necessary to represent a "typical" time spanned by the TimeFrame. The default Epoch value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame's TimeOrigin attribute. If no value has been set for TimeOrigin, then the default Epoch value is J2000.0.

Returns:
this object's Epoch attribute

setEpoch

public void setEpoch(double epoch)
Set epoch of observation. This attribute is used to qualify the coordinate systems described by a Frame, by giving the moment in time when the coordinates are known to be correct. Often, this will be the date of observation, and is important in cases where coordinates systems move with respect to each other over the course of time.

The Epoch attribute is stored as a Modified Julian Date, but when setting its value it may be given in a variety of formats. See the "Input Formats" section (below) for details. Strictly, the Epoch value should be supplied in the TDB timescale, but for some purposes (for instance, for converting sky positions between different types of equatorial system) the timescale is not significant, and UTC may be used.

Input Formats

The formats accepted when setting an Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:


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


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


- Year: Decimal years, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise.


- Julian Date: With or without decimal places ("JD 2454321.9" for example).


- Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).


- Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).


- Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

When enquiring Epoch values, the format used is the "Year" format described under "Input Formats". This is a value in decimal years which will be a Besselian epoch if less than 1984.0 and a Julian epoch otherwise. By omitting any character prefix, this format allows the Epoch value to be obtained as either a character string or a floating point value.

Class Applicability

Frame
All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the System attribute).
CmpFrame
The default Epoch value for a CmpFrame is selected as follows; if the Epoch attribute has been set in the first component Frame then the Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch attribute has been set in the second component Frame then the Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames.
FrameSet
The Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The coordinates of sources within a SkyFrame can changed with time for various reasons, including: (i) changing aberration of light caused by the observer's velocity (e.g. due to the Earth's motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer's position with time, (iii) fictitious motion due to rotation of non-inertial coordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame class because it affects individual sources rather than the coordinate system as a whole).

The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the System attribute) and J2000.0 (Julian) for all others.

Care must be taken to distinguish the Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar Equinox value. The latter is used to qualify a coordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator).

See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system.

TimeFrame
A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch value. For this reason the TimeFrame class makes no use of the Epoch attribute. However, user code can still make use of the attribute if necessary to represent a "typical" time spanned by the TimeFrame. The default Epoch value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame's TimeOrigin attribute. If no value has been set for TimeOrigin, then the default Epoch value is J2000.0.

Parameters:
epoch - the Epoch attribute of this object

setEpoch

public void setEpoch(String epoch)
Set epoch of observation. This attribute is used to qualify the coordinate systems described by a Frame, by giving the moment in time when the coordinates are known to be correct. Often, this will be the date of observation, and is important in cases where coordinates systems move with respect to each other over the course of time.

The Epoch attribute is stored as a Modified Julian Date, but when setting its value it may be given in a variety of formats. See the "Input Formats" section (below) for details. Strictly, the Epoch value should be supplied in the TDB timescale, but for some purposes (for instance, for converting sky positions between different types of equatorial system) the timescale is not significant, and UTC may be used.

Input Formats

The formats accepted when setting an Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:


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


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


- Year: Decimal years, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise.


- Julian Date: With or without decimal places ("JD 2454321.9" for example).


- Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).


- Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).


- Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

When enquiring Epoch values, the format used is the "Year" format described under "Input Formats". This is a value in decimal years which will be a Besselian epoch if less than 1984.0 and a Julian epoch otherwise. By omitting any character prefix, this format allows the Epoch value to be obtained as either a character string or a floating point value.

Class Applicability

Frame
All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the System attribute).
CmpFrame
The default Epoch value for a CmpFrame is selected as follows; if the Epoch attribute has been set in the first component Frame then the Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch attribute has been set in the second component Frame then the Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames.
FrameSet
The Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The coordinates of sources within a SkyFrame can changed with time for various reasons, including: (i) changing aberration of light caused by the observer's velocity (e.g. due to the Earth's motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer's position with time, (iii) fictitious motion due to rotation of non-inertial coordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame class because it affects individual sources rather than the coordinate system as a whole).

The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the System attribute) and J2000.0 (Julian) for all others.

Care must be taken to distinguish the Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar Equinox value. The latter is used to qualify a coordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator).

See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system.

TimeFrame
A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch value. For this reason the TimeFrame class makes no use of the Epoch attribute. However, user code can still make use of the attribute if necessary to represent a "typical" time spanned by the TimeFrame. The default Epoch value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame's TimeOrigin attribute. If no value has been set for TimeOrigin, then the default Epoch value is J2000.0.

Parameters:
epoch - formatted string giving the Epoch attribute of this object

getFormat

public String getFormat(int axis)
Get format specification for axis values by axis. This attribute specifies the format to be used when displaying coordinate values associated with a particular Frame axis (i.e. to convert values from binary to character form). It is interpreted by the astFormat function and determines the formatting which it applies.

If no Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits, or Digits(axis), attribute and is chosen so that it displays the requested number of digits of precision.

SkyFrame Formats

The Format string supplied for a SkyFrame should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity:


- "+": Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used.


- "z": Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added.


- "i": Use the standard ISO field separator (a colon) between fields. This is the default behaviour.


- "b": Use a blank to separate fields.


- "l": Use a letter ("h"/"d", "m" or "s" as appropriate) to separate fields.


- "g": Use a letter and symbols to separate fields ("h"/"d", "m" or "s", etc, as appropriate), but include escape sequences in the formatted value so that the Plot class will draw the separators as small super-scripts. The default escape sequences are optimised for the pgplot graphics package, but new escape sequences may be specified using function astSetSkyDelim.


- "d": Include a degrees field. Expressing the angle purely in degrees is also the default if none of "h", "m", "s" or "t" are given.


- "h": Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if "t" is given without either "m" or "s".


- "m": Include a minutes field. By default this is not included.


- "s": Include a seconds field. By default this is not included. This request is ignored if "d" or "h" is given, unless a minutes field is also included.


- "t": Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either "d" or "h" is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If "t" is given without "d", "h", "m" or "s" being present, then it is equivalent to "h".


- ".": Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The "." should be followed immediately by an unsigned integer which gives the number of decimal places required, or by an asterisk. If an asterisk is supplied, a default number of decimal places is used which is based on the value of the Digits attribute.

All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both "i" and "b" appear), then the character occurring last takes precedence, except that "d" and "h" always override "t".

If the format string starts with a percentage sign (%), then the whole format string is assumed to conform to the syntax defined by the Frame class, and the axis values is formated as a decimal radians value.

TimeFrame Formats

The Format string supplied for a TimeFrame should either use the syntax defined by the base Frame class (i.e. a C "printf" format string), or the extended "iso" syntax described below (the default value is inherited from the Frame class):


- C "printf" syntax: If the Format string is a C "printf" format description such as "%1.7G", the TimeFrame axis value will be formatted without change as a floating point value using this format. The formatted string will thus represent an offset from the zero point specified by the TimeFrame's TimeOrigin attribute, measured in units given by the TimeFrame's Unit attribute.


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

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The Frame class interprets this attribute as a format specification string to be passed to the C "printf" function (e.g. "%1.7G") in order to format a single coordinate value (supplied as a double precision number).

When supplying a value for this attribute, beware that the "%" character may be interpreted directly as a format specification by some printf-like functions (such as astSet). You may need to double it (i.e. use "%%") to avoid this.

SkyFrame
The SkyFrame class re-defines the syntax and default value of the Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the "SkyFrame Formats" section.
FrameSet
The Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute). Note that the syntax of the Format string is also determined by the current Frame.
TimeFrame
The TimeFrame class extends the syntax of the Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format strings is described (below) in the "TimeFrame Formats" section.

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Format attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setFormat

public void setFormat(int axis,
                      String format)
Set format specification for axis values by axis. This attribute specifies the format to be used when displaying coordinate values associated with a particular Frame axis (i.e. to convert values from binary to character form). It is interpreted by the astFormat function and determines the formatting which it applies.

If no Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits, or Digits(axis), attribute and is chosen so that it displays the requested number of digits of precision.

SkyFrame Formats

The Format string supplied for a SkyFrame should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity:


- "+": Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used.


- "z": Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added.


- "i": Use the standard ISO field separator (a colon) between fields. This is the default behaviour.


- "b": Use a blank to separate fields.


- "l": Use a letter ("h"/"d", "m" or "s" as appropriate) to separate fields.


- "g": Use a letter and symbols to separate fields ("h"/"d", "m" or "s", etc, as appropriate), but include escape sequences in the formatted value so that the Plot class will draw the separators as small super-scripts. The default escape sequences are optimised for the pgplot graphics package, but new escape sequences may be specified using function astSetSkyDelim.


- "d": Include a degrees field. Expressing the angle purely in degrees is also the default if none of "h", "m", "s" or "t" are given.


- "h": Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if "t" is given without either "m" or "s".


- "m": Include a minutes field. By default this is not included.


- "s": Include a seconds field. By default this is not included. This request is ignored if "d" or "h" is given, unless a minutes field is also included.


- "t": Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either "d" or "h" is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If "t" is given without "d", "h", "m" or "s" being present, then it is equivalent to "h".


- ".": Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The "." should be followed immediately by an unsigned integer which gives the number of decimal places required, or by an asterisk. If an asterisk is supplied, a default number of decimal places is used which is based on the value of the Digits attribute.

All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both "i" and "b" appear), then the character occurring last takes precedence, except that "d" and "h" always override "t".

If the format string starts with a percentage sign (%), then the whole format string is assumed to conform to the syntax defined by the Frame class, and the axis values is formated as a decimal radians value.

TimeFrame Formats

The Format string supplied for a TimeFrame should either use the syntax defined by the base Frame class (i.e. a C "printf" format string), or the extended "iso" syntax described below (the default value is inherited from the Frame class):


- C "printf" syntax: If the Format string is a C "printf" format description such as "%1.7G", the TimeFrame axis value will be formatted without change as a floating point value using this format. The formatted string will thus represent an offset from the zero point specified by the TimeFrame's TimeOrigin attribute, measured in units given by the TimeFrame's Unit attribute.


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

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The Frame class interprets this attribute as a format specification string to be passed to the C "printf" function (e.g. "%1.7G") in order to format a single coordinate value (supplied as a double precision number).

When supplying a value for this attribute, beware that the "%" character may be interpreted directly as a format specification by some printf-like functions (such as astSet). You may need to double it (i.e. use "%%") to avoid this.

SkyFrame
The SkyFrame class re-defines the syntax and default value of the Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the "SkyFrame Formats" section.
FrameSet
The Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute). Note that the syntax of the Format string is also determined by the current Frame.
TimeFrame
The TimeFrame class extends the syntax of the Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format strings is described (below) in the "TimeFrame Formats" section.

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
format - the Format attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getLabel

public String getLabel(int axis)
Get axis label by axis. This attribute specifies a label to be attached to each axis of a Frame when it is represented (e.g.) in graphical output.

If a Label value has not been set for a Frame axis, then a suitable default is supplied.

Notes


- Axis labels are intended purely for interpretation by human readers and not by software.
- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is the string "Axis ", where is 1, 2, etc. for each successive axis.
SkyFrame
The SkyFrame class re-defines the default Label value (e.g. to "Right ascension" or "Galactic latitude") as appropriate for the particular celestial coordinate system being represented.
TimeFrame
The TimeFrame class re-defines the default Label value as appropriate for the particular time system being represented.
FrameSet
The Label attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Label attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setLabel

public void setLabel(int axis,
                     String label)
Set axis label by axis. This attribute specifies a label to be attached to each axis of a Frame when it is represented (e.g.) in graphical output.

If a Label value has not been set for a Frame axis, then a suitable default is supplied.

Notes


- Axis labels are intended purely for interpretation by human readers and not by software.
- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is the string "Axis ", where is 1, 2, etc. for each successive axis.
SkyFrame
The SkyFrame class re-defines the default Label value (e.g. to "Right ascension" or "Galactic latitude") as appropriate for the particular celestial coordinate system being represented.
TimeFrame
The TimeFrame class re-defines the default Label value as appropriate for the particular time system being represented.
FrameSet
The Label attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
label - the Label attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getMatchEnd

public boolean getMatchEnd()
Get match trailing axes. This attribute is a boolean value which controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It applies only in the case where a match occurs between template and target Frames with different numbers of axes.

If the MatchEnd value of the template Frame is zero, then the axes which occur first in the target Frame will be matched and any trailing axes (in either the target or template) will be disregarded. If it is non-zero, the final axes in each Frame will be matched and any un-matched leading axes will be disregarded instead.

Class Applicability

Frame
The default MatchEnd value for a Frame is zero, so that trailing axes are disregarded.
FrameSet
The MatchEnd attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Returns:
this object's MatchEnd attribute

setMatchEnd

public void setMatchEnd(boolean matchEnd)
Set match trailing axes. This attribute is a boolean value which controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It applies only in the case where a match occurs between template and target Frames with different numbers of axes.

If the MatchEnd value of the template Frame is zero, then the axes which occur first in the target Frame will be matched and any trailing axes (in either the target or template) will be disregarded. If it is non-zero, the final axes in each Frame will be matched and any un-matched leading axes will be disregarded instead.

Class Applicability

Frame
The default MatchEnd value for a Frame is zero, so that trailing axes are disregarded.
FrameSet
The MatchEnd attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
matchEnd - the MatchEnd attribute of this object

getMaxAxes

public int getMaxAxes()
Get maximum number of Frame axes to match. This attribute controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It specifies the maximum number of axes that the target Frame may have in order to match the template.

Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes.

Notes


- When setting a MaxAxes value, the value of the MinAxes attribute may also be silently changed so that it remains consistent with (i.e. does not exceed) the new value. The default MaxAxes value may also be reduced to remain consistent with the MinAxes value.
- If a template Frame is used to match a target with a different number of axes, the MatchEnd attribute of the template is used to determine how the individual axes of each Frame should match.

Class Applicability

Frame
The default MaxAxes value for a Frame is equal to the number of Frame axes (Naxes attribute).
CmpFrame
The MaxAxes attribute of a CmpFrame defaults to a large number (1000000) which is much larger than any likely number of axes in a Frame. Combined with the MinAxes default of zero (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MaxAxes and MinAxes attributes to the number of axes in the CmpFrame.
FrameSet
The MaxAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Returns:
this object's MaxAxes attribute

setMaxAxes

public void setMaxAxes(int maxAxes)
Set maximum number of Frame axes to match. This attribute controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It specifies the maximum number of axes that the target Frame may have in order to match the template.

Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes.

Notes


- When setting a MaxAxes value, the value of the MinAxes attribute may also be silently changed so that it remains consistent with (i.e. does not exceed) the new value. The default MaxAxes value may also be reduced to remain consistent with the MinAxes value.
- If a template Frame is used to match a target with a different number of axes, the MatchEnd attribute of the template is used to determine how the individual axes of each Frame should match.

Class Applicability

Frame
The default MaxAxes value for a Frame is equal to the number of Frame axes (Naxes attribute).
CmpFrame
The MaxAxes attribute of a CmpFrame defaults to a large number (1000000) which is much larger than any likely number of axes in a Frame. Combined with the MinAxes default of zero (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MaxAxes and MinAxes attributes to the number of axes in the CmpFrame.
FrameSet
The MaxAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
maxAxes - the MaxAxes attribute of this object

getMinAxes

public int getMinAxes()
Get minimum number of Frame axes to match. This attribute controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It specifies the minimum number of axes that the target Frame may have in order to match the template.

Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes.

Notes


- When setting a MinAxes value, the value of the MaxAxes attribute may also be silently changed so that it remains consistent with (i.e. is not less than) the new value. The default MinAxes value may also be reduced to remain consistent with the MaxAxes value.
- If a template Frame is used to match a target with a different number of axes, the MatchEnd attribute of the template is used to determine how the individual axes of each Frame should match.

Class Applicability

Frame
The default MinAxes value for a Frame is equal to the number of Frame axes (Naxes attribute).
CmpFrame
The MinAxes attribute of a CmpFrame defaults to zero. Combined with the MaxAxes default of 1000000 (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MinAxes and MaxAxes attributes to the number of axes in the CmpFrame.
FrameSet
The MinAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Returns:
this object's MinAxes attribute

setMinAxes

public void setMinAxes(int minAxes)
Set minimum number of Frame axes to match. This attribute controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It specifies the minimum number of axes that the target Frame may have in order to match the template.

Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes.

Notes


- When setting a MinAxes value, the value of the MaxAxes attribute may also be silently changed so that it remains consistent with (i.e. is not less than) the new value. The default MinAxes value may also be reduced to remain consistent with the MaxAxes value.
- If a template Frame is used to match a target with a different number of axes, the MatchEnd attribute of the template is used to determine how the individual axes of each Frame should match.

Class Applicability

Frame
The default MinAxes value for a Frame is equal to the number of Frame axes (Naxes attribute).
CmpFrame
The MinAxes attribute of a CmpFrame defaults to zero. Combined with the MaxAxes default of 1000000 (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MinAxes and MaxAxes attributes to the number of axes in the CmpFrame.
FrameSet
The MinAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
minAxes - the MinAxes attribute of this object

getNaxes

public int getNaxes()
Get number of Frame axes. This is a read-only attribute giving the number of axes in a Frame (i.e. the number of dimensions of the coordinate space which the Frame describes). This value is determined when the Frame is created.

Class Applicability

Frame
All Frames have this attribute.
FrameSet
The Naxes attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
CmpFrame
The Naxes attribute of a CmpFrame is equal to the sum of the Naxes values of its two component Frames.

Returns:
this object's Naxes attribute

getObsLat

public String getObsLat()
Get the geodetic latitude of the observer. This attribute specifies the geodetic latitude of the observer, in degrees, relative to the IAU 1976 reference ellipsoid. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.

The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "22:19:23.2", "22 19 23.2", "22:19.387", "22.32311", "N22.32311", "-45.6", "S45.6". As indicated, the sign of the latitude can optionally be indicated using characters "N" and "S" in place of the usual "+" and "-". When converting the stored value to a string, the format "[s]dd:mm:ss.ss" is used, when "[s]" is "N" or "S".

Class Applicability

Frame
All Frames have this attribute.
SpecFrame
Together with the ObsLon, Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
TimeFrame
Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

Returns:
this object's ObsLat attribute

setObsLat

public void setObsLat(String obsLat)
Set the geodetic latitude of the observer. This attribute specifies the geodetic latitude of the observer, in degrees, relative to the IAU 1976 reference ellipsoid. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.

The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "22:19:23.2", "22 19 23.2", "22:19.387", "22.32311", "N22.32311", "-45.6", "S45.6". As indicated, the sign of the latitude can optionally be indicated using characters "N" and "S" in place of the usual "+" and "-". When converting the stored value to a string, the format "[s]dd:mm:ss.ss" is used, when "[s]" is "N" or "S".

Class Applicability

Frame
All Frames have this attribute.
SpecFrame
Together with the ObsLon, Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
TimeFrame
Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

Parameters:
obsLat - the ObsLat attribute of this object

getObsLon

public String getObsLon()
Get the geodetic longitude of the observer. This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute ObsLat. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.

The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "155:19:23.2", "155 19 23.2", "155:19.387", "155.32311", "E155.32311", "-204.67689", "W204.67689". As indicated, the sign of the longitude can optionally be indicated using characters "E" and "W" in place of the usual "+" and "-". When converting the stored value to a string, the format "[s]ddd:mm:ss.ss" is used, when "[s]" is "E" or "W" and the numerical value is chosen to be less than 180 degrees.

Class Applicability

Frame
All Frames have this attribute.
SpecFrame
Together with the ObsLon, Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
TimeFrame
Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

Returns:
this object's ObsLon attribute

setObsLon

public void setObsLon(String obsLon)
Set the geodetic longitude of the observer. This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute ObsLat. The basic Frame class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame classes use it. The default value is zero.

The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "155:19:23.2", "155 19 23.2", "155:19.387", "155.32311", "E155.32311", "-204.67689", "W204.67689". As indicated, the sign of the longitude can optionally be indicated using characters "E" and "W" in place of the usual "+" and "-". When converting the stored value to a string, the format "[s]ddd:mm:ss.ss" is used, when "[s]" is "E" or "W" and the numerical value is chosen to be less than 180 degrees.

Class Applicability

Frame
All Frames have this attribute.
SpecFrame
Together with the ObsLon, Epoch, RefRA and RefDec attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero.
TimeFrame
Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST)

Parameters:
obsLon - the ObsLon attribute of this object

getPermute

public boolean getPermute()
Get permute axis order. This attribute is a boolean value which controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It specifies whether the axis order of the target Frame may be permuted in order to obtain a match.

If the template's Permute value is zero, it will match a target only if it can do so without changing the order of its axes. Otherwise, it will attempt to permute the target's axes as necessary.

The default value is 1, so that axis permutation will be attempted.

Class Applicability

Frame
All Frames have this attribute. However, the Frame class effectively ignores this attribute and behaves as if it has the value 1. This is because the axes of a basic Frame are not distinguishable and will always match any other Frame whatever their order.
SkyFrame
Unlike a basic Frame, the SkyFrame class makes use of this attribute.
FrameSet
The Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Returns:
this object's Permute attribute

setPermute

public void setPermute(boolean permute)
Set permute axis order. This attribute is a boolean value which controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It specifies whether the axis order of the target Frame may be permuted in order to obtain a match.

If the template's Permute value is zero, it will match a target only if it can do so without changing the order of its axes. Otherwise, it will attempt to permute the target's axes as necessary.

The default value is 1, so that axis permutation will be attempted.

Class Applicability

Frame
All Frames have this attribute. However, the Frame class effectively ignores this attribute and behaves as if it has the value 1. This is because the axes of a basic Frame are not distinguishable and will always match any other Frame whatever their order.
SkyFrame
Unlike a basic Frame, the SkyFrame class makes use of this attribute.
FrameSet
The Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
permute - the Permute attribute of this object

getPreserveAxes

public boolean getPreserveAxes()
Get preserve axes. This attribute controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It determines which axes appear (and in what order) in the "result" Frame produced.

If PreserveAxes is zero in the template Frame, then the result Frame will have the same number (and order) of axes as the template. If it is non-zero, however, the axes of the target Frame will be preserved, so that the result Frame will have the same number (and order) of axes as the target.

The default value is zero, so that target axes are not preserved and the result Frame resembles the template.

Returns:
this object's PreserveAxes attribute

setPreserveAxes

public void setPreserveAxes(boolean preserveAxes)
Set preserve axes. This attribute controls how a Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame. It determines which axes appear (and in what order) in the "result" Frame produced.

If PreserveAxes is zero in the template Frame, then the result Frame will have the same number (and order) of axes as the template. If it is non-zero, however, the axes of the target Frame will be preserved, so that the result Frame will have the same number (and order) of axes as the target.

The default value is zero, so that target axes are not preserved and the result Frame resembles the template.

Parameters:
preserveAxes - the PreserveAxes attribute of this object

getSymbol

public String getSymbol(int axis)
Get axis symbol by axis. This attribute specifies a short-form symbol to be used to represent coordinate values for a particular axis of a Frame. This might be used (e.g.) in algebraic expressions where a full description of the axis would be inappropriate. Examples include "RA" and "Dec" (for Right Ascension and Declination).

If a Symbol value has not been set for a Frame axis, then a suitable default is supplied.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default Symbol value supplied by the Frame class is the string "", where is 1, 2, etc. for successive axes, and is the value of the Frame's Domain attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain value has been set, "x" is used as the value in constructing this default string.
SkyFrame
The SkyFrame class re-defines the default Symbol value (e.g. to "RA" or "Dec") as appropriate for the particular celestial coordinate system being represented.
TimeFrame
The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented.
FrameSet
The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Symbol attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setSymbol

public void setSymbol(int axis,
                      String symbol)
Set axis symbol by axis. This attribute specifies a short-form symbol to be used to represent coordinate values for a particular axis of a Frame. This might be used (e.g.) in algebraic expressions where a full description of the axis would be inappropriate. Examples include "RA" and "Dec" (for Right Ascension and Declination).

If a Symbol value has not been set for a Frame axis, then a suitable default is supplied.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default Symbol value supplied by the Frame class is the string "", where is 1, 2, etc. for successive axes, and is the value of the Frame's Domain attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain value has been set, "x" is used as the value in constructing this default string.
SkyFrame
The SkyFrame class re-defines the default Symbol value (e.g. to "RA" or "Dec") as appropriate for the particular celestial coordinate system being represented.
TimeFrame
The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented.
FrameSet
The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
symbol - the Symbol attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getSystem

public String getSystem()
Get coordinate system used to describe positions within the domain. In general it is possible for positions within a given physical domain to be described using one of several different coordinate systems. For instance, the SkyFrame class can use galactic coordinates, equatorial coordinates, etc, to describe positions on the sky. As another example, the SpecFrame class can use frequency, wavelength, velocity, etc, to describe a position within an electromagnetic spectrum. The System attribute identifies the particular coordinate system represented by a Frame. Each class of Frame defines a set of acceptable values for this attribute, as listed below (all are case insensitive). Where more than one alternative System value is shown, the first of will be returned when an enquiry is made.

Class Applicability

Frame
The System attribute for a basic Frame always equals "Cartesian", and may not be altered.
CmpFrame
The System attribute for a CmpFrame always equals "Compound", and may not be altered. In addition, the CmpFrame class allows the System attribute to be referenced for a component Frame by including the index of an axis within the required component Frame. For instance, "System(3)" refers to the System attribute of the component Frame which includes axis 3 of the CmpFrame.
FrameSet
The System attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The SkyFrame class supports the following System values and associated celestial coordinate systems:

- "AZEL": Horizon coordinates. The longitude axis is azimuth such that geographic north has an azimuth of zero and geographic east has an azimuth of +PI/2 radians. The zenith has elevation +PI/2. When converting to and from other celestial coordinate systems, no corrections are applied for atmospheric refraction or polar motion (however, a correction for diurnal aberattion is applied). Note, unlike most other celestial coordinate systems, this system is right handed. Also, unlike other SkyFrame systems, the AzEl system is sensitive to the timescale in which the Epoch value is supplied. This is because of the gross diurnal rotation which this system undergoes, causing a small change in time to translate to a large rotation. When converting to or from an AzEl system, the Epoch value for both source and destination SkyFrames should be supplied in the TDB timescale. The difference between TDB and TT is between 1 and 2 milliseconds, and so a TT value can usually be supplied in place of a TDB value. The TT timescale is related to TAI via TT = TAI + 32.184 seconds.

- "ECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox specified by the qualifying Equinox value.

- "FK4": The old FK4 (barycentric) equatorial coordinate system, which should be qualified by an Equinox value. The underlying model on which this is based is non-inertial and rotates slowly with time, so for accurate work FK4 coordinate systems should also be qualified by an Epoch value.

- "FK4-NO-E" or "FK4_NO_E": The old FK4 (barycentric) equatorial system but without the "E-terms of aberration" (e.g. some radio catalogues). This coordinate system should also be qualified by both an Equinox and an Epoch value.

- "FK5" or "EQUATORIAL": The modern FK5 (barycentric) equatorial coordinate system. This should be qualified by an Equinox value.

- "GALACTIC": Galactic coordinates (IAU 1958).

- "GAPPT", "GEOCENTRIC" or "APPARENT": The geocentric apparent equatorial coordinate system, which gives the apparent positions of sources relative to the true plane of the Earth's equator and the equinox (the coordinate origin) at a time specified by the qualifying Epoch value. (Note that no Equinox is needed to qualify this coordinate system because no model "mean equinox" is involved.) These coordinates give the apparent right ascension and declination of a source for a specified date of observation, and therefore form an approximate basis for pointing a telescope. Note, however, that they are applicable to a fictitious observer at the Earth's centre, and therefore ignore such effects as atmospheric refraction and the (normally much smaller) aberration of light due to the rotational velocity of the Earth's surface. Geocentric apparent coordinates are derived from the standard FK5 (J2000.0) barycentric coordinates by taking account of the gravitational deflection of light by the Sun (usually small), the aberration of light caused by the motion of the Earth's centre with respect to the barycentre (larger), and the precession and nutation of the Earth's spin axis (normally larger still).

- "HELIOECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox of J2000.0, in which an offset is added to the longitude value which results in the centre of the sun being at zero longitude at the date given by the Epoch attribute. Attempts to set a value for the Equinox attribute will be ignored, since this system is always referred to J2000.0.

- "ICRS": The Internation Celestial Reference System, realised through the Hipparcos catalogue. Whilst not an equatorial system by definition, the ICRS is very close to the FK5 (J2000) system and is usually treated as an equatorial system. The distinction between ICRS and FK5 (J2000) only becomes important when accuracies of 50 milli-arcseconds or better are required. ICRS need not be qualified by an Equinox value.

- "J2000": An equatorial coordinate system based on the mean dynamical equator and equinox of the J2000 epoch. The dynamical equator and equinox differ slightly from those used by the FK5 model, and so a "J2000" SkyFrame will differ slightly from an "FK5(Equinox=J2000)" SkyFrame. The J2000 System need not be qualified by an Equinox value

- "SUPERGALACTIC": De Vaucouleurs Supergalactic coordinates.

- "UNKNOWN": Any other general spherical coordinate system. No Mapping can be created between a pair of SkyFrames if either of the SkyFrames has System set to "Unknown".

Currently, the default System value is "ICRS". However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in future). If you intend to use the ICRS system indefinitely, then you should specify it explicitly.

SpecFrame
The SpecFrame class supports the following System values and associated spectral coordinate systems (the default is "WAVE" - wavelength). They are all defined in FITS-WCS paper III:

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

The default value for the Unit attribute for each system is shown in parentheses. Note that the default value for the ActiveUnit flag is non-zero for a SpecFrame, meaning that changes to the Unit attribute for a SpecFrame will result in the SpecFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information).

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

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

The default value for the Unit attribute for each system is shown in parentheses. Strictly, these systems should not allow changes to be made to the units. For instance, the usual definition of "MJD" and "JD" include the statement that the values will be in units of days. However, AST does allow the use of other units with all the above supported systems (except BEPOCH), on the understanding that conversion to the "correct" units involves nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined in terms of tropical years of 365.2422 days, rather than the usual Julian year of 365.25 days. Therefore, to avoid any confusion, the Unit attribute is automatically cleared to "yr" when a System value of BEPOCH System is selected, and an error is reported if any attempt is subsequently made to change the Unit attribute.

Note that the default value for the ActiveUnit flag is non-zero for a TimeFrame, meaning that changes to the Unit attribute for a TimeFrame will result in the TimeFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information).

FluxFrame
The FluxFrame class supports the following System values and associated systems for measuring observed value:

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

The above lists specified the default units for each System. If an explicit value is set for the Unit attribute but no value is set for System, then the default System value is determined by the Unit string (if the units are not appropriate for describing any of the supported Systems then an error will be reported when an attempt is made to access the System value). If no value has been specified for either Unit or System, then System=FLXDN and Unit=W/m^2/Hz are used.

Returns:
this object's System attribute

setSystem

public void setSystem(String system)
Set coordinate system used to describe positions within the domain. In general it is possible for positions within a given physical domain to be described using one of several different coordinate systems. For instance, the SkyFrame class can use galactic coordinates, equatorial coordinates, etc, to describe positions on the sky. As another example, the SpecFrame class can use frequency, wavelength, velocity, etc, to describe a position within an electromagnetic spectrum. The System attribute identifies the particular coordinate system represented by a Frame. Each class of Frame defines a set of acceptable values for this attribute, as listed below (all are case insensitive). Where more than one alternative System value is shown, the first of will be returned when an enquiry is made.

Class Applicability

Frame
The System attribute for a basic Frame always equals "Cartesian", and may not be altered.
CmpFrame
The System attribute for a CmpFrame always equals "Compound", and may not be altered. In addition, the CmpFrame class allows the System attribute to be referenced for a component Frame by including the index of an axis within the required component Frame. For instance, "System(3)" refers to the System attribute of the component Frame which includes axis 3 of the CmpFrame.
FrameSet
The System attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).
SkyFrame
The SkyFrame class supports the following System values and associated celestial coordinate systems:

- "AZEL": Horizon coordinates. The longitude axis is azimuth such that geographic north has an azimuth of zero and geographic east has an azimuth of +PI/2 radians. The zenith has elevation +PI/2. When converting to and from other celestial coordinate systems, no corrections are applied for atmospheric refraction or polar motion (however, a correction for diurnal aberattion is applied). Note, unlike most other celestial coordinate systems, this system is right handed. Also, unlike other SkyFrame systems, the AzEl system is sensitive to the timescale in which the Epoch value is supplied. This is because of the gross diurnal rotation which this system undergoes, causing a small change in time to translate to a large rotation. When converting to or from an AzEl system, the Epoch value for both source and destination SkyFrames should be supplied in the TDB timescale. The difference between TDB and TT is between 1 and 2 milliseconds, and so a TT value can usually be supplied in place of a TDB value. The TT timescale is related to TAI via TT = TAI + 32.184 seconds.

- "ECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox specified by the qualifying Equinox value.

- "FK4": The old FK4 (barycentric) equatorial coordinate system, which should be qualified by an Equinox value. The underlying model on which this is based is non-inertial and rotates slowly with time, so for accurate work FK4 coordinate systems should also be qualified by an Epoch value.

- "FK4-NO-E" or "FK4_NO_E": The old FK4 (barycentric) equatorial system but without the "E-terms of aberration" (e.g. some radio catalogues). This coordinate system should also be qualified by both an Equinox and an Epoch value.

- "FK5" or "EQUATORIAL": The modern FK5 (barycentric) equatorial coordinate system. This should be qualified by an Equinox value.

- "GALACTIC": Galactic coordinates (IAU 1958).

- "GAPPT", "GEOCENTRIC" or "APPARENT": The geocentric apparent equatorial coordinate system, which gives the apparent positions of sources relative to the true plane of the Earth's equator and the equinox (the coordinate origin) at a time specified by the qualifying Epoch value. (Note that no Equinox is needed to qualify this coordinate system because no model "mean equinox" is involved.) These coordinates give the apparent right ascension and declination of a source for a specified date of observation, and therefore form an approximate basis for pointing a telescope. Note, however, that they are applicable to a fictitious observer at the Earth's centre, and therefore ignore such effects as atmospheric refraction and the (normally much smaller) aberration of light due to the rotational velocity of the Earth's surface. Geocentric apparent coordinates are derived from the standard FK5 (J2000.0) barycentric coordinates by taking account of the gravitational deflection of light by the Sun (usually small), the aberration of light caused by the motion of the Earth's centre with respect to the barycentre (larger), and the precession and nutation of the Earth's spin axis (normally larger still).

- "HELIOECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox of J2000.0, in which an offset is added to the longitude value which results in the centre of the sun being at zero longitude at the date given by the Epoch attribute. Attempts to set a value for the Equinox attribute will be ignored, since this system is always referred to J2000.0.

- "ICRS": The Internation Celestial Reference System, realised through the Hipparcos catalogue. Whilst not an equatorial system by definition, the ICRS is very close to the FK5 (J2000) system and is usually treated as an equatorial system. The distinction between ICRS and FK5 (J2000) only becomes important when accuracies of 50 milli-arcseconds or better are required. ICRS need not be qualified by an Equinox value.

- "J2000": An equatorial coordinate system based on the mean dynamical equator and equinox of the J2000 epoch. The dynamical equator and equinox differ slightly from those used by the FK5 model, and so a "J2000" SkyFrame will differ slightly from an "FK5(Equinox=J2000)" SkyFrame. The J2000 System need not be qualified by an Equinox value

- "SUPERGALACTIC": De Vaucouleurs Supergalactic coordinates.

- "UNKNOWN": Any other general spherical coordinate system. No Mapping can be created between a pair of SkyFrames if either of the SkyFrames has System set to "Unknown".

Currently, the default System value is "ICRS". However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in future). If you intend to use the ICRS system indefinitely, then you should specify it explicitly.

SpecFrame
The SpecFrame class supports the following System values and associated spectral coordinate systems (the default is "WAVE" - wavelength). They are all defined in FITS-WCS paper III:

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

The default value for the Unit attribute for each system is shown in parentheses. Note that the default value for the ActiveUnit flag is non-zero for a SpecFrame, meaning that changes to the Unit attribute for a SpecFrame will result in the SpecFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information).

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

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

The default value for the Unit attribute for each system is shown in parentheses. Strictly, these systems should not allow changes to be made to the units. For instance, the usual definition of "MJD" and "JD" include the statement that the values will be in units of days. However, AST does allow the use of other units with all the above supported systems (except BEPOCH), on the understanding that conversion to the "correct" units involves nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined in terms of tropical years of 365.2422 days, rather than the usual Julian year of 365.25 days. Therefore, to avoid any confusion, the Unit attribute is automatically cleared to "yr" when a System value of BEPOCH System is selected, and an error is reported if any attempt is subsequently made to change the Unit attribute.

Note that the default value for the ActiveUnit flag is non-zero for a TimeFrame, meaning that changes to the Unit attribute for a TimeFrame will result in the TimeFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information).

FluxFrame
The FluxFrame class supports the following System values and associated systems for measuring observed value:

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

The above lists specified the default units for each System. If an explicit value is set for the Unit attribute but no value is set for System, then the default System value is determined by the Unit string (if the units are not appropriate for describing any of the supported Systems then an error will be reported when an attempt is made to access the System value). If no value has been specified for either Unit or System, then System=FLXDN and Unit=W/m^2/Hz are used.

Parameters:
system - the System attribute of this object

getTitle

public String getTitle()
Get frame title. This attribute holds a string which is used as a title in (e.g.) graphical output to describe the coordinate system which a Frame represents. Examples might be "Detector Coordinates" or "Galactic Coordinates".

If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame.

Notes


- A Frame's Title is intended purely for interpretation by human readers and not by software.

Class Applicability

Frame
The default supplied by the Frame class is "-d coordinate system", where is the number of Frame axes (Naxes attribute).
CmpFrame
The CmpFrame class re-defines the default Title value to be "-d compound coordinate system", where is the number of CmpFrame axes (Naxes attribute).
FrameSet
The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Returns:
this object's Title attribute

setTitle

public void setTitle(String title)
Set frame title. This attribute holds a string which is used as a title in (e.g.) graphical output to describe the coordinate system which a Frame represents. Examples might be "Detector Coordinates" or "Galactic Coordinates".

If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame.

Notes


- A Frame's Title is intended purely for interpretation by human readers and not by software.

Class Applicability

Frame
The default supplied by the Frame class is "-d coordinate system", where is the number of Frame axes (Naxes attribute).
CmpFrame
The CmpFrame class re-defines the default Title value to be "-d compound coordinate system", where is the number of CmpFrame axes (Naxes attribute).
FrameSet
The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
title - the Title attribute of this object

getTop

public double getTop(int axis)
Get highest axis value to display by axis. This attribute gives the highest axis value to be displayed (for instance, by the astGrid method).

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is to display all axis values, without any limit.
SkyFrame
The SkyFrame class re-defines the default Top value to +90 degrees for latitude axes, and 180 degrees for co-latitude axes. The default for longitude axes is to display all axis values.

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Top attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setTop

public void setTop(int axis,
                   double top)
Set highest axis value to display by axis. This attribute gives the highest axis value to be displayed (for instance, by the astGrid method).

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is to display all axis values, without any limit.
SkyFrame
The SkyFrame class re-defines the default Top value to +90 degrees for latitude axes, and 180 degrees for co-latitude axes. The default for longitude axes is to display all axis values.

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
top - the Top attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getUnit

public String getUnit(int axis)
Get axis physical units by axis. This attribute contains a textual representation of the physical units used to represent coordinate values on a particular axis of a Frame. The astSetActiveUnit function controls how the Unit values are used.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is an empty string.
SkyFrame
The SkyFrame class re-defines the default Unit value (e.g. to "hh:mm:ss.sss") to describe the character string returned by the astFormat function when formatting coordinate values.
SpecFrame
The SpecFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit.
TimeFrame
The TimeFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit (e.g. "km").
FrameSet
The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the Unit attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setUnit

public void setUnit(int axis,
                    String unit)
Set axis physical units by axis. This attribute contains a textual representation of the physical units used to represent coordinate values on a particular axis of a Frame. The astSetActiveUnit function controls how the Unit values are used.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Class Applicability

Frame
The default supplied by the Frame class is an empty string.
SkyFrame
The SkyFrame class re-defines the default Unit value (e.g. to "hh:mm:ss.sss") to describe the character string returned by the astFormat function when formatting coordinate values.
SpecFrame
The SpecFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit.
TimeFrame
The TimeFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit (e.g. "km").
FrameSet
The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute).

Parameters:
axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.
unit - the Unit attribute for the indicated axis of this object.
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getNormUnit

public String getNormUnit(int axis)
Get normalised Axis physical units by axis. The value of this read-only attribute is derived from the current value of the Unit attribute. It will represent an equivalent system of units to the Unit attribute, but will potentially be simplified. For instance, if Unit is set to "s*(m/s)", the NormUnit value will be "m". If no simplification can be performed, the value of the NormUnit attribute will equal that of the Unit attribute.

Notes


- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

Parameters:
axis - index of the axis for which the attribute is to be got. Must be >= 1 and <= the value of the Naxes attribute.
Returns:
the NormUnit attribute for the indicated axis of this object
Throws:
IndexOutOfBoundsException - if axis is not in the range 1..Naxes


Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.