uk.ac.starlink.ast

Class SlaMap

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.SlaMap

public class SlaMap
extends Mapping

Java interface to the AST SlaMap class - sequence of celestial coordinate conversions. An SlaMap is a specialised form of Mapping which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems.

When an SlaMap is first created, it simply performs a unit (null) Mapping on a pair of coordinates. Using the astSlaAdd function, a series of coordinate conversion steps may then be added, selected from those provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67). This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB.

For details of the individual coordinate conversions available, see the description of the astSlaAdd function.

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:

SUN/67 - SLALIB, AST SlaMap

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
SlaMap() Creates a default SlaMap.
SlaMap(int flags) Creates a SlaMap.

Method Summary

Modifier and Type	Method and Description
void	add(String cvt, double[] args) Add a celestial coordinate conversion to an SlaMap.

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

SlaMap

public SlaMap()

Creates a default SlaMap.

SlaMap

public SlaMap(int flags)

Creates a SlaMap.

Parameters:

flags - This parameter is reserved for future use and should currently always be set to zero.

Throws:

AstException - if an error occurred in the AST library

Method Detail

add

public void add(String cvt,
                double[] args)

Add a celestial coordinate conversion to an SlaMap. This function adds one of the standard celestial coordinate system conversions provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67) to an existing SlaMap.

When an SlaMap is first created (using astSlaMap), it simply performs a unit (null) Mapping. By using astSlaAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SlaMap will perform in sequence. This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB.

Normally, if an SlaMap's Invert attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astSlaAdd in the order given (i.e. with the most recently added conversion applied last).

This order is reversed if the SlaMap's Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SlaMap. In this case, the first conversion to be applied would be the inverse of the one most recently added.

Notes

- All coordinate values processed by an SlaMap are in radians. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude.
- When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, converting to the standard FK5 coordinate system as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use astSimplify to simplify the resulting SlaMap. The simplification process will eliminate any steps which turn out not to be needed.
- This function does not check to ensure that the sequence of coordinate conversions added to an SlaMap is physically meaningful.

SLALIB Conversions

The following strings (which are case-insensitive) may be supplied via the "cvt" parameter to indicate which celestial coordinate conversion is to be added to the SlaMap. Each string is derived from the name of the SLALIB routine that performs the conversion and the relevant documentation (SUN/67) should be consulted for details. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the "args" array, in the order indicated. The argument names match the corresponding SLALIB routine arguments and their values should be given using exactly the same units, time scale, calendar, etc. as described in SUN/67:

- "ADDET" (EQ): Add E-terms of aberration.
- "SUBET" (EQ): Subtract E-terms of aberration.
- "PREBN" (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4) precession model.
- "PREC" (EP0,EP1): Apply IAU 1975 (FK5) precession model.
- "FK45Z" (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax).
- "FK54Z" (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax).
- "AMP" (DATE,EQ): Convert geocentric apparent to mean place.
- "MAP" (EQ,DATE): Convert mean place to geocentric apparent.
- "ECLEQ" (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial.
- "EQECL" (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates.
- "GALEQ": Convert galactic coordinates to FK5 J2000.0 equatorial.
- "EQGAL": Convert FK5 J2000.0 equatorial to galactic coordinates.
- "HFK5Z" (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial.
- "FK5HZ" (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS.
- "GALSUP": Convert galactic to supergalactic coordinates.
- "SUPGAL": Convert supergalactic coordinates to galactic.
- "J2000H": Convert dynamical J2000.0 to ICRS.
- "HJ2000": Convert ICRS to dynamical J2000.0.
- "R2H" (LAST): Convert RA to Hour Angle.
- "H2R" (LAST): Convert Hour Angle to RA.

For example, to use the "ADDET" conversion, which takes a single argument EQ, you should consult the documentation for the SLALIB routine SLA_ADDET. This describes the conversion in detail and shows that EQ is the Besselian epoch of the mean equator and equinox. This value should then be supplied to astSlaAdd in args[0].

In addition the following strings may be supplied for more complex conversions which do not correspond to any one single SLALIB routine (DIURAB is the magnitude of the diurnal aberration vector in units of "day/(2.PI)", DATE is the Modified Julian Date of the observation, and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian coordinates, in metres, of the observer):

- "HPCEQ" (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial.
- "EQHPC" (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian.
- "HPREQ" (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial.
- "EQHPR" (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial.
- "HEEQ" (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial.
- "EQHE" (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic.
- "H2E" (LAT,DIRUAB): Convert horizon coordinates to equatorial.
- "E2H" (LAT,DIURAB): Convert equatorial coordinates to horizon.

Note, the "H2E" and "E2H" conversions convert between topocentric horizon coordinates (azimuth,elevation), and apparent local equatorial coordinates (hour angle,declination). Thus, the effects of diurnal aberration are taken into account in the conversions but the effects of atmospheric refraction are not.

Parameters:

cvt - Pointer to a null-terminated string which identifies the celestial coordinate conversion to be added to the SlaMap. See the "SLALIB Conversions" section for details of those available.

args - An array containing argument values for the celestial coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the "SLALIB Conversions" section). This array is ignored and a NULL pointer may be supplied if no arguments are needed.

Throws:

AstException - if an error occurred in the AST library

See Also:

SUN/67 - SLALIB