astronoby 0.9.0 → 0.11.0

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,26 +108,47 @@ 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:02 UTC
 
 event.morning_nautical_twilight_time
-# => 2025-05-01 03:10:17 UTC
+# => 2025-05-01 03:09:39 UTC
 
 event.morning_civil_twilight_time
-# => 2025-05-01 03:55:17 UTC
+# => 2025-05-01 03:54:36 UTC
 
 event.evening_civil_twilight_time
-# => 2025-05-01 19:40:12 UTC
+# => 2025-05-01 19:41:58 UTC
 
 event.evening_nautical_twilight_time
-# => 2025-05-01 20:25:12 UTC
+# => 2025-05-01 20:27:15 UTC
 
 event.evening_astronomical_twilight_time
-# => 2025-05-01 21:18:01 UTC
+# => 2025-05-01 21:20:32 UTC
 ```
 
 You can learn more about this calculator on the [Twilight times page].
 
+## Find when a body reaches any altitude
+
+```rb
+calculator = Astronoby::AltitudeCrossingCalculator.new(
+  body: Astronoby::Sun,
+  observer: observer,
+  ephem: ephem
+)
+
+crossing = calculator.crossings_between(
+  Time.utc(2025, 5, 1),
+  Time.utc(2025, 5, 2),
+  altitude: Astronoby::Angle.from_degrees(30)
+).first
+
+crossing.direction
+# => :rising
+```
+
+You can learn more about this calculator on the [Altitude crossings page].
+
 ## Moon phases
 
 You can either get all the major Moon phases that will happen in a month, or get
@@ -141,7 +162,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 +171,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:46 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 +226,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 +281,17 @@ 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].
+You can learn more about deep-sky objects, and about converting many points to
+horizontal coordinates at once with `HorizontalTransformation`, 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
 
@@ -219,6 +304,10 @@ You can learn more about deep-sky objects on the [Deep-sky Bodies page].
 [Coordinates page]: coordinates.md
 [Rise, transit and setting times page]: rise_transit_set_times.md
 [Twilight times page]: twilight_times.md
+[Altitude crossings page]: altitude_crossings.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/altitude_crossings.md

@@ -0,0 +1,92 @@
+# Altitude crossings
+
+`Astronoby::AltitudeCrossingCalculator` finds when a body reaches any altitude above the observer's horizon, positive or negative, with instants that are not rounded. [Twilight times](twilight_times.md) are built on it.
+
+## Initialization
+
+It takes as key arguments:
+
+- `body`: the body to track, for example `Astronoby::Sun`
+- `observer` (`Astronoby::Observer`): location on Earth of the observer
+- `ephem`: ephemeris to provide the initial raw data
+- `refraction` (optional, `false` by default): whether atmospheric refraction is applied to the altitude, `false` being the twilight convention
+- `reference` (optional, `:center` by default): which point of the body reaches the altitude, `:center`, `:upper_limb` or `:lower_limb`. The limbs use the body's true semi-diameter and need a solar system body.
+
+```rb
+calculator = Astronoby::AltitudeCrossingCalculator.new(
+  body: Astronoby::Sun,
+  observer: observer,
+  ephem: ephem
+)
+```
+
+## `#crossings_between`
+
+It returns the `Astronoby::AltitudeCrossing` objects in a time range, sorted by time.
+
+```rb
+crossings = calculator.crossings_between(
+  Time.utc(2026, 10, 23),
+  Time.utc(2026, 10, 24),
+  altitude: Astronoby::Angle.from_degrees(-17.5)
+)
+
+crossing = crossings.first
+
+crossing.instant    # => Astronoby::Instant, unrounded
+crossing.direction  # => :rising or :setting
+crossing.grazing?   # => true when the body only just reaches the altitude
+```
+
+A crossing is `:rising` when the altitude increases through the target. It is `grazing?` when the target is within 0.05° of the body's highest or lowest altitude, where the instant is sensitive to small errors.
+
+## `#multiple_crossings_between`
+
+It does the same for several altitudes at once and returns one array of crossings per altitude, in the order given. The culminations and the computed positions are shared between the altitudes, which makes it much cheaper than one call per altitude.
+
+```rb
+civil, nautical = calculator.multiple_crossings_between(
+  start_time,
+  end_time,
+  altitudes: [Astronoby::Angle.from_degrees(-6), Astronoby::Angle.from_degrees(-12)]
+)
+```
+
+## `#crossing_on`
+
+It returns the first crossing of a given direction on a local day, or `nil`.
+
+```rb
+calculator.crossing_on(
+  Date.new(2026, 10, 23),
+  altitude: Astronoby::Angle.from_degrees(-17.5),
+  direction: :setting,
+  utc_offset: "+02:00"
+)
+```
+
+## `#extremes_between`
+
+It returns the upper and lower culminations in a time range, as `Astronoby::AltitudeExtreme` objects with `#kind`, `#instant` and `#altitude`. They are useful to explain why a crossing is absent: the body never got as high as, or as low as, the target.
+
+```rb
+calculator.extremes_between(start_time, end_time)
+```
+
+## Accuracy
+
+The altitude at the returned instant is within 10⁻⁵° of the target, and crossings agree with independent tools. The Sun's centre, without refraction, was compared on 2026-10-23 in Paris, 2026-03-20 in Makkah and 2026-12-21 at 60° N 10° E and 75° N 10° E, at -6°, -12° and -18° (22 crossings, observer at sea level):
+
+| Tool | Resolution | Largest difference with Astronoby |
+| --- | --- | --- |
+| [IMCCE OPALE](https://opale.imcce.fr) | 1 s | 0.6 s |
+| [JPL Horizons](https://ssd.jpl.nasa.gov/horizons/) | 1 min table, interpolated | 0.10 s |
+| [Skyfield](https://rhodesmills.github.io/skyfield/) on the same DE440s excerpt | 1 ms | 0.19 s |
+| [USNO](https://aa.usno.navy.mil/data/api) | 1 min, civil twilight only | within its rounding |
+
+The Skyfield differences are a time-scale effect rather than a geometric one: they are 0.00 s in March, 0.14 s in October and 0.18 s in December, which is the difference between Skyfield's built-in ΔT prediction and the IERS value Astronoby uses on those days. The remaining differences with Horizons and IMCCE come from the ephemerides (DE441 and INPOP19A against DE440s). The comparison also includes the polar night at 75° N, where the Sun does not rise but reaches -12° and -18°, and where the Sun never reaches -6°, as every tool agrees.
+
+## See also
+
+- [Twilight Times](twilight_times.md)
+- [Rise, Transit and Set Times](rise_transit_set_times.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,20 @@ 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
+- Greenwich mean and apparent sidereal times, which also cover the local
+  apparent sidereal time
+
+Sidereal times are cached for the exact UTC time, with no rounding. The cache
+helps when the same instant is used many times, for example when converting
+many points to horizontal coordinates for one observer. Calling
+`DeepSkyObject#at(instant).observed_by(observer).horizontal` repeatedly at one
+instant is about 2.5 times faster with the cache enabled.
 
 ## Cache precision
 
@@ -35,10 +44,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 +59,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 +102,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].
@@ -96,6 +96,51 @@ event.rising_time
 # => 2025-10-01 01:31:25 UTC
 ```
 
+## Many points at once
+
+Getting the horizontal coordinates of a single object goes through the whole
+chain of reference frames. Doing so for thousands of points at the same instant
+for the same observer, like the stars of a catalogue for a sky chart, repeats
+the same work for each of them: the rotation from the ICRS to the true equator
+and equinox of date, and the sidereal time only depend on the observer and the
+instant.
+
+`Astronoby::HorizontalTransformation` computes them once, and then converts
+any equatorial coordinates at J2000 epoch into horizontal coordinates. It is
+about 70 times faster per point than going through
+`DeepSkyObject#at(instant).observed_by(observer).horizontal`.
+
+```rb
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(51.5072),
+  longitude: Astronoby::Angle.from_degrees(-0.1276)
+)
+instant = Astronoby::Instant.from_time(Time.utc(2025, 10, 1, 3))
+
+sirius = Astronoby::Coordinates::Equatorial.new(
+  right_ascension: Astronoby::Angle.from_hms(6, 45, 8.917),
+  declination: Astronoby::Angle.from_dms(-16, 42, 58.02)
+)
+
+transformation = Astronoby::HorizontalTransformation.new(
+  observer: observer,
+  instant: instant
+)
+horizontal = transformation.apply(sirius)
+
+horizontal.altitude.str(:dms, precision: 0)
+# => "+10° 36′ 27″"
+horizontal.azimuth.str(:dms, precision: 0)
+# => "+134° 56′ 25″"
+```
+
+The result is the same as the one of a `DeepSkyObject` without an ephemeris,
+which means the points are treated as fixed directions: there is no aberration,
+no proper motion and no parallax. Atmospheric refraction is not applied by
+default, and can be requested with `transformation.apply(sirius, refraction:
+true)`. The coordinates must be at J2000 epoch, otherwise an
+`Astronoby::IncompatibleArgumentsError` is raised.
+
 [ephemerides]: ephem.md
 [reference frames]: reference_frames.md
 [SIMBAD Astronomical Database]: https://simbad.u-strasbg.fr/simbad/

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

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