@openwaters/almanac 0.2.1 → 0.3.0

package/README.md

@@ -1,8 +1,9 @@
 # Almanac
 
 Offline sun & moon engine for the Salish Sea and everywhere else — positions,
-rise/set/twilight, moon phase, and lunar eclipses (solar planned), computed from pure
-geometry with zero network and zero runtime data files.
+rise/set/twilight, moon phase, lunar eclipses (solar planned), and where any fixed
+star stands from a catalog position, computed from pure geometry with zero network
+and zero runtime data files.
 
 Twin implementations, one behavior:
 
@@ -73,7 +74,7 @@ npm install @openwaters/almanac
 ```
 
 ```ts
-import { nextLunarEclipse, lunarEclipseVisibility, sunEvents } from '@openwaters/almanac';
+import { nextLunarEclipse, lunarEclipseVisibility, sunEvents, starAltAz } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
 
@@ -86,12 +87,15 @@ const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
 for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
   console.log(kind, time.toISOString());
 }
+
+// Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
+const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ```
 
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.2.1")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.3.0")
 ```
 
 ```swift
@@ -109,6 +113,9 @@ let tomorrow = today.addingTimeInterval(24 * 60 * 60)
 for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
   print(event.kind, event.time)
 }
+
+// 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)
 ```
 
 ### Eclipse searches

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { AlmanacOutOfRangeError } from './types.js';
 export type { SunPosition, MoonPosition } from './positions.js';
 export { sunPosition, moonPosition } from './positions.js';
 export type { AltAz } from './transforms.js';
-export { sunAltAz, moonAltAz } from './transforms.js';
+export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export type { MoonIllumination } from './illumination.js';
 export { moonIllumination } from './illumination.js';
 export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName } from './events.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { AlmanacOutOfRangeError } from './types.js';
 export { sunPosition, moonPosition } from './positions.js';
-export { sunAltAz, moonAltAz } from './transforms.js';
+export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination } from './illumination.js';
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';

package/dist/transforms.d.ts

@@ -59,3 +59,15 @@ export declare function sunAltAz(time: Date, observer: Observer): AltAz;
  * refraction (upstream `'normal'` model) both applied.
  */
 export declare function moonAltAz(time: Date, observer: Observer): AltAz;
+/**
+ * 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 declare function starAltAz(raDeg: number, decDeg: number, time: Date, observer: Observer): AltAz;

package/dist/transforms.js

@@ -196,3 +196,41 @@ export function moonAltAz(time, observer) {
     const ut = utDays(time);
     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);
+    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);
+    const rCosDec = STAR_DISTANCE_AU * Math.cos(decDeg * DEG2RAD);
+    const eqj = {
+        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));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar eclipses.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/openwatersio/almanac.git", "directory": "typescript" },