@johnmorrisdotca/hoshi-stars 0.0.0-stage → 0.2.0

package/dist/projection.js

@@ -0,0 +1,284 @@
+// Map projections of the celestial sphere for drawing star charts: stereographic, orthographic, gnomonic, azimuthal equidistant, equirectangular, Mollweide and Hammer-Aitoff.
+// Pure maths, no DOM and no dependencies. The formulas are written from J. P. Snyder, "Map Projections: A Working Manual", U.S. Geological Survey Professional Paper 1395 (1987, public domain):
+// the azimuthal family in chapters 20 to 22 and 25, the cylindrical one in chapter 12, Mollweide in chapter 31 and Hammer in chapter 24 (on the unit sphere, with the centre as the origin).
+// The sky is a sphere seen from inside, so the default puts east on the LEFT (right ascension grows toward the left); `mirror: true` gives the map convention with east on the right.
+/**
+ * The projections: the five that show a hemisphere or less, then the two that show the whole sky.
+ *
+ * @example
+ * ```ts
+ * import { PROJECTIONS } from "@johnmorrisdotca/hoshi-stars/projection";
+ *
+ * console.log(PROJECTIONS.join(", "));
+ * ```
+ */
+export const PROJECTIONS = ["stereographic", "orthographic", "gnomonic", "equidistant", "equirectangular", "mollweide", "hammer"];
+const RAD = Math.PI / 180;
+const DEG = 180 / Math.PI;
+const TWO_PI = 2 * Math.PI;
+const SQRT2 = Math.SQRT2;
+// A hair of slack so a point exactly on the edge (90 degrees, the oval's rim) is not lost to rounding.
+const EDGE = 1e-12;
+function finite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new RangeError(`${name} must be a finite number, got ${String(value)}`);
+    return value;
+}
+function sky(name, point) {
+    if (typeof point !== "object" || point === null)
+        throw new TypeError(`${name} must be an object with rightAscension and declination, got ${String(point)}`);
+    const p = point;
+    finite(`${name}.rightAscension`, p.rightAscension);
+    const declination = finite(`${name}.declination`, p.declination);
+    if (declination < -90 || declination > 90)
+        throw new RangeError(`${name}.declination must be between -90 and 90 degrees, got ${declination}`);
+    return p;
+}
+function setup(kind, options) {
+    if (!PROJECTIONS.includes(kind))
+        throw new RangeError(`kind must be one of ${PROJECTIONS.map((k) => `"${k}"`).join(", ")}, got "${String(kind)}"`);
+    if (typeof options !== "object" || options === null)
+        throw new TypeError(`options must be an object with a centre, got ${String(options)}`);
+    const centre = sky("options.centre", options.centre);
+    const scale = options.scale === undefined ? 1 : finite("options.scale", options.scale);
+    if (scale <= 0)
+        throw new RangeError(`options.scale must be greater than 0, got ${scale}`);
+    const rotation = options.rotation === undefined ? 0 : finite("options.rotation", options.rotation) * RAD;
+    const dec0 = centre.declination * RAD;
+    return {
+        ra0: centre.rightAscension * RAD,
+        sinD0: Math.sin(dec0),
+        cosD0: Math.cos(dec0),
+        dec0,
+        scale,
+        sinR: Math.sin(rotation),
+        cosR: Math.cos(rotation),
+        rotated: rotation !== 0,
+        mirror: options.mirror === true,
+    };
+}
+/** An angle in radians brought to -pi up to pi. */
+function wrapPi(angle) {
+    return angle - TWO_PI * Math.round(angle / TWO_PI);
+}
+/** Mollweide's auxiliary angle: with t = 2 theta, t + sin t = pi sin(latitude), by Newton's method (Snyder 31). */
+function mollweideAngle(latitude) {
+    const target = Math.PI * Math.sin(latitude);
+    const sign = target < 0 ? -1 : 1;
+    const wanted = Math.abs(target);
+    if (wanted >= Math.PI - 1e-15)
+        return sign * Math.PI;
+    // Near a pole the root is a triple one, so start from its cube-root form there; elsewhere the latitude doubled is close.
+    let t = wanted > 2.9 ? Math.PI - Math.cbrt(6 * (Math.PI - wanted)) : 2 * Math.abs(latitude);
+    for (let i = 0; i < 60; i += 1) {
+        const step = (t + Math.sin(t) - wanted) / (1 + Math.cos(t));
+        t -= step;
+        if (Math.abs(step) < 1e-15)
+            break;
+    }
+    return sign * t;
+}
+/**
+ * Where a point of the sky lands on the chart.
+ *
+ * With the default `mirror: false` the chart is the sky seen looking up: north is up and east is to the LEFT, so `x` grows toward decreasing right ascension. Set `mirror: true` for the map convention (east right).
+ * `y` grows toward the north (up the chart).
+ *
+ * @param kind - The projection.
+ * @param point - The sky position in degrees (`rightAscension` wraps at 360; `declination` is -90 to 90).
+ * @param options - The `centre` that lands at (0, 0), and optionally `scale`, `rotation` and `mirror`.
+ * @returns The point on the chart, or `undefined` when the sky position is not on the visible side: the far hemisphere of `orthographic` and `gnomonic` (90 degrees or more from the centre for `gnomonic`), and the antipode of the centre for `stereographic`.
+ * @throws RangeError if `kind` is unknown, or a number is not finite, or a declination is outside -90 to 90, or `scale` is not above 0.
+ *
+ * @example
+ * ```ts
+ * import { project } from "@johnmorrisdotca/hoshi-stars/projection";
+ *
+ * const orion = { centre: { rightAscension: 83.8, declination: -5.4 }, scale: 300 };
+ * const betelgeuse = project("stereographic", { rightAscension: 88.79, declination: 7.41 }, orion);
+ * console.log(betelgeuse); // left of the middle (it is east of the centre) and above it
+ * ```
+ */
+export function project(kind, point, options) {
+    const o = setup(kind, options);
+    sky("point", point);
+    const dec = point.declination * RAD;
+    const dl = wrapPi(point.rightAscension * RAD - o.ra0);
+    // X is east-positive on the unit sphere, Y is north-positive.
+    let X;
+    let Y;
+    if (kind === "equirectangular") {
+        X = dl;
+        Y = dec - o.dec0;
+    }
+    else {
+        const sinD = Math.sin(dec);
+        const cosD = Math.cos(dec);
+        const cosDl = Math.cos(dl);
+        // The point in the frame of the centre: u toward the centre, e toward the east, n toward the north.
+        const u = o.sinD0 * sinD + o.cosD0 * cosD * cosDl;
+        const e = cosD * Math.sin(dl);
+        const n = o.cosD0 * sinD - o.sinD0 * cosD * cosDl;
+        let k;
+        switch (kind) {
+            case "orthographic":
+                if (u < -EDGE)
+                    return undefined;
+                k = 1;
+                break;
+            case "stereographic":
+                if (1 + u < EDGE)
+                    return undefined;
+                k = 2 / (1 + u);
+                break;
+            case "gnomonic":
+                if (u <= EDGE)
+                    return undefined;
+                k = 1 / u;
+                break;
+            case "equidistant": {
+                const s = Math.hypot(e, n);
+                if (s < 1e-300) {
+                    if (u < 0)
+                        return finish(o, Math.PI, 0);
+                    k = 1;
+                }
+                else {
+                    k = Math.atan2(s, u) / s;
+                }
+                break;
+            }
+            case "mollweide": {
+                const lambda = Math.atan2(e, u);
+                const t = mollweideAngle(Math.atan2(n, Math.hypot(e, u)));
+                return finish(o, ((2 * SQRT2) / Math.PI) * lambda * Math.cos(t / 2), SQRT2 * Math.sin(t / 2));
+            }
+            default: {
+                const lambda = Math.atan2(e, u);
+                const cosPhi = Math.hypot(e, u);
+                const d = Math.sqrt(1 + cosPhi * Math.cos(lambda / 2));
+                return finish(o, (2 * SQRT2 * cosPhi * Math.sin(lambda / 2)) / d, (SQRT2 * n) / d);
+            }
+        }
+        X = k * e;
+        Y = k * n;
+    }
+    return finish(o, X, Y);
+}
+/** Scales, applies east-left or `mirror`, and turns the chart: from east-positive unit-sphere coordinates to the answer. */
+function finish(o, X, Y) {
+    const x = (o.mirror ? X : -X) * o.scale;
+    const y = Y * o.scale;
+    // Adding zero turns -0 into 0, so the centre is exactly (0, 0).
+    if (!o.rotated)
+        return { x: x + 0, y: y + 0 };
+    return { x: x * o.cosR - y * o.sinR + 0, y: x * o.sinR + y * o.cosR + 0 };
+}
+/**
+ * The sky position under a point of the chart: the inverse of `project`, with the same `options`.
+ *
+ * @param kind - The projection.
+ * @param point - A point of the chart, in the same units and convention as `project` gives.
+ * @param options - The same options that drew the chart.
+ * @returns Right ascension (0 up to 360) and declination in degrees, or `undefined` when the point is outside the map: beyond the edge of the orthographic disc, the equidistant disc (radius pi times `scale`), the Mollweide and Hammer ovals, or the equirectangular rectangle.
+ * @throws RangeError if `kind` is unknown or a number is not finite.
+ *
+ * @example
+ * ```ts
+ * import { project, unproject } from "@johnmorrisdotca/hoshi-stars/projection";
+ *
+ * const options = { centre: { rightAscension: 279.2, declination: 38.8 }, scale: 200 };
+ * const spot = project("orthographic", { rightAscension: 290, declination: 45 }, options)!;
+ * console.log(unproject("orthographic", spot, options)); // { rightAscension: 290, declination: 45 }, to rounding
+ * ```
+ */
+export function unproject(kind, point, options) {
+    const o = setup(kind, options);
+    if (typeof point !== "object" || point === null)
+        throw new TypeError(`point must be an object with x and y, got ${String(point)}`);
+    finite("point.x", point.x);
+    finite("point.y", point.y);
+    // Undo the turn, then the mirror, then the scale, to east-positive unit-sphere coordinates.
+    const px = o.rotated ? point.x * o.cosR + point.y * o.sinR : point.x;
+    const py = o.rotated ? point.y * o.cosR - point.x * o.sinR : point.y;
+    const X = (o.mirror ? px : -px) / o.scale;
+    const Y = py / o.scale;
+    let u;
+    let e;
+    let n;
+    switch (kind) {
+        case "equirectangular": {
+            const declination = Y + o.dec0;
+            if (Math.abs(X) > Math.PI + EDGE || Math.abs(declination) > Math.PI / 2 + EDGE)
+                return undefined;
+            return answer(o.ra0 + X, Math.max(-Math.PI / 2, Math.min(Math.PI / 2, declination)));
+        }
+        case "mollweide": {
+            if ((X * X) / 8 + (Y * Y) / 2 > 1 + EDGE)
+                return undefined;
+            const s = Math.max(-1, Math.min(1, Y / SQRT2));
+            const cosT = Math.sqrt(1 - s * s);
+            // sin(latitude) = (2 theta + sin 2 theta) / pi, with 2 theta = 2 atan2(sin theta, cos theta)
+            const sinPhi = Math.max(-1, Math.min(1, (2 * Math.atan2(s, cosT) + 2 * s * cosT) / Math.PI));
+            const lambda = cosT < 1e-300 ? 0 : (Math.PI * X) / (2 * SQRT2 * cosT);
+            const cosPhi = Math.sqrt(1 - sinPhi * sinPhi);
+            u = cosPhi * Math.cos(lambda);
+            e = cosPhi * Math.sin(lambda);
+            n = sinPhi;
+            break;
+        }
+        case "hammer": {
+            if ((X * X) / 8 + (Y * Y) / 2 > 1 + EDGE)
+                return undefined;
+            const z2 = Math.max(0.5, 1 - (X * X) / 16 - (Y * Y) / 4);
+            const z = Math.sqrt(z2);
+            const lambda = 2 * Math.atan2(z * X, 2 * (2 * z2 - 1));
+            const sinPhi = Math.max(-1, Math.min(1, z * Y));
+            const cosPhi = Math.sqrt(1 - sinPhi * sinPhi);
+            u = cosPhi * Math.cos(lambda);
+            e = cosPhi * Math.sin(lambda);
+            n = sinPhi;
+            break;
+        }
+        default: {
+            const rho = Math.hypot(X, Y);
+            if (rho < 1e-300)
+                return answer(o.ra0, o.dec0);
+            let sinC;
+            let cosC;
+            if (kind === "orthographic") {
+                if (rho > 1 + EDGE)
+                    return undefined;
+                sinC = Math.min(rho, 1);
+                cosC = Math.sqrt(1 - sinC * sinC);
+            }
+            else if (kind === "stereographic") {
+                sinC = (4 * rho) / (4 + rho * rho);
+                cosC = (4 - rho * rho) / (4 + rho * rho);
+            }
+            else if (kind === "gnomonic") {
+                sinC = rho / Math.sqrt(1 + rho * rho);
+                cosC = 1 / Math.sqrt(1 + rho * rho);
+            }
+            else {
+                if (rho > Math.PI + EDGE)
+                    return undefined;
+                sinC = Math.sin(rho);
+                cosC = Math.cos(rho);
+            }
+            const f = sinC / rho;
+            u = cosC;
+            e = X * f;
+            n = Y * f;
+        }
+    }
+    const w = o.cosD0 * u - o.sinD0 * n;
+    return answer(o.ra0 + Math.atan2(e, w), Math.atan2(o.sinD0 * u + o.cosD0 * n, Math.hypot(e, w)));
+}
+/** Radians to degrees, with right ascension in 0 up to 360. */
+function answer(ra, dec) {
+    let rightAscension = (((ra * DEG) % 360) + 360) % 360;
+    if (rightAscension >= 360)
+        rightAscension = 0;
+    return { rightAscension, declination: dec * DEG };
+}

