astronoby 0.8.0 → 0.10.0

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,16 +154,74 @@ 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
-- [Celestial Bodies](celestial_bodies.md) - for object positions
+- [Solar System Bodies](solar_system_bodies.md) - for object positions

data/docs/deep_sky_bodies.md

@@ -0,0 +1,101 @@
+# Deep-sky Bodies
+
+Deep-sky objects represent celestial object that are not part of the Solar
+System, like stars, nebulae, clusters, galaxies. They are not affected by any
+body of the Solar System.
+
+Because we know billions of there objects, it is impossible for Astronoby to
+store a comprehensive catalogue. Therefore, it is up to the developer to build
+the object they need, based on equatorial coordinates from official catalogues
+at J2000 epoch. The [SIMBAD Astronomical Database] is an example of database
+where such coordinates can be found.
+
+Astronoby makes the difference between the body and the position.
+`Astronoby::DeepSkyObject` represent the body in itself, defined by fixed
+coordinates. It can also be support proper motion parameters, also given from
+official catalogues, which provides a bit more precision.
+
+```rb
+vega_j2000 = Astronoby::Coordinates::Equatorial.new(
+  right_ascension: Astronoby::Angle.from_hms(18, 36, 56.33635),
+  declination: Astronoby::Angle.from_dms(38, 47, 1.2802),
+  epoch: Astronoby::JulianDate::J2000
+)
+
+vega = Astronoby::DeepSkyObject.new(equatorial_coordinates: vega_j2000)
+
+vega_with_proper_motion = Astronoby::DeepSkyObject.new(
+  equatorial_coordinates: vega_j2000,
+  proper_motion_ra: Astronoby::AngularVelocity
+    .from_milliarcseconds_per_year(200.94),
+  proper_motion_dec: Astronoby::AngularVelocity
+    .from_milliarcseconds_per_year(286.23),
+  parallax: Astronoby::Angle.from_degree_arcseconds(130.23 / 1000.0),
+  radial_velocity: Astronoby::Velocity.from_kilometers_per_second(-13.5)
+)
+```
+
+From a `DeepSkyObject` instance, it is possible to instantiate the position
+of the body at a given instant. If given the optional `ephem` parameter,
+precision will increase as some astronomical corrections will be
+applied.
+
+A `DeepSkyPosition` object exposes `astrometric`, `apparent` and `topocentric`
+reference frames.
+
+```rb
+time = Time.utc(2025, 10, 1)
+instant = Astronoby::Instant.from_time(time)
+
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+vega
+  .at(instant)
+  .apparent
+  .equatorial
+  .right_ascension
+  .str(:hms)
+# => "18h 37m 48.2804s"
+
+vega_with_proper_motion
+  .at(instant, ephem: ephem)
+  .apparent
+  .equatorial
+  .right_ascension
+  .str(:hms)
+# => "18h 37m 48.706s"
+```
+
+You can learn more about [ephemerides] and [reference frames].
+
+A deep-sky body object can also be used in calculators.
+
+```rb
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(51.5072),
+  longitude: Astronoby::Angle.from_degrees(-0.1276)
+)
+date = Date.new(2025, 10, 1)
+
+body = Astronoby::DeepSkyObject.new(
+  equatorial_coordinates: Astronoby::Coordinates::Equatorial.new(
+    right_ascension: Astronoby::Angle.from_hms(6, 45, 8.917),
+    declination: Astronoby::Angle.from_dms(-16, 42, 58.02)
+  )
+)
+
+calculator = Astronoby::RiseTransitSetCalculator.new(
+  body: body,
+  observer: observer,
+  ephem: ephem
+)
+
+event = calculator.event_on(date)
+
+event.rising_time
+# => 2025-10-01 01:31:25 UTC
+```
+
+[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,7 +81,8 @@ the target `399`.
 [IMCCE]: https://www.imcce.fr
 
 ## See also
-- [Celestial Bodies](celestial_bodies.md) - for using ephemeris data
+
+- [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
 - [Configuration](configuration.md) - for performance tuning

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