++ed by:

1 non-PAUSE user.

Chris Phillips

NAME

Astro::Coord - Astronomical coordinate transformations

SYNOPSIS

``````    use Astro::Coord;

(\$l, \$b) = fk4gal(\$ra, \$dec);
(\$az, \$el) = eqazel(\$ha, \$dec, \$latitude);``````

DESCRIPTION

Astro::Coord contains an assorted set Perl routines for coordinate conversions, such as hour angle to elevation and J2000 to B1950.

AUTHOR

Chris Phillips Chris.Phillips@csiro.au

FUNCTIONS

pol2r
``````  (\$x, \$y, \$z) = pol2r(\$polar1, \$polar2);

Converts a position in polar coordinates into rectangular coordinates
\$polar1, \$polar2   The polar coordinates to convert (turns)
\$x, \$y, \$z         The rectangular coordinates``````
r2pol
``````  (\$polar1, \$polar2) = r2pol(\$x, \$y, \$z);

Converts a position in rectangular coordinates into polar coordinates
\$x, \$y, \$y         The rectangular coordinates to convert
\$polar1, \$polar2   The polar coordinates (turns);
Returns undef if too few or too many arguments are passed.``````
xy2azel
``````  (\$az, \$el) = xy2azel(\$x, \$y);

Converts a telescope position in X,Y coordinates into Az,El coordinates
\$x, \$y     The X and Y coordinates (turns)
\$az, \$el    The azimuth and elevation (turns)``````
azel2xy
``````  (\$x, \$y) = azel2xy(\$az, \$el);

Converts a position in Az,El coordinates into X,Y coordinates
\$az, \$el    The azimuth and elevation (turns)
\$x, \$y      The X and Y coordinate (turns)``````
eqazel
``````  (\$ha, \$dec) = eqazel(\$az, \$el, \$latitude);
(\$az, \$el) = eqazel(\$ha, \$dec, \$latitude);
(\$ha, \$dec) = eqazel(\$az, \$el, \$latitude, \$allownegative);

Converts HA/Dec coordinates to Az/El and vice versa.
\$ha, \$dec     Hour angle and declination of source (turns)
\$az, \$el      Azimuth and elevation of source (turns)
\$latitude     Latitude of the observatory (turns)
\$allownegative  If true, allow negative \$ha or \$az on return (Optional)
Note:
The ha,dec and az,el conversion is symmetrical``````
fk4fk5
`````` (\$JRA, \$JDec) = fk4fk5(\$BRA, \$BDec);
(@fk5) = fk4fk5(@fk4);

Converts an FK4 (B1950) position to the equivalent FK5 (J2000)
position.
\$BRA,\$BDec     fk4/B1950 position (turns)
\$JRA,\$Dec      fk5/J2000 position (turns)
@fk4           fk4/B1950 position (as a 3-vector)
@fk5           fk5/J2000 position (as a 3-vector)
Note:
This code is based on similar routines from the Fortran SLALIB
package, so are quite accurate, but subject to a restrictive
fk4fk5r
`````` @fk5 = fk4fk5r(@fk4);

Converts an FK4 (B1950) position to the equivalent FK5 (J2000) position.
Note: Convert equitoral positions to/from 3-vectors using pol2r and r2pol.
@fk4       fk4 position (as a 3-vector, turns)
@fk5       fk5 position (as a 3-vector, turns)
Note:
Just a wrapper to fk4fk5 which now handler polar and rectangular
arguments``````
fk5fk4
`````` (\$JRA, \$JDec) = fk4fk5(\$BRA, \$BDec);
(\$@fk5) = fk4fk5(@fk4);

Converts an FK5 (J2000) position to the equivalent FK4 (B1950) position.
\$JRA,\$Dec      fk5/J2000 position (turns)
\$BRA,\$BDec     fk4/B1950 position (turns)
@fk5           fk5/J2000 position (as a 3-vector)
@fk4           fk4/B1950 position (as a 3-vector)
Note:
This code is based on similar routines from the Fortran SLALIB
package, so are quite accurate, but subject to a restrictive
fk5fk4r
`````` @fk4 = fk5fk4r(@fk5);

