@openwaters/almanac 0.10.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # Almanac
 
-Offline sky engine for the Salish Sea and everywhere else: Sun, Moon, and planet positions, apparent horizon dip, rise, set, twilight, any Sun altitude, upper and lower transits, Moon phase and orientation, equinoxes and solstices, lunar perigee and apogee, the equation of time, planetary brightness, lunar and solar eclipses, and fixed-star altitude and azimuth from catalog positions, computed from pure geometry with zero network and zero runtime data files.
+Offline sky engine for the Salish Sea and everywhere else: Sun, Moon, and planet positions, apparent horizon dip, rise, set, twilight, any Sun altitude, upper and lower transits, Moon phase and orientation, equinoxes and solstices, lunar perigee and apogee, the equation of time, planetary brightness, lunar and solar eclipses, fixed-star apparent places, altitude, and azimuth from catalog positions, and Greenwich sidereal time for sight reduction, computed from pure geometry with zero network and zero runtime data files.
 
 Three implementations, one behavior:
 
@@ -111,7 +111,8 @@ npm install @openwaters/almanac
 ```ts
 import {
   nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, nextGlobalSolarEclipse, sunEvents, starAltAz,
-  seasons, moonApsides, equationOfTime
+  starPosition, greenwichSiderealTime,
+  seasons, moonApsides, earthApsides, equationOfTime
 } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
@@ -136,11 +137,16 @@ for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
 // Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
 const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 
+// Its apparent place and Greenwich hour angle for sight reduction, in degrees.
+const place = starPosition(88.792939, 7.407064, today);
+const ghaDeg = (greenwichSiderealTime(today) - place.raDeg + 360) % 360;
+
 // The year's equinoxes and solstices, the Moon's perigees and apogees with
 // distances, and the equation of time in minutes.
 const year = new Date(today.getUTCFullYear() + 1, 0, 1);
 for (const { kind, time } of seasons(today, year)) console.log(kind, time.toISOString());
 for (const { kind, time, distanceKm } of moonApsides(today, year)) console.log(kind, time.toISOString(), distanceKm);
+for (const { kind, time, distanceKm } of earthApsides(today, year)) console.log(kind, time.toISOString(), distanceKm);
 console.log(equationOfTime(today));   // sundial minus clock, minutes
 ```
 
@@ -160,7 +166,7 @@ const crossings = sunEvents(today, tomorrow, viewer, eyeHeightM);
 Requires a Swift 6 or newer toolchain.
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.10.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.12.0")
 ```
 
 ```swift
@@ -192,17 +198,22 @@ for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
 // Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
 let star = try starAltAz(raDeg: 88.792939, decDeg: 7.407064, at: today, observer: observer)
 
+// Its apparent place and Greenwich hour angle for sight reduction, in degrees.
+let place = try starPosition(raDeg: 88.792939, decDeg: 7.407064, at: today)
+let ghaDeg = (try greenwichSiderealTime(today) - place.raDeg + 360).truncatingRemainder(dividingBy: 360)
+
 // The year's equinoxes and solstices, the Moon's perigees and apogees with
 // distances, and the equation of time in minutes.
 let year = today.addingTimeInterval(366 * 24 * 60 * 60)
 for event in try seasons(from: today, to: year) { print(event.kind, event.time) }
 for apsis in try moonApsides(from: today, to: year) { print(apsis.kind, apsis.time, apsis.distanceKm) }
+for apsis in try earthApsides(from: today, to: year) { print(apsis.kind, apsis.time, apsis.distanceKm) }
 print(try equationOfTime(today))   // sundial minus clock, minutes
 ```
 
 ### Kotlin/JVM and Android
 
-The Kotlin library provides the same 38 functions and result fields, using `java.time.Instant` and immutable data classes. It targets JVM 8 and Android minSdk 26, builds with JDK 17, and has no runtime dependencies beyond the Kotlin standard library and platform APIs. Maven publication and a Kotlin benchmark runner are deferred; consume the source at a reviewed Git SHA as described in [`kotlin/README.md`](kotlin/README.md).
+The Kotlin library provides the same functions and result fields, using `java.time.Instant` and immutable data classes. It targets JVM 8 and Android minSdk 26, builds with JDK 17, and has no runtime dependencies beyond the Kotlin standard library and platform APIs. Maven publication and a Kotlin benchmark runner are deferred; consume the source at a reviewed Git SHA as described in [`kotlin/README.md`](kotlin/README.md).
 
 ```kotlin
 import io.openwaters.almanac.*

