It has been a while, but Astronoby just got a brand new release, and it's massive! Let me introduce you to all the new wonders you can reach with Astronoby.

Lunar eclipses

Lunar eclipses happen up to 3 times a year. They are the passages of the Moon through Earth's shadow. Astronoby can now find when such eclipses will happen, along with all their general circumstances.

Astronoby::Moon.eclipse_events takes an ephemeris and a time range, and returns the lunar eclipses whose greatest instant falls in that range, sorted by time.

ephem = Astronoby::Ephem.load("inpop19a.bsp")

eclipses = Astronoby::Moon.eclipse_events(
  ephem: ephem,
  start_time: Time.utc(2026, 1, 1),
  end_time: Time.utc(2027, 1, 1)
)

eclipses.map { |eclipse| [eclipse.instant.to_time, eclipse.kind] }
# => [[2026-03-03 11:33:42 UTC, :total], [2026-08-28 04:12:56 UTC, :partial]]

Each eclipse is an Astronoby::LunarEclipse.

eclipse = eclipses.first

eclipse.kind                 # => :total
eclipse.total?               # => true
eclipse.instant.to_time      # => 2026-03-03 11:33:42 UTC

An eclipse exposes its phases as Astronoby::EclipsePhase objects.

eclipse.penumbral.starting_instant.to_time  # => 2026-03-03 08:44:26 UTC (P1)
eclipse.partial.starting_instant.to_time    # => 2026-03-03 09:50:04 UTC (U1)
eclipse.total.starting_instant.to_time      # => 2026-03-03 11:04:28 UTC (U2)
eclipse.total.ending_instant.to_time        # => 2026-03-03 12:02:55 UTC (U3)
eclipse.partial.ending_instant.to_time      # => 2026-03-03 13:17:18 UTC (U4)
eclipse.penumbral.ending_instant.to_time    # => 2026-03-03 14:23:05 UTC (P4)

eclipse.total.duration.seconds              # => 3506 (seconds of totality)

I'm also considering supporting solar eclipses and local circumstances in a future version of Astronoby.

Planetary phenomena

Planetary phenomena are events relative to the Sun, seen from Earth: conjunctions, oppositions, and greatest elongations.

Oppositions

An opposition is the instant when a superior planet and the Sun have opposite apparent ecliptic longitudes, so the planet is opposite the Sun in the sky.

ephem = Astronoby::Ephem.load("inpop19a.bsp")

opposition = Astronoby::Saturn.opposition_events(
  ephem: ephem,
  start_time: Time.utc(2026, 1, 1),
  end_time: Time.utc(2027, 1, 1)
).first

opposition.instant.to_time # => 2026-10-04 12:29:13 UTC

This event will provide the best days to observe Mars, Jupiter, Saturn, Uranus and Neptune.

Conjunctions

A conjunction is the instant when a planet and the Sun share the same apparent ecliptic longitude. Each conjunction is classified as inferior (the planet passes between the Earth and the Sun) or superior (the planet passes behind the Sun), determined from the apparent distances.

conjunction = Astronoby::Venus.conjunction_events(
  ephem: ephem,
  start_time: Time.utc(2026, 1, 1),
  end_time: Time.utc(2027, 1, 1)
).last

conjunction.instant.to_time # => 2026-10-24 03:44:07 UTC
conjunction.inferior?       # => true
conjunction.superior?       # => false

This event doesn't lead to observations, since the planet is always either behind the Sun or right in front of it, but it helps to keep track of the continuous progress of these planets in the sky.

Greatest elongations

A greatest elongation is the instant when an inferior planet reaches its maximum apparent angular separation from the Sun. It is eastern when the planet is east of the Sun (visible in the evening sky) and western when it is west of the Sun (visible in the morning sky).

elongation = Astronoby::Mercury.greatest_elongation_events(
  ephem: ephem,
  start_time: Time.utc(2026, 1, 1),
  end_time: Time.utc(2027, 1, 1)
).first

elongation.instant.to_time   # => 2026-02-19 17:41:09 UTC
elongation.angle.degrees     # => 18.12
elongation.eastern?          # => true
elongation.western?          # => false

