astronoby 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: becadc2ba01e7620f12b20a5192e8537ed9f717336bb43471734fd5be9561675
-  data.tar.gz: 47c5743867f09c58f49093645da7534def3836135883f44929d4da15f73a441a
+  metadata.gz: 3e781560f80c12781becc942c58f026386dbc252bff0830ab154e1217dba319f
+  data.tar.gz: '0939683834940fe9bef423fe6e59b5a8ce5a1c53921015ee612c0f258c0fd224'
 SHA512:
-  metadata.gz: 2b04c971a79ac8201e21398dc0cc02b920cdadde538a0eb7d5d59dbc260661cbda51f3a72a434695b596634848f361a96b9533074f399d23d1e3d21fac89d772
-  data.tar.gz: f71973fd392c15a243a28ac09e521e813adf4900eefacfbc55712bd4f942c46b3351cfe44e183c1e809b0285b0ffb22ab320afd26b84c3d329be7fe79897378d
+  metadata.gz: 731fe3a326ddeca238f9479647e61e0554bbef2e10a35e468079240a58e8482a3e21b316fc61d5bcfb6962de353002e882c1e104f3e5c1626f6a02177a55a9a1
+  data.tar.gz: 035fb37802b80e6be88c216d0b117e3804bcd55c75871c4de4d6554e55fe8634f39e7dfe73e794bef4d00d35e59ccdbab65851bf34525a05f3ef290c4a5d2373

data/.ruby-version

@@ -1 +1 @@
-3.4.4
+4.0.5