Converts an FK5 (J2000) position to the equivalent FK4 (B1950) position.
Note: Convert equitoral positions to/from 3-vectors using pol2r and r2pol.
@fk4       fk4 position (as a 3-vector, turns)
@fk5       fk5 position (as a 3-vector, turns)
Note:
Just a wrapper to fk5fk4 which now handler polar and rectangular
arguments``````
fk4galr
``````  @gal = fk4galr(@fk4)

Converts an FK4 position (B1950.0) to the IAU 1958 Galactic
coordinate system
Note: convert equitoral positions to/from 3-vectors using pol2r and r2pol.
@fk4     fk4 position to convert (as a 3-vector, turns)
@gal     Galactic position (as a 3-vector, turns)
Returns undef if too few or two many arguments are passed.
Reference : Blaauw et al., 1960, MNRAS, 121, 123.``````
galfk4
``````  (\$bRA, \$bDec) = galfk4(\$l, \$b);
@fk4 = galfk4(@gal);

Converts an IAU 1958 Galactic position to the FK4 coordinate system (B1950)
Notes: Converts equitoral positions to/from 3-vectors using pol2r and r2pol.
\$BRA,\$BDec  fk4/B1950 position (turns)
\$l, \$b      Galactic longitude and latitude
@gal        Galactic position (as a 3-vector, turns)
@fk4        fk4 position (as a  3-vector, turns)
Reference : Blaauw et al., 1960, MNRAS, 121, 123.``````
fk4gal
``````  (\$l, \$b) = fk4gal(\$ra, \$dec);

Converts an FK4 position (B1950) to the IAU 1958 Galactic
coordinate system
(\$ra, \$dec)  fk4 position to convert (turns)
(\$l, \$b)     Galactic position (turns)
Reference : Blaauw et al., 1960, MNRAS, 121, 123.``````
ephem_vars
``````  (\$omega, \$rma, \$mlanom, \$F, \$D, \$eps0) = ephem_vars(\$jd)

Given the Julian day (\$jd) this routine calculates the ephemeris
values required by the prcmat and nutate routines

The returned values are :
\$omega  - Longitude of the ascending node of the Moons mean orbit on
the ecliptic, measured from the mean equinox of date.
\$rma    - Mean anomaly of the Sun.
\$mlanom - Mean anomaly of the Moon.
\$F      - L - omega, where L is the mean longitude of the Moon.
\$D      - Mean elongation of the Moon from the Sun.
\$eps0   - Mean obilquity of the ecliptic.``````
J2000todate
`````` (\$DRA, \$DDec) = J2000todate(\$JRA, \$JDec, \$mjd);
@date = J2000todate(@J2000, \$mjd);

Converts an J2000 position date coordinate

\$DRA,\$DDec     Date coordinate (turns)
\$JRA,\$Dec      J2000 position (turns)
@date          Date coordinate (as a 3-vector)
@J2000         J2000 position (as a 3-vector)``````
nutate
``````  (\$deps, \$dpsi, @nu) = nutate(\$omega, \$F, \$D, \$rma, \$mlanom, \$eps0);

To calculate the nutation in longitude and obliquity according to
the 1980 IAU Theory of Nutation including terms with amplitudes
greater than 0.01 arcsecond.  The nutation matrix is used to
compute true place from mean place: true vector = N x mean place
vector where the three components of each vector are the direction
cosines wrt the mean equinox and equator.

/   1          -dpsi.cos(eps)    -dpsi.sin(eps)  \
|                                                  |
N = |  dpsi.cos(eps)      1               -deps        |
|                                                  |
\ dpsi.sin(eps)    deps                 1        /

The required inputs are : (NOTE: these are the values returned by ephem_vars)
\$omega  - Longitude of the ascending node of the Moons mean orbit on
the ecliptic, measured from the mean equinox of date.
\$rma    - Mean anomaly of the Sun.
\$mlanom - Mean anomaly of the Moon.
\$F      - L - omega, where L is the mean longitude of the Moon.
\$D      - Mean elongation of the Moon from the Sun.
\$eps0   - Mean obilquity of the ecliptic.

The returned values are :
\$deps - nutation in obliquity
\$dpsi - nutation in longitude (scalar)
@nu   - nutation matrix (array [3][3])``````
precsn
``````  @gp = precsn(\$jd_start, \$jd_stop);

