astronoby 0.9.0 → 0.11.0

data/docs/lunar_observation.md

@@ -0,0 +1,87 @@
+# Lunar Observation
+
+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. By default they follow Jean Meeus, *Astronomical Algorithms*, 2nd edition, and are derived from the Moon's and the Sun's apparent positions, which Astronoby already computes from the ephemeris. The libration and the position angle of the axis can additionally use the integrated lunar orientation from a JPL DE kernel to reach arcsecond accuracy, as described below.
+
+All of these are available directly on a `Astronoby::Moon` instance.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+instant = Astronoby::Instant.from_time(Time.utc(2025, 3, 1))
+moon = Astronoby::Moon.new(instant: instant, ephem: ephem)
+```
+
+## Libration
+
+Libration is the apparent oscillation that lets an observer on Earth see slightly more than half of the lunar surface over time. `Astronoby::Moon#libration` returns a `Astronoby::Libration` value object holding the total (optical plus physical) libration in longitude and latitude, both as `Astronoby::Angle` objects. A positive longitude exposes more of the Moon's eastern limb (Mare Crisium side); a positive latitude exposes more of its northern limb.
+
+```rb
+libration = moon.libration
+
+libration.longitude.str(:dms) # => "-2° 5′ 4.4219″"
+libration.latitude.str(:dms)  # => "+0° 28′ 45.9616″"
+```
+
+By default this is the analytic optical plus physical libration from Meeus's series. Compared with the lunar orientation integrated in the JPL DE solution (as reported by JPL Horizons), the libration in longitude and the position angle of the axis agree to within a few arcseconds, while the libration in latitude agrees to about 0.02 degrees. That residual is the well known difference between the mean lunar equator used by the classical Meeus method and the DE mean-Earth frame. It is eliminated by loading an orientation kernel.
+
+## Arcsecond accuracy with an orientation kernel
+
+For the libration and the position angle of the axis, you can reach the accuracy of JPL Horizons, Skyfield and IMCCE by also loading a binary PCK lunar orientation kernel, such as `moon_pa_de440_200625.bpc`, which carries the integrated DE440 orientation of the Moon. Load it once with `Astronoby::Orientation` and pass it to the Moon alongside the ephemeris.
+
+```rb
+ephem = Astronoby::Ephem.load("de440.bsp")
+orientation = Astronoby::Orientation.load("moon_pa_de440_200625.bpc")
+
+moon = Astronoby::Moon.new(instant: instant, ephem: ephem, orientation: orientation)
+
+moon.libration.latitude.str(:dms)     # => "+0° 27′ 27.7258″"
+moon.position_angle_of_axis.str(:dms) # => "-21° 48′ 32.9625″"
+```
+
+The libration is then computed as the selenographic longitude and latitude of the sub-Earth point in the Moon's mean-Earth body-fixed frame, and matches JPL Horizons to better than an arcsecond. Without an orientation kernel the Moon keeps using the analytic method, so this is an opt-in refinement, not a requirement. The `bright_limb_position_angle` and `parallactic_angle` are unaffected and do not need a kernel.
+
+If you do not already have the kernel, Astronoby can download it for you.
+
+```rb
+Astronoby::Orientation.download(
+  name: "moon_pa_de440_200625.bpc",
+  target: "moon_pa_de440_200625.bpc"
+)
+```
+
+## Position angle of the axis
+
+`Astronoby::Moon#position_angle_of_axis` returns the position angle of the Moon's axis of rotation, the angle of the projection of the lunar north pole, measured eastward from the north point of the disk. It is returned as an `Astronoby::Angle`.
+
+```rb
+moon.position_angle_of_axis.str(:dms) # => "-21° 48′ 46.657″"
+```
+
+## Position angle of the bright limb
+
+`Astronoby::Moon#bright_limb_position_angle` returns the position angle of the midpoint of the illuminated limb, measured eastward from the north point of the disk, between 0 and 360 degrees. It is a geocentric quantity computed from the apparent equatorial coordinates of the Moon and the Sun, and it points towards the Sun, since the bright limb is the limb facing the Sun.
+
+```rb
+moon.bright_limb_position_angle.str(:dms) # => "+248° 1′ 57.9467″"
+```
+
+## 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. Unlike the previous quantities it depends on the observer, so it is computed from the topocentric place, where lunar parallax is significant. `Astronoby::Moon#parallactic_angle` takes an observer and returns an `Astronoby::Angle`.
+
+```rb
+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) # => "+11° 42′ 47.1246″"
+```
+
+## See also
+
+- [Solar System Bodies](solar_system_bodies.md) - for the Moon's other properties
+- [Moon Phases](moon_phases.md) - for lunar phase events
+- [Lunar Eclipses](lunar_eclipses.md) - for eclipses of the Moon
+- [Observer](observer.md) - for setting up observation locations
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Angles](angles.md) - for working with angular measurements

