Astro::Coord(3pm)

📦

version 0.78 · 2 versions

0.78 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
0.78 · alpine 3.24

, in debian trixie, ubuntu resolute, ubuntu stonking

✨ NAME ✨

Astro::Coord — astronomical coordinate transformations, bestie 💫

🎀 SYNOPSIS 🎀

use Astro::Coord;

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

💖 DESCRIPTION 💖

Astro::Coord is a whole assorted grab-bag of Perl routines for coordinate conversions — hour angle ➡️ elevation, J2000 ➡️ B1950, all of it. It's giving "I got you, astronomer bestie" energy and honestly? We love to see it 🦋

👑 AUTHOR 👑

Chris Phillips Chris.Phillips@csiro.au — king behavior, no cap 💅

🔥 FUNCTIONS 🔥

💅 `pol2r`

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

Takes a position in polar coordinates and hands you back rectangular coordinates, periodt ✨

$polar1, $polar2 — the polar coordinates to convert (turns)
$x, $y, $z — the rectangular coordinates

💅 `r2pol`

($polar1, $polar2) = r2pol($x, $y, $z);

The reverse glow-up: rectangular coordinates in, polar coordinates out 🌸

$x, $y, $y — the rectangular coordinates to convert
$polar1, $polar2 — the polar coordinates (turns)

Heads up: returns undef if too few or too many arguments get passed. Strict vibe check, sorry 😭

💅 `xy2azel`

($az, $el) = xy2azel($x, $y);

Converts a telescope position from X,Y coordinates into Az,El coordinates. Slay 🎀

$x, $y — the X and Y coordinates (turns)
$az, $el — the azimuth and elevation (turns)

💅 `azel2xy`

($x, $y) = azel2xy($az, $el);

And the other direction — Az,El ➡️ X,Y, iconic 💖

$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. It goes both ways, which is main character energy fr fr 🔥

$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 ↔ az,el conversion is symmetrical. Same energy in both directions, no notes 💫

💅 `fk4fk5`

($JRA, $JDec) = fk4fk5($BRA, $BDec);
     (@fk5) = fk4fk5(@fk4);

Takes an FK4 (B1950) position and gives you 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 it's quite accurate — but it's subject to a restrictive license (see README). Read the fine print, bestie 📜

💅 `fk4fk5r`

@fk5 = fk4fk5r(@fk4);

Converts an FK4 (B1950) position to the equivalent FK5 (J2000) position.

Note: convert equatorial 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 handles 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 it's quite accurate — but it's subject to a restrictive license (see README).

💅 `fk5fk4r`

@fk4 = fk5fk4r(@fk5);

Converts an FK5 (J2000) position to the equivalent FK4 (B1950) position.

Note: convert equatorial 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 handles polar and rectangular arguments.

💅 `fk4galr`

@gal = fk4galr(@fk4)

Converts an FK4 position (B1950.0) to the IAU 1958 Galactic coordinate system 🌌

Note: convert equatorial 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 too 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 equatorial 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)

Hand it the Julian day ($jd) and this routine calculates the ephemeris values that the prcmat and nutate routines need 💫

What you get back:

$omega — longitude of the ascending node of the Moon's 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 obliquity of the ecliptic

💅 `J2000todate`

($DRA, $DDec) = J2000todate($JRA, $JDec, $mjd);
@date = J2000todate(@J2000, $mjd);

Converts a J2000 position into a 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);

Calculates 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 × 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 Moon's 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 obliquity 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);

Calculates 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 like this:

Express the position as a direction cosine 3-vector (V1) — use pol2r to do this.
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) aren't 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, because the routine will return undef if it is not passed 8 parameters. No exceptions, bestie 😤

The RA/Dec date system is defined with respect to the celestial sphere, but it 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 determine 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

okay bestie picking right back up where that conversion matrix left off — no re-intro, we're mid-glow-up 💅 here come the rest of the rows, and the four flags read left to right in order:

Galactic, RA/Dec J2000, B1950 <-> RA/Dec date — Y N N N
Galactic, RA/Dec J2000, B1950, date <-> HA/Dec — Y Y N N
Galactic, RA/Dec J2000, B1950, date <-> X/Y, Az/El — Y Y Y Y
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. so like, at the horizon it just... keeps going. iconic but also be aware 🫠

✨ the inputs you gotta feed it ✨

$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 you want the coordinates converted to
$mjd — the time as modified Julian day, if necessary, at which to do the conversion
$longitude — the longitude of the location/observatory, if necessary, at which to do the conversion (turns)
$latitude — the latitude of the location/observatory, if necessary, at which to do the conversion (turns)
$ref0 — the refraction constant (if you're in doubt, use 0.00005)

💖 what it hands back 💖

$output_left — the left/longitude output coordinate (turns)
$output_right — the right/latitude output coordinate (turns)

🛰️ `haset_ewxy`

$haset = haset_ewxy($declination, $latitude, %limits);

so this one takes the $declination of your source plus the $latitude of your EWXY mounted antenna and works out the hour angle at which the source is gonna set. and then it's literally trivial to get the time until the source sets — just subtract the current hour angle of the source from the hour angle at which it sets. math is mathing ✨

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 should 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 the %limits hash is missing any of the required keys. no keys, no answer, no cap 😭

🌸 `ewxy_tlos`

$tlos = ewxy_tlos($hour_angle, $declination, $latitude, %limits);

this cutie calculates the time left on-source (tlos) for a source sitting at $hour_angle, $declination, for an EWXY mount antenna at $latitude. she's telling you how much time you got left before it dips 💅

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);

same energy, different mount: this one 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. then, again, getting the time until it sets is trivial — subtract the current hour angle of the source from the hour angle at which it sets. and just so we're clear, this routine assumes the antenna is able to rotate through 360 degrees in azimuth. full spin, main character energy 👑

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. same rule, always 🫶

🎀 `azel_tlos`

$tlos = azel_tlos($hour_angle, $declination, $latitude, \%limits);

the Az/El twin of ewxy_tlos: it 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);

okay this is the big one. given the $declination of the source, the $latitude of the antenna, the type of the antenna $mount, and a reference to a hash holding info on the antenna limits, this routine calculates the hour angle at which the source sets for the antenna. and here's the slay: 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. so many options, so much power 💅

if you want to calculate source rise times above arbitrary elevation, use the routine rise. different tool, different job, don't mix them up bestie.

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, and 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.

and that's a wrap on this part, bestie 💖 this whole thing is perl v5.38.2, dated 2024-05-15, and it lives its life as Astro::Coord(3pm) — go point some telescopes at the sky, you've got this 🫶🦋✨

📦 where this page comes from

debian trixie: libastro-perl 0.78-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libastro-perl 0.78-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libastro-perl 0.78-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Astro::Coord(3pm)

✨ NAME ✨

🎀 SYNOPSIS 🎀

💖 DESCRIPTION 💖

👑 AUTHOR 👑

🔥 FUNCTIONS 🔥

💅 pol2r

💅 r2pol

💅 xy2azel

💅 azel2xy

💅 eqazel

💅 fk4fk5

💅 fk4fk5r

💅 fk5fk4

💅 fk5fk4r

💅 fk4galr

💅 galfk4

💅 fk4gal

💅 ephem_vars

💅 J2000todate

💅 nutate

💅 precsn

💅 coord_convert

✨ the inputs you gotta feed it ✨

💖 what it hands back 💖

🛰️ haset_ewxy

🌸 ewxy_tlos

🦋 haset_azel

🎀 azel_tlos

🌈 antenna_rise

💅 `pol2r`

💅 `r2pol`

💅 `xy2azel`

💅 `azel2xy`

💅 `eqazel`

💅 `fk4fk5`

💅 `fk4fk5r`

💅 `fk5fk4`

💅 `fk5fk4r`

💅 `fk4galr`

💅 `galfk4`

💅 `fk4gal`

💅 `ephem_vars`

💅 `J2000todate`

💅 `nutate`

💅 `precsn`

💅 `coord_convert`

🛰️ `haset_ewxy`

🌸 `ewxy_tlos`

🦋 `haset_azel`

🎀 `azel_tlos`

🌈 `antenna_rise`