@openwaters/almanac 0.5.0 → 0.6.0

package/README.md

@@ -101,7 +101,7 @@ const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.5.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.6.0")
 ```
 
 ```swift
@@ -155,7 +155,7 @@ anchor. Search results are global; apply `lunarEclipseVisibility` for an observe
 
 Solar eclipses are searched for an observer, because their contacts only exist for a place: `nextSolarEclipse(after, observer)`, `previousSolarEclipse(before, observer)`, and `solarEclipses(startUtc, endUtc, observer)`. An eclipse whose Sun is below the horizon at C1, the peak, and C4 is not returned.
 
-To ask about the whole Earth instead, `nextGlobalSolarEclipse(after)`, `previousGlobalSolarEclipse(before)`, and `globalSolarEclipses(startUtc, endUtc)` need no observer. Each eclipse reports its greatest eclipse, the shadow axis's distance from the Earth's center, and where the axis meets the ground, with the kind and obscuration seen there. When the axis misses the Earth the eclipse is partial and has no ground point.
+To ask about the whole Earth instead, `nextGlobalSolarEclipse(after)`, `previousGlobalSolarEclipse(before)`, and `globalSolarEclipses(startUtc, endUtc)` need no observer. Each eclipse reports its greatest eclipse, the shadow axis's distance from the Earth's center, and where the axis meets the ground, with the kind and obscuration seen there. When the axis misses the Earth the eclipse is partial and has no ground point, and greatest eclipse falls on the Earth's limb nearest the axis, with the Sun on the horizon: `greatestLatitudeDeg`, `greatestLongitudeDeg`, and `greatestObscuration` give that place for every eclipse.
 
 `solarEclipseCentralLine(peak, stepSeconds)` samples where the axis meets the ground from its first contact to its last, and `solarEclipseAxisPoint(time)` gives that point at any instant. How far the next totality passes from a place is a distance to each point of a line:
 

package/dist/globalSolar.d.ts