package/dist/earthApsides.d.ts

@@ -0,0 +1,14 @@
+/** Closest approach or farthest remove of the Earth from the Sun's centre. */
+export type EarthApsisKind = 'perihelion' | 'aphelion';
+/** A terrestrial perihelion or aphelion, with the Sun–Earth centre distance there. */
+export interface EarthApsis {
+    time: Date;
+    kind: EarthApsisKind;
+    distanceKm: number;
+}
+/**
+ * The Earth's perihelia and aphelia within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, each with the heliocentric distance
+ * at that instant.
+ */
+export declare function earthApsides(startUtc: Date, endUtc: Date): EarthApsis[];

package/dist/earthApsides.js

@@ -0,0 +1,76 @@
+// SearchPlanetApsis (Earth), pinned Astronomy Engine 865d3da7d8112bbc7911238052c6af4aaf877181.
+// Central difference in UT, orbital-period/6 brackets; fixed J2000 grid gives window-independent roots.
+import { assertSupported, assertSupportedWindowEnd } from './types.js';
+import { utDays, ttDaysFromUt, dateFromUt } from './time.js';
+import { KM_PER_AU } from './nutation.js';
+import { earthHelioDistance } from './sun.js';
+import { search, quantizedUt, assertReached } from './events.js';
+/** UPSTREAM: the central-difference half-width `dt` inside `SearchPlanetApsis`. */
+const SLOPE_DT_DAYS = 0.001;
+/** UPSTREAM: `increment` — the scan step, here also the grid cell in days since J2000 UT. */
+const APSIS_CELL_DAYS = 365.256 / 6;
+/** UPSTREAM: `positive_slope` — dr/dt in AU per day, by central difference. */
+function distanceSlope(ut) {
+    const r1 = earthHelioDistance(ttDaysFromUt(ut - SLOPE_DT_DAYS / 2));
+    const r2 = earthHelioDistance(ttDaysFromUt(ut + SLOPE_DT_DAYS / 2));
+    return (r2 - r1) / SLOPE_DT_DAYS;
+}
+function negativeDistanceSlope(ut) {
+    return -distanceSlope(ut);
+}
+/**
+ * UPSTREAM: the body of `SearchPlanetApsis`'s scan loop for one cell `[t1, t2]`
+ * with the slopes `m1`, `m2` at its ends. A slope rising through zero is a
+ * perihelion and falling through zero an aphelion. A zero exactly at a grid point
+ * belongs to the cell it ends, so no apsis is reported twice.
+ */
+function searchApsisInCell(t1, t2, m1, m2) {
+    if (m1 < 0 && m2 >= 0) {
+        const ut = search(distanceSlope, t1, t2, 1, undefined, 'perihelion search');
+        assertReached(ut !== null, 'perihelion search');
+        return { ut: ut, kind: 'perihelion' };
+    }
+    if (m1 > 0 && m2 <= 0) {
+        const ut = search(negativeDistanceSlope, t1, t2, 1, undefined, 'aphelion search');
+        assertReached(ut !== null, 'aphelion search');
+        return { ut: ut, kind: 'aphelion' };
+    }
+    return null;
+}
+/**
+ * The Earth's perihelia and aphelia within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, each with the heliocentric distance
+ * at that instant.
+ */
+export function earthApsides(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const startUt = utDays(startUtc);
+    const endUt = utDays(endUtc);
+    const events = [];
+    let cell = Math.floor(startUt / APSIS_CELL_DAYS);
+    let t1 = cell * APSIS_CELL_DAYS;
+    let m1 = distanceSlope(t1);
+    while (t1 < endUt) {
+        const t2 = (cell + 1) * APSIS_CELL_DAYS;
+        const m2 = distanceSlope(t2);
+        const found = searchApsisInCell(t1, t2, m1, m2);
+        if (found !== null) {
+            const q = quantizedUt(found.ut); // judge the half-open bounds on the reported instant, not the raw root
+            if (q >= endUt)
+                break;
+            if (q >= startUt) {
+                events.push({
+                    time: dateFromUt(found.ut), kind: found.kind,
+                    distanceKm: earthHelioDistance(ttDaysFromUt(found.ut)) * KM_PER_AU
+                });
+            }
+        }
+        cell++;
+        t1 = t2;
+        m1 = m2;
+    }
+    return events;
+}