data/docs/moon_phases.md

@@ -69,11 +69,14 @@ phases.each { puts "#{_1.phase}: #{_1.time}" }
 # new_moon: 2024-05-08 03:21:56 UTC
 # first_quarter: 2024-05-15 11:48:02 UTC
 # full_moon: 2024-05-23 13:53:12 UTC
-# last_quarter: 2024-05-30 17:12:43 UTC
+# last_quarter: 2024-05-30 17:12:42 UTC
 ```
 
 ## See also
+
 - [Twilight Times](twilight_times.md) - for sun-related events
 - [Rise, Transit and Set Times](rise_transit_set_times.md) - for moon events
+- [Lunar Observation](lunar_observation.md) - for libration, axis and limb angles
+- [Lunar Eclipses](lunar_eclipses.md) - for eclipses of the Moon
 - [Solar System Bodies](solar_system_bodies.md) - for moon object details
 - [Ephemerides](ephem.md) - for data sources

data/docs/observer.md

@@ -6,19 +6,31 @@ events computed by Astronoby are location and date based.
 ## Initialization
 
 The two required key arguments to instantiate an observer are:
-* `latitude` (`Astronoby::Angle`): the angle from the equator to the observer,
+
+- `latitude` (`Astronoby::Angle`): the angle from the equator to the observer,
   from 90° to -90°, with positive angles for the Northern Hemisphere.
-* `longitude` (`Astronoby::Angle`): the angle from the Greenwich meridian to the
+- `longitude` (`Astronoby::Angle`): the angle from the Greenwich meridian to the
   observer, from 180° to -180°, with positive angles eastward of the Greenwich
   meridian.
 
-Latitude and longitude are defined according to the [World Geodetic System].
-In other words, they are the same as those used for the [GPS].
+Latitude and longitude are defined according to the [World Geodetic System]
+(WGS-84). In other words, they are the same as those used for the [GPS].
+
+Internally, the observer's geodetic coordinates are converted to geocentric
+Cartesian coordinates in the **International Terrestrial Reference System
+(ITRS)**, also known as Earth-Centered Earth-Fixed (ECEF). These are then
+rotated into the celestial frame using Earth rotation (GAST) via
+`Astronoby::EarthRotation` and IERS polar motion corrections. See
+[Reference Frames](reference_frames.md) for details.
+
+The reverse conversion (ECEF → geodetic) is available via
+[`Astronoby::Coordinates::Geodetic.from_ecef`][Coordinates page].
 
 It is also possible to give the following optional key arguments:
-* `elevation` (`Astronoby::Distance`): the distance above or below the average
+
+- `elevation` (`Astronoby::Distance`): the distance above or below the average
   sea level
-* `utc_offset`: local time difference with UTC. Check the [timezone specifiers]
+- `utc_offset`: local time difference with UTC. Check the [timezone specifiers]
   for the format.
 
 ```rb
@@ -57,8 +69,10 @@ observer1 == observer2
 [GPS]: https://en.wikipedia.org/wiki/GPS
 [timezone specifiers]: https://ruby-doc.org/3.4.1/Time.html#class-Time-label-Timezone+Specifiers
 [Angles page]: angles.md