@@ -13,6 +13,12 @@ export interface GlobalSolarEclipse {
     longitudeDeg: number | null;
     /** Fraction of the Sun's disc area covered at that point; exactly 1 for a total eclipse; `null` for a partial eclipse. */
     obscuration: number | null;
+    /** Geodetic latitude of greatest eclipse, degrees: the ground point, or for a partial eclipse the point on the Earth's limb nearest the axis, with the Sun on the horizon. */
+    greatestLatitudeDeg: number;
+    /** Longitude of greatest eclipse, degrees east in (−180, 180]. */
+    greatestLongitudeDeg: number;
+    /** Fraction of the Sun's disc area covered at greatest eclipse. */
+    greatestObscuration: number;
 }
 /** A point on a solar eclipse's central line: where the Moon's shadow axis meets the ground at one instant. */
 export interface SolarEclipseAxisPoint {

package/dist/globalSolar.js

@@ -30,6 +30,10 @@
 // quadratic's discriminant, and an axis point rejects the crossing on the
 // Sun's side of the Moon that upstream, asking only at greatest eclipse,
 // never meets.
+//
+// Neither is greatest eclipse for an axis that misses the Earth: upstream
+// reports no place at all, and this package reports the point on the limb
+// nearest the axis, where the Sun is on the horizon.
 import { assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
 import { EARTH_EQUATORIAL_RADIUS_KM, EARTH_FLATTENING, EARTH_FLATTENING_SQUARED, KM_PER_AU, RAD2DEG, PrecessDirection, gyration } from './nutation.js';
@@ -133,6 +137,24 @@ function axisGround(shadow, axis, u) {
     const px = u * v.x - e.x;
     const py = u * v.y - e.y;
     const pz = (u * v.z - e.z) * EARTH_FLATTENING;
+    const { latitudeDeg, longitudeDeg, o } = geodeticPlace(shadow, tt, px, py, pz);
+    // Recalculate the shadow using a vector from the Moon's center toward the observer.
+    const surface = calcShadow(MOON_POLAR_RADIUS_KM, shadow.ut, o, shadow.dir);
+    // If we did everything right, the shadow distance should be very close to zero.
+    // That's because we already determined the observer 'o' is on the shadow axis!
+    // Upstream's bound is 1e-9 km; exceeding it is an implementation failure.
+    if (surface.r > 1.0e-9 || surface.r < 0.0)
+        throw new Error(`almanac internal: unexpected shadow distance from geoid intersection = ${surface.r}`);
+    const kind = eclipseKindFromUmbra(surface.k);
+    const obscuration = (kind === 'total') ? 1.0 : solarEclipseObscuration(shadow.dir, o);
+    return { latitudeDeg, longitudeDeg, kind, obscuration };
+}
+/**
+ * UPSTREAM: the middle of `GeoidIntersect`, astronomy.ts ~8842 — geodetic
+ * latitude and longitude of a geocentric equator-of-date point in km, and the
+ * lunacentric EQJ vector toward it in AU.
+ */
+function geodeticPlace(shadow, tt, px, py, pz) {
     // Convert cartesian coordinates into geodetic latitude/longitude.
     const proj = Math.hypot(px, py) * EARTH_FLATTENING_SQUARED;
     let latitudeDeg;
@@ -153,16 +175,31 @@ function axisGround(shadow, axis, u) {
     const og = gyration({ x: px / KM_PER_AU, y: py / KM_PER_AU, z: pz / KM_PER_AU }, tt, PrecessDirection.Into2000);
     // Convert geocentric vector to lunacentric vector.
     const o = { x: og.x + shadow.target.x, y: og.y + shadow.target.y, z: og.z + shadow.target.z };
-    // Recalculate the shadow using a vector from the Moon's center toward the observer.
+    return { latitudeDeg, longitudeDeg, o };
+}
+/**
+ * Greatest eclipse when the axis misses the geoid: the point on the Earth's
+ * limb nearest the axis. In the dilated coordinates the geoid is a sphere, and
+ * the axis's closest approach to its center, scaled onto it, stands for that point.
+ * The axis runs perpendicular to the radius there, so it lies in the sphere's
+ * tangent plane; dilation maps tangent planes to tangent planes, so on the
+ * ellipsoid the axis lies in the geodetic horizon and the Sun's center is at
+ * geometric altitude zero, as the catalog tabulates. The observer there sees
+ * what the local search would: a total or annular phase only inside the
+ * umbra, which a non-central eclipse can graze.
+ */
+function limbGround(shadow, axis) {
+    const { tt, v, e, A, B } = axis;
+    const u = -B / (2 * A);
+    const cx = u * v.x - e.x;
+    const cy = u * v.y - e.y;
+    const cz = u * v.z - e.z;
+    const scale = EARTH_EQUATORIAL_RADIUS_KM / Math.sqrt(cx * cx + cy * cy + cz * cz);
+    const { latitudeDeg, longitudeDeg, o } = geodeticPlace(shadow, tt, cx * scale, cy * scale, cz * scale * EARTH_FLATTENING);
     const surface = calcShadow(MOON_POLAR_RADIUS_KM, shadow.ut, o, shadow.dir);
-    // If we did everything right, the shadow distance should be very close to zero.
-    // That's because we already determined the observer 'o' is on the shadow axis!
-    // Upstream's bound is 1e-9 km; exceeding it is an implementation failure.
-    if (surface.r > 1.0e-9 || surface.r < 0.0)
-        throw new Error(`almanac internal: unexpected shadow distance from geoid intersection = ${surface.r}`);
-    const kind = eclipseKindFromUmbra(surface.k);
-    const obscuration = (kind === 'total') ? 1.0 : solarEclipseObscuration(shadow.dir, o);
-    return { latitudeDeg, longitudeDeg, kind, obscuration };
+    const obscuration = (surface.r < Math.abs(surface.k) && eclipseKindFromUmbra(surface.k) === 'total')
+        ? 1.0 : solarEclipseObscuration(shadow.dir, o);
+    return { latitudeDeg, longitudeDeg, obscuration };
 }
 /**
  * UPSTREAM: `GeoidIntersect`'s choice of root — where the axis first meets
@@ -201,13 +238,18 @@ function grazingGround(shadow) {
 function geoidIntersect(shadow, peak) {
     const ground = nearAxisGround(shadow);
     if (ground === null) {
-        // This is a partial solar eclipse, and an obscuration needs a place:
-        // `solarEclipses` and `solarObscuration` take an observer.
-        return { kind: 'partial', peak, axisDistanceKm: shadow.r, latitudeDeg: null, longitudeDeg: null, obscuration: null };
+        // This is a partial solar eclipse: no one stands on the axis, and
+        // greatest eclipse is on the limb nearest it.
+        const limb = limbGround(shadow, dilatedAxis(shadow));
+        return {
+            kind: 'partial', peak, axisDistanceKm: shadow.r, latitudeDeg: null, longitudeDeg: null, obscuration: null,
+            greatestLatitudeDeg: limb.latitudeDeg, greatestLongitudeDeg: limb.longitudeDeg, greatestObscuration: limb.obscuration
+        };
     }
     return {
         kind: ground.kind, peak, axisDistanceKm: shadow.r,
-        latitudeDeg: ground.latitudeDeg, longitudeDeg: ground.longitudeDeg, obscuration: ground.obscuration
+        latitudeDeg: ground.latitudeDeg, longitudeDeg: ground.longitudeDeg, obscuration: ground.obscuration,
+        greatestLatitudeDeg: ground.latitudeDeg, greatestLongitudeDeg: ground.longitudeDeg, greatestObscuration: ground.obscuration
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar and solar eclipses.",
   "license": "MIT",
   "repository": {