package/dist/index.d.ts

@@ -4,14 +4,14 @@ export type { HeliocentricPosition, PlanetPosition, PlanetIllumination } from '.
 export { planetHeliocentricPosition, planetPosition, planetAltAz, planetIllumination } from './planets.js';
 export { horizonDip } from './horizon.js';
 export { AlmanacOutOfRangeError } from './types.js';
-export type { SunPosition, MoonPosition } from './positions.js';
-export { sunPosition, moonPosition, equationOfTime } from './positions.js';
+export type { SunPosition, MoonPosition, StarPosition } from './positions.js';
+export { sunPosition, moonPosition, starPosition, equationOfTime } from './positions.js';
 export type { SeasonKind, SeasonEvent } from './seasons.js';
 export { seasons } from './seasons.js';
 export type { MoonApsisKind, MoonApsis } from './apsides.js';
 export { moonApsides } from './apsides.js';
 export type { AltAz } from './transforms.js';
-export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
+export { sunAltAz, moonAltAz, starAltAz, greenwichSiderealTime } from './transforms.js';
 export type { MoonIllumination, MoonOrientation } from './illumination.js';
 export { moonIllumination, moonOrientation } from './illumination.js';
 export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName, PlanetEvent, PlanetEventKind, AltitudeEvent, AltitudeEventKind, TransitEvent, TransitEventKind } from './events.js';
@@ -22,3 +22,5 @@ export type { SolarEclipse, SolarEclipseKind, SolarEclipseSunAltitudes } from '.
 export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';
 export type { GlobalSolarEclipse, SolarEclipseAxisPoint } from './globalSolar.js';
 export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';
+export type { EarthApsisKind, EarthApsis } from './earthApsides.js';
+export { earthApsides } from './earthApsides.js';

package/dist/index.js

@@ -3,12 +3,13 @@ export { degreesToRadians, radiansToDegrees } from './angles.js';
 export { planetHeliocentricPosition, planetPosition, planetAltAz, planetIllumination } from './planets.js';
 export { horizonDip } from './horizon.js';
 export { AlmanacOutOfRangeError } from './types.js';
-export { sunPosition, moonPosition, equationOfTime } from './positions.js';
+export { sunPosition, moonPosition, starPosition, equationOfTime } from './positions.js';
 export { seasons } from './seasons.js';
 export { moonApsides } from './apsides.js';
