astronoby 0.9.0 → 0.10.0

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

data/docs/twilight_times.md

@@ -5,14 +5,15 @@ some of its light still illuminates the atmosphere, making the sky brighter than
 during full night.
 
 We usually define 4 moments when talking about twilight:
-* sunrise/sunset: right when the Sun goes above the horizon or right after it
+
+- sunrise/sunset: right when the Sun goes above the horizon or right after it
   goes below the horizon. The Sun's horizon angle is 0°.
-* civil twilight: when the horizon angle is between 0° and -6°. Usually, during
+- civil twilight: when the horizon angle is between 0° and -6°. Usually, during
   this time, artificial light is not needed yet.
-* nautical twilight: when the horizon angle is between -6° and -12°. When the
+- nautical twilight: when the horizon angle is between -6° and -12°. When the
   nautical twilight starts, the difference between the horizon at sea and the
   sky cannot be seen clearly anymore.
-* astronomical twilight: when the horizon angle is between -12° and -18°. Some
+- astronomical twilight: when the horizon angle is between -12° and -18°. Some
   stars can be seen during this time.
 
 These moments change every day and depend on the observer's location. They can
@@ -24,8 +25,9 @@ Once instantiated, the calculator doesn't do anything yet, it waits for your
 instruction.
 
 It takes as key arguments:
-* `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 ephemerides on the [Ephem page].
 
@@ -53,17 +55,18 @@ that will happen between two dates.
 
 It returns a `Astronoby::TwilightEvents` object which exposes the 6 following
 instance methods:
-* `#morning_astronomical_twilight_times`: when the rising Sun reaches 18° below
+
+- `#morning_astronomical_twilight_times`: when the rising Sun reaches 18° below
   the horizon
-* `#morning_nautical_twilight_times`: when the rising Sun reaches 12° below the
+- `#morning_nautical_twilight_times`: when the rising Sun reaches 12° below the
   horizon
-* `#morning_civil_twilight_times`: when the rising Sun reaches 6° below the
+- `#morning_civil_twilight_times`: when the rising Sun reaches 6° below the
   horizon
-* `#evening_civil_twilight_times`: when the setting Sun reaches 6° below the
+- `#evening_civil_twilight_times`: when the setting Sun reaches 6° below the
   horizon
-* `#evening_nautical_twilight_times`: when the setting Sun reaches 12° below the
+- `#evening_nautical_twilight_times`: when the setting Sun reaches 12° below the
   horizon
-* `#evening_astronomical_twilight_times`: when the setting Sun reaches 18° below
+- `#evening_astronomical_twilight_times`: when the setting Sun reaches 18° below
   the horizon
 
 ```rb
@@ -76,11 +79,11 @@ events.morning_civil_twilight_times
 # =>
 # [2025-08-01 02:29:17 UTC,
 #  2025-08-02 02:30:21 UTC,
-#  2025-08-03 02:31:26 UTC,
+#  2025-08-03 02:31:25 UTC,
 #  2025-08-04 02:32:30 UTC,
-#  2025-08-05 02:33:35 UTC,
-#  2025-08-06 02:34:40 UTC,
-#  2025-08-07 02:35:45 UTC]
+#  2025-08-05 02:33:34 UTC,
+#  2025-08-06 02:34:39 UTC,
+#  2025-08-07 02:35:44 UTC]
 ```
 
 ## `#event_on`
@@ -98,25 +101,26 @@ instance methods: `#morning_astronomical_twilight_time`,
 event = calculator.event_on(Date.new(2025, 5, 1))
 
 event.morning_astronomical_twilight_time
-# => 2025-05-01 01:17:18 UTC
+# => 2025-05-01 01:16:21 UTC
 
 event.morning_nautical_twilight_time
-# => 2025-05-01 01:56:48 UTC
+# => 2025-05-01 01:55:54 UTC
 
 event.evening_civil_twilight_time
-# => 2025-05-01 17:29:41 UTC
+# => 2025-05-01 17:30:45 UTC
 
 event.evening_nautical_twilight_time
-# => 2025-05-01 18:06:08 UTC
+# => 2025-05-01 18:07:13 UTC
 
 event.evening_astronomical_twilight_time
-# => 2025-05-01 18:45:38 UTC
+# => 2025-05-01 18:46:47 UTC
 ```
 
 [Ephem page]: ephem.md
 [Observer page]: observer.md
 
 ## See also
+
 - [Rise, Transit and Set Times](rise_transit_set_times.md) - for sun and moon events
 - [Observer](observer.md) - for location setup
 - [Ephemerides](ephem.md) - for data sources