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
Constructor Summary |
SkyFrame()
Create a SkyFrame. |
Method Summary |
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 |
SkyFrame
public SkyFrame()
- Create a SkyFrame.
- Throws:
AstException
- if an error occurred in the AST library
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
Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.