-export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
+export { sunAltAz, moonAltAz, starAltAz, greenwichSiderealTime } from './transforms.js';
 export { moonIllumination, moonOrientation } from './illumination.js';
 export { sunIsUp, sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
 export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';
 export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';
+export { earthApsides } from './earthApsides.js';

package/dist/nutation.d.ts

@@ -34,6 +34,12 @@ export declare enum PrecessDirection {
 }
 /** UPSTREAM: `Frac`, astronomy.ts line 235. */
 export declare function frac(x: number): number;
+/**
+ * Not upstream: an angle wrapped into [0, 360). Upstream adds 360 to a
+ * negative remainder, and a remainder within an ulp below zero then rounds
+ * to 360 itself.
+ */
+export declare function wrapDeg360(deg: number): number;
 /** UPSTREAM: `mean_obliq`, astronomy.ts lines 1437-1447. Degrees. */
 export declare function meanObliquityDeg(tt: number): number;
 /** UPSTREAM: `EarthTiltInfo`, astronomy.ts lines 1449-1457. dpsi/deps arcsec, mobl/tobl degrees. */

package/dist/nutation.js

@@ -37,6 +37,19 @@ export var PrecessDirection;
 export function frac(x) {
     return x - Math.floor(x);
 }
+/**
+ * Not upstream: an angle wrapped into [0, 360). Upstream adds 360 to a
+ * negative remainder, and a remainder within an ulp below zero then rounds
+ * to 360 itself.
+ */
+export function wrapDeg360(deg) {
+    let r = deg % 360;
+    if (r < 0)
+        r += 360;
+    if (r >= 360)
+        r -= 360;
+    return r;
+}
 /**
  * UPSTREAM: `iau2000b`, astronomy.ts lines 1392-1435. The IAU 2000B nutation
  * series truncated to its five largest terms; returns arcseconds.
@@ -247,9 +260,7 @@ export function equatorialFromVector(pos) {
             throw new Error('Indeterminate sky coordinates');
         return { raDeg: 0, decDeg: (pos.z < 0) ? -90 : +90, distanceAu: dist };
     }
-    let raDeg = RAD2DEG * Math.atan2(pos.y, pos.x);
-    if (raDeg < 0)
-        raDeg += 360;
+    const raDeg = wrapDeg360(RAD2DEG * Math.atan2(pos.y, pos.x));
     const decDeg = RAD2DEG * Math.atan2(pos.z, Math.sqrt(xyproj));
     return { raDeg, decDeg, distanceAu: dist };
 }

package/dist/positions.d.ts

@@ -10,6 +10,11 @@ export interface MoonPosition {
     decDeg: number;
     distanceKm: number;
 }
+/** Apparent geocentric position of a fixed star: equator of date, RA in [0, 360). */
+export interface StarPosition {
+    raDeg: number;
+    decDeg: number;
+}
 /**
  * INTERNAL: apparent Sun for a TT instant, expressed as days since the J2000
  * epoch in Terrestrial Time. This is the entry point the TT-labeled position
@@ -32,6 +37,17 @@ export declare function sunPosition(time: Date): SunPosition;
  * the Earth-Moon centre distance in kilometres.
  */
 export declare function moonPosition(time: Date): MoonPosition;
+/**
+ * Apparent geocentric position of a fixed star from its J2000 (ICRS) catalog
+ * right ascension and declination, both in degrees — right ascension and
+ * declination on the true equator and equinox of date, with annual
+ * aberration, precession and nutation applied. Proper motion and stellar
+ * parallax are not applied.
+ *
+ * UPSTREAM: `Equator(star, date, observer, ofdate=true, aberration=true)`
+ * (astronomy.ts ~2803) with the geocentric observer term dropped.
+ */
+export declare function starPosition(raDeg: number, decDeg: number, time: Date): StarPosition;
 /**
  * INTERNAL: equation of time for a TT instant, in minutes. Not from upstream:
  * Meeus, *Astronomical Algorithms*, formula 28.1, `E = L0 − 0.0057183° − α +

package/dist/positions.js

@@ -1,5 +1,5 @@
-// L1 public positions: apparent geocentric Sun and Moon on the true equator and
-// equinox of date.
+// L1 public positions: apparent geocentric Sun, Moon and fixed stars on the true
+// equator and equinox of date.
 //
 // The composition chain mirrors the cosinekitty/astronomy upstream (pinned sha
 // 865d3da7d8112bbc7911238052c6af4aaf877181):
@@ -13,9 +13,10 @@
 // parallax subtraction) is zero and drops out.
 import { assertSupported } from './types.js';
 import { ttDays } from './time.js';
-import { DEG2RAD, KM_PER_AU, earthTilt, equatorialFromVector } from './nutation.js';
+import { DEG2RAD, KM_PER_AU, PrecessDirection, earthTilt, equatorialFromVector, gyration } from './nutation.js';
 import { moonGeoVector } from './moon.js';
 import { sunGeoVector } from './sun.js';
+import { assertStarCatalog, starGeoVectorEqj } from './transforms.js';
 /**
  * INTERNAL: apparent Sun for a TT instant, expressed as days since the J2000
  * epoch in Terrestrial Time. This is the entry point the TT-labeled position
@@ -50,6 +51,23 @@ export function moonPosition(time) {
     assertSupported(time);
     return moonApparentAtTT(ttDays(time));
 }
+/**
+ * Apparent geocentric position of a fixed star from its J2000 (ICRS) catalog
+ * right ascension and declination, both in degrees — right ascension and
+ * declination on the true equator and equinox of date, with annual
+ * aberration, precession and nutation applied. Proper motion and stellar
+ * parallax are not applied.
+ *
+ * UPSTREAM: `Equator(star, date, observer, ofdate=true, aberration=true)`
+ * (astronomy.ts ~2803) with the geocentric observer term dropped.
+ */
+export function starPosition(raDeg, decDeg, time) {
+    assertSupported(time);
+    assertStarCatalog(raDeg, decDeg);
+    const tt = ttDays(time);
+    const { raDeg: ra, decDeg: dec } = equatorialFromVector(gyration(starGeoVectorEqj(raDeg, decDeg, tt), tt, PrecessDirection.From2000));
+    return { raDeg: ra, decDeg: dec };
+}
 /**
  * INTERNAL: equation of time for a TT instant, in minutes. Not from upstream:
  * Meeus, *Astronomical Algorithms*, formula 28.1, `E = L0 − 0.0057183° − α +

package/dist/sun.d.ts

@@ -11,11 +11,24 @@ export declare const vsopEarth: VsopModel;
 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;
+export declare function earthHelioDistance(tt: number): number;
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).
  */
 export declare function earthHelioVector(tt: number): Vec3;
+/** Heliocentric position in AU and velocity in AU per day, J2000 mean equator (EQJ). */
+export interface HelioState {
+    pos: Vec3;
+    vel: Vec3;
+}
+/**
+ * UPSTREAM: `CalcVsopPosVel`, astronomy.ts lines 3264-3314, specialised to
+ * `vsop.Earth` — i.e. `HelioState(Body.Earth, time)`. Not upstream: a
+ * one-entry cache on the exact instant, because a star catalog drawn for one
+ * moment asks for the same Earth state once per star.
+ */
+export declare function earthHelioState(tt: number): HelioState;
 /**
  * UPSTREAM: `CorrectLightTravel` (astronomy.ts 4170-4191) driving
  * `BodyPosition.Position` (4193-4241) with observerBody = Earth,

package/dist/sun.js

@@ -223,6 +223,8 @@ export function vsopSphereToRect(lon, lat, radius) {
         z: radius * Math.sin(lat)
     };
 }
+// UPSTREAM: HelioDistance(Body.Earth), the scalar VSOP radius without rotations.
+export function earthHelioDistance(tt) { return earthRad(tt / 365250); }
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).
@@ -235,6 +237,75 @@ export function earthHelioVector(tt) {
     const eclip = vsopSphereToRect(lon, lat, rad);
     return vsopRotate(eclip);
 }
+/**
+ * UPSTREAM: `VsopDeriv`, astronomy.ts lines 3207-3227 — the time derivative
+ * of a VSOP series, per millennium. It loops over the table rather than
+ * unrolling like `earthLon`: only the star path needs it, once per call.
+ */
+function vsopDeriv(formula, t) {
+    let tpower = 1; // t^s
+    let dpower = 0; // t^(s-1)
+    let deriv = 0;
+    let s = 0;
+    for (const series of formula) {
+        let sin_sum = 0;
+        let cos_sum = 0;
+        for (const [ampl, phas, freq] of series) {
+            const angle = phas + (t * freq);
+            sin_sum += ampl * freq * Math.sin(angle);
+            if (s > 0)
+                cos_sum += ampl * Math.cos(angle);
+        }
+        deriv += (s * dpower * cos_sum) - (tpower * sin_sum);
+        dpower = tpower;
+        tpower *= t;
+        ++s;
+    }
+    return deriv;
+}
+let cacheEarthState;
+let cacheEarthStateTt = NaN;
+/**
+ * UPSTREAM: `CalcVsopPosVel`, astronomy.ts lines 3264-3314, specialised to
+ * `vsop.Earth` — i.e. `HelioState(Body.Earth, time)`. Not upstream: a
+ * one-entry cache on the exact instant, because a star catalog drawn for one
+ * moment asks for the same Earth state once per star.
+ */
+export function earthHelioState(tt) {
+    if (!cacheEarthState || cacheEarthStateTt !== tt) {
+        cacheEarthState = computeEarthHelioState(tt);
+        cacheEarthStateTt = tt;
+    }
+    return cacheEarthState;
+}
+function computeEarthHelioState(tt) {
+    const t = tt / DAYS_PER_MILLENNIUM;
+    const lon = earthLon(t);
+    const lat = earthLat(t);
+    const rad = earthRad(t);
+    const dlon_dt = vsopDeriv(vsopEarth[0], t);
+    const dlat_dt = vsopDeriv(vsopEarth[1], t);
+    const drad_dt = vsopDeriv(vsopEarth[2], t);
+    const coslon = Math.cos(lon);
+    const sinlon = Math.sin(lon);
+    const coslat = Math.cos(lat);
+    const sinlat = Math.sin(lat);
+    const vx = (+(drad_dt * coslat * coslon)
+        - (rad * sinlat * coslon * dlat_dt)
+        - (rad * coslat * sinlon * dlon_dt));
+    const vy = (+(drad_dt * coslat * sinlon)
+        - (rad * sinlat * sinlon * dlat_dt)
+        + (rad * coslat * coslon * dlon_dt));
+    const vz = (+(drad_dt * sinlat)
+        + (rad * coslat * dlat_dt));
+    // AU per millennium to AU per day.
+    const eclipVel = {
+        x: vx / DAYS_PER_MILLENNIUM,
+        y: vy / DAYS_PER_MILLENNIUM,
+        z: vz / DAYS_PER_MILLENNIUM
+    };
+    return { pos: vsopRotate(vsopSphereToRect(lon, lat, rad)), vel: vsopRotate(eclipVel) };
+}
 /**
  * UPSTREAM: `CorrectLightTravel` (astronomy.ts 4170-4191) driving
  * `BodyPosition.Position` (4193-4241) with observerBody = Earth,

package/dist/transforms.d.ts

@@ -72,15 +72,35 @@ export declare function sunAltAz(time: Date, observer: Observer): AltAz;
  * refraction (upstream `'normal'` model) both applied.
  */
 export declare function moonAltAz(time: Date, observer: Observer): AltAz;
+/** INTERNAL: shared argument checks for the J2000 catalog position the star functions take. */
+export declare function assertStarCatalog(raDeg: number, decDeg: number): void;
+/**
+ * UPSTREAM: `GeoVector` for a `DefineStar` body with aberration = true —
+ * `HelioVector`'s `VectorFromSphere(Spherical(dec, 15*ra, dist))`
+ * (astronomy.ts ~4097, 7015) through the user-defined-star branch of
+ * `BackdatePosition` (4270-4300). The star is not backdated; the vector from
+ * Earth to the star is shifted by Earth's heliocentric velocity over the
+ * light travel time, which is the annual aberration, at most 20.5″.
+ *
+ * @returns geocentric position in AU, J2000 mean equator (EQJ).
+ */
+export declare function starGeoVectorEqj(raDeg: number, decDeg: number, tt: number): Vec3;
 /**
  * Topocentric azimuth/altitude of a fixed star from its J2000 (ICRS)
  * catalog right ascension and declination, both in degrees.
  *
- * Applied: precession and nutation to the equator of date, Greenwich
- * apparent sidereal time, and atmospheric refraction (upstream `'normal'`
- * model, the same as sunAltAz/moonAltAz). Not applied: annual aberration
- * (at most 20.5″ — see the roadmap), proper motion (pass catalog
- * coordinates; fast movers such as Arcturus drift ~1′ in 26 years), and
- * stellar parallax (negligible at the 1000 ly the star is placed at).
+ * Applied: annual aberration, precession and nutation to the equator of
+ * date, Greenwich apparent sidereal time, and atmospheric refraction
+ * (upstream `'normal'` model, the same as sunAltAz/moonAltAz). Not applied:
+ * proper motion (pass catalog coordinates; fast movers such as Arcturus
+ * drift ~1′ in 26 years) and stellar parallax (negligible at the 1000 ly the
+ * star is placed at).
  */
 export declare function starAltAz(raDeg: number, decDeg: number, time: Date, observer: Observer): AltAz;
+/**
+ * Greenwich apparent sidereal time in degrees, [0, 360): the hour angle of
+ * the true equinox of date at Greenwich, including the equation of the
+ * equinoxes. A body's Greenwich hour angle is this minus its right ascension
+ * of date.
+ */
+export declare function greenwichSiderealTime(time: Date): number;

package/dist/transforms.js

@@ -13,20 +13,17 @@
 //   refinement since this layer only needs az/alt; Refraction 'normal' (~7176).
 //
 // INTERNAL: not part of the curated public API (see index.ts) except
-// sunAltAz/moonAltAz.
+// sunAltAz, moonAltAz, starAltAz and greenwichSiderealTime.
 import { assertObserver, assertSupported } from './types.js';
 import { ttDaysFromUt, utDays } from './time.js';
-import { DEG2RAD, RAD2DEG, EARTH_EQUATORIAL_RADIUS_KM, EARTH_FLATTENING, EARTH_FLATTENING_SQUARED, KM_PER_AU, PrecessDirection, earthTilt, equatorialFromVector, gyration } from './nutation.js';
-import { sunGeoVectorEqj } from './sun.js';
+import { C_AUDAY, DEG2RAD, RAD2DEG, EARTH_EQUATORIAL_RADIUS_KM, EARTH_FLATTENING, EARTH_FLATTENING_SQUARED, KM_PER_AU, PrecessDirection, earthTilt, equatorialFromVector, gyration, wrapDeg360 } from './nutation.js';
+import { earthHelioState, sunGeoVectorEqj } from './sun.js';
 import { moonGeoVectorEqj } from './moon.js';
 /** UPSTREAM: `era` (Earth Rotation Angle), astronomy.ts ~2014. */
 function earthRotationAngleDeg(ut) {
     const thet1 = 0.7790572732640 + 0.00273781191135448 * ut;
     const thet3 = ut % 1;
-    let theta = 360 * ((thet1 + thet3) % 1);
-    if (theta < 0)
-        theta += 360;
-    return theta;
+    return wrapDeg360(360 * ((thet1 + thet3) % 1));
 }
 /**
  * UPSTREAM: `sidereal_time`, astronomy.ts ~2031 — Greenwich Apparent Sidereal
@@ -46,10 +43,7 @@ export function siderealDeg(ut) {
             - 0.00000044) * t
             + 1.3915817) * t
             + 4612.156534) * t;
-    let gastDeg = (st / 3600 + theta) % 360;
-    if (gastDeg < 0)
-        gastDeg += 360;
-    return gastDeg;
+    return wrapDeg360(st / 3600 + theta);
 }
 /**
  * UPSTREAM: `terra` (astronomy.ts ~2147 — position only; its velocity output
@@ -149,17 +143,13 @@ export function topoAltAzUnrefracted(bodyEqj, ut, observer) {
     const proj = Math.hypot(pn, pw);
     let az;
     if (proj > 0) {
-        az = -RAD2DEG * Math.atan2(pw, pn);
-        if (az < 0)
-            az += 360;
+        az = wrapDeg360(-RAD2DEG * Math.atan2(pw, pn));
     }
     else {
         az = 0;
     }
     const zd = RAD2DEG * Math.atan2(proj, pz);
-    let hourAngleDeg = (gast + observer.longitudeDeg - raDeg) % 360;
-    if (hourAngleDeg < 0)
-        hourAngleDeg += 360;
+    const hourAngleDeg = wrapDeg360(gast + observer.longitudeDeg - raDeg);
     return { azDeg: az, altDeg: 90 - zd, hourAngleDeg, distanceAu, raDeg, decDeg };
 }
 /**
@@ -208,40 +198,64 @@ export function moonAltAz(time, observer) {
     return refract(topoAltAzUnrefracted(moonGeoVectorEqj(ttDaysFromUt(ut)), ut, observer));
 }
 /**
- * UPSTREAM: the user-defined star path — `HelioVector` for a `DefineStar`
- * body (astronomy.ts ~4097: `VectorFromSphere(Spherical(dec, 15*ra, dist))`)
- * into `Equator(body, date, observer, ofdate=true, aberration=false)` (~2803)
- * and `Horizon` (~2565): the same topocentric path sunAltAz/moonAltAz take.
  * Upstream floors a star's distance at 1 light-year and suggests 1000 when
  * unknown; the star sits at 1000 ly here (`AU_PER_LY`, astronomy.ts line 52).
- * Upstream's geocentric step (star vector minus Earth's heliocentric
- * position) is skipped: at 1000 ly it moves the star 0.003″.
  */
 const STAR_DISTANCE_AU = 1000 * 63241.07708807546;
-/**
- * Topocentric azimuth/altitude of a fixed star from its J2000 (ICRS)
- * catalog right ascension and declination, both in degrees.
- *
- * Applied: precession and nutation to the equator of date, Greenwich
- * apparent sidereal time, and atmospheric refraction (upstream `'normal'`
- * model, the same as sunAltAz/moonAltAz). Not applied: annual aberration
- * (at most 20.5″ — see the roadmap), proper motion (pass catalog
- * coordinates; fast movers such as Arcturus drift ~1′ in 26 years), and
- * stellar parallax (negligible at the 1000 ly the star is placed at).
- */
-export function starAltAz(raDeg, decDeg, time, observer) {
-    assertSupported(time);
-    assertObserver(observer);
+/** INTERNAL: shared argument checks for the J2000 catalog position the star functions take. */
+export function assertStarCatalog(raDeg, decDeg) {
     if (!(raDeg >= 0 && raDeg < 360))
         throw new RangeError(`raDeg out of range: ${raDeg}`);
     if (!(decDeg >= -90 && decDeg <= 90))
         throw new RangeError(`decDeg out of range: ${decDeg}`);
-    const ut = utDays(time);
+}
+/**
+ * UPSTREAM: `GeoVector` for a `DefineStar` body with aberration = true —
+ * `HelioVector`'s `VectorFromSphere(Spherical(dec, 15*ra, dist))`
+ * (astronomy.ts ~4097, 7015) through the user-defined-star branch of
+ * `BackdatePosition` (4270-4300). The star is not backdated; the vector from
+ * Earth to the star is shifted by Earth's heliocentric velocity over the
+ * light travel time, which is the annual aberration, at most 20.5″.
+ *
+ * @returns geocentric position in AU, J2000 mean equator (EQJ).
+ */
+export function starGeoVectorEqj(raDeg, decDeg, tt) {
     const rCosDec = STAR_DISTANCE_AU * Math.cos(decDeg * DEG2RAD);
-    const eqj = {
+    const tvec = {
         x: rCosDec * Math.cos(raDeg * DEG2RAD),
         y: rCosDec * Math.sin(raDeg * DEG2RAD),
         z: STAR_DISTANCE_AU * Math.sin(decDeg * DEG2RAD),
     };
-    return refract(topoAltAzUnrefracted(eqj, ut, observer));
+    const ostate = earthHelioState(tt);
+    const rvec = { x: tvec.x - ostate.pos.x, y: tvec.y - ostate.pos.y, z: tvec.z - ostate.pos.z };
+    const s = C_AUDAY / Math.sqrt(rvec.x * rvec.x + rvec.y * rvec.y + rvec.z * rvec.z);
+    return { x: rvec.x + ostate.vel.x / s, y: rvec.y + ostate.vel.y / s, z: rvec.z + ostate.vel.z / s };
+}
+/**
+ * Topocentric azimuth/altitude of a fixed star from its J2000 (ICRS)
+ * catalog right ascension and declination, both in degrees.
+ *
+ * Applied: annual aberration, precession and nutation to the equator of
+ * date, Greenwich apparent sidereal time, and atmospheric refraction
+ * (upstream `'normal'` model, the same as sunAltAz/moonAltAz). Not applied:
+ * proper motion (pass catalog coordinates; fast movers such as Arcturus
+ * drift ~1′ in 26 years) and stellar parallax (negligible at the 1000 ly the
+ * star is placed at).
+ */
+export function starAltAz(raDeg, decDeg, time, observer) {
+    assertSupported(time);
+    assertObserver(observer);
+    assertStarCatalog(raDeg, decDeg);
+    const ut = utDays(time);
+    return refract(topoAltAzUnrefracted(starGeoVectorEqj(raDeg, decDeg, ttDaysFromUt(ut)), ut, observer));
+}
+/**
+ * Greenwich apparent sidereal time in degrees, [0, 360): the hour angle of
+ * the true equinox of date at Greenwich, including the equation of the
+ * equinoxes. A body's Greenwich hour angle is this minus its right ascension
+ * of date.
+ */
+export function greenwichSiderealTime(time) {
+    assertSupported(time);
+    return siderealDeg(utDays(time));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {