@openwaters/almanac 0.6.0 → 0.8.0

package/dist/planets.d.ts

@@ -0,0 +1,32 @@
+import { type Planet, type Observer } from './types.js';
+import { type AltAz } from './transforms.js';
+/** Geometric Sun-centered AU vector in the fixed J2000 mean equatorial frame. */
+export interface HeliocentricPosition {
+    xAu: number;
+    yAu: number;
+    zAu: number;
+}
+/** Apparent geocentric position on the true equator and equinox of date. */
+export interface PlanetPosition {
+    raDeg: number;
+    decDeg: number;
+    distanceAu: number;
+}
+/** Geometric phase and approximate airless visual magnitude, plus apparent solar separation. */
+export interface PlanetIllumination {
+    fraction: number;
+    phaseAngleDeg: number;
+    magnitude: number;
+    elongationDeg: number;
+}
+export declare function planetIlluminationAtTT(planet: Planet, tt: number): PlanetIllumination;
+/** Approximate airless magnitude includes Saturn's rings; elongation is apparent separation from the Sun. */
+export declare function planetIllumination(planet: Planet, time: Date): PlanetIllumination;
+/** INTERNAL: TT-labeled evidence bypasses the civil-time Delta-T conversion. */
+export declare function planetApparentAtTT(planet: Planet, tt: number): PlanetPosition;
+/** Geometric position at the requested instant; accepts Earth. */
+export declare function planetHeliocentricPosition(planet: Planet, time: Date): HeliocentricPosition;
+/** Apparent geocentric position with light-time, aberration, precession, and nutation. */
+export declare function planetPosition(planet: Planet, time: Date): PlanetPosition;
+/** Refracted topocentric position; altitude remains relative to the horizontal plane. */
+export declare function planetAltAz(planet: Planet, time: Date, observer: Observer): AltAz;

package/dist/planets.js

@@ -0,0 +1,111 @@
+import { assertPlanet, assertSupported, assertObserver } from './types.js';
+import { ttDays, ttDaysFromUt, utDays } from './time.js';
+import { gyration, PrecessDirection, equatorialFromVector, DEG2RAD, RAD2DEG, earthTilt, eclipticToEquatorial } from './nutation.js';
+import { planetHelioVector, planetGeoVectorEqj } from './planetModels.js';
+import { topoAltAzUnrefracted, refract } from './transforms.js';
+import { angleBetweenDeg } from './illumination.js';
+import { earthHelioVector, sunGeoVectorEqj } from './sun.js';
+// VisualMagnitude: https://github.com/cosinekitty/astronomy/blob/865d3da7d8112bbc7911238052c6af4aaf877181/source/js/astronomy.ts#L4901.
+function visualMagnitude(planet, phase, helioDist, geoDist) {
+    let c0, c1 = 0, c2 = 0, c3 = 0;
+    switch (planet) {
+        case 'mercury':
+            c0 = -0.60;
+            c1 = 4.98;
+            c2 = -4.88;
+            c3 = 3.02;
+            break;
+        case 'venus':
+            if (phase < 163.6) {
+                c0 = -4.47;
+                c1 = 1.03;
+                c2 = 0.57;
+                c3 = 0.13;
+            }
+            else {
+                c0 = 0.98;
+                c1 = -1.02;
+            }
+            break;
+        case 'mars':
+            c0 = -1.52;
+            c1 = 1.60;
+            break;
+        case 'jupiter':
+            c0 = -9.40;
+            c1 = 0.50;
+            break;
+        case 'uranus':
+            c0 = -7.19;
+            c1 = 0.25;
+            break;
+        case 'neptune':
+            c0 = -6.87;
+            break;
+        default: throw new Error('unsupported planet in visualMagnitude');
+    }
+    const x = phase / 100;
+    let mag = c0 + x * (c1 + x * (c2 + x * c3));
+    mag += 5 * Math.log10(helioDist * geoDist);
+    return mag;
+}
+// SaturnMagnitude: pinned astronomy.ts#L4927; Ecliptic: #L3013.
+function saturnMagnitude(phase, helioDist, geoDist, gc, tt) {
+    const ecl = eclipticToEquatorial(-earthTilt(tt).tobl, gyration(gc, tt, PrecessDirection.From2000));
+    const lat = RAD2DEG * Math.atan2(ecl.z, Math.hypot(ecl.x, ecl.y));
+    let lon = RAD2DEG * Math.atan2(ecl.y, ecl.x);
+    if (lon < 0)
+        lon += 360;
+    const ir = DEG2RAD * 28.06, nr = DEG2RAD * (169.51 + (3.82e-5 * tt));
+    const tilt = Math.asin(Math.sin(DEG2RAD * lat) * Math.cos(ir) - Math.cos(DEG2RAD * lat) * Math.sin(ir) * Math.sin(DEG2RAD * lon - nr));
+    const sinTilt = Math.sin(Math.abs(tilt));
+    let mag = -9 + 0.044 * phase;
+    mag += sinTilt * (-2.6 + 1.2 * sinTilt);
+    mag += 5 * Math.log10(helioDist * geoDist);
+    return mag;
+}
+// Illumination: pinned astronomy.ts#L5066; AngleFromSun: #L4869.
+export function planetIlluminationAtTT(planet, tt) {
+    const earth = earthHelioVector(tt), hc = planetHelioVector(planet, tt);
+    const gc = { x: hc.x - earth.x, y: hc.y - earth.y, z: hc.z - earth.z };
+    const phaseAngleDeg = angleBetweenDeg(gc, hc);
+    const helioDist = Math.sqrt(hc.x * hc.x + hc.y * hc.y + hc.z * hc.z);
+    const geoDist = Math.sqrt(gc.x * gc.x + gc.y * gc.y + gc.z * gc.z);
+    const magnitude = planet === 'saturn' ? saturnMagnitude(phaseAngleDeg, helioDist, geoDist, gc, tt) : visualMagnitude(planet, phaseAngleDeg, helioDist, geoDist);
+    return { fraction: (1 + Math.cos(DEG2RAD * phaseAngleDeg)) / 2, phaseAngleDeg, magnitude,
+        elongationDeg: angleBetweenDeg(sunGeoVectorEqj(tt), planetGeoVectorEqj(planet, tt)) };
+}
+/** Approximate airless magnitude includes Saturn's rings; elongation is apparent separation from the Sun. */
+export function planetIllumination(planet, time) {
+    assertPlanet(planet);
+    assertSupported(time);
+    return planetIlluminationAtTT(planet, ttDays(time));
+}
+/** INTERNAL: TT-labeled evidence bypasses the civil-time Delta-T conversion. */
+export function planetApparentAtTT(planet, tt) {
+    const direction = equatorialFromVector(gyration(planetGeoVectorEqj(planet, tt), tt, PrecessDirection.From2000));
+    // Aberration changes direction, not physical range; keep Earth at reception for distance.
+    const range = planetGeoVectorEqj(planet, tt, false);
+    return { raDeg: direction.raDeg, decDeg: direction.decDeg, distanceAu: Math.hypot(range.x, range.y, range.z) };
+}
+/** Geometric position at the requested instant; accepts Earth. */
+export function planetHeliocentricPosition(planet, time) {
+    assertPlanet(planet, true);
+    assertSupported(time);
+    const p = planetHelioVector(planet, ttDays(time));
+    return { xAu: p.x, yAu: p.y, zAu: p.z };
+}
+/** Apparent geocentric position with light-time, aberration, precession, and nutation. */
+export function planetPosition(planet, time) {
+    assertPlanet(planet);
+    assertSupported(time);
+    return planetApparentAtTT(planet, ttDays(time));
+}
+/** Refracted topocentric position; altitude remains relative to the horizontal plane. */
+export function planetAltAz(planet, time, observer) {
+    assertPlanet(planet);
+    assertSupported(time);
+    assertObserver(observer);
+    const ut = utDays(time);
+    return refract(topoAltAzUnrefracted(planetGeoVectorEqj(planet, ttDaysFromUt(ut)), ut, observer));
+}