To calculate the precession matrix P for dates AFTER 1984.0 (JD =
2445700.5) Given the position of an object referred to the equator
and equinox of the epoch \$jd_start its position referred to the
equator and equinox of epoch \$jd_stop can be calculated as follows :

1) Express the position as a direction cosine 3-vector (V1)
(use pol2r to do this).
2) The corresponding vector V2 for epoch jd_end is V2 = P.V1

The required inputs are :
\$jd_start - The Julian day of the current epoch of the coordinates.
\$jd_end   - The Julian day at the required epoch for the conversion.

The returned values are :
@gp - The required precession matrix (array [3][3])``````
coord_convert
``````  (\$output_left, \$output_right) = coord_convert(\$input_left, \$input_right,
\$input_mode, \$output_mode,
\$mjd, \$longitude, \$latitude,
\$ref0);

A routine for converting between any of the following coordinate systems :
Coordinate system                               input/output mode
-----------------                               -----------------
X, Y (East-West mounted)                                    0
Azimuth, Elevation                                          1
Hour Angle, Declination                                     2
Right Ascension, Declination (date, J2000 or B1950)       3,4,5
Galactic (B1950)                                            6

The last four parameters in the call (\$mjd, \$longitude, \$latitude
and \$ref0) are not always required for the coordinate conversion.
In particular if the conversion is between two coordinate systems
which are fixed with respect to the celestial sphere (RA/Dec J2000,
B1950 or Galactic), or two coordinate systems which are fixed with
respect to the antenna (X/Y and Az/El) then these parameters are not
used (NOTE: they must always be passed, even if they only hold 0 or
undef as the routine will return undef if it is not passed 8
parameters).  The RA/Dec date system is defined with respect to the
celestial sphere, but varies with time.  The table below shows which
of \$mjd, \$longitude, \$latitude and \$ref0 are used for a given
conversion.  If in doubt you should determing the correct values for
all input parameters, no checking is done in the routine that the
passed values are sensible.

Conversion                 \$mjd \$longitude \$latitude \$ref0
------------------------------------------------------------------------
Galactic,             Galactic,
RA/Dec J2000,B1950 <->RA/Dec J2000, B1950  N       N         N       N

Galactic,
RA/Dec J2000,B1950 <->RA/Dec date          Y       N         N       N

Galactic,
RA/Dec J2000,B1950,<->HA/Dec               Y       Y         N       N
date

Galactic,
RA/Dec J2000,B1950,<->X/Y, Az/El           Y       Y         Y       Y
date

X/Y, Az/El         <->X/Y, Az/El           N       N         N       N

X/Y, Az/El         <->HA/Dec               N       N         Y       Y

NOTE :  The method used for refraction correction is asymptotic at
an elevation of 0 degrees.

The required inputs are :
\$input_left   - The left/longitude input coordinate (turns)
\$input_right  - The right/latitude input coordinate (turns)
\$input_mode   - The mode of the input coordinates (0-6)
\$output_mode  - The mode to convert the coordinates to.
\$mjd          - The time as modified Julian day (if necessary) at
which to perform the conversion
\$longitude    - The longitude of the location/observatory (if necessary)
at which to perform the conversion (turns)
\$latitude     - The latitude of the location/observatory (if necessary)
at which to perform the conversion (turns)
\$ref0         - The refraction constant (if in doubt use 0.00005).

The returned values are :
\$output_left  - The left/longitude output coordinate (turns)
\$output_right - The right/latitude output coordinate (turns)``````
haset_ewxy
``````  \$haset = haset_ewxy(\$declination, \$latitude, %limits);

This routine takes the \$declination of the source, and the \$latitude of the
EWXY mounted antenna and calculates the hour angle at which the source
will set.  It is then trivial to calculate the time until the source
sets, simply by subtracting the current hour angle of the source from
the hour angle at which it sets.

The required inputs are :
\$declination - The declination of the source (turns)
\$latitude    - The latitude of the observatory (turns)
%limits     - A reference to a hash holding the EWXY antenna limits
The following keys must be defined XLOW, XLOW_KEYHOLE,
XHIGH, XHIGH_KEYHOLE, YLOW, YLOW_KEYHOLE, YHIGH,
YHIGH_KEYHOLE (all values shoule be in turns)

