uk.ac.starlink.ast

Class SkyFrame

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.Frame

uk.ac.starlink.ast.SkyFrame

public class SkyFrame
extends Frame

Java interface to the AST SkyFrame class - celestial coordinate system description. A SkyFrame is a specialised form of Frame which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame's System attribute (currently, the default is ICRS) qualified, as necessary, by a mean Equinox value and/or an Epoch.

For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified reference point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef, SkyRefIs, SkyRefP and AlignOffset.

All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using astFormat.

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 SkyFrame

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

Constructors

Constructor and Description
SkyFrame() Create a SkyFrame.

Method Summary

Modifier and Type	Method and Description
boolean	getAlignOffset() Get align SkyFrames using the offset coordinate system.
boolean	getAsTime(int axis) Get format celestal coordinates as times by axis.
double	getEquinox() Get epoch of the mean equinox.
int	getLatAxis() Get index of the latitude axis.
int	getLonAxis() Get index of the longitude axis.
boolean	getNegLon() Get display negative longitude values.
String	getProjection() Get sky projection description.
String	getSkyRef() Get position defining the offset coordinate system.
double	getSkyRef(int axis) Get position defining the offset coordinate system by axis.
String	getSkyRefIs() Get selects the nature of the offset coordinate system.
String	getSkyRefP() Get position on primary meridian of offset coordinate system.
double	getSkyRefP(int axis) Get position on primary meridian of offset coordinate system by axis.
void	setAlignOffset(boolean alignOffset) Set align SkyFrames using the offset coordinate system.
void	setAsTime(int axis, boolean asTime) Set format celestal coordinates as times by axis.
void	setEquinox(double equinox) Set epoch of the mean equinox.
void	setNegLon(boolean negLon) Set display negative longitude values.
void	setProjection(String projection) Set sky projection description.
void	setSkyRef(int axis, double skyRef) Set position defining the offset coordinate system by axis.
void	setSkyRef(String skyRef) Set position defining the offset coordinate system.
void	setSkyRefIs(String skyRefIs) Set selects the nature of the offset coordinate system.
void	setSkyRefP(int axis, double skyRefP) Set position on primary meridian of offset coordinate system by axis.
void	setSkyRefP(String skyRefP) Set position on primary meridian of offset coordinate system.

Methods inherited from class uk.ac.starlink.ast.Frame

angle, axAngle, axDistance, axOffset, convert, distance, findFrame, format, getActiveUnit, getAlignSystem, getBottom, getDigits, getDigits, getDirection, getDomain, getDut1, getEpoch, getFormat, getLabel, getMatchEnd, getMaxAxes, getMinAxes, getNaxes, getNormUnit, getObsLat, getObsLon, getPermute, getPreserveAxes, getSymbol, getSystem, getTitle, getTop, getUnit, intersect, norm, offset, offset2, permAxes, pickAxes, resolve, setActiveUnit, setAlignSystem, setBottom, setDigits, setDigits, setDirection, setDomain, setDut1, setEpoch, setEpoch, setFormat, setLabel, setMatchEnd, setMaxAxes, setMinAxes, setObsLat, setObsLon, setPermute, setPreserveAxes, setSymbol, setSystem, setTitle, setTop, setUnit, unformat

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

SkyFrame

public SkyFrame()

Create a SkyFrame.

Throws:

AstException - if an error occurred in the AST library

Method Detail

getAsTime

public boolean getAsTime(int axis)

Get format celestal coordinates as times by axis. This attribute specifies the default style of formatting to be used (e.g. by astFormat) for the celestial coordinate values described by a SkyFrame. It takes a separate boolean value for each SkyFrame axis so that, for instance, the setting "AsTime(2)=0" specifies the default formatting style for celestial latitude values.

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

The default value of AsTime is chosen according to the sky coordinate system being represented, as determined by the SkyFrame's System attribute. This ensures, for example, that right ascension values will be formatted as times by default, following normal conventions.

Notes

- The AsTime attribute operates by changing the default value of the corresponding Format(axis) attribute. This, in turn, may also affect the value of the Unit(axis) attribute.
- Only the default style of formatting is affected by the AsTime value. If an explicit Format(axis) value is set, it will over-ride any effect from the AsTime attribute.

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 AsTime attribute for the indicated axis of this object

Throws:

IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setAsTime

public void setAsTime(int axis,
                      boolean asTime)

