astronoby 0.9.0 → 0.11.0

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,21 @@ 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
+- **International Atomic Time (TAI)**: The atomic time scale TT is defined against, 32.184 seconds behind it
+- **Barycentric Dynamical Time (TDB)**: Time at the Solar System barycentre, within about 1.7 milliseconds of TT
 - **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

data/docs/instant.md

@@ -14,7 +14,9 @@ from the irregularities in the rotation of Earth and the irregularly fluctuating
 mean solar time.
 
 Astronoby handles this situation by implementing an `Astronoby::Instant` class,
-used in most calculations instead of `Time`.
+used in most calculations instead of `Time`. Converting between UTC and
+Terrestrial Time requires knowing [Delta T (TT - UT1)][Delta T], which
+Astronoby obtains from [IERS data](iers.md).
 
 `Astronoby::Instant` is a value object that stores an instant in time on Earth
 in [Terrestrial Time], an astronomical time standard defined by the
@@ -23,14 +25,18 @@ International Astronomical Union, as a [Julian Date].
 From this instant in <abbr title="Terrestrial Time">TT</abbr>, other time
 standards can be expressed, such as the
 <abbr title="International Atomic Time">TAI</abbr> or the
-<abbr title="Barycentric Dynamic Time">TDB</abbr>.
+<abbr title="Barycentric Dynamical Time">TDB</abbr>. Those two are computed by
+the [horologium] gem, which owns the time scales that convert by definition or
+by model. UT1 is not one of them: it follows the actual rotation of the Earth,
+so it stays in Astronoby, backed by [IERS data](iers.md).
 
 ## Initialization
 
 An `Astronoby::Instant` object can be instantiated from:
-* Terrestrial time (`Numeric`): `.from_terrestrial_time`
-* Ruby `Time` object: `.from_time`
-* UTC Julian date (`Numeric`): `.from_utc_julian_date`
+
+- Terrestrial time (`Numeric`): `.from_terrestrial_time`
+- Ruby `Time` object: `.from_time`
+- UTC Julian date (`Numeric`): `.from_utc_julian_date`
 
 ```rb
 Astronoby::Instant.from_terrestrial_time(2460796)
@@ -48,7 +54,7 @@ Astronoby::Instant.from_utc_julian_date(2460796)
 
 From the same instant, it is possible to extract different time standards.
 
-* Gregorian `Date`
+- Gregorian `Date`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
@@ -57,62 +63,65 @@ instant.to_date
 # => #<Date: 2025-04-30 ((2460796j,0s,0n),+0s,2299161j)>
 ```
 
-* UTC `DateTime`
+- UTC `DateTime`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.to_datetime
-# => #<DateTime: 2025-04-30T11:58:51+00:00 ((2460796j,43131s,12159n),+0s,2299161j)>
+# => #<DateTime: 2025-04-30T11:58:50+00:00 ((2460796j,43130s,845637619n),+0s,2299161j)>
 ```
 
-* UTC `Time`
+- UTC `Time`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.to_datetime
-# => 2025-04-30 11:58:51.000012159 UTC
+# => 2025-04-30T11:58:50+00:00 UTC
 ```
 
-* Greenwich Sidereal Time
+- Greenwich Sidereal Time
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.gmst
-# => 2.5597425440141457
+# => 2.5597070126923764
 ```
 
-* International Atomic Time
+- International Atomic Time
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.tai.to_f
-# => 2460795.9996275003
+# => 2460795.9996275
 ```
 
-* UTC offset (difference with UTC in days)
+- UTC offset (difference with UTC in days)
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.utc_offset.to_f
-# => 0.0007986109703819444
+# => 0.0008003974106626159
 ```
 
-* Barycentric Dynamic Time
+- Barycentric Dynamical Time
 
 ```rb
-# This is not handled for now, and returns TT
-
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
-instant.tdb
-# => 2460796
+instant.tdb.to_f
+# => 2460796.000000017
 ```
 
+`tai` and `tdb` are read as a `Rational`. A Julian Date is around 2.46
+million, so a single `Float` rounds to about 47 microseconds of the day, which
+is more than the whole TDB - TT correction. Call `to_f` when a `Float` is what
+you want.
+
 ## Value Equality
 
 As a value object, it is possible to compare different instants.
@@ -128,11 +137,14 @@ instant1 < instant2
 # => true
 ```
 
