public class Frame extends Mapping
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.
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
Mapping.Interpolator, Mapping.Spreader
LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER
AST__BAD, AST__TUNULL, pointer
Modifier | Constructor and Description |
---|---|
protected |
Frame()
Dummy constructor.
|
|
Frame(int naxes)
Creates a new Frame.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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
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
public Frame(int naxes)
naxes
- The number of Frame axes (i.e. the number of dimensions of
the coordinate space which the Frame describes).AstException
- if an error occurred in the AST libraryprotected Frame()
public double angle(double[] a, double[] b, double[] c)
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.AstException
- if an error occurred in the AST librarypublic double axAngle(double[] a, double[] b, int axis)
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).AstException
- if an error occurred in the AST librarypublic double axDistance(int axis, double v1, double 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.
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.AstException
- if an error occurred in the AST librarypublic double[] intersect(double[] a1, double[] a2, double[] b1, double[] b2)
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.
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.AstException
- if an error occurred in the AST librarypublic double axOffset(int axis, double v1, double dist)
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.
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.AstException
- if an error occurred in the AST librarypublic FrameSet convert(Frame to, String domainlist)
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.
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.
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.
AstException
- if an error occurred in the AST librarypublic double distance(double[] point1, double[] point2)
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.
AstException
- if an error occurred in the AST librarypublic FrameSet findFrame(Frame template, String domainlist)
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.
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.
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.
AstException
- if an error occurred in the AST librarypublic String format(int axis, double value)
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.AstException
- if an error occurred in the AST librarypublic boolean getActiveUnit()
AstException
- if an error occurred in the AST librarypublic void norm(double[] value)
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.AstException
- if an error occurred in the AST librarypublic double[] offset(double[] point1, double[] point2, double offset)
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.
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.AstException
- if an error occurred in the AST librarypublic double offset2(double[] point1, double angle, double offset, double[] point2)
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.
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.AstException
- if an error occurred in the AST librarypublic void permAxes(int[] perm)
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).AstException
- if an error occurred in the AST librarypublic Frame pickAxes(int naxes, int[] axes, Mapping[] map)
Optionally, a Mapping that converts between the coordinate systems described by the two Frames will also be returned.
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.
AstException
- if an error occurred in the AST librarypublic double[] resolve(double[] point1, double[] point2, double[] point3, double[] point4)
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.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.
AstException
- if an error occurred in the AST librarypublic void setActiveUnit(boolean value)
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).
value
- The new value to use.AstException
- if an error occurred in the AST librarypublic double unformat(int axis, String 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.
Examples of acceptable Frame input formats include:
- 99
- 1.25
- -1.6
- 1E8
- -.99e-17
- <bad>
This final convention is intended to ensure that values formatted by astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters.
Examples of acceptable SkyFrame input formats (with
interpretation in parentheses) include:
- -14d 13m 22.2s (-14d 13' 22.2")
- + 12:34:56.7 (12d 34' 56.7" or 12h 34m 56.7s)
- 001 : 02 : 03.4 (1d 02' 03.4" or 1h 02m 03.4s)
- 22h 30 (22h 30m 00s)
- 136::10" (136d 00' 10" or 136h 00m 10s)
- -14M 27S (-0d 14' 27" or -0h 14m 27s)
- -:14: (-0d 14' 00" or -0h 14m 00s)
- -::4.1 (-0d 00' 04.1" or -0h 00m 04.1s)
- .9" (0d 00' 00.9")
- d12m (0d 12' 00")
- H 12:22.3s (0h 12m 22.3s)
- <bad> (AST__BAD)
Where alternative interpretations are shown, the choice of angle or time depends on the associated Format(axis) attribute.
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.AstException
- if an error occurred in the AST librarypublic String getAlignSystem()
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.
public void setAlignSystem(String alignSystem)
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.
alignSystem
- the AlignSystem attribute of this objectpublic double getBottom(int axis)
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setBottom(int axis, double bottom)
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public int getDigits()
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.
public void setDigits(int digits)
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.
digits
- the Digits attribute of this objectpublic int getDigits(int axis)
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.
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setDigits(int axis, int digits)
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.
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public boolean getDirection(int axis)
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setDirection(int axis, boolean direction)
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public String getDomain()
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.
public void setDomain(String domain)
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.
domain
- the Domain attribute of this objectpublic double getDut1()
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.
public void setDut1(double dut1)
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.
dut1
- the Dut1 attribute of this objectpublic double getEpoch()
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.
- 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).
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.
public void setEpoch(double epoch)
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.
- 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).
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.
epoch
- the Epoch attribute of this objectpublic void setEpoch(String epoch)
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.
- 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).
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.
epoch
- formatted string giving the Epoch
attribute of this objectpublic String getFormat(int axis)
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.
- "+": 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.
- 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.
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.
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setFormat(int axis, String format)
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.
- "+": 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.
- 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.
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.
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public String getLabel(int axis)
If a Label value has not been set for a Frame axis, then a suitable default is supplied.
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setLabel(int axis, String label)
If a Label value has not been set for a Frame axis, then a suitable default is supplied.
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public boolean getMatchEnd()
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.
public void setMatchEnd(boolean matchEnd)
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.
matchEnd
- the MatchEnd attribute of this objectpublic int getMaxAxes()
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.
public void setMaxAxes(int maxAxes)
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.
maxAxes
- the MaxAxes attribute of this objectpublic int getMinAxes()
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.
public void setMinAxes(int minAxes)
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.
minAxes
- the MinAxes attribute of this objectpublic int getNaxes()
public String getObsLat()
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".
public void setObsLat(String obsLat)
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".
obsLat
- the ObsLat attribute of this objectpublic String getObsLon()
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.
public void setObsLon(String obsLon)
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.
obsLon
- the ObsLon attribute of this objectpublic boolean getPermute()
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.
public void setPermute(boolean permute)
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.
permute
- the Permute attribute of this objectpublic boolean getPreserveAxes()
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.
public void setPreserveAxes(boolean preserveAxes)
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.
preserveAxes
- the PreserveAxes attribute of this objectpublic String getSymbol(int axis)
If a Symbol value has not been set for a Frame axis, then a suitable default is supplied.
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setSymbol(int axis, String symbol)
If a Symbol value has not been set for a Frame axis, then a suitable default is supplied.
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public String getSystem()
- "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.
- "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).
- "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).
- "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.
public void setSystem(String system)
- "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.
- "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).
- "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).
- "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.
system
- the System attribute of this objectpublic String getTitle()
If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame.
public void setTitle(String title)
If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame.
title
- the Title attribute of this objectpublic double getTop(int axis)
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setTop(int axis, double top)
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public String getUnit(int axis)
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public void setUnit(int axis, String unit)
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.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
public String getNormUnit(int axis)
axis
- index of the axis for which the attribute is to be got.
Must be >= 1 and <= the value of the Naxes
attribute.IndexOutOfBoundsException
- if axis
is not in the
range 1..Naxes
Copyright © 2024 Central Laboratory of the Research Councils. All Rights Reserved.