This event will provide the best days to observe Mercury and Venus.

All things about the Moon

Beyond phases and apsides, Astronoby exposes the quantities lunar observers rely on to describe the Moon's appearance and orientation in the sky: its libration, the position angle of its rotation axis, the position angle of its bright limb, and the parallactic angle.

ephem = Astronoby::Ephem.load("inpop19a.bsp")
instant = Astronoby::Instant.from_time(Time.utc(2026, 6, 26))
moon = Astronoby::Moon.new(instant: instant, ephem: ephem)

All the following values let you draw the visible Moon disk with extreme precision.

Libration

Libration is the apparent oscillation that lets an observer on Earth see slightly more than half of the lunar surface over time.

libration = moon.libration

libration.longitude.str(:dms) # => "+3° 39′ 29.3043″"
libration.latitude.str(:dms)  # => "+6° 32′ 59.5729″"

Position angle of the axis

The position angle of the Moon's axis of rotation is the angle of the projection of the lunar north pole, measured eastward from the north point of the disk.

moon.position_angle_of_axis.str(:dms) # => "+15° 31′ 47.7578″"

Position angle of the bright limb

The position angle of the midpoint of the illuminated limb is measured eastward from the north point of the disk.

moon.bright_limb_position_angle.str(:dms) # => "+280° 39′ 10.4943″"

Parallactic angle

The parallactic angle is the angle at the Moon between the direction of the north celestial pole and the direction of the observer's zenith.

observer = Astronoby::Observer.new(
  latitude: Astronoby::Angle.from_degrees(48.8566),
  longitude: Astronoby::Angle.from_degrees(2.3522)
)

moon.parallactic_angle(observer: observer).str(:dms) # => "+30° 27′ 19.7031″"

Ground work for satellite tracking

Tracking an artificial satellite means turning the output of an orbit propagator into something you can actually point a telescope at, or plot on a map. Astronoby now provides the reference frames to make that journey, from the satellite's orbit all the way down to a spot on the ground.

It starts with TEME (True Equator, Mean Equinox), the frame the standard SGP4/SDP4 propagators speak. From there, Astronoby converts the position to ECEF (Earth-Centered, Earth-Fixed), a frame that rotates along with the Earth, and finally to WGS-84 geodetic coordinates, the good old latitude, longitude and elevation that GPS uses. In other words, given where a satellite is on its orbit, Astronoby can tell you the point on Earth it is flying over.

And because Astronoby already knows how to observe the sky from a given place, a satellite can also be observed directly by an Astronoby::Observer, telling you where to look in the sky.

This is the groundwork for a new gem dedicated to satellite tracking, currently in the making on top of Astronoby. But that's a story for another post.

Even more accurate with IERS integration

The Earth isn't a perfect clock: its rotation speeds up and slows down ever so slightly, and its axis wobbles by a few metres at the poles. These tiny irregularities can't be predicted from a formula, they have to be measured. That's the job of the International Earth Rotation and Reference Systems Service (IERS), which publishes that data continuously.

Astronoby now taps into those measurements through a dedicated gem, iers, to bring its calculations even closer to reality. Concretely, it sharpens a few things under the hood:

• Delta T, the difference between Terrestrial Time and Universal Time, now comes from measured values, improving every conversion between civil time and Astronoby's internal time scale.
• Sidereal time is now computed through the IERS Conventions 2010, the same standard used by professional observatories.
• Polar motion is taken into account when placing an observer on the rotating Earth, refining topocentric positions, the coordinates of a body as seen from a specific location.

The best part: you don't have to do anything to benefit from it. The data ships with the gem and is used automatically.

What's next?

You can read the full changelog on GitHub.

We are getting closer to the first major version of Astronoby. It will come once I consider most of the indispensable features implemented in the gem, and most importantly once the public API is truly stable.

As mentioned above I have a few ideas in mind, including satellite tracking, solar eclipses and local circumstances of eclipses. Minor bodies such as asteroids, dwarf planets and comets could also be really nice. Or even planets' satellites.

Please let me know in the comments what you would need the most.

Cover picture credits: Dramatic City Sunset Sky Pro Vector by John Alberton