data/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.10.0 - 2026-06-26
+
+_If you are upgrading: please see [UPGRADING.md]._
+
+### Bug fixes
+
+* Fix constant name typo ([#245])
+* Fix matrix multiplication order in Apparent frame ([#250])
+* Remove spurious N·P from observer ECEF-to-TOD transformation ([#251])
+* Apply aberration in GCRS before precession/nutation rotation ([#253])
+* Fix Moon magnitude ([#254])
+* Fix astrometric position for Deep Sky Objects ([#272])
+
+### Features
+
+* Defer Solar System body computations lazily ([#244])
+* Integrate `iers` gem for Delta T and GMST ([#249])
+* Add IERS polar motion correction to observer ECEF-to-TOD transformation ([#252])
+* Fall back to polynomial GMST for dates outside IERS EOP range ([#255])
+* Add ICRS frame bias to precession matrix ([#257])
+* Extract `EarthRotation` class from `Observer` ([#260])
+* Add TEME reference frame for satellite tracking ([#261])
+* Add ECEF to geodetic conversion (WGS-84) ([#262])
+* Memoize per-instant conversions on `Instant` ([#268])
+* Add `ReferenceFrame#separation_from` for angular separation ([#269])
+* Introduce `Center`, `Body` and `Position` domain objects ([#270])
+* Add planetary phenomena ([#271])
+* Add lunar libration, position angle of axis and bright limb ([#273])
+* Add `Astronoby::Orientation` for arcsecond lunar libration ([#279])
+* Add Lunar eclipses ([#280])
+* Add `Astronoby::Duration` ([#281])
+
+### Improvements
+
+* Optimize nutation loop by eliminating array allocations ([#246])
+* Reuse single Nutation instance in observer matrix computation ([#247])
+* Memoize Observer geodetic computation methods ([#248])
+* Update documentation with recent values ([#256])
+* Update referential frames documentation ([#258])
+* YARD documentation update ([#259])
+* Update zlib, JSON and ERB for security reasons
+* Add references to README
+* Bump actions/checkout from 5 to 7 by @dependabot ([#239], [#276])
+* Bump rubyzip from 3.2.1 to 3.4.0 by @dependabot ([#237], [#267], [#275])
+* Bump irb from 1.15.2 to 1.17.0 by @dependabot ([#242])
+* Bump standard from 1.51.1 to 1.55.0 by @dependabot ([#243], [#274])
+* Bump rake from 13.3.1 to 13.4.2 by @dependabot ([#264])
+* Bump ephem from 0.4.1 to 0.5.0 by @dependabot ([#278])
+* Upgrade default Ruby to 4.0.5 ([#277])
+
+### Backward-incompatible changes
+
+* Minimum Ruby version bumped to 3.2.0 ([#249])
+* Delta T and GMST now use IERS data ([#249])
+* Defer Solar System body computations lazily ([#244])
+* `SolarSystemBody#ephem` is now publicly accessible ([#244])
+* `ReferenceFrame#center_identifier` replaced by `#center` ([#270])
+* `Sun#equation_of_time` now returns a `Duration` ([#281])
+
+**Full Changelog**: https://github.com/rhannequin/astronoby/compare/v0.9.0...v0.10.0
+
+[#237]: https://github.com/rhannequin/astronoby/pull/237
+[#239]: https://github.com/rhannequin/astronoby/pull/239
+[#242]: https://github.com/rhannequin/astronoby/pull/242
+[#243]: https://github.com/rhannequin/astronoby/pull/243
+[#244]: https://github.com/rhannequin/astronoby/pull/244
+[#245]: https://github.com/rhannequin/astronoby/pull/245
+[#246]: https://github.com/rhannequin/astronoby/pull/246
+[#247]: https://github.com/rhannequin/astronoby/pull/247
+[#248]: https://github.com/rhannequin/astronoby/pull/248
+[#249]: https://github.com/rhannequin/astronoby/pull/249
+[#250]: https://github.com/rhannequin/astronoby/pull/250
+[#251]: https://github.com/rhannequin/astronoby/pull/251
+[#252]: https://github.com/rhannequin/astronoby/pull/252
+[#253]: https://github.com/rhannequin/astronoby/pull/253
+[#254]: https://github.com/rhannequin/astronoby/pull/254
+[#255]: https://github.com/rhannequin/astronoby/pull/255
+[#256]: https://github.com/rhannequin/astronoby/pull/256
+[#257]: https://github.com/rhannequin/astronoby/pull/257
+[#258]: https://github.com/rhannequin/astronoby/pull/258
+[#259]: https://github.com/rhannequin/astronoby/pull/259
+[#260]: https://github.com/rhannequin/astronoby/pull/260
+[#261]: https://github.com/rhannequin/astronoby/pull/261
+[#262]: https://github.com/rhannequin/astronoby/pull/262
+[#264]: https://github.com/rhannequin/astronoby/pull/264
+[#267]: https://github.com/rhannequin/astronoby/pull/267
+[#268]: https://github.com/rhannequin/astronoby/pull/268
+[#269]: https://github.com/rhannequin/astronoby/pull/269
+[#270]: https://github.com/rhannequin/astronoby/pull/270
+[#271]: https://github.com/rhannequin/astronoby/pull/271
+[#272]: https://github.com/rhannequin/astronoby/pull/272
+[#273]: https://github.com/rhannequin/astronoby/pull/273
+[#274]: https://github.com/rhannequin/astronoby/pull/274
+[#275]: https://github.com/rhannequin/astronoby/pull/275
+[#276]: https://github.com/rhannequin/astronoby/pull/276
+[#277]: https://github.com/rhannequin/astronoby/pull/277
+[#278]: https://github.com/rhannequin/astronoby/pull/278
+[#279]: https://github.com/rhannequin/astronoby/pull/279
+[#280]: https://github.com/rhannequin/astronoby/pull/280
+[#281]: https://github.com/rhannequin/astronoby/pull/281
+
 ## 0.9.0 - 2025-10-31
 
 _If you are upgrading: please see [UPGRADING.md]._

data/README.md

@@ -11,7 +11,9 @@ Some algorithms are based on the following astrometry books:
   Duffet-Smith and Jonathan Zwart
 
 Solar System bodies' positions are computed based on ephemerides from the
-[IMCCE] or [NASA/JPL].
+[IMCCE] or [NASA/JPL]. The library also supports Earth-orbiting satellite
+tracking through the [TEME] reference frame, suitable for use with SGP4/SDP4
+orbit propagators.
 
 ## Content
 - [Installation](#installation)
@@ -45,6 +47,8 @@ previous versions, you can access the documentation in the README for each
   and objects
 - [Reference Frames](docs/reference_frames.md) - for coordinate systems
 - [Observer Setup](docs/observer.md) - for location configuration
+- [IERS Data](docs/iers.md) - for Delta T and Greenwich Mean Sidereal Time
+  (GMST) data management
 - [Glossary](docs/glossary.md) - for astronomical and technical terms
 
 ### Expected breaking changes notice
@@ -122,6 +126,7 @@ Everyone interacting in the Astronoby project's codebases, issue trackers, chat
 rooms and mailing lists is expected to follow the [code of conduct].
 
 [NASA/JPL]: https://ssd.jpl.nasa.gov/planets/eph_export.html
+[TEME]: https://github.com/rhannequin/astronoby/blob/main/docs/reference_frames.md#teme
 [Bundler]: https://bundler.io
 [`docs/`]: https://github.com/rhannequin/astronoby/blob/main/docs
 [release]: https://github.com/rhannequin/astronoby/releases

data/UPGRADING.md

@@ -7,6 +7,90 @@ changes to it as long as a major version has not been released.
 If you are already using Astronoby and wish to follow the changes to its
 public API, please read the upgrading notes for each release.
 
+## Upgrading from 0.9.0 to 0.10.0
+
+### Minimum Ruby version bumped to 3.2.0
+
+The minimum required Ruby version is now 3.2.0 (previously 3.0.0), due to the
+new `iers` gem dependency.
+
+### Delta T and GMST now use IERS data
+
+Delta T (TT - UT1) is now computed from IERS data via the
+[`iers`](https://github.com/rhannequin/iers) gem instead of hardcoded lookup
+tables. Greenwich Mean Sidereal Time (GMST) is now computed using the IERS
+Conventions 2010 ERA-based expression instead of the Duffett-Smith polynomial.
+
+Both changes improve accuracy significantly (Delta T error reduced from ~0.5s
+to ~0.001s, GMST error reduced by 600-2200x vs Skyfield). As a result,
+computed values for sidereal times, horizontal coordinates, and
+rise/transit/set times may differ slightly from previous versions.
+
+The `iers` gem ships with bundled data files that work out of the box. See
+[IERS Data](docs/iers.md) for details on data coverage and updates.
+
+### `SolarSystemBody` initialization is now lazy
+
+`SolarSystemBody#initialize` no longer eagerly computes geometric positions,
+light-time corrections, or Sun data. All computations are now deferred until
+the corresponding method is first called. This means ephemeris-related errors
+will surface on first property access rather than during instantiation.
+
+### `SolarSystemBody#geometric` is now a lazy method
+
+`geometric` was previously exposed via `attr_reader` and eagerly computed in
+`initialize`. It is now a lazy memoized method. The public interface is
+unchanged — `body.geometric` still returns a `Geometric` object.
+
+### `SolarSystemBody#ephem` is now publicly accessible
+
+The `ephem` object passed to `initialize` is now exposed via `attr_reader`.
+
+### `ReferenceFrame#center_identifier` replaced by `#center`
+
+Every reference frame previously exposed `#center_identifier`, an `Integer`
+(e.g. `Astronoby::SolarSystemBody::EARTH`) for barycentric/geocentric frames or
+a `[longitude, latitude]` array for topocentric frames. It is replaced by
+`#center`, which returns an `Astronoby::Center` value object.
+
+```rb
+# Before
+frame.center_identifier # => 399 or [longitude, latitude]
+
+# After
+frame.center                 # => #<Astronoby::Center ...>
+frame.center.geocentric?     # => true
+frame.center == Astronoby::Center.geocentric # => true
+frame.center.observer        # => the Observer, for topocentric frames
+```
+
+Two topocentric centers are equal when their observers share the same
+latitude, longitude and elevation (atmospheric parameters are ignored).
+
+### `Sun#equation_of_time` now returns a `Duration`
+
+Lengths of time are now wrapped in a new `Astronoby::Duration` value object,
+consistent with `Angle`, `Distance` and `Velocity`. As a result,
+`Sun#equation_of_time` returns an `Astronoby::Duration` instead of an
+`Integer` of seconds. Call `#seconds` to get the previous value.
+
+```rb
+# Before
+sun.equation_of_time # => -185
+
+# After
+sun.equation_of_time         # => #<Astronoby::Duration ...>
+sun.equation_of_time.seconds # => -185
+sun.equation_of_time.minutes # => -3.08...
+```
+
+A `Duration` can be built with `from_seconds`, `from_minutes`, `from_hours`
+and `from_days`, and read back in any of those units. It is immutable,
+comparable, and supports `+` and `-`.
+
+Note that `EclipsePhase#duration`, also introduced in this release, returns
+an `Astronoby::Duration` as well.
+
 ## Upgrading from 0.8.0 to 0.9.0
 
 ### Constant `MINUTES_PER_DEGREE` renamed

data/docs/README.md

@@ -62,10 +62,10 @@ You can learn more about reference frames and positions on the
 
 ```rb
 topocentric.horizontal.azimuth.str(:dms)
-# => "+175° 34′ 28.2724″"
+# => "+175° 34′ 33.2353″"
 
 topocentric.horizontal.altitude.str(:dms)
-# => "+64° 22′ 58.1084″"
+# => "+64° 22′ 58.229″"
 ```
 
 You can learn more about coordinates on the [Coordinates page].
@@ -108,22 +108,22 @@ calculator = Astronoby::TwilightCalculator.new(
 event = calculator.event_on(Date.new(2025, 5, 1))
 
 event.morning_astronomical_twilight_time
-# => 2025-05-01 02:17:28 UTC
+# => 2025-05-01 02:17:07 UTC
 
 event.morning_nautical_twilight_time
-# => 2025-05-01 03:10:17 UTC
+# => 2025-05-01 03:09:44 UTC
 
 event.morning_civil_twilight_time
-# => 2025-05-01 03:55:17 UTC
+# => 2025-05-01 03:54:38 UTC
 
 event.evening_civil_twilight_time
-# => 2025-05-01 19:40:12 UTC
+# => 2025-05-01 19:41:51 UTC
 
 event.evening_nautical_twilight_time
-# => 2025-05-01 20:25:12 UTC
+# => 2025-05-01 20:26:56 UTC
 
 event.evening_astronomical_twilight_time
-# => 2025-05-01 21:18:01 UTC
+# => 2025-05-01 21:19:57 UTC
 ```
 
 You can learn more about this calculator on the [Twilight times page].
@@ -141,7 +141,7 @@ may_2024_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
 ```
 
 ```rb
@@ -150,14 +150,53 @@ instant = Astronoby::Instant.from_time(time)
 moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
 
 moon.illuminated_fraction.round(2)
-# => 0.15
+# => 0.95
 
 moon.current_phase_fraction.round(2)
-# => 0.11
+# => 0.59
 ```
 
 You can learn more about phases on the [Moon phases page].
 
+## Lunar observation
+
+```rb
+time = Time.utc(2025, 3, 1)
+instant = Astronoby::Instant.from_time(time)
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+
+moon.libration.longitude.str(:dms)
+# => "-2° 5′ 4.4219″"
+
+moon.libration.latitude.str(:dms)
+# => "+0° 28′ 45.9616″"
+
+moon.position_angle_of_axis.str(:dms)
+# => "-21° 48′ 46.657″"
+
+moon.bright_limb_position_angle.str(:dms)
+# => "+248° 1′ 57.9467″"
+```
+
+You can learn more about libration, axis and limb angles on the
+[Lunar observation page].
+
+## Lunar eclipses
+
+```rb
+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]]
+```
+
+You can learn more about umbral and penumbral magnitudes, phases and contact
+times on the [Lunar eclipses page].
+
 ## Equinox and solstice times
 
 ```rb
@@ -166,18 +205,39 @@ 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
 ```
 
 You can learn more about equinoxes and solstices on the
 [Equinoxes and solstices times page].
 
+## Planetary phenomena
+
+```rb
+Astronoby::Mars.opposition_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first.instant.to_time
+# => 2025-01-16 02:38:35 UTC
+
+Astronoby::Venus.greatest_elongation_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first.angle.degrees.round(1)
+# => 47.2
+```
+
+You can learn more about conjunctions, oppositions and greatest elongations on
+the [Planetary phenomena page].
+
 ## Deep-sky objects
 
 It is possible to manipulate any deep-sky possible, given equatorial coordinates
@@ -200,13 +260,15 @@ vega = Astronoby::DeepSkyObject.new(equatorial_coordinates: vega_j2000)
 vega_position = vega.at(instant)
 
 vega_position.apparent.equatorial.right_ascension.str(:hms)
-# => "18h 36m 56.3363s"
+# => "18h 37m 48.2804s"
 ```
 
 You can learn more about deep-sky objects on the [Deep-sky Bodies page].
 
 ## See also
+
 - [Glossary](glossary.md) - for astronomical and technical terms
+- [IERS Data](iers.md) - for Delta T and GMST data management
 - [Configuration](configuration.md) - for performance tuning
 - [Performance Benchmarks](../benchmarks/README.md) - for testing improvements
 
@@ -220,5 +282,8 @@ You can learn more about deep-sky objects on the [Deep-sky Bodies page].
 [Rise, transit and setting times page]: rise_transit_set_times.md
 [Twilight times page]: twilight_times.md
 [Moon phases page]: moon_phases.md
+[Lunar observation page]: lunar_observation.md
+[Lunar eclipses page]: lunar_eclipses.md
 [Equinoxes and solstices times page]: equinoxes_solstices_times.md
+[Planetary phenomena page]: planetary_phenomena.md
 [Deep-sky Bodies page]: deep_sky_bodies.md

data/docs/angles.md

@@ -131,6 +131,7 @@ angle1.negative? # => false
 ```
 
 ## See also
+
 - [Coordinates](coordinates.md) - for using angles in coordinate systems
 - [Observer](observer.md) - for latitude and longitude
 - [Reference Frames](reference_frames.md) - for position calculations

data/docs/configuration.md

@@ -20,11 +20,12 @@ Astronoby.configuration.cache_enabled = true
 
 Once caching is enabled, it will be used for the following parts of the library
 with default precision values:
-* [Geometric positions]
-* [Topocentric positions] when computing rising/transit/setting times
-* [Moon phases]
-* Nutation
-* Precession
+
+- [Geometric positions]
+- [Topocentric positions] when computing rising/transit/setting times
+- [Moon phases]
+- Nutation
+- Precession
 
 ## Cache precision
 
@@ -35,10 +36,11 @@ However, users may want to improve performance even more at the cost of some
 precision.
 
 It is possible to change the precision value for the following:
-* Geometric position, default: `9`
-* Topocentric position, default: `5`
-* Nutation, default: `2`
-* Precession, default: `2`
+
+- Geometric position, default: `9`
+- Topocentric position, default: `5`
+- Nutation, default: `2`
+- Precession, default: `2`
 
 ### Precision value
 
@@ -49,14 +51,14 @@ Let's take the example of `1`. Rounding a Julian Day with only one digit means
 that all times within 8640 seconds will be rounded to the same instant, which
 means a maximum rounding of 2.4 hours.
 
-* `1`: 2.4 hours
-* `2`: 14.4 minutes
-* `3`: 86.4 seconds
-* `4`: 8.6 seconds
-* `5`: 0.86 seconds
-* `6`: 0.086 seconds
-* `7`: 0.0086 seconds
-* ...
+- `1`: 2.4 hours
+- `2`: 14.4 minutes
+- `3`: 86.4 seconds
+- `4`: 8.6 seconds
+- `5`: 0.86 seconds
+- `6`: 0.086 seconds
+- `7`: 0.0086 seconds
+- ...
 
 ### Setting custom precision
 
@@ -92,6 +94,7 @@ Astronoby.cache.max_size
 [Julian Day]: https://en.wikipedia.org/wiki/Julian_day
 
 ## See also
+
 - [Reference Frames](reference_frames.md) - for understanding position calculations
 - [Ephemerides](ephem.md) - for data sources
 - [Performance Benchmarks](benchmarks/README.md) - for testing improvements

data/docs/coordinates.md

@@ -1,13 +1,15 @@
 # Coordinates
 
-Astronoby provides three different types of coordinates:
+Astronoby provides four types of coordinates:
 
-* Equatorial
-* Ecliptic
-* Horizontal
+- Equatorial
+- Ecliptic
+- Horizontal
+- Geodetic
 
 Equatorial and ecliptic coordinates are available for each [reference frame],
-while horizontal coordinates are only available for a topocentric position.
+horizontal coordinates are only available for a topocentric position, and
+geodetic coordinates are used for Earth-surface positions (ECEF ↔ WGS-84).
 
 ## Equatorial
 
@@ -36,7 +38,7 @@ saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
 equatorial = saturn.apparent.equatorial
 
 equatorial.right_ascension.str(:hms)
-# => "20h 45m 2.6702s"
+# => "20h 45m 2.6681s"
 ```
 
 You can learn more about angles on the [Angle page].
@@ -49,7 +51,7 @@ is at -90°.
 
 ```rb
 equatorial.declination.str(:dms)
-# => "-18° 46′ 16.1226″"
+# => "-18° 46′ 16.0931″"
 ```
 
 ### Hour angle
@@ -63,7 +65,7 @@ time. By convention, the hour angle is usually displayed in hours.
 longitude = Astronoby::Angle.from_degrees(2)
 
 equatorial.compute_hour_angle(longitude: longitude, time: time).str(:hms)
-# => "23h 27m 54.9585s"
+# => "23h 27m 54.1924s"
 ```
 
 ## Ecliptic
@@ -101,7 +103,7 @@ saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
 ecliptic = saturn.apparent.ecliptic
 
 ecliptic.latitude.str(:dms)
-# => "-0° 41′ 27.5439″"
+# => "-0° 41′ 27.5077″"
 ```
 
 ### Longitude
@@ -111,7 +113,7 @@ ecliptic towards the north (positive) or south (negative) ecliptic pole.
 
 ```rb
 ecliptic.longitude.str(:dms)
-# => "+308° 38′ 33.1744″"
+# => "+308° 38′ 33.1535″"
 ```
 
 ## Horizontal
@@ -142,7 +144,7 @@ saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
 horizontal = saturn.observed_by(observer).horizontal
 
 horizontal.altitude.str(:dms)
-# => "+28° 46′ 39.5994″"
+# => "+28° 46′ 38.3398″"
 ```
 
 ### Azimuth
@@ -152,15 +154,73 @@ eastward.
 
 ```rb
 horizontal.azimuth.str(:dms)
-# => "+171° 19′ 50.5798″"
+# => "+171° 19′ 38.2567″"
 ```
 
+## Geodetic
+
+Geodetic coordinates describe a position on or above the Earth's surface using
+the [WGS-84] reference ellipsoid, the same system used by GPS. They have three
+attributes:
+
+### Latitude
+
+The angle from the equator to the point on the ellipsoid surface, from +90°
+(North Pole) to -90° (South Pole).
+
+### Longitude
+
+The angle from the Greenwich meridian, from +180° to -180°, with positive
+angles eastward.
+
+### Elevation
+
+The distance above (or below) the WGS-84 ellipsoid surface.
+
+### From ECEF
+
+Geodetic coordinates can be derived from Earth-Centered Earth-Fixed (ECEF)
+Cartesian coordinates using `Astronoby::Coordinates::Geodetic.from_ecef`. This
+is particularly useful for satellite tracking, where a propagator produces ECEF
+positions via `Astronoby::Teme#to_ecef`:
+
+```rb
+teme = Astronoby::Teme.new(
+  position: Astronoby::Distance.vector_from_meters(
+    [5_094_180.16, 6_127_644.66, 6_380_344.53]
+  ),
+  velocity: Astronoby::Velocity.vector_from_mps(
+    [-4746.13, 785.82, 5531.93]
+  ),
+  instant: instant
+)
+
+geodetic = teme.to_ecef.geodetic
+
+geodetic.latitude.str(:dms)
+# => "+38° 48′ 3.3038″"
+
+geodetic.longitude.str(:dms)
+# => "+97° 27′ 6.7374″"
+
+geodetic.elevation.km.round
+# => 3838
+```
+
+The conversion uses Bowring's iterative method, which converges in 2-3
+iterations for typical satellite altitudes.
+
+The forward direction (geodetic → ECEF) is handled by
+[`Astronoby::Observer#geocentric_position`][Observer page].
+
+[WGS-84]: https://en.wikipedia.org/wiki/World_Geodetic_System
 [reference frame]: reference_frames.md
 [Wikipedia]: https://en.wikipedia.org/wiki/Equatorial_coordinate_system
 [Angle page]: angles.md
 [topocentric position]: reference_frames.md#topocentric
 
 ## See also
+
 - [Reference Frames](reference_frames.md) - for coordinate system details
 - [Angles](angles.md) - for working with angular measurements
 - [Observer](observer.md) - for location setup

data/docs/deep_sky_bodies.md

@@ -63,7 +63,7 @@ vega_with_proper_motion
   .equatorial
   .right_ascension
   .str(:hms)
-# => "18h 37m 48.7215s"
+# => "18h 37m 48.706s"
 ```
 
 You can learn more about [ephemerides] and [reference frames].

data/docs/ephem.md

@@ -17,8 +17,9 @@ providing the filename.
 ### Manually
 
 Ephemerides are available for download from:
-* the JPL public FTP interface: https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/
-* the INPOP releases page of the IMCCE: https://www.imcce.fr/inpop
+
+- the JPL public FTP interface: https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/
+- the INPOP releases page of the IMCCE: https://www.imcce.fr/inpop
 
 You can download any `.bsp` file. For the moment, Astronoby only supports the
 planets of the Solar System, and the Sun and the Moon, so you need to
@@ -48,6 +49,7 @@ ephem = Astronoby::Ephem.load("tmp/de421.bsp")
 
 JPL produces many different kernels over the years, with different accuracy and
 ranges of supported years. Here are some that we recommend to begin with:
+
 - `de421.bsp`: from 1900 to 2050, 17 MB
 - `de440s.bsp`: from 1849 to 2150, 32 MB
 - `inpop19a.bsp`: from 1900 to 2100, 22 MB
@@ -79,6 +81,7 @@ the target `399`.
 [IMCCE]: https://www.imcce.fr
 
 ## See also
+
 - [Solar System Bodies](solar_system_bodies.md) - for using ephemeris data
 - [Reference Frames](reference_frames.md) - for coordinate calculations
 - [Observer](observer.md) - for location-based calculations