package/dist/solar.d.ts

@@ -67,7 +67,7 @@ export declare function eclipseKindFromUmbra(k: number): 'total' | 'annular';
  *      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 declare function nextSolarEclipse(after: Date, observer: Observer): SolarEclipse;
+export declare function nextSolarEclipse(after: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse;
 /**
  * The last solar eclipse `observer` can see whose peak falls strictly before
  * `before`, skipping peaks within 100 ms of it, just as `nextSolarEclipse`
@@ -77,6 +77,6 @@ export declare function nextSolarEclipse(after: Date, observer: Observer): Solar
  *      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 declare function previousSolarEclipse(before: Date, observer: Observer): SolarEclipse;
+export declare function previousSolarEclipse(before: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse;
 /** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
-export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer): SolarEclipse[];
+export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse[];

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

@@ -7,13 +7,16 @@ export interface AltAz {
 }
 /**
  * INTERNAL: what {@link topoAltAzUnrefracted} already computes on the way to
- * az/alt. The L3 event layer needs all four from a single evaluation — the
- * local hour angle brackets each daily cycle's altitude extrema, and the
- * topocentric distance sets the Moon's semidiameter, hence its rise/set target.
+ * az/alt. The L3 event layer needs these from a single evaluation — the
+ * local hour angle brackets each daily cycle's altitude extrema, the
+ * topocentric distance sets the Moon's semidiameter, hence its rise/set target,
+ * and the topocentric RA/Dec orient the Moon's disc.
  */
 export interface TopoUnrefracted extends AltAz {
     hourAngleDeg: number;
     distanceAu: number;
+    raDeg: number;
+    decDeg: number;
 }
 /**
  * UPSTREAM: `sidereal_time`, astronomy.ts ~2031 — Greenwich Apparent Sidereal
@@ -56,6 +59,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

@@ -160,7 +160,7 @@ export function topoAltAzUnrefracted(bodyEqj, ut, observer) {
     let hourAngleDeg = (gast + observer.longitudeDeg - raDeg) % 360;
     if (hourAngleDeg < 0)
         hourAngleDeg += 360;
-    return { azDeg: az, altDeg: 90 - zd, hourAngleDeg, distanceAu };
+    return { azDeg: az, altDeg: 90 - zd, hourAngleDeg, distanceAu, raDeg, decDeg };
 }
 /**
  * UPSTREAM: `Refraction('normal', altitude)`, astronomy.ts ~7176 — the
@@ -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' | 'uranus' | 'neptune';
+/** 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', 'uranus', 'neptune'].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.6.0",
-  "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar and solar eclipses.",
+  "version": "0.8.0",
+  "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,7 +18,8 @@
     "ephemeris",
     "lunar-eclipse",
     "solar-eclipse",
-    "marine"
+    "marine",
+    "suncalc"
   ],
   "publishConfig": {
     "access": "public"