+[horologium]: https://github.com/rhannequin/horologium
 [Gregorian calendar]: https://en.wikipedia.org/wiki/Gregorian_calendar
 [Terrestrial Time]: https://en.wikipedia.org/wiki/Terrestrial_Time
 [Julian Date]: https://en.wikipedia.org/wiki/Julian_day
+[Delta T]: https://en.wikipedia.org/wiki/ΔT_(timekeeping)
 
 ## See also
+
 - [Ephemerides](ephem.md) - for time-based calculations
 - [Solar System Bodies](solar_system_bodies.md) - for object positions
 - [Reference Frames](reference_frames.md) - for coordinate systems

data/docs/lunar_eclipses.md

@@ -0,0 +1,208 @@
+# Lunar Eclipses
+
+Astronoby computes lunar eclipses: the passages of the Moon through Earth's shadow. A lunar eclipse is a geocentric event, the same for every observer who can see the Moon, so finding one takes no observer. What one place sees of it depends only on whether the Moon is above its horizon, which is covered in [Local circumstances](#local-circumstances) below. The geometry is built from the apparent geocentric positions of the Sun and Moon, which matches the standard reduction used by [NASA's Five Millennium Canon of Lunar Eclipses] and by IMCCE.
+
+There are three kinds of lunar eclipses. A penumbral eclipse is when the Moon only enters Earth's penumbra, the outer, partial shadow. A partial eclipse is when part of the Moon enters the umbra, the inner, total shadow. A total eclipse is when the whole Moon enters the umbra.
+
+## Finding eclipses
+
+`Astronoby::Moon.eclipse_events` takes an ephemeris and a time range, and returns the lunar eclipses whose greatest instant falls in that range, sorted by time.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+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]]
+```
+
+## An eclipse
+
+Each eclipse is an `Astronoby::LunarEclipse`. Its `#instant` (also available as `#greatest_eclipse_instant`) is the moment of greatest eclipse, when the Moon's centre is least distant from the axis of Earth's shadow.
+
+```rb
+eclipse = eclipses.first
+
+eclipse.kind                 # => :total
+eclipse.total?               # => true
+eclipse.instant.to_time      # => 2025-03-14 06:58:46 UTC
+eclipse.greatest_eclipse_instant # => same as #instant
+```
+
+The umbral and penumbral magnitudes are the fractions of the Moon's diameter immersed in the umbra and the penumbra at greatest eclipse. The umbral magnitude is negative for a penumbral eclipse (the Moon misses the umbra), between 0 and 1 for a partial eclipse, and 1 or more for a total eclipse.
+
+```rb
+eclipse.umbral_magnitude     # => 1.179
+eclipse.penumbral_magnitude  # => 2.26
+```
+
+`#gamma` is the least distance of the Moon's centre from the axis of Earth's shadow at greatest eclipse, in Earth radii, positive when the Moon passes north of the axis and negative when it passes south. It is the standard, dimensionless eclipse parameter used by IMCCE and NASA. The same quantity is also available as an `Astronoby::Distance` through `#shadow_axis_distance`, and the side of the axis it takes its sign from is on the geometry as `#north_of_axis?`.
+
+```rb
+eclipse.gamma                       # => 0.348
+eclipse.shadow_axis_distance.km     # => 2222.37
+```
+
+## Phases
+
+An eclipse exposes its phases as `Astronoby::LunarEclipsePhase` objects, each with a `#starting_instant`, an `#ending_instant`, and a `#duration` (an `Astronoby::Duration`). The penumbral phase is always present. The partial phase is present for partial and total eclipses, and the total phase (totality) only for total eclipses. A phase that does not occur is `nil`.
+
+```rb
+eclipse.penumbral.starting_instant.to_time # => 2025-03-14 03:57:28 UTC (P1)
+eclipse.partial.starting_instant.to_time   # => 2025-03-14 05:09:36 UTC (U1)
+eclipse.total.starting_instant.to_time     # => 2025-03-14 06:26:02 UTC (U2)
+eclipse.total.ending_instant.to_time       # => 2025-03-14 07:31:29 UTC (U3)
+eclipse.partial.ending_instant.to_time     # => 2025-03-14 08:47:55 UTC (U4)
+eclipse.penumbral.ending_instant.to_time   # => 2025-03-14 10:00:08 UTC (P4)
+
+eclipse.total.duration.seconds # => 3927.11 (seconds of totality)
+```
+
+For a penumbral eclipse, `#partial` and `#total` are `nil`. For a partial eclipse, `#total` is `nil`.
+
+## Shadow geometry
+
+`Astronoby::LunarEclipseGeometry` describes Earth's shadow and the Moon's place in it at one instant. The eclipse carries the geometry at greatest eclipse, and each phase carries the geometry at its two contacts, so all six contacts of a total eclipse are reachable as well as greatest eclipse. It gives the size of the two shadow cones, how far the Moon's centre is from the shadow axis, and where on the Moon's limb the shadow bites.
+
+```rb
+geometry = eclipse.geometry
+
+geometry.umbra_angular_radius.degrees * 60     # => 39.23 (arcminutes)
+geometry.penumbra_angular_radius.degrees * 60  # => 71.39
+geometry.angular_axis_distance.degrees * 60    # => 19.03
+geometry.position_angle.degrees                # => 29.07
+```
+
+The cone radii are measured in the plane perpendicular to the shadow axis at the Moon's distance, which is where they are published. They are available as an `Astronoby::Distance` through `#umbra_radius` and `#penumbra_radius`, and as an `Astronoby::Angle` through `#umbra_angular_radius` and `#penumbra_angular_radius`. `#moon_distance` is the geocentric distance of the Moon, the distance of that plane.
+
+`#position_angle` is the position angle of the contact point on the Moon's limb, seen from the Moon's centre, from celestial north through east. This is the quantity IMCCE and NASA publish. At greatest eclipse, where there is no contact point, it is the direction from the shadow axis to the Moon, which is what they report there too.
+
+`#umbral_magnitude` and `#penumbral_magnitude` are available at any of these instants, not only at greatest eclipse. Each one is 0 at the contacts that define it, so the penumbral magnitude at P1 and P4 and the umbral magnitude at U1 and U4. The umbral magnitude is 1 at U2 and U3, where the Moon is wholly inside the umbra. The penumbral magnitude is well past 1 by then, since the Moon is far deeper into the penumbra than into the umbra.
+
+```rb
+eclipse.penumbral.starting_geometry.penumbral_magnitude # => 0.0 (P1)
+eclipse.partial.starting_geometry.umbral_magnitude      # => 0.0 (U1)
+eclipse.total.starting_geometry.umbral_magnitude        # => 1.0 (U2)
+```
+
+```rb
+eclipse.penumbral.starting_geometry.position_angle.degrees # => 131.8 (P1)
+eclipse.total.starting_geometry.position_angle.degrees     # => 350.46 (U2)
+```
+
+Note that IMCCE labels the end of the penumbral phase `P2`, where this documentation uses `P4`.
+
+```rb
+penumbral_eclipse = Astronoby::Moon.eclipse_events(
+  ephem: ephem,
+  start_time: Time.utc(2024, 3, 1),
+  end_time: Time.utc(2024, 4, 1)
+).first
+
+penumbral_eclipse.kind    # => :penumbral
+penumbral_eclipse.partial # => nil
+penumbral_eclipse.total   # => nil
+```
+
+## Local circumstances
+
+The eclipse is the same everywhere, so there is no path of visibility to compute. All that changes from place to place is whether the Moon is above the horizon, and visibility is the intersection of the eclipse with the time the Moon spends up. Half the Earth sees an eclipse; the other half is in daylight, with the Moon below the horizon.
+
+`LunarEclipse#visibility_from` takes an `Astronoby::Observer` and returns an `Astronoby::LunarEclipseVisibility`. No ephemeris is involved: the Moon's place at every contact is already carried by the geometry, so an eclipse can be observed from as many places as wanted, including after a round trip through a cache.
+
+```rb
+paris = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.8566),
+  longitude: Astronoby::Angle.from_degrees(2.3522)
+)
+
+visibility = eclipse.visibility_from(paris)
+
+visibility.visible?           # => true
+visibility.entirely_visible?  # => false
+visibility.circumstance       # => :ends_after_moonset
+```
+
+`#circumstance` sums up what the place gets of the eclipse:
+
+- `:not_visible`, the Moon is below the horizon for the whole eclipse
+- `:entirely_visible`, the Moon is up from the first to the last penumbral contact
+- `:begins_before_moonrise`, the eclipse is already under way when the Moon rises
+- `:ends_after_moonset`, the eclipse is still under way when the Moon sets
+- `:partially_visible`, anything else, which at high latitudes can be the Moon rising and setting within the eclipse
+
+`#coverage` takes a phase and answers how much of it happens with the Moon up, in the same three words `#circumstance` uses of the whole eclipse: `:entirely_visible`, `:partially_visible`, `:not_visible`, or `nil` when the eclipse has no such phase. In the example, in Paris, the Moon sets during the partial phase, before totality begins.
+
+```rb
+visibility.coverage(:penumbral) # => :partially_visible
+visibility.coverage(:partial)   # => :partially_visible
+visibility.coverage(:total)     # => :not_visible
+```
+
+`#horizon_crossings` are the instants of the eclipse at which the Moon rises or sets, and `#observable_windows` are the stretches of the eclipse spent with the Moon up. There is one window for an eclipse seen whole or in part, none for one not seen at all, and more than one only where the Moon crosses the horizon repeatedly.
+
+```rb
+visibility.horizon_crossings.map { |instant| instant.to_time }
+# => [2025-03-14 06:11:41 UTC]
+
+visibility.observable_windows.map { |window| [window.first.to_time, window.last.to_time] }
+# => [[2025-03-14 03:57:28 UTC, 2025-03-14 06:11:41 UTC]]
+```
+
+From Mexico City the same eclipse runs from end to end with the Moon high in the sky.
+
+```rb
+mexico_city = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(19.4326),
+  longitude: Astronoby::Angle.from_degrees(-99.1332)
+)
+
+visibility = eclipse.visibility_from(mexico_city)
+
+visibility.circumstance     # => :entirely_visible
+visibility.coverage(:total) # => :entirely_visible
+visibility.horizon_crossings # => []
+```
+
+`#above_horizon_at?` answers whether the Moon is up at an instant of the eclipse, and raises outside it.
+
+```rb
+visibility.above_horizon_at?(eclipse.total.starting_instant) # => true
+```
+
+Visibility answers whether the Moon is up, not how high it is. The Moon's place at each contact is interpolated from what the eclipse carries, which is what lets an eclipse be observed from anywhere without an ephemeris, and that is accurate well past what the horizon convention can resolve. For the altitude itself, ask the Moon, which computes it from the ephemeris with no interpolation at all.
+
+```rb
+Astronoby::Moon
+  .new(ephem: ephem, instant: eclipse.total.starting_instant)
+  .observed_by(mexico_city)
+  .horizontal
+  .altitude
+  .degrees # => 72.45
+```
+
+The Moon counts as up once its upper limb clears the refracted horizon, which is the convention Astronoby uses for moonrise and moonset, through `Astronoby::Horizon`.
+
+## Precision
+
+Two conventions shape the result. Earth's shadow is enlarged by its atmosphere, so Astronoby adds a 64 km shell to Earth's radius before building the shadow cones. And eclipse contacts are reduced with the IAU eclipse constant k, which puts the Moon's radius at 1738.09 km, slightly above its physical equatorial radius. Both are calibrated against IMCCE.
+
+Validated against IMCCE, the eclipse kind and the magnitudes match, and the contacts agree to within a couple of seconds. The shadow radii and the distance from the shadow axis match to well under an arcsecond, and position angles to 0.03 degrees.
+
+The local circumstances are reduced without the ephemeris, from the Moon's place at the contacts and the sidereal rate. The altitudes agree with the topocentric places computed from the ephemeris to under an arcminute, and the horizon crossings put the Moon on the horizon to a few arcseconds, which is well inside the uncertainty of the fixed refraction the convention assumes.
+
+## See also
+
+- [Moon Phases](moon_phases.md) - for lunar phases
+- [Lunar Observation](lunar_observation.md) - for libration, axis and limb angles
+- [Planetary Phenomena](planetary_phenomena.md) - for conjunctions, oppositions and elongations
+- [Solar System Bodies](solar_system_bodies.md) - for moon object details
+- [Ephemerides](ephem.md) - for data sources
+
+[NASA's Five Millennium Canon of Lunar Eclipses]: https://eclipse.gsfc.nasa.gov/SEpubs/5MCLE.html
+[IMCCE]: https://www.imcce.fr/