Set format celestal coordinates as times by axis. This attribute specifies the default style of formatting to be used (e.g. by astFormat) for the celestial coordinate values described by a SkyFrame. It takes a separate boolean value for each SkyFrame axis so that, for instance, the setting "AsTime(2)=0" specifies the default formatting style for celestial latitude values.

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

The default value of AsTime is chosen according to the sky coordinate system being represented, as determined by the SkyFrame's System attribute. This ensures, for example, that right ascension values will be formatted as times by default, following normal conventions.

Notes

- The AsTime attribute operates by changing the default value of the corresponding Format(axis) attribute. This, in turn, may also affect the value of the Unit(axis) attribute.
- Only the default style of formatting is affected by the AsTime value. If an explicit Format(axis) value is set, it will over-ride any effect from the AsTime attribute.

Parameters:

axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.

asTime - the AsTime attribute for the indicated axis of this object.

Throws:

IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getEquinox

public double getEquinox()

Get epoch of the mean equinox. This attribute is used to qualify those celestial coordinate systems described by a SkyFrame which are notionally based on the ecliptic (the plane of the Earth's orbit around the Sun) and/or the Earth's equator.

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

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

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

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

Notes

- Care must be taken to distinguish the Equinox value, which relates to the definition of a time-dependent coordinate system (based on solar system reference planes which are in motion), from the superficially similar Epoch value. The latter is used to qualify coordinate systems where the positions of sources change with time (or appear to do so) for a variety of other reasons, such as aberration of light caused by the observer's motion, etc.
- See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system.

Returns:

this object's Equinox attribute

setEquinox

public void setEquinox(double equinox)

Set epoch of the mean equinox. This attribute is used to qualify those celestial coordinate systems described by a SkyFrame which are notionally based on the ecliptic (the plane of the Earth's orbit around the Sun) and/or the Earth's equator.

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

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

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

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

Notes

- Care must be taken to distinguish the Equinox value, which relates to the definition of a time-dependent coordinate system (based on solar system reference planes which are in motion), from the superficially similar Epoch value. The latter is used to qualify coordinate systems where the positions of sources change with time (or appear to do so) for a variety of other reasons, such as aberration of light caused by the observer's motion, etc.
- See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system.

Parameters:

equinox - the Equinox attribute of this object

getLatAxis

public int getLatAxis()

Get index of the latitude axis. This read-only attribute gives the index (1 or 2) of the latitude axis within the SkyFrame (taking into account any current axis permutations).

Returns:

this object's LatAxis attribute

getLonAxis

public int getLonAxis()

Get index of the longitude axis. This read-only attribute gives the index (1 or 2) of the longitude axis within the SkyFrame (taking into account any current axis permutations).

Returns:

this object's LonAxis attribute

getNegLon

public boolean getNegLon()

Get display negative longitude values. This attribute is a boolean value which controls how longitude values are normalized for display by astNorm.

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

The default value depends on the current value of the SkyRefIs attribute, If SkyRefIs has a value of "Origin", then the default for NegLon is one, otherwise the default is zero.

Returns:

this object's NegLon attribute

setNegLon

public void setNegLon(boolean negLon)

Set display negative longitude values. This attribute is a boolean value which controls how longitude values are normalized for display by astNorm.

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

The default value depends on the current value of the SkyRefIs attribute, If SkyRefIs has a value of "Origin", then the default for NegLon is one, otherwise the default is zero.

Parameters:

negLon - the NegLon attribute of this object

getProjection

public String getProjection()

Get sky projection description. This attribute provides a place to store a description of the type of sky projection used when a SkyFrame is attached to a 2-dimensional object, such as an image or plotting surface. For example, typical values might be "orthographic", "Hammer-Aitoff" or "cylindrical equal area".

The Projection value is purely descriptive and does not affect the celestial coordinate system represented by the SkyFrame in any way. If it is set to a non-blank string, the description provided may be used when forming the default value for the SkyFrame's Title attribute (so that typically it will appear in graphical output, for instance). The default value is an empty string.

Returns:

this object's Projection attribute

setProjection

public void setProjection(String projection)

Set sky projection description. This attribute provides a place to store a description of the type of sky projection used when a SkyFrame is attached to a 2-dimensional object, such as an image or plotting surface. For example, typical values might be "orthographic", "Hammer-Aitoff" or "cylindrical equal area".

The Projection value is purely descriptive and does not affect the celestial coordinate system represented by the SkyFrame in any way. If it is set to a non-blank string, the description provided may be used when forming the default value for the SkyFrame's Title attribute (so that typically it will appear in graphical output, for instance). The default value is an empty string.

Parameters:

projection - the Projection attribute of this object

getAlignOffset

public boolean getAlignOffset()

Get align SkyFrames using the offset coordinate system. This attribute is a boolean value which controls how a SkyFrame behaves when it is used (by astFindFrame or astConvert) as a template to match another (target) SkyFrame. It determines the coordinate system in which the two SkyFrames are aligned if a match occurs.

If the template and target SkyFrames both have defined offset coordinate systems (i.e. the SkyRefIs attribute is set to either "Origin" or " Pole"), and they both have a non-zero value for AlignOffset, then alignment occurs within the offset coordinate systems (that is, a UnitMap will always be used to align the two SkyFrames). If either the template or target SkyFrame has zero (the default value) for AlignOffset, or if either SkyFrame has SkyRefIs set to "Ignored", then alignment occurring within the coordinate system specified by the AlignSystem attribute.

Returns:

this object's AlignOffset attribute

setAlignOffset

public void setAlignOffset(boolean alignOffset)

Set align SkyFrames using the offset coordinate system. This attribute is a boolean value which controls how a SkyFrame behaves when it is used (by astFindFrame or astConvert) as a template to match another (target) SkyFrame. It determines the coordinate system in which the two SkyFrames are aligned if a match occurs.

If the template and target SkyFrames both have defined offset coordinate systems (i.e. the SkyRefIs attribute is set to either "Origin" or " Pole"), and they both have a non-zero value for AlignOffset, then alignment occurs within the offset coordinate systems (that is, a UnitMap will always be used to align the two SkyFrames). If either the template or target SkyFrame has zero (the default value) for AlignOffset, or if either SkyFrame has SkyRefIs set to "Ignored", then alignment occurring within the coordinate system specified by the AlignSystem attribute.

Parameters:

alignOffset - the AlignOffset attribute of this object

getSkyRefIs

public String getSkyRefIs()

Get selects the nature of the offset coordinate system. This attribute controls how the values supplied for the SkyRef and SkyRefP attributes are used. These three attributes together allow a SkyFrame to represent offsets relative to some specified origin or pole within the coordinate system specified by the System attribute, rather than absolute axis values. SkyRefIs can take one of the case-insensitive values "Origin", "Pole" or "Ignored".

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

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

If SkyRefIs is set to "Ignored" (the default), then any value set for the SkyRef attribute is ignored, and the SkyFrame represents the coordinate system specified by the System attribute directly without any rotation.

Returns:

this object's SkyRefIs attribute

setSkyRefIs

public void setSkyRefIs(String skyRefIs)

Set selects the nature of the offset coordinate system. This attribute controls how the values supplied for the SkyRef and SkyRefP attributes are used. These three attributes together allow a SkyFrame to represent offsets relative to some specified origin or pole within the coordinate system specified by the System attribute, rather than absolute axis values. SkyRefIs can take one of the case-insensitive values "Origin", "Pole" or "Ignored".

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

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

If SkyRefIs is set to "Ignored" (the default), then any value set for the SkyRef attribute is ignored, and the SkyFrame represents the coordinate system specified by the System attribute directly without any rotation.

Parameters:

skyRefIs - the SkyRefIs attribute of this object

getSkyRef

public double getSkyRef(int axis)

Get position defining the offset coordinate system by axis. This attribute allows a SkyFrame to represent offsets, rather than absolute axis values, within the coordinate system specified by the System attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the SkyRefIs attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute.

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

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

The default values for SkyRef are zero longitude and zero latitude.

Aligning SkyFrames with Offset Coordinate Systems

The offset coordinate system within a SkyFrame should normally be considered as a superficial "re-badging" of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical "label" for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may "drift" with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the astConvert or astFindFrame routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the AlignSystem attribute. However, by setting the AlignOffset attribute ot a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames.

Notes

- If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System.
- If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending " offset" to the end, the default axis Symbols for the SkyFrame are modified by prepending the character "D" to the start, and the default title is modified by replacing the projection information by the origin information.

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 SkyRef attribute for the indicated axis of this object

Throws:

IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setSkyRef

public void setSkyRef(int axis,
                      double skyRef)

Set position defining the offset coordinate system by axis. This attribute allows a SkyFrame to represent offsets, rather than absolute axis values, within the coordinate system specified by the System attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the SkyRefIs attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute.

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

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

The default values for SkyRef are zero longitude and zero latitude.

Aligning SkyFrames with Offset Coordinate Systems

The offset coordinate system within a SkyFrame should normally be considered as a superficial "re-badging" of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical "label" for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may "drift" with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the astConvert or astFindFrame routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the AlignSystem attribute. However, by setting the AlignOffset attribute ot a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames.

Notes

- If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System.
- If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending " offset" to the end, the default axis Symbols for the SkyFrame are modified by prepending the character "D" to the start, and the default title is modified by replacing the projection information by the origin information.

Parameters:

axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.

skyRef - the SkyRef attribute for the indicated axis of this object.

Throws:

IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getSkyRef

public String getSkyRef()

Get position defining the offset coordinate system. This attribute allows a SkyFrame to represent offsets, rather than absolute axis values, within the coordinate system specified by the System attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the SkyRefIs attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute.

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

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

The default values for SkyRef are zero longitude and zero latitude.

Aligning SkyFrames with Offset Coordinate Systems

The offset coordinate system within a SkyFrame should normally be considered as a superficial "re-badging" of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical "label" for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may "drift" with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the astConvert or astFindFrame routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the AlignSystem attribute. However, by setting the AlignOffset attribute ot a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames.

Notes

- If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System.
- If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending " offset" to the end, the default axis Symbols for the SkyFrame are modified by prepending the character "D" to the start, and the default title is modified by replacing the projection information by the origin information.

Returns:

this object's SkyRef attribute

setSkyRef

public void setSkyRef(String skyRef)

Set position defining the offset coordinate system. This attribute allows a SkyFrame to represent offsets, rather than absolute axis values, within the coordinate system specified by the System attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the SkyRefIs attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute.

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

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

The default values for SkyRef are zero longitude and zero latitude.

Aligning SkyFrames with Offset Coordinate Systems

The offset coordinate system within a SkyFrame should normally be considered as a superficial "re-badging" of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical "label" for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may "drift" with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the astConvert or astFindFrame routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the AlignSystem attribute. However, by setting the AlignOffset attribute ot a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames.

Notes

- If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System.
- If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending " offset" to the end, the default axis Symbols for the SkyFrame are modified by prepending the character "D" to the start, and the default title is modified by replacing the projection information by the origin information.

Parameters:

skyRef - the SkyRef attribute of this object

getSkyRefP

public double getSkyRefP(int axis)

Get position on primary meridian of offset coordinate system by axis. This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and SkyRefIs. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The offset coordinate system represented by the SkyFrame will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of +90 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute).

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

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

Notes

- If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to "origin"), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude).
- An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation.
- If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System.

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 SkyRefP attribute for the indicated axis of this object