The returned value is :
\$haset       - The hour angle (turns) at which a source at this
declination sets for an EWXY mounted antenna with the
given limits at the given latitude

NOTE: returns undef if %limits hash is missing any of the required keys``````
ewxy_tlos
``````  \$tlos = ewxy_tlos(\$hour_angle, \$declination, \$latitude, %limits);

This routine calculates the time left on-source (tlos) for a source
at \$hour_angle, \$declination for an EWXY mount antenna at \$latitude.

The required inputs are :
\$hour_angle  - The current hour angle of the source (turns)
\$declination - The declination of the source (turns)
\$latitude    - The latitude of the observatory (turns)
\%limits     - A reference to a hash holding the EWXY antenna limits
The following keys must be defined XLOW, XLOW_KEYHOLE,
XHIGH, XHIGH_KEYHOLE, YLOW, YLOW_KEYHOLE, YHIGH,
YHIGH_KEYHOLE (all values should be in turns)

The returned value is :
\$tlos        - The time left on-source (turns)``````
haset_azel
``````  \$haset = haset_azel(\$declination, \$latitude, %limits);

This routine takes the \$declination of the source, and the
\$latitude of the Az/El mounted antenna and calculates the hour
angle at which the source will set.  It is then trivial to
calculate the time until the source sets, simply by subtracting the
current hour angle of the source from the hour angle at which it
sets.  This routine assumes that the antenna is able to rotate
through 360 degrees in azimuth.

The required inputs are :
\$declination - The declination of the source (turns)
\$latitude    - The latitude of the observatory (turns)
\%limits     - A reference to a hash holding the Az/El antenna limits
The following keys must be defined ELLOW (all values should
be in turns)

The returned value is :
\$haset       - The hour angle (turns) at which a source at this
declination sets for an Az/El mounted antenna with the
given limits at the given latitude

NOTE: returns undef if the %limits hash is missing any of the required keys``````
azel_tlos
``````  \$tlos = azel_tlos(\$hour_angle, \$declination, \$latitude, \%limits);

This routine calculates the time left on-source (tlos) for a source
at \$hour_angle, \$declination for an Az/El mount antenna at \$latitude.

The required inputs are :
\$hour_angle  - The current hour angle of the source (turns)
\$declination - The declination of the source (turns)
\$latitude    - The latitude of the observatory (turns)
%limits     - A reference to a hash holding the Az/El antenna limits
The following keys must be defined ELLOW (all values
should be in turns)

The returned value is :
\$tlos        - The time left on-source (turns)``````
antenna_rise
``````  \$ha_set = antenna_rise(\$declination, \$latitude, \$mount, \%limits);

Given the \$declination of the source, the \$latitude of the antenna,
the type of the antenna \$mount and a reference to a hash holding
information on the antenna limits, this routine calculates the hour
angle at which the source sets for the antenna.  The hour angle at
which it rises is simply the negative of that at which it sets.
These values in turn can be used to calculate the LMST at which the
source rises/sets and from that the UT at which the source
rises/sets on a given day, or to calculate the native coordinates
at which the source rises/sets.

If you want to calculate source rise times above arbitrary elevation,
use the routine rise.

The required inputs are :
\$declination - The declination of the source (turns)
\$latitude    - The latitude of the observatory (turns)
\$mount       - The type of antenna mount, 0 => EWXY mount, 1 => Az/El,
any other number will cause the routine to return
undef
%limits     - A reference to a hash holding the antenna limits
For an EWXY antenna there must be keys for all the
limits (i.e.  XLOW, XLOW_KEYHOLE, XHIGH, XHIGH_KEYHOLE,
YLOW, YLOW_KEYHOLE, YHIGH, YHIGH_KEYHOLE).  For an Az/El
antenna there must be a key for ELLOW (all values should
be in turns).

The returned values are :
\$ha_set  - The hour angle at which the source sets (turns).  The hour
angle at which the source rises is simply the negative of this
value.``````

1 POD Error

The following errors were encountered while parsing the POD:

Around line 114:

'=item' outside of any '=over'

=over without closing =back