caelus 0.9.0 → 0.10.0

package/dist/src/astrocartography.d.ts

@@ -0,0 +1,16 @@
+import { Engine, BodyId } from "./chart.js";
+export interface AngleLines {
+    /** MC meridian longitude (culmination). */
+    mc: number;
+    /** IC meridian longitude (anti-culmination). */
+    ic: number;
+    /** Rising track, [lon, lat] points over the latitude band. */
+    asc: [number, number][];
+    /** Setting track, [lon, lat] points. */
+    dsc: [number, number][];
+}
+/** Angle lines for one body at right ascension/declination (degrees) and a
+ *  Greenwich apparent sidereal time (degrees). */
+export declare function planetLines(ra: number, dec: number, gastDeg: number, latMin?: number, latMax?: number, latStep?: number): AngleLines;
+/** Angle lines for each body at jdUt: { body: AngleLines }. */
+export declare function astrocartography(engine: Engine, jdUt: number, bodies: BodyId[], latMin?: number, latMax?: number, latStep?: number): Record<string, AngleLines>;

package/dist/src/astrocartography.js

@@ -0,0 +1,47 @@
+/**
+ * astroengine astrocartography -- planetary angle lines across the globe.
+ *
+ * For one moment, each planet is exactly on an angle along a curve on the
+ * Earth's surface: MC and IC are meridians (culmination / anti-culmination),
+ * ASC and DSC are the curved rising / setting tracks. Geometry from each body's
+ * right ascension and declination and the moment's Greenwich apparent sidereal
+ * time. Mirrors the Python reference (astroengine/astrocartography.py); the
+ * golden pins the two.
+ */
+import { DEG } from "./core.js";
+import { gast } from "./houses.js";
+/** Wrap a longitude to (-180, 180], east positive. */
+function mapLon(deg) {
+    const d = ((deg % 360) + 360) % 360;
+    return d > 180 ? d - 360 : d;
+}
+/** Angle lines for one body at right ascension/declination (degrees) and a
+ *  Greenwich apparent sidereal time (degrees). */
+export function planetLines(ra, dec, gastDeg, latMin = -85.0, latMax = 85.0, latStep = 1.0) {
+    const mc = mapLon(ra - gastDeg);
+    const ic = mapLon(ra - gastDeg - 180.0);
+    const td = Math.tan(dec * DEG);
+    const asc = [];
+    const dsc = [];
+    const n = Math.floor((latMax - latMin) / latStep + 1e-9); // never exceed latMax
+    for (let i = 0; i <= n; i++) {
+        const phi = latMin + i * latStep;
+        const x = -Math.tan(phi * DEG) * td;
+        if (x >= -1.0 && x <= 1.0) {
+            const h0 = Math.acos(x) / DEG; // hour-angle half-width, degrees
+            asc.push([mapLon(ra - h0 - gastDeg), phi]); // eastern horizon
+            dsc.push([mapLon(ra + h0 - gastDeg), phi]); // western horizon
+        }
+    }
+    return { mc, ic, asc, dsc };
+}
+/** Angle lines for each body at jdUt: { body: AngleLines }. */
+export function astrocartography(engine, jdUt, bodies, latMin = -85.0, latMax = 85.0, latStep = 1.0) {
+    const g = gast(engine.data, jdUt) / DEG; // Greenwich apparent sidereal time, deg
+    const out = {};
+    for (const b of bodies) {
+        const p = engine.position(b, jdUt);
+        out[b] = planetLines(p.ra, p.dec, g, latMin, latMax, latStep);
+    }
+    return out;
+}

package/dist/src/ephemeris.d.ts

@@ -0,0 +1,27 @@
+/**
+ * astroengine ephemeris -- a time series of one value per body over a range, the
+ * data behind a graphic ephemeris. A thin collector over the validated
+ * positions (longitude, latitude, declination, right ascension, or speed), so
+ * there is no new math here; the underlying values are the ones the conformance
+ * suite already pins. Pair it with caelus-wheel's EphemerisGraph to draw it.
+ */
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export type EphemerisValue = "longitude" | "latitude" | "declination" | "rightAscension" | "speed";
+export interface EphemerisOptions {
+    /** First instant, UT Julian Day (inclusive). */
+    start: number;
+    /** Last instant, UT Julian Day (inclusive). */
+    end: number;
+    /** Spacing between samples, days. Must be positive. */
+    step: number;
+    /** Which quantity to sample (default longitude). */
+    value?: EphemerisValue;
+    zodiac?: Zodiac;
+}
+export interface EphemerisPoint {
+    jd: number;
+    value: number;
+}
+/** Sample `value` for each body across [start, end], returning per-body series
+ *  in time order. */
+export declare function ephemeris(engine: Engine, bodies: BodyId[], opts: EphemerisOptions): Record<string, EphemerisPoint[]>;