Throws:

IndexOutOfBoundsException - if axis is not in the range 1..Naxes

setSkyRefP

public void setSkyRefP(int axis,
                       double skyRefP)

Set position on primary meridian of offset coordinate system by axis. This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and SkyRefIs. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The offset coordinate system represented by the SkyFrame will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of +90 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute).

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

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

Notes

- If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to "origin"), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude).
- An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation.
- If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System.

Parameters:

axis - index of the axis for which the attribute is to be set. Must be >= 1 and <= the value of the Naxes attribute.

skyRefP - the SkyRefP attribute for the indicated axis of this object.

Throws:

IndexOutOfBoundsException - if axis is not in the range 1..Naxes

getSkyRefP

public String getSkyRefP()

Get position on primary meridian of offset coordinate system. This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and SkyRefIs. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The offset coordinate system represented by the SkyFrame will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of +90 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute).

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

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

Notes

- If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to "origin"), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude).
- An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation.
- If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System.

Returns:

this object's SkyRefP attribute

setSkyRefP

public void setSkyRefP(String skyRefP)

Set position on primary meridian of offset coordinate system. This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and SkyRefIs. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The offset coordinate system represented by the SkyFrame will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of +90 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute).

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

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

Notes

- If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to "origin"), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude).
- An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation.
- If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System.

Parameters:

skyRefP - the SkyRefP attribute of this object