+[Coordinates page]: coordinates.md#geodetic
 
 ## See also
+
 - [Angles](angles.md) - for working with latitude and longitude
 - [Coordinates](coordinates.md) - for understanding position systems
 - [Reference Frames](reference_frames.md) - for topocentric calculations

data/docs/planetary_phenomena.md

@@ -0,0 +1,78 @@
+# Planetary Phenomena
+
+Astronoby computes the classic planetary phenomena relative to the Sun: conjunctions, oppositions, and greatest elongations. They are all defined in the apparent geocentric ecliptic frame of date.
+
+The available phenomena depend on the planet. Inferior planets (Mercury and Venus) have conjunctions and greatest elongations. Superior planets (Mars to Neptune) have conjunctions and oppositions. Requesting a phenomenon that cannot occur for a given body raises an `Astronoby::UnsupportedEventError`.
+
+Each method takes an ephemeris and a time range, and returns the events found within that range.
+
+## Oppositions
+
+An opposition is the instant when a superior planet and the Sun have opposite apparent ecliptic longitudes (a difference of 180 degrees), so the planet is opposite the Sun in the sky.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+opposition = Astronoby::Mars.opposition_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first
+
+opposition.instant.to_time # => 2025-01-16 02:38:35 UTC
+opposition.body            # => Astronoby::Mars
+```
+
+## 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. Superior planets only ever have superior conjunctions.
+
+```rb
+conjunction = Astronoby::Venus.conjunction_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first
+
+conjunction.instant.to_time # => 2025-03-23 01:07:30 UTC
+conjunction.inferior?       # => true
+conjunction.superior?       # => false
+```
+
+## 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).
+
+```rb
+elongation = Astronoby::Mercury.greatest_elongation_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first
+
+elongation.instant.to_time   # => 2025-03-08 06:09:18 UTC
+elongation.angle.degrees     # => 18.25
+elongation.eastern?          # => true
+elongation.western?          # => false
+```
+
+## Elongation of a body
+
+The elongation of any Solar System body, the apparent Sun-Earth-body angle, is also available directly on a body instance, along with the side of the Sun it lies on.
+
+```rb
+instant = Astronoby::Instant.from_time(Time.utc(2025, 7, 14))
+venus = Astronoby::Venus.new(instant: instant, ephem: ephem)
+
+venus.elongation.degrees # => 41.47
+venus.eastern?           # => false
+venus.western?           # => true
+```
+
+## See also
+
+- [Solar System Bodies](solar_system_bodies.md) - for planets and their properties
+- [Equinoxes and Solstices Times](equinoxes_solstices_times.md) - for solar events
+- [Moon Phases](moon_phases.md) - for lunar events
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Ephemerides](ephem.md) - for data sources

data/docs/reference_frames.md

@@ -3,28 +3,42 @@
 A given body at a given time can be perceived at different positions, depending
 on the reference frame and the corrections applied.
 
-Astronoby provides five reference frames for each celestial body:
+Astronoby provides five reference frames for celestial bodies, forming a
+transformation chain:
 
-* Geometric
-* Astrometric
-* Mean of date
-* Apparent
-* Topocentric
+```
+Geometric (BCRS)
+  → Astrometric (GCRS)
+    → Mean of date
+      → Apparent
+        → Topocentric
+```
+
+Each step applies physical corrections to move closer to what an observer
+actually sees. The standard reference systems used follow the IAU/IERS
+conventions (see [Standard reference systems](#standard-reference-systems)
+below).
+
+A separate **TEME** (True Equator, Mean Equinox) frame is also available for
+satellite tracking. See [TEME](#teme) below.
 
 All reference frames provide this common interface:
 
-* `#position`: Vector of position as x,y,z `Astronoby::Distance` objects
-* `#velocity`: Vector of velocity as x,y,z `Astronoby::Velocity` objects
-* `#distance`: Distance from the centre (`Astronoby::Distance`)
-* `#equatorial`: Equatorial coordinates (`Astronoby::Coordinates::Equatorial`)
-* `#ecliptic`: Ecliptic coordinates (`Astronoby::Coordinates::Ecliptic`)
+- `#position`: Vector of position as x,y,z `Astronoby::Distance` objects
+- `#velocity`: Vector of velocity as x,y,z `Astronoby::Velocity` objects
+- `#distance`: Distance from the centre (`Astronoby::Distance`)
+- `#center`: The centre the frame is relative to (`Astronoby::Center`)
+- `#equatorial`: Equatorial coordinates (`Astronoby::Coordinates::Equatorial`)
+- `#ecliptic`: Ecliptic coordinates (`Astronoby::Coordinates::Ecliptic`)
+- `#separation_from(other)`: Angular separation to another frame
+  (`Astronoby::Angle`)
 
 ## Geometric
 
-Also called "mean J2000", this reference frame is related to the mean ecliptic
-or terrestrial equator and the mean equinox of the reference date (J2000). It is
-the strict position computed from the ephemeris file in a reference frame
-centered on the Solar System barycentre, with no corrections applied.
+The geometric frame corresponds to the **Barycentric Celestial Reference System
+(BCRS)**, centered on the Solar System barycentre, with axes aligned to the
+**International Celestial Reference System (ICRS)**. It is the raw position
+read from the ephemeris file, with no corrections applied.
 
 ```rb
 ephem = Astronoby::Ephem.load("inpop19a.bsp")
@@ -36,7 +50,7 @@ geometric = moon.geometric
 # => #<Astronoby::Geometric:0x000000011e7ffd40
 
 geometric.distance.au
-# => 1.0095091198501744
+# => 1.0095091267969827
 
 geometric.equatorial.right_ascension.str(:hms, precision: 0)
 # => "20h 13m 52s"
@@ -44,11 +58,11 @@ geometric.equatorial.right_ascension.str(:hms, precision: 0)
 
 ## Astrometric
 
-Also called "astrometric J2000", this reference frame is related to the ecliptic
-or the mean terrestrial equator and the mean equinox of the reference date
-(J2000). It applies light-time correction between the celestial body and the
-observer. The frame is centred on the Earth's centre, as are all the following
-reference frames.
+The astrometric frame corresponds to the **Geocentric Celestial Reference System
+(GCRS)**, centered on the Earth's centre, with axes still aligned to the ICRS.
+It is obtained by subtracting the Earth's barycentric position from the target's
+light-time-corrected barycentric position. All subsequent frames are also
+Earth-centered.
 
 ```rb
 ephem = Astronoby::Ephem.load("inpop19a.bsp")
@@ -67,10 +81,13 @@ astrometric.equatorial.right_ascension.str(:hms, precision: 0)
 
 ## Mean of date
 
-This reference frame is related to the ecliptic or the mean equator and the mean
-equinox of the date. It provides the geometric position corrected for the
-precessional motion of the Earth's rotation axis (precession and nutation).
+This frame is referred to the **mean equator and mean equinox of the date**. It
+is obtained by applying the precession-bias matrix to the geocentric ICRS
+position, rotating it from the ICRS axes to the mean pole and equinox at the
+given instant.
 
+Astronoby uses the **IAU 2006 precession** model in its Fukushima-Williams
+four-angle parameterization, which includes the ICRS-to-J2000 frame bias.
 
 ```rb
 ephem = Astronoby::Ephem.load("inpop19a.bsp")
@@ -86,11 +103,17 @@ mean_of_date.equatorial.right_ascension.str(:hms, precision: 0)
 
 ## Apparent
 
-This reference frame is related to the true ecliptic or equator and the true
-equinox of the date. It is the actual position in the sky of a celestial object
-as seen from the centre of the Earth. It applies several corrections to the
-astrometric position:the deflection of light, the aberration, the precession and
-the nutation.
+This frame is referred to the **true equator and true equinox of the date**. It
+represents the position of a celestial object as seen from the centre of the
+Earth. The following corrections are applied to the astrometric position:
+
+- **Aberration**: relativistic stellar aberration due to Earth's velocity
+  (Explanatory Supplement, Ch. 7.2.3)
+- **Precession**: IAU 2006 Fukushima-Williams precession-bias matrix
+- **Nutation**: IAU 2000B 77-term nutation model
+
+The combined N \* PB matrix rotates the aberration-corrected GCRS position into
+the true equator and equinox frame of the date.
 
 ```rb
 ephem = Astronoby::Ephem.load("inpop19a.bsp")
@@ -106,10 +129,16 @@ apparent.equatorial.right_ascension.str(:hms, precision: 0)
 
 ## Topocentric
 
-This reference frame is the final transformation of a position. It provides the
-apparent position of a celestial body as seen from a location on Earth. It can
-only be produced given an observer (`Astronoby::Observer`). It provides another
-set of coordinates: horizontal (`Astronoby::Coordinates::Horizontal`).
+This is the final frame in the chain, providing the position of a celestial body
+as seen from a specific location on Earth's surface. It can only be produced
+given an observer (`Astronoby::Observer`). It provides an additional set of
+coordinates: horizontal (`Astronoby::Coordinates::Horizontal`).
+
+To go from the apparent frame (true equator and equinox) to the topocentric
+frame, the observer's position must be transformed from the **International
+Terrestrial Reference System (ITRS)** into the same true-equinox frame. This is
+done by applying the **IERS polar motion matrix** (W) followed by the Earth
+rotation via **Greenwich Apparent Sidereal Time (GAST)**.
 
 ```rb
 ephem = Astronoby::Ephem.load("inpop19a.bsp")
@@ -124,12 +153,141 @@ moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
 topocentric = moon.observed_by(observer)
 
 topocentric.horizontal.azimuth.str(:dms, precision: 0)
-# => "+90° 14′ 19″"
+# => "+90° 14′ 24″"
 ```
 
 You can learn more about observers on the [Observer page].
 
