astronoby 0.9.0 → 0.10.0

data/docs/equinoxes_solstices_times.md

@@ -15,16 +15,17 @@ Astronoby::EquinoxSolstice.march_equinox(2025, ephem)
 # => 2025-03-20 09:01:29 UTC
 
 Astronoby::EquinoxSolstice.june_solstice(2025, ephem)
-# => 2025-06-21 02:42:19 UTC
+# => 2025-06-21 02:42:16 UTC
 
 Astronoby::EquinoxSolstice.september_equinox(2025, ephem)
-# => 2025-09-22 18:19:22 UTC
+# => 2025-09-22 18:19:21 UTC
 
 Astronoby::EquinoxSolstice.december_solstice(2025, ephem)
-# => 2025-12-21 15:03:03 UTC
+# => 2025-12-21 15:03:05 UTC
 ```
 
 ## See also
+
 - [Twilight Times](twilight_times.md) - for seasonal sun events
 - [Moon Phases](moon_phases.md) - for lunar events
 - [Ephemerides](ephem.md) - for data sources

data/docs/glossary.md

@@ -5,130 +5,223 @@ This glossary defines key astronomical and technical terms used throughout the A
 ## Astronomical Terms
 
 ### **Aberration**
+
 The apparent displacement of a celestial object due to the finite speed of light and the motion of the observer. In Astronoby, this is automatically corrected in apparent reference frames.
 
 ### **Altitude**
+
 The angular distance of a celestial object above the observer's local horizon, measured in degrees from 0° (horizon) to 90° (zenith).
 
 ### **Apparent Position**
+
 The position of a celestial object as it appears in the sky, corrected for light-time, aberration, and other effects. This is what you actually see when looking through a telescope.
 
 ### **Arc Second**
+
 A unit of angular measurement equal to 1/3600th of a degree. Often used to describe the precision of astronomical calculations.
 
 ### **Azimuth**
+
 The angular distance around the horizon from north, measured clockwise in degrees. North is 0°, east is 90°, south is 180°, and west is 270°.
 
 ### **Barycentre**
+
 The centre of mass of a system of bodies. In the Solar System, this is the point around which all planets orbit, which is usually close to but not exactly at the Sun's centre.
 
 ### **Celestial Equator**
+
 The projection of Earth's equator onto the celestial sphere. It's the reference plane for equatorial coordinates.
 
 ### **Celestial Sphere**
+
 An imaginary sphere surrounding Earth, on which all celestial objects appear to be located. Used as a reference system for astronomical coordinates.
 
 ### **Constellation**
+
 A region of the sky containing a group of stars that form a recognizable pattern. Astronoby can determine which constellation a celestial body appears to be in.
 
 ### **Declination**
+
 The angular distance north or south of the celestial equator, measured in degrees. Positive values are north, negative values are south.
 
 ### **Ecliptic**
+
 The apparent path of the Sun across the celestial sphere throughout the year. It's the plane of Earth's orbit around the Sun.
 
 ### **Ephemeris**
+
 A table or file containing the calculated positions of celestial objects at specific times. Astronoby uses ephemeris files from JPL and IMCCE for high-precision calculations.
 
 ### **Equinox**
+
 The two times each year when the Sun crosses the celestial equator, making day and night approximately equal in length. The March (vernal) and September (autumnal) equinoxes.
 
 ### **Geocentric**
+
 As seen from the centre of Earth. Geocentric coordinates are useful for calculations but don't account for an observer's specific location.
 
 ### **Horizon**
+
 The apparent boundary between Earth and sky as seen by an observer. The local horizon depends on the observer's location and elevation.
 
 ### **Illuminated Fraction**
+
 The portion of a celestial body's disk that appears illuminated as seen from Earth. For the Moon, this varies from 0 (new moon) to 1 (full moon).
 
 ### **Julian Date**
+
 A continuous count of days since January 1, 4713 BCE. Used in astronomy for precise time measurements and calculations.
 
 ### **Light-Time Correction**
+
 The adjustment made to account for the time it takes light to travel from a celestial object to Earth. Important for accurate position calculations.
 
 ### **Magnitude**
+
 A measure of a celestial object's brightness. Lower numbers indicate brighter objects (e.g., -4 is brighter than +2). Apparent magnitude is as seen from Earth, absolute magnitude is intrinsic brightness.
 
 ### **Meridian**
+
 An imaginary line passing through the observer's zenith and the north and south celestial poles. Objects transit (cross) the meridian when they reach their highest point in the sky.
 
 ### **Nutation**
+
 Small periodic variations in the orientation of Earth's rotation axis, caused by gravitational forces from the Sun and Moon.
 
 ### **Obliquity**
+
 The angle between Earth's equatorial plane and the ecliptic plane. Currently about 23.4° and slowly decreasing.
 
 ### **Parallax**
+
 The apparent shift in position of a nearby object when viewed from different locations. Important for calculating distances to nearby stars.
 
 ### **Phase Angle**
+
 The angle between the Sun, a celestial object, and Earth. For planets, this determines how much of the disk is illuminated.
 
 ### **Precession**
+
 The slow, continuous change in the orientation of Earth's rotation axis, causing the positions of the equinoxes to shift over time.
 
 ### **Refraction**
+
 The bending of light as it passes through Earth's atmosphere, causing celestial objects to appear slightly higher in the sky than they actually are.
 
 ### **Right Ascension**
+
 The angular distance eastward along the celestial equator from the vernal equinox, measured in hours (0-24h) or degrees (0-360°).
 
 ### **Solstice**
+
 The two times each year when the Sun reaches its northernmost (June) or southernmost (December) position relative to the celestial equator.
 
 ### **Topocentric**
+
 As seen from a specific location on Earth's surface. Topocentric positions account for the observer's latitude, longitude, and elevation.
 
+### **TEME (True Equator, Mean Equinox)**
+
+The reference frame used by the SGP4/SDP4 satellite orbit propagators. It shares the true equator with the apparent frame but uses the mean equinox (tracked by GMST) instead of the true equinox (tracked by GAST).
+
 ### **Transit**
+
 The moment when a celestial object crosses the observer's meridian, reaching its highest point in the sky for that day.
 
 ### **Twilight**
+
 The period before sunrise and after sunset when the sky is partially illuminated by scattered sunlight. Civil, nautical, and astronomical twilight have different definitions based on the Sun's position below the horizon.
 
 ### **Zenith**
+
 The point directly above an observer on Earth, at an altitude of 90°.
 
 ## Technical Terms
 
 ### **API (Application Programming Interface)**
+
 The set of methods and classes that programmers use to interact with the Astronoby library.
 
+### **Body**
+
+A catalog definition that can position itself at an instant, returning a Position. Solar system bodies (the classes themselves, e.g. `Astronoby::Saturn`) and deep-sky objects (`Astronoby::DeepSkyObject` instances) both fulfil this role.
+
 ### **Cache**
+
 A temporary storage system that stores frequently used calculation results to improve performance.
 
+### **Centre**
+
+The point a reference frame is relative to, modelled by the `Astronoby::Center` value object: barycentric (Solar System barycentre), geocentric (Earth's centre), or topocentric (a specific observer's location).
+
 ### **Coordinate System**
+
 A system for specifying the position of objects in space. Astronoby supports equatorial, ecliptic, and horizontal coordinate systems.
 
 ### **Ephemeris File**
+
 A binary file (usually with .bsp extension) containing orbital data for Solar System bodies. These files are produced by JPL and IMCCE.
 
 ### **Floating-Point Precision**
+
 The accuracy of decimal number calculations. Higher precision values in Astronoby provide more accurate results but may be slower.
 
+### **BCRS (Barycentric Celestial Reference System)**
+
+A coordinate system centered on the Solar System barycentre with axes aligned to the ICRS. In Astronoby, this corresponds to the geometric reference frame.
+
+### **ECEF (Earth-Centered Earth-Fixed)**
+
+A Cartesian coordinate system that rotates with the Earth. Equivalent to ITRS. In Astronoby, observer positions are expressed in ECEF.
+
+### **Equation of the Equinoxes**
+
+The difference between Greenwich Apparent Sidereal Time (GAST) and Greenwich Mean Sidereal Time (GMST), equal to the nutation in longitude projected onto the equator (Δψ cos ε₀). It defines the angular offset between the mean and true equinoxes.
+
+### **GAST (Greenwich Apparent Sidereal Time)**
+
+The hour angle of the true vernal equinox at the Greenwich meridian. Equal to GMST plus the equation of the equinoxes. Used to rotate observer positions from ECEF into the true-equinox celestial frame.
+
+### **GCRS (Geocentric Celestial Reference System)**
+
+A coordinate system centered on the Earth's centre with axes aligned to the ICRS. In Astronoby, this corresponds to the astrometric reference frame.
+
+### **GMST (Greenwich Mean Sidereal Time)**
+
+The hour angle of the mean vernal equinox at the Greenwich meridian. It measures Earth's rotation relative to the mean equinox, without nutation corrections. Used in the TEME ↔ ECEF conversion.
+
+### **ICRS (International Celestial Reference System)**
+
+The standard celestial reference system adopted by the IAU. Its axes are defined by the positions of extragalactic radio sources and are practically fixed in space. JPL ephemeris data is given in ICRS-aligned coordinates.
+
+### **ITRS (International Terrestrial Reference System)**
+
+The standard Earth-fixed reference system, also known as ECEF (Earth-Centered Earth-Fixed). Observer positions in Astronoby are expressed in ITRS before being rotated into the celestial frame.
+
+### **Position**
+
+A target resolved at a specific instant, exposing the reference frame chain (astrometric, apparent, topocentric, ...) for a Body. Solar system body instances and `Astronoby::DeepSkyObjectPosition` instances fulfil this role.
+
 ### **Reference Frame**
-A coordinate system used to specify positions. Astronoby provides geometric, astrometric, mean of date, apparent, and topocentric reference frames.
+
+A coordinate system used to specify positions. Astronoby provides geometric, astrometric, mean of date, apparent, and topocentric reference frames for celestial bodies, plus TEME for satellite tracking. See [Reference Frames](reference_frames.md) for how they map to IAU/IERS standard systems.
+
+### **WGS-84 (World Geodetic System 1984)**
+
+The geodetic reference system used by GPS and Astronoby for specifying observer latitude, longitude, and elevation. Observer coordinates are converted from WGS-84 geodetic to ITRS geocentric Cartesian internally.
 
 ### **SPICE**
+
 A NASA toolkit for computing positions and orientations of Solar System bodies. Astronoby uses SPICE binary kernels (.bsp files) for ephemeris data.
 
 ### **UTC (Coordinated Universal Time)**
+
 The primary time standard used worldwide. All astronomical calculations in Astronoby are based on UTC.
 
 ## Units and Measurements
 
 ### **Angular Units**
+
 - **Degree (°)**: 1/360th of a circle
 - **Arc Minute (′)**: 1/60th of a degree
 - **Arc Second (″)**: 1/60th of an arc minute
@@ -136,16 +229,19 @@ The primary time standard used worldwide. All astronomical calculations in Astro
 - **Radian**: 180/π degrees (≈57.3°)
 
 ### **Distance Units**
+
 - **Astronomical Unit (AU)**: The average distance between Earth and Sun (≈149.6 million km)
 - **Kilometre (km)**: Standard metric unit for distances
 - **Metre (m)**: Standard metric unit for elevations
 
 ### **Time Units**
+
 - **Julian Day**: Continuous day count since 4713 BCE
 - **Terrestrial Time (TT)**: Astronomical time scale used for calculations
 - **UTC**: Coordinated Universal Time, the standard for civil time
 
 ## See also
+
 - [Quick Start Guide](README.md) - for getting started
 - [Coordinates](coordinates.md) - for coordinate systems
 - [Reference Frames](reference_frames.md) - for position calculations

data/docs/iers.md

@@ -0,0 +1,40 @@
+# IERS Data
+
+Astronoby relies on the [`iers`](https://github.com/rhannequin/iers) gem for
+access to data published by the [International Earth Rotation and Reference
+Systems Service (IERS)][IERS]. This data is used for:
+
+- **Delta T (TT - UT1)**: the difference between Terrestrial Time and Universal
+  Time, used when converting between UTC and the internal TT time scale (see
+  [Instant](instant.md))
+- **Greenwich Mean Sidereal Time (GMST)**: computed via the Earth Rotation Angle
+  (ERA) based expression from the [IERS Conventions (2010)]
+
+## Data coverage
+
+The `iers` gem ships with bundled IERS data files that work out of the box
+with no network access required. The bundled data covers dates roughly from
+1800 to early 2027.
+
+- **Before 1800**: Delta T is not available; Astronoby returns 0.
+- **After the end of bundled data**: Astronoby uses the last known Delta T
+  value, which remains a reasonable approximation for dates in the near future.
+
+## Updating data
+
+The bundled data can be refreshed to extend coverage into the future:
+
+```rb
+IERS::Data.update!
+```
+
+This downloads the latest IERS finals data and stores it in the gem's cache
+directory. Updated data is used automatically on subsequent calculations.
+
+## See also
+
+- [Instant](instant.md) - for time scales and Delta T
+- [Configuration](configuration.md) - for performance settings
+
+[IERS]: https://www.iers.org
+[IERS Conventions (2010)]: https://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html

data/docs/instant.md

@@ -14,7 +14,9 @@ from the irregularities in the rotation of Earth and the irregularly fluctuating
 mean solar time.
 
 Astronoby handles this situation by implementing an `Astronoby::Instant` class,
-used in most calculations instead of `Time`.
+used in most calculations instead of `Time`. Converting between UTC and
+Terrestrial Time requires knowing [Delta T (TT - UT1)][Delta T], which
+Astronoby obtains from [IERS data](iers.md).
 
 `Astronoby::Instant` is a value object that stores an instant in time on Earth
 in [Terrestrial Time], an astronomical time standard defined by the
@@ -28,9 +30,10 @@ standards can be expressed, such as the
 ## Initialization
 
 An `Astronoby::Instant` object can be instantiated from:
-* Terrestrial time (`Numeric`): `.from_terrestrial_time`
-* Ruby `Time` object: `.from_time`
-* UTC Julian date (`Numeric`): `.from_utc_julian_date`
+
+- Terrestrial time (`Numeric`): `.from_terrestrial_time`
+- Ruby `Time` object: `.from_time`
+- UTC Julian date (`Numeric`): `.from_utc_julian_date`
 
 ```rb
 Astronoby::Instant.from_terrestrial_time(2460796)
