@openwaters/almanac 0.5.0 → 0.7.0

package/dist/solar.js

@@ -34,6 +34,7 @@ import { moonGeoVectorEqj } from './moon.js';
 import { sunGeoVectorEqj } from './sun.js';
 import { observerGeoVectorEqj, refractionDeg, topoAltAzUnrefracted } from './transforms.js';
 import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './events.js';
+import { horizonDip } from './horizon.js';
 import { calcShadow, moonEclipticLatitudeDeg, PRUNE_LATITUDE_DEG, SAME_ECLIPSE_MS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP } from './eclipse.js';
 /** UPSTREAM: `SUN_RADIUS_AU` and `MOON_POLAR_RADIUS_AU`, astronomy.ts 135 and 149-150.
  *  INTERNAL: `MOON_POLAR_RADIUS_KM` is shared with globalSolar.ts. */
@@ -66,7 +67,7 @@ function localMoonShadow(ut, observer) {
     return calcShadow(MOON_MEAN_RADIUS_KM, ut, o, hm);
 }
 /** UPSTREAM: `AngleBetween`, astronomy.ts ~256 — degrees. */
-function angleBetweenDeg(a, b) {
+function solarAngleBetweenDeg(a, b) {
     const aa = (a.x * a.x + a.y * a.y + a.z * a.z);
     if (Math.abs(aa) < 1.0e-8)
         throw new Error('almanac internal: AngleBetween first vector is too short');
@@ -131,7 +132,7 @@ function discObscuration(hm, lo) {
     // Calculate the apparent angular radius of the Moon for the observer.
     const moonRadius = Math.asin(MOON_POLAR_RADIUS_AU / Math.hypot(lo.x, lo.y, lo.z));
     // Calculate the apparent angular separation between the Sun's center and the Moon's center.
-    const sunMoonSeparation = angleBetweenDeg(lo, ho);
+    const sunMoonSeparation = solarAngleBetweenDeg(lo, ho);
     // Find the fraction of the Sun's apparent disc area that is covered by the Moon.
     return discOverlap(sunRadius, moonRadius, sunMoonSeparation * DEG2RAD);
 }
@@ -254,8 +255,8 @@ function buildSolarEclipse(shadow, observer) {
  * ponytail: three samples, not a sunrise search — a day that starts after C1
  * and ends before the peak still drops. Upgrade path: sunEvents over [c1, c4].
  */
-function seesAnyOfIt(e) {
-    return e.sunAltDeg.c1 > 0.0 || e.sunAltDeg.peak > 0.0 || e.sunAltDeg.c4 > 0.0;
+function seesAnyOfIt(e, dip) {
+    return e.sunAltDeg.c1 > dip || e.sunAltDeg.peak > dip || e.sunAltDeg.c4 > dip;
 }
 /**
  * The first solar eclipse `observer` can see whose peak falls strictly after
@@ -270,8 +271,8 @@ function seesAnyOfIt(e) {
  *      interval, or if no visible eclipse remains before the end of it.
  * @throws {RangeError} if `after` is invalid or `observer` is out of range.
  */
-export function nextSolarEclipse(after, observer) {
-    return nearestSolarEclipse(after, 1, observer);
+export function nextSolarEclipse(after, observer, heightAboveGroundM = 0) {
+    return nearestSolarEclipse(after, 1, observer, heightAboveGroundM);
 }
 /**
  * The last solar eclipse `observer` can see whose peak falls strictly before
@@ -282,30 +283,30 @@ export function nextSolarEclipse(after, observer) {
  *      interval, or if no visible eclipse remains after the start of it.
  * @throws {RangeError} if `before` is invalid or `observer` is out of range.
  */
-export function previousSolarEclipse(before, observer) {
-    return nearestSolarEclipse(before, -1, observer);
+export function previousSolarEclipse(before, observer, heightAboveGroundM = 0) {
+    return nearestSolarEclipse(before, -1, observer, heightAboveGroundM);
 }
 /** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
-export function solarEclipses(startUtc, endUtc, observer) {
+export function solarEclipses(startUtc, endUtc, observer, heightAboveGroundM = 0) {
     assertSupported(startUtc);
     assertSupportedWindowEnd(endUtc);
-    assertObserver(observer);
-    return scanSolarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false, observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
+    return scanSolarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false, observer, dip);
 }
-function nearestSolarEclipse(anchor, direction, observer) {
+function nearestSolarEclipse(anchor, direction, observer, heightAboveGroundM) {
     assertSupported(anchor);
-    assertObserver(observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
     const ms = anchor.getTime();
     // No scan limit: walk to the supported boundary. A place can go years
     // without a visible solar eclipse, and a pruned new moon is cheap.
     const startMs = direction > 0 ? ms + SAME_ECLIPSE_MS + 1 : SUPPORTED_MIN;
     const endMs = direction > 0 ? SUPPORTED_MAX : ms - SAME_ECLIPSE_MS;
-    const found = scanSolarEclipses(startMs, endMs, direction, true, observer);
+    const found = scanSolarEclipses(startMs, endMs, direction, true, observer, dip);
     if (found.length)
         return found[0];
     throw new AlmanacOutOfRangeError();
 }
-function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer) {
+function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer, dip) {
     const found = [];
     if (startMs >= endMs)
         return found;
@@ -337,7 +338,7 @@ function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer) {
         // This is at least a partial solar eclipse for the observer.
         const eclipse = buildSolarEclipse(shadow, observer);
         // Ignore any eclipse that happens completely at night.
-        if (!seesAnyOfIt(eclipse))
+        if (!seesAnyOfIt(eclipse, dip))
             continue;
         found.push(eclipse);
         if (firstOnly)

package/dist/sun.d.ts

@@ -7,6 +7,10 @@ type VsopModel = [VsopFormula, VsopFormula, VsopFormula];
  * below are checked against; exported for that test only.
  */
 export declare const vsopEarth: VsopModel;
+/** UPSTREAM: `VsopRotate`, astronomy.ts lines 3234-3241 — VSOP ecliptic to J2000 equatorial. */
+export declare function vsopRotate(eclip: Vec3): Vec3;
+/** UPSTREAM: `VsopSphereToRect`, astronomy.ts lines 3243-3253. */
+export declare function vsopSphereToRect(lon: number, lat: number, radius: number): Vec3;
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).

package/dist/sun.js

@@ -204,7 +204,7 @@ function earthRad(t) {
     return coord;
 }
 /** UPSTREAM: `VsopRotate`, astronomy.ts lines 3234-3241 — VSOP ecliptic to J2000 equatorial. */
-function vsopRotate(eclip) {
+export function vsopRotate(eclip) {
     return {
         x: eclip.x + 0.000000440360 * eclip.y - 0.000000190919 * eclip.z,
         y: -0.000000479966 * eclip.x + 0.917482137087 * eclip.y - 0.397776982902 * eclip.z,
@@ -212,7 +212,7 @@ function vsopRotate(eclip) {
     };
 }
 /** UPSTREAM: `VsopSphereToRect`, astronomy.ts lines 3243-3253. */
-function vsopSphereToRect(lon, lat, radius) {
+export function vsopSphereToRect(lon, lat, radius) {
     // Convert spherical coordinates to ecliptic cartesian coordinates.
     const r_coslat = radius * Math.cos(lat);
     const coslon = Math.cos(lon);

package/dist/transforms.d.ts

@@ -56,6 +56,7 @@ export declare function topoAltAzUnrefracted(bodyEqj: Vec3, ut: number, observer
  * altitude never drops below -90.
  */
 export declare function refractionDeg(altitudeDeg: number): number;
+export declare function refract(unrefracted: AltAz): AltAz;
 /**
  * Topocentric azimuth/altitude of the Sun — parallax (via the observer's
  * geocentric position, WGS-84 flattening, elevation) and atmospheric

package/dist/transforms.js

@@ -182,7 +182,7 @@ export function refractionDeg(altitudeDeg) {
     }
     return refr;
 }
-function refract(unrefracted) {
+export function refract(unrefracted) {
     return { azDeg: unrefracted.azDeg, altDeg: unrefracted.altDeg + refractionDeg(unrefracted.altDeg) };
 }
 /**

package/dist/types.d.ts

@@ -3,6 +3,9 @@ export interface Observer {
     longitudeDeg: number;
     elevationM?: number;
 }
+export type Planet = 'mercury' | 'venus' | 'earth' | 'mars' | 'jupiter' | 'saturn';
+/** INTERNAL: Earth has no planetary direction from an Earth-based observer. */
+export declare function assertPlanet(planet: Planet, earthAllowed?: boolean): void;
 export declare class AlmanacOutOfRangeError extends RangeError {
     constructor(msg?: string);
 }

package/dist/types.js

@@ -1,3 +1,8 @@
+/** INTERNAL: Earth has no planetary direction from an Earth-based observer. */
+export function assertPlanet(planet, earthAllowed = false) {
+    if (!['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn'].includes(planet) || (!earthAllowed && planet === 'earth'))
+        throw new RangeError(`invalid planet: ${planet}`);
+}
 export class AlmanacOutOfRangeError extends RangeError {
     constructor(msg = 'time outside supported interval 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z') { super(msg); this.name = 'AlmanacOutOfRangeError'; }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.5.0",
-  "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar and solar eclipses.",
+  "version": "0.7.0",
+  "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {
     "type": "git",