astronoby 0.8.0 → 0.10.0

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,15 +153,144 @@ 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
-- [Celestial Bodies](celestial_bodies.md) - for object positions
+- [Solar System Bodies](solar_system_bodies.md) - for object positions
 - [Ephemerides](ephem.md) - for data sources
 
 [Observer page]: observer.md

data/docs/rise_transit_set_times.md

@@ -10,12 +10,13 @@ Once instantiated, the calculator doesn't do anything yet, it waits for your
 instruction.
 
 It takes as key arguments:
-* `body` (`Astronoby::SolarSystemBody`): 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
 
-You can learn more about [celestial bodies] and [ephemerides].
+- `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
+
+You can learn more about [Solar System bodies] and [ephemerides].
 
 ```rb
 ephem = Astronoby::Ephem.load("inpop19a.bsp")
@@ -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`
@@ -109,11 +110,12 @@ event.setting_time.localtime(utc_offset)
 # => 2025-05-01 16:14:24 +0300
 ```
 
-[celestial bodies]: celestial_bodies.md
+[Solar System bodies]: solar_system_bodies.md
 [ephemerides]: ephem.md
 
 ## See also
+
 - [Twilight Times](twilight_times.md) - for sun-related events
-- [Celestial Bodies](celestial_bodies.md) - for object information
+- [Solar System Bodies](solar_system_bodies.md) - for object information
 - [Observer](observer.md) - for location setup
 - [Ephemerides](ephem.md) - for data sources

data/docs/{celestial_bodies.md → solar_system_bodies.md}

@@ -1,10 +1,11 @@
-# Celestial Bodies
+# Solar System Bodies
 
 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