@@ -48,7 +51,7 @@ Astronoby::Instant.from_utc_julian_date(2460796)
 
 From the same instant, it is possible to extract different time standards.
 
-* Gregorian `Date`
+- Gregorian `Date`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
@@ -57,34 +60,34 @@ instant.to_date
 # => #<Date: 2025-04-30 ((2460796j,0s,0n),+0s,2299161j)>
 ```
 
-* UTC `DateTime`
+- UTC `DateTime`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.to_datetime
-# => #<DateTime: 2025-04-30T11:58:51+00:00 ((2460796j,43131s,12159n),+0s,2299161j)>
+# => #<DateTime: 2025-04-30T11:58:50+00:00 ((2460796j,43130s,845637619n),+0s,2299161j)>
 ```
 
-* UTC `Time`
+- UTC `Time`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.to_datetime
-# => 2025-04-30 11:58:51.000012159 UTC
+# => 2025-04-30T11:58:50+00:00 UTC
 ```
 
-* Greenwich Sidereal Time
+- Greenwich Sidereal Time
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.gmst
-# => 2.5597425440141457
+# => 2.5597070126923764
 ```
 
-* International Atomic Time
+- International Atomic Time
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
@@ -93,16 +96,16 @@ instant.tai.to_f
 # => 2460795.9996275003
 ```
 
-* UTC offset (difference with UTC in days)
+- UTC offset (difference with UTC in days)
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.utc_offset.to_f
-# => 0.0007986109703819444
+# => 0.0008003974106626159
 ```
 