+## Angular separation
+
+Any two frames can be compared with `#separation_from`, which returns the
+angular separation (an `Astronoby::Angle`, between 0° and 180°) between the two
+targets' directions as seen from their shared centre.
+
+The two frames may belong to different kinds of objects (a Solar System body
+and a deep-sky object, for example) as long as they are in the same reference
+frame and at the same instant. Otherwise the separation is not physically
+meaningful and an `Astronoby::IncompatibleArgumentsError` is raised.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+instant = Astronoby::Instant.from_time(Time.utc(2020, 12, 21, 18))
+
+jupiter = Astronoby::Jupiter.new(ephem: ephem, instant: instant)
+saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
+
+# The 2020 "Great Conjunction", the closest since 1623
+separation = jupiter.apparent.separation_from(saturn.apparent)
+
+separation.str(:dms, precision: 0)
+# => "+0° 6′ 6″"
+```
+
+## TEME
+
+The **TEME (True Equator, Mean Equinox)** frame is the output frame of the
+SGP4/SDP4 satellite orbit propagators. Unlike the five frames above, TEME is
+not part of the celestial body chain — it is constructed directly from SGP4
+output and provides its own conversion methods.
+
+TEME shares the true equator with the apparent frame but uses the mean equinox
+(tracked by GMST) instead of the true equinox (tracked by GAST). The
+difference between the two is the equation of the equinoxes.
+
+### Conversions
+
+`Astronoby::Teme` provides three conversion methods:
+
+- `#to_ecef` - ECEF position and velocity, using R₃(GMST) and the ω×r
+  velocity correction. The returned `EcefCoordinates` object also provides
+  a `#geodetic` method to convert to WGS-84 geodetic coordinates
+  (`Astronoby::Coordinates::Geodetic`)
+- `#to_gcrs` - GCRS position and velocity (returns an `Astronoby::Astrometric`
+  frame), using the transposed precession and nutation matrices
+- `#observed_by(observer)` - topocentric position as seen from a specific
+  observer (returns an `Astronoby::Topocentric` frame)
+
+```rb
+instant = Astronoby::Instant.from_time(Time.utc(2025, 6, 15, 12))
+
+# Construct from SGP4 output
+teme = Astronoby::Teme.new(
+  position: Astronoby::Distance.vector_from_meters(
+    [4_154_639.35, 768_141.62, -5_327_440.29]
+  ),
+  velocity: Astronoby::Velocity.vector_from_mps(
+    [-1152.15, 7561.14, 192.76]
+  ),
+  instant: instant
+)
+
+# Convert to ECEF
+ecef = teme.to_ecef
+ecef.position[0].km
+# => 1196.49...
+
+# Convert ECEF to geodetic (WGS-84)
+geodetic = ecef.geodetic
+geodetic.latitude.str(:dms)
+# => "+10° 29′ 51.7526″"
+
+# Convert to GCRS
+gcrs = teme.to_gcrs
+gcrs.equatorial.right_ascension.str(:hms, precision: 0)
+# => "0h 40m 42s"
+
+# Observe from a location
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.8566),
+  longitude: Astronoby::Angle.from_degrees(2.3522)
+)
+topocentric = teme.observed_by(observer)
+topocentric.horizontal.azimuth.str(:dms, precision: 0)
+# => "+223° 53′ 41″"
+```
+
+## Earth rotation
+
+`Astronoby::EarthRotation` provides standalone Earth rotation matrices:
+
+- `EarthRotation.matrix_for(instant)` — R₃(GAST), the apparent rotation
+  matrix (used for observer placement in the true-equinox frame)
+- `EarthRotation.mean_matrix_for(instant)` — R₃(GMST), the mean rotation
+  matrix (used for TEME ↔ ECEF conversions)
+
+Both return 3×3 orthogonal rotation matrices that transform ECEF coordinates
+into the corresponding celestial frame.
+
+## Standard reference systems
+
+The table below maps Astronoby's reference frames to standard IAU/IERS
+reference systems and lists the corrections applied at each step.
+
+| Astronoby frame | Standard system | Origin                  | Axes                                | Corrections applied                                                     |
+| --------------- | --------------- | ----------------------- | ----------------------------------- | ----------------------------------------------------------------------- |
+| Geometric       | BCRS            | Solar System barycentre | ICRS                                | None (raw ephemeris)                                                    |
+| Astrometric     | GCRS            | Earth centre            | ICRS                                | Light-time, origin shift                                                |
+| Mean of date    | —               | Earth centre            | Mean equator & equinox of date      | IAU 2006 precession (Fukushima-Williams, incl. frame bias)              |
+| Apparent        | —               | Earth centre            | True equator & equinox of date      | Aberration, precession, IAU 2000B nutation                              |
+| Topocentric     | —               | Observer                | True equator & equinox of date      | GAST earth rotation, IERS polar motion, observer position (WGS-84/ITRS) |
+| TEME            | —               | Earth centre            | True equator & mean equinox of date | SGP4/SDP4 output frame; converts to ECEF, GCRS, or topocentric          |
+
+### Models and references
+
+- **Precession**: IAU 2006 P03, Fukushima-Williams parameterization including
+  ICRS frame bias (IERS Conventions 2010, Section 5.6.4; ERFA `eraPfw06` /
+  `eraFw2m`)
+- **Nutation**: IAU 2000B, 77-term truncation of the IAU 2000A model (IERS
+  Conventions 2010, Section 5.5.2)
+- **Aberration**: Relativistic stellar aberration (Explanatory Supplement to the
+  Astronomical Almanac, Ch. 7.2.3)
+- **Earth rotation**: Greenwich Apparent Sidereal Time (GAST) computed as GMST +
+  equation of equinoxes (IERS Conventions 2010, Section 5.5.7)
+- **Polar motion**: IERS Earth Orientation Parameters via the `iers` gem
+- **Observer coordinates**: WGS-84 geodetic to geocentric (ITRS/ECEF) conversion
+
 ## See also
+
 - [Coordinates](coordinates.md) - for understanding coordinate systems
 - [Observer](observer.md) - for location setup
 - [Solar System Bodies](solar_system_bodies.md) - for object positions

data/docs/rise_transit_set_times.md

@@ -10,10 +10,11 @@ Once instantiated, the calculator doesn't do anything yet, it waits for your
 instruction.
 
 It takes as key arguments:
-* `body` (`Astronoby::SolarSystemBody` or `Astronoby::DeepSkyObject`): any
+
+- `body` (`Astronoby::SolarSystemBody` or `Astronoby::DeepSkyObject`): any
   supported celestial body, e.g. `Astronoby::Sun`
-* `observer` (`Astronoby::Observer`): location on Earth of the observer
-* `ephem`: ephemeris to provide the initial raw data
+- `observer` (`Astronoby::Observer`): location on Earth of the observer
+- `ephem`: ephemeris to provide the initial raw data
 
 You can learn more about [Solar System bodies] and [ephemerides].
 
@@ -56,7 +57,7 @@ events.transit_times
 # => [2025-05-01 07:21:34 UTC, 2025-05-02 07:18:01 UTC]
 
 events.setting_times
-# => [2025-05-01 13:14:24 UTC, 2025-05-02 13:10:59 UTC]
+# => [2025-05-01 13:14:24 UTC, 2025-05-02 13:10:58 UTC]
 ```
 
 ## `#events_on`
@@ -113,6 +114,7 @@ event.setting_time.localtime(utc_offset)
 [ephemerides]: ephem.md
 
 ## See also
+
 - [Twilight Times](twilight_times.md) - for sun-related events
 - [Solar System Bodies](solar_system_bodies.md) - for object information
 - [Observer](observer.md) - for location setup

data/docs/solar_system_bodies.md

@@ -2,9 +2,10 @@
 
 Currently, Astronoby only supports the following major bodies of the Solar
 System:
-* the Sun (`Astronoby::Sun`)
-* planets from Mercury to Neptune, including the Earth (`Astronoby::Earth`, ...)
-* the Moon (`Astronoby::Moon`)
+
+- the Sun (`Astronoby::Sun`)
+- planets from Mercury to Neptune, including the Earth (`Astronoby::Earth`, ...)
+- the Moon (`Astronoby::Moon`)
 
 Given an ephemeris (`Astronoby::Ephem`) and an instant object
 (`Astronoby::Instant`), these classes enable you to get instances which provide
@@ -21,7 +22,7 @@ venus = Astronoby::Venus.new(ephem: ephem, instant: instant)
 apparent_position = venus.apparent.position
 
 apparent_position.x.km.round
-# => -148794622
+# => -148794597
 ```
 
 Each of these bodies also provides its own equatorial radius
@@ -60,6 +61,26 @@ venus.constellation.abbreviation
 # => "Cnc"
 ```
 
+### `#elongation`
+
+Apparent angular distance between the body and the Sun, as seen from Earth
+("Sun-Earth-object" angle). Returns a `Astronoby::Angle` object.
+
+```rb
+venus.elongation.degrees.round
+# => 41
+```
+
+### `#eastern?` and `#western?`
+
+Whether the body lies east of the Sun (visible in the evening) or west of it
+(visible in the morning). Both return a `Boolean`.
+
+```rb
+venus.eastern? # => false
+venus.western? # => true
+```
+
 ### `#phase_angle`
 
 "Sun-object-Earth" angle. Returns a `Astronoby::Angle` object.
@@ -101,6 +122,7 @@ Astronoby::Venus.absolute_magnitude
 [reference frames]: reference_frames.md
 
 ## See also
+
 - [Ephemerides](ephem.md) - for understanding data sources
 - [Reference Frames](reference_frames.md) - for coordinate systems
 - [Observer](observer.md) - for setting up observation locations