package/dist/sky.d.ts

@@ -0,0 +1,202 @@
+import { type When } from "./when.ts";
+import type { SkyPoint } from "./projection.ts";
+export type { SkyPoint };
+/**
+ * Where a star or a planet is in your sky: degrees above the horizon (negative below it) and degrees round from north through east.
+ *
+ * @example
+ * ```ts
+ * import type { Horizontal } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * const view: Horizontal = { altitude: 45, azimuth: 90 };
+ * console.log(view.altitude, view.azimuth); // 45 degrees up, due east
+ * ```
+ */
+export interface Horizontal {
+    /** Degrees above the horizon, -90 (straight down) to 90 (the zenith). Negative means below the horizon. */
+    altitude: number;
+    /** Degrees from north through east: 0 north, 90 east, 180 south, 270 west. 0 up to but not including 360; 0 at the zenith and nadir, where it has no meaning. */
+    azimuth: number;
+}
+/**
+ * Where you stand on Earth, in degrees.
+ *
+ * @example
+ * ```ts
+ * import type { Observer } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * const vancouver: Observer = { latitude: 49.28, longitude: -123.12 };
+ * console.log(vancouver.latitude);
+ * ```
+ */
+export interface Observer {
+    /** Degrees north of the equator, -90 to 90. */
+    latitude: number;
+    /** Degrees east of Greenwich (west is negative). Any finite number; it wraps at 360. */
+    longitude: number;
+    /** Metres above sea level; checked but not used, because a star is so far away that height changes its direction by nothing you could measure, and the horizon dip is left out. */
+    heightM?: number;
+}
+/**
+ * How to read the position and whether to bend the light.
+ *
+ * @example
+ * ```ts
+ * import type { HorizontalOptions } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * const options: HorizontalOptions = { refraction: true, pressureHpa: 900, temperatureC: -5 };
+ * console.log(options.refraction);
+ * ```
+ */
+export interface HorizontalOptions {
+    /** `"J2000"` (the default) when the position is a catalogue position, which is turned to the equinox of the date first; `"date"` when it is already the mean equator and equinox of the moment (planets are, from an almanac). */
+    equinox?: "J2000" | "date";
+    /** True to lift the altitude by the air's bending of light (Saemundsson's formula, Meeus 16.4): about 0.48 degrees at the horizon, 0.02 at 45 degrees up. Default false, the geometric altitude. Not applied below -1 degree, where the formula stops being true. */
+    refraction?: boolean;
+    /** Air pressure in hectopascals for the refraction; default 1010 (a standard sea-level day). Only used with `refraction`. */
+    pressureHpa?: number;
+    /** Air temperature in degrees Celsius for the refraction; default 10. Only used with `refraction`. */
+    temperatureC?: number;
+}
+/**
+ * The spin of another planet, as the IAU WGCCRE gives it: where its north pole points, and how far its prime meridian has turned.
+ *
+ * The pole is a right ascension and declination in the ICRF (the same J2000 frame as the star positions). The prime meridian is `W = w0 + rate * d`, with `d` the days since J2000.0 (2000 January 1.5): `w0` is W at J2000 in degrees and `rate` the degrees a day (negative for a planet that turns backwards, such as Venus). W is the angle, east, from the point where the planet's equator crosses the ICRF equator going north (the right ascension of the pole plus 90 degrees) to its prime meridian.
+ *
+ * @example
+ * ```ts
+ * import type { PlanetSpin } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Mars, IAU 2015 values at J2000 (the slow drift of the pole is left out)
+ * const mars: PlanetSpin = { pole: { rightAscension: 317.269202, declination: 54.432516 }, primeMeridian: { w0: 176.049863, rate: 350.891982443297 } };
+ * console.log(mars.pole.declination);
+ * ```
+ */
+export interface PlanetSpin {
+    /** The direction of the planet's north pole at J2000, in degrees. */
+    pole: SkyPoint;
+    /** The prime meridian: `w0` degrees at J2000 and `rate` degrees a day. */
+    primeMeridian: {
+        w0: number;
+        rate: number;
+    };
+}
+/**
+ * The Greenwich mean sidereal time: how far the Earth has turned against the stars, as the right ascension on the meridian of Greenwich, in degrees (Meeus 12.4, the IAU 1982 expression). It uses UT, which is UTC to under a second, and is the mean time, without the nutation term (at most about 1.1 seconds of time, 17 arc-seconds).
+ *
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @returns Degrees, 0 up to but not including 360. Divide by 15 for hours.
+ * @throws TypeError if `when` is not a Date or a number, RangeError if it is an invalid Date or not finite.
+ *
+ * @example
+ * ```ts
+ * import { greenwichSiderealTime } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Meeus example 12.a: 1987 April 10 at 0h UT is 13h10m46.3668s, 197.693195 degrees
+ * console.log(greenwichSiderealTime(Date.UTC(1987, 3, 10)).toFixed(6));
+ * ```
+ */
+export declare function greenwichSiderealTime(when: When): number;
+/**
+ * The local mean sidereal time: the right ascension that is on your meridian, due south or north of you, in degrees. A star with this right ascension is crossing the meridian.
+ *
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @param longitude - Degrees east of Greenwich (west is negative). Any finite number.
+ * @returns Degrees, 0 up to but not including 360.
+ * @throws TypeError if `when` is not a Date or a number, RangeError if it is invalid or `longitude` is not finite.
+ *
+ * @example
+ * ```ts
+ * import { localSiderealTime } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Greenwich's 197.693195 degrees at 0h UT, 1987 April 10, and Washington is 77.07 degrees west of it
+ * console.log(localSiderealTime(Date.UTC(1987, 3, 10), -77.0656).toFixed(3)); // 120.628
+ * ```
+ */
+export declare function localSiderealTime(when: When, longitude: number): number;
+/**
+ * A J2000 position carried to the mean equator and equinox of a date: the precession of the Earth's axis (Meeus chapter 21, the rigorous method with the IAU 1976 constants, good for a few centuries either side of 2000 to far under an arc-second). It leaves out the star's own proper motion (which `starPosition` adds), nutation and aberration, together under a minute of arc.
+ *
+ * @param position - A right ascension and declination in degrees at J2000.
+ * @param when - The date to carry it to.
+ * @returns The right ascension (0 up to but not including 360) and declination in degrees.
+ * @throws TypeError or RangeError, naming the argument, if `position` or `when` is not valid.
+ *
+ * @example
+ * ```ts
+ * import { precess } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Meeus example 21.b: theta Persei, carried to 2028 November 13.19 (about 15 minutes of arc east in right ascension)
+ * const there = precess({ rightAscension: 41.054063, declination: 49.227750 }, Date.UTC(2028, 10, 13, 4, 33, 36));
+ * console.log(there.rightAscension.toFixed(3), there.declination.toFixed(3)); // 41.547 49.348
+ * ```
+ */
+export declare function precess(position: SkyPoint, when: When): SkyPoint;
+/**
+ * Where a star (or any J2000 position) stands in the sky of a place on Earth at a moment: its altitude above the horizon and azimuth from north through east. The position is carried from J2000 to the equinox of the date (`precess`), the hour angle comes from the local mean sidereal time, and the horizon formulas are Meeus's (chapter 13). The result is geometric (no refraction) unless you ask for it. UTC stands for UT; nutation, aberration and parallax are left out, so it is good to about an arc-minute, far finer than the eye. The star's own proper motion is not added: pass `starPosition(star, when)` if you want it.
+ *
+ * @param position - A right ascension and declination in degrees, J2000 (the catalogue's frame), or of the date with `equinox: "date"`.
+ * @param observer - Latitude north and longitude east in degrees, and optionally `heightM`.
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @param options - `equinox`, and `refraction` with `pressureHpa` and `temperatureC`.
+ * @returns `{ altitude, azimuth }` in degrees.
+ * @throws TypeError or RangeError, naming the argument and the value, for a position, observer, moment or option that is not valid (a latitude or declination outside -90 to 90, a number that is not finite, a `pressureHpa` of 0 or less).
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ * import { horizontal } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * const polaris = starPosition(starByName("Polaris")!);
+ * const view = horizontal(polaris, { latitude: 49.28, longitude: -123.12 }, new Date("2026-11-08T06:00:00Z"));
+ * console.log(view.altitude.toFixed(1)); // 49.8: within a degree of the latitude, 49.28
+ * ```
+ */
+export declare function horizontal(position: SkyPoint, observer: Observer, when: When, options?: HorizontalOptions): Horizontal;
+/**
+ * Whether a position is above the horizon of a place at a moment (altitude greater than 0). With `refraction: true` it counts the bending of the light, so a star can be seen a little below the geometric horizon.
+ *
+ * @param position - A right ascension and declination in degrees, J2000 or (with `equinox: "date"`) of the date.
+ * @param observer - Latitude north and longitude east in degrees.
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @param options - The same as `horizontal`.
+ * @returns True when it is up.
+ * @throws TypeError or RangeError, as `horizontal` does.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ * import { isAboveHorizon } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Polaris never sets for anyone in the northern hemisphere
+ * const polaris = starPosition(starByName("Polaris")!);
+ * console.log(isAboveHorizon(polaris, { latitude: 49.28, longitude: -123.12 }, Date.now()));
+ * ```
+ */
+export declare function isAboveHorizon(position: SkyPoint, observer: Observer, when: When, options?: HorizontalOptions): boolean;
+/**
+ * Where a star stands in the sky of a place on ANOTHER planet: the sky turns about that planet's pole (the IAU WGCCRE pole and prime meridian, passed in as `spin`), so the star is rotated into the planet's own equatorial frame, its hour angle is the prime meridian plus the observer's east longitude minus its right ascension there, and the horizon formulas are the same as for Earth.
+ *
+ * The stars look the same from every planet: the nearest star, Proxima Centauri, shifts only about 40 arc-seconds seen from Pluto (annual parallax 0.77 arc-seconds times Pluto's 49 AU at its farthest), and a typical star far less, so a star's J2000 position serves anywhere in the solar system. Only the pole and the turning change.
+ *
+ * Limits: the latitude is used as the angle from the planet's equator on a sphere (the difference between planetographic and planetocentric latitude, up to a fifth of a degree on Mars, is ignored); the pole's slow drift is the caller's to add in if wanted (`spin.pole` is read as given); there is no atmosphere, and no precession of the pole is applied. `when` is UTC, like every moment in the package: it is turned into Terrestrial Time inside, the scale the IAU rates are in (69.184 s ahead of UTC since 2017, by the leap-second table back to 1972 and by Espenak and Meeus's delta T before it; a leap second announced after 2017 is not known until the table gets its row). TDB differs from TT by under 2 milliseconds, which is ignored. Without the conversion Mars would be turned 0.28 degrees out.
+ *
+ * @param position - A right ascension and declination in degrees at J2000.
+ * @param spin - The planet's `pole` (right ascension and declination, degrees) and `primeMeridian` (`w0` degrees at J2000 and `rate` degrees a day).
+ * @param observer - Latitude north and longitude east on that planet, in degrees (north being the side of the pole).
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @returns `{ altitude, azimuth }` in degrees, the azimuth from north through east.
+ * @throws TypeError or RangeError, naming the argument and the value, for a position, spin, observer or moment that is not valid.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ * import { horizontalFrom } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Mars, IAU 2015 values: its north celestial pole is only 10 degrees from Deneb, so from the pole Deneb stands almost overhead
+ * const mars = { pole: { rightAscension: 317.269202, declination: 54.432516 }, primeMeridian: { w0: 176.049863, rate: 350.891982443297 } };
+ * const deneb = starPosition(starByName("Deneb")!);
+ * console.log(horizontalFrom(deneb, mars, { latitude: 90, longitude: 0 }, Date.UTC(2026, 10, 8)).altitude.toFixed(1)); // 79.8
+ * ```
+ */
+export declare function horizontalFrom(position: SkyPoint, spin: PlanetSpin, observer: Observer, when: When): Horizontal;