-* Barycentric Dynamic Time
+- Barycentric Dynamic Time
 
 ```rb
 # This is not handled for now, and returns TT
@@ -131,8 +134,10 @@ instant1 < instant2
 [Gregorian calendar]: https://en.wikipedia.org/wiki/Gregorian_calendar
 [Terrestrial Time]: https://en.wikipedia.org/wiki/Terrestrial_Time
 [Julian Date]: https://en.wikipedia.org/wiki/Julian_day
+[Delta T]: https://en.wikipedia.org/wiki/ΔT_(timekeeping)
 
 ## See also
+
 - [Ephemerides](ephem.md) - for time-based calculations
 - [Solar System Bodies](solar_system_bodies.md) - for object positions
 - [Reference Frames](reference_frames.md) - for coordinate systems

data/docs/lunar_eclipses.md

@@ -0,0 +1,93 @@
+# Lunar Eclipses
+
+Astronoby computes lunar eclipses: the passages of the Moon through Earth's shadow. A lunar eclipse is a geocentric event, the same for every observer who can see the Moon, so no observer is involved. The geometry is built from the apparent geocentric positions of the Sun and Moon, which matches the standard reduction used by [NASA's Five Millennium Canon of Lunar Eclipses] and by IMCCE.
+
+There are three kinds of lunar eclipses. A penumbral eclipse is when the Moon only enters Earth's penumbra, the outer, partial shadow. A partial eclipse is when part of the Moon enters the umbra, the inner, total shadow. A total eclipse is when the whole Moon enters the umbra.
+
+## Finding eclipses
+
+`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.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+eclipses = Astronoby::Moon.eclipse_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+)
+
+eclipses.map { |eclipse| [eclipse.instant.to_time, eclipse.kind] }
+# => [[2025-03-14 06:58:47 UTC, :total], [2025-09-07 18:11:49 UTC, :total]]
+```
+
+## An eclipse
+
+Each eclipse is an `Astronoby::LunarEclipse`. Its `#instant` (also available as `#greatest_eclipse`) is the moment of greatest eclipse, when the Moon's centre is least distant from the axis of Earth's shadow.
+
+```rb
+eclipse = eclipses.first
+
+eclipse.kind                 # => :total
+eclipse.total?               # => true
+eclipse.instant.to_time      # => 2025-03-14 06:58:47 UTC
+eclipse.greatest_eclipse     # => same as #instant
+```
+
+The umbral and penumbral magnitudes are the fractions of the Moon's diameter immersed in the umbra and the penumbra at greatest eclipse. The umbral magnitude is negative for a penumbral eclipse (the Moon misses the umbra), between 0 and 1 for a partial eclipse, and 1 or more for a total eclipse.
+
+```rb
+eclipse.umbral_magnitude     # => 1.179
+eclipse.penumbral_magnitude  # => 2.26
+```
+
+`#gamma` is the least distance of the Moon's centre from the axis of Earth's shadow at greatest eclipse, in Earth radii, positive when the Moon passes north of the axis and negative when it passes south. It is the standard, dimensionless eclipse parameter used by IMCCE and NASA. The same quantity is also available as a `Astronoby::Distance` through `#shadow_axis_distance`.
+
+```rb
+eclipse.gamma                       # => 0.348
+eclipse.shadow_axis_distance.km     # => 2222.37
+```
+
+## Phases
+
+An eclipse exposes its phases as `Astronoby::EclipsePhase` objects, each with a `#starting_instant`, an `#ending_instant`, and a `#duration` (an `Astronoby::Duration`). The penumbral phase is always present. The partial phase is present for partial and total eclipses, and the total phase (totality) only for total eclipses. A phase that does not occur is `nil`.
+
+```rb
+eclipse.penumbral.starting_instant.to_time # => 2025-03-14 03:57:29 UTC (P1)
+eclipse.partial.starting_instant.to_time   # => 2025-03-14 05:09:37 UTC (U1)
+eclipse.total.starting_instant.to_time     # => 2025-03-14 06:26:01 UTC (U2)
+eclipse.total.ending_instant.to_time       # => 2025-03-14 07:31:32 UTC (U3)
+eclipse.partial.ending_instant.to_time     # => 2025-03-14 08:47:55 UTC (U4)
+eclipse.penumbral.ending_instant.to_time   # => 2025-03-14 10:00:08 UTC (P4)
+
+eclipse.total.duration.seconds # => 3931 (seconds of totality)
+```
+
+For a penumbral eclipse, `#partial` and `#total` are `nil`. For a partial eclipse, `#total` is `nil`.
+
+```rb
+penumbral_eclipse = Astronoby::Moon.eclipse_events(
+  ephem: ephem,
+  start_time: Time.utc(2024, 3, 1),
+  end_time: Time.utc(2024, 4, 1)
+).first
+
+penumbral_eclipse.kind    # => :penumbral
+penumbral_eclipse.partial # => nil
+penumbral_eclipse.total   # => nil
+```
+
+## Precision
+
+Earth's shadow is enlarged by its atmosphere. Astronoby enlarges Earth's radius by 1/99 before building the shadow cones, a factor calibrated against IMCCE. Validated across the 2023 to 2025 eclipses, the eclipse kind, greatest eclipse instant, magnitudes, and contact times all match IMCCE to within a second or two.
+
+## See also
+
+- [Moon Phases](moon_phases.md) - for lunar phases
+- [Lunar Observation](lunar_observation.md) - for libration, axis and limb angles
+- [Planetary Phenomena](planetary_phenomena.md) - for conjunctions, oppositions and elongations
+- [Solar System Bodies](solar_system_bodies.md) - for moon object details
+- [Ephemerides](ephem.md) - for data sources
+
+[NASA's Five Millennium Canon of Lunar Eclipses]: https://eclipse.gsfc.nasa.gov/SEpubs/5MCLE.html
+[IMCCE]: https://www.imcce.fr/

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