package/dist/src/ephemeris.js

@@ -0,0 +1,30 @@
+/** Sample `value` for each body across [start, end], returning per-body series
+ *  in time order. */
+export function ephemeris(engine, bodies, opts) {
+    if (opts.step <= 0)
+        throw new Error("ephemeris step must be positive");
+    const value = opts.value ?? "longitude";
+    const zodiac = opts.zodiac ?? "tropical";
+    const out = {};
+    for (const b of bodies)
+        out[b] = [];
+    const total = Math.floor((opts.end - opts.start) / opts.step + 1e-9) + 1;
+    for (let i = 0; i < total; i++) {
+        const jd = opts.start + i * opts.step;
+        for (const b of bodies) {
+            let v;
+            if (value === "longitude") {
+                v = engine.longitude(b, jd, { zodiac });
+            }
+            else {
+                const p = engine.position(b, jd, { zodiac });
+                v = value === "latitude" ? p.lat
+                    : value === "declination" ? p.dec
+                        : value === "rightAscension" ? p.ra
+                            : p.speed;
+            }
+            out[b].push({ jd, value: v });
+        }
+    }
+    return out;
+}

package/dist/src/index.d.ts

@@ -10,3 +10,6 @@ export * from "./derived.js";
 export * from "./turbo.js";
 export * from "./electional.js";
 export * from "./scan.js";
+export * from "./spherical.js";
+export * from "./astrocartography.js";
+export * from "./ephemeris.js";

package/dist/src/index.js

@@ -10,3 +10,6 @@ export * from "./derived.js";
 export * from "./turbo.js";
 export * from "./electional.js";
 export * from "./scan.js";
+export * from "./spherical.js";
+export * from "./astrocartography.js";
+export * from "./ephemeris.js";

package/dist/src/spherical.d.ts

@@ -0,0 +1,8 @@
+export type Vec3 = [number, number, number];
+/** Unit vector on the sphere for an (ecliptic longitude, latitude) pair, in the
+ *  ecliptic frame: x toward 0 Aries, z toward the north ecliptic pole. */
+export declare function unitVector(lonDeg: number, latDeg: number): Vec3;
+/** True great-circle angle (degrees) between two bodies from their ecliptic
+ *  longitude and latitude. With both latitudes zero this is the unsigned
+ *  longitude difference; latitude pulls the two apart in three dimensions. */
+export declare function angularSeparation3d(lonA: number, latA: number, lonB: number, latB: number): number;

package/dist/src/spherical.js

@@ -0,0 +1,28 @@
+/**
+ * astroengine spherical -- spherical-geometry primitives for 3D chart views.
+ *
+ * A body sits at a point on the celestial sphere, not just a zodiac longitude.
+ * `unitVector` gives the direction for an (ecliptic longitude, latitude) pair;
+ * `angularSeparation3d` gives the true great-circle angle between two bodies,
+ * which is the basis for 3D aspects (the separation in space, accounting for
+ * ecliptic latitude, rather than the 2D longitude difference). Mirrors the
+ * Python reference (astroengine/spherical.py); the golden pins the two.
+ */
+import { DEG } from "./core.js";
+/** Unit vector on the sphere for an (ecliptic longitude, latitude) pair, in the
+ *  ecliptic frame: x toward 0 Aries, z toward the north ecliptic pole. */
+export function unitVector(lonDeg, latDeg) {
+    const lam = lonDeg * DEG;
+    const beta = latDeg * DEG;
+    const cb = Math.cos(beta);
+    return [cb * Math.cos(lam), cb * Math.sin(lam), Math.sin(beta)];
+}
+/** True great-circle angle (degrees) between two bodies from their ecliptic
+ *  longitude and latitude. With both latitudes zero this is the unsigned
+ *  longitude difference; latitude pulls the two apart in three dimensions. */
+export function angularSeparation3d(lonA, latA, lonB, latB) {
+    const [ax, ay, az] = unitVector(lonA, latA);
+    const [bx, by, bz] = unitVector(lonB, latB);
+    const dot = Math.max(-1, Math.min(1, ax * bx + ay * by + az * bz));
+    return Math.acos(dot) / DEG;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Astrological ephemeris engine. MIT, no AGPL, no ephemeris files. Checked against Swiss Ephemeris.",
   "type": "module",
   "main": "dist/src/index.js",