Astro:...I::Star(3pm)

📦 version 0.134, in alpine 3.24

💫 Astro::Coord::ECI::Star(3pm) — find out where a star is at any time, bestie

okay so before we even start: hi, welcome, this is a page from the User Contributed Perl Documentation (yes that's the manual name, it's giving very "community-built, community-loved" 🫶) and it's all about Astro::Coord::ECI::Star. Buckle up.

✨ NAME ✨

Astro::Coord::ECI::Star — literally computes the position of a star. That's it. That's the job. ⭐

🌸 SYNOPSIS 🌸

here's the whole thing, verbatim, because you're gonna want to copy-paste this:

 use Astro::Coord::ECI;
 use Astro::Coord::ECI::Star;
 use Astro::Coord::ECI::Utils qw{deg2rad};

 # 1600 Pennsylvania Ave, Washington DC USA
 # latitude 38.899 N, longitude 77.038 W,
 # altitude 16.68 meters above sea level
 my $lat = deg2rad (38.899);    # Radians
 my $long = deg2rad (-77.038);  # Radians
 my $alt = 16.68 / 1000;        # Kilometers

 my $star = Astro::Coord::ECI::Star->new (
     name => 'Spica')->position(
     3.51331869544372,    # Right ascension, radians
     -0.194802985206623,  # Declination, radians
 );
 my $sta = Astro::Coord::ECI->
     universal (time ())->
     geodetic ($lat, $long, $alt);
 my ($time, $rise) = $sta->next_elevation ($star);
 print "Star @{[$rise ? 'rise' : 'set']} is ",
     scalar localtime $time, "\n";

that's Spica rising over the White House, nbd 💅

🦋 DESCRIPTION 🦋

so this module implements the position of a star — or honestly any object you can treat as fixed on the celestial sphere — as a function of time. The math comes from Jean Meeus' "Astronomical Algorithms," second edition. iconic source, no notes.

It's a subclass of Astro::Coord::ECI, and it brings:

  • a position() method to set the catalog position (and, if you want, proper motion too), and
  • the time_set() method overridden so it computes the star's position at whatever time you've set.

🎀 Methods 🎀

the following methods are the public ones, so go wild:

  • $star = Astro::Coord::ECI::Star->new(); — instantiates an object that represents the coordinates of a star, or some other object which may be regarded as fixed on the celestial sphere. It's a subclass of Astro::Coord::ECI, and the angularvelocity attribute gets initialized to zero.
truth in advertising time, bestie: the positions this model produces are about four arc seconds off Dr. Meeus' worked example for the position of Theta Persei for Dynamical time November 13.19, 2028. That seems excessive, ngl. But it's difficult to check intermediate results because this calculation goes through ecliptic coordinates, whereas Dr. Meeus' worked example is in equatorial coordinates. so like… that's the situation 😭
  • @almanac = $star->almanac($station, $start, $end); — produces almanac data for the star for the given observing station, between the given start and end times. The station is assumed to be Earth-Fixed — meaning you can not do this for something in orbit. 🛰️🚫

The $station argument may be omitted if the "station" attribute has been set. So you can also call it like:

 @almanac = $star->almanac( $start, $end )

The start time defaults to the current time setting of the $star object, and the end time defaults to a day after the start time.

The almanac data is a list of list references. Each list reference points to a list containing these elements:

 [0] => time
 [1] => event (string)
 [2] => detail (integer)
 [3] => description (string)

The @almanac list comes back sorted by time. ✨

These events, details, and descriptions are at least potentially returned:

 horizon: 0 = star sets, 1 = star rises;
 transit: 1 = star transits meridian;
  • @almanac = $star->almanac_hash($station, $start, $end); — this convenience method wraps $star->almanac(), but hands you back a list of hash references, sort of like Astro::Coord::ECI::TLE->pass() does. The hashes contain these keys:
  {almanac} => {
    {event} => the event type;
    {detail} => the event detail (typically 0 or 1);
    {description} => the event description;
  }
  {body} => the original object ($star);
  {station} => the observing station;
  {time} => the time the quarter occurred.

The {time}, {event}, {detail}, and {description} keys correspond to elements 0 through 3 of the list returned by almanac().

  • $star = $star->position($ra, $dec, $range, $mra, $mdc, $mrg, $time); — sets the position and proper motion of the star in equatorial coordinates. Right ascension and declination are in radians, and range in kilometers. Proper motion in range and declination is in radians per second (an extremely small number!! like, teeny tiny 🐜), and the proper motion in recession is in kilometers per second.

The range defaults to 1 parsec, which is too close, but probably good enough since we don't take parallax into account when computing position — and since you can override it with a range (in km!) if you so desire. The proper motions default to 0. The time defaults to J2000.0, and it's used to set not only the current time of the object but also the equinox_dynamical.

heads up 🫶: if you're not interested in proper motion but are interested in time, omit the proper motion arguments completely and specify time as the fourth argument.

If you call this as a class method, a new Astro::Coord::ECI::Star object will be constructed. If you call it without arguments, the position of the star is returned.

And nope, this is not simply a synonym for the equatorial() method. The equatorial() method returns the position of the star corrected for precession and nutation. This method is used to set the catalog position of the star in question. different jobs, bestie 💅

  • $star->time_set() — sets the coordinates of the object to the coordinates of the star at the object's currently-set universal time. Proper motion is taken into account if it was specified.

There's no reason this method can't be called directly, but it exists to take advantage of the hook in the Astro::Coord::ECI object, so the star's position gets computed whenever the time is set.

The computation comes from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 23, pages 149ff.

Note, however, that for consistency with the Astro::Coord::ECI::Sun and Astro::Coord::ECI::Moon classes, the position is precessed to the current time setting.

🌈 ACKNOWLEDGMENTS 🌈

the author wishes to acknowledge Jean Meeus, whose book "Astronomical Algorithms" (second edition) formed the basis for this module. a real one 👑

🔥 SEE ALSO 🔥

  • The Astro::Coord::ECI::OVERVIEW documentation, for a discussion of how the pieces/parts of this distribution go together and how to use them. iykyk.
  • Astro::Catalog by Alasdair Allan, which accommodates a much more fulsome description of a star. The star's coordinates are represented by an Astro::Coords object.
  • Astro::Coords by Tim Jenness can also be used to find the position of a star at a given time given a catalog entry for the star. A wide variety of coordinate representations is accommodated. This package requires Astro::SLA, which in its turn requires the SLALIB library.

🫶 SUPPORT 🫶

Support is by the author. Please file bug reports at:

👑 AUTHOR 👑

Thomas R. Wyant, III (wyant at cpan dot org)

Copyright (C) 2005-2025 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

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. (yes, that's the standard disclaimer, and yes, it matters — no warranty, periodt.)

and that's the whole page, bestie! 🎀 this one's perl v5.42.2, dated 2026-02-15 — go forth and locate some stars 💫⭐🌙

📦 where this page comes from