@johnmorrisdotca/chikyu-earth 0.5.0 → 0.8.0

package/dist/rotate.d.ts

@@ -1,14 +1,69 @@
 import type { GeoPoint, Rotation } from "./types.ts";
-/** One sidereal day — the Earth's turn against the stars, 23 h 56 min 4.0905 s — in milliseconds. */
+/**
+ * One sidereal day — the Earth's turn against the stars, 23 h 56 min 4.0905 s — in milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { SIDEREAL_DAY_MS } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(SIDEREAL_DAY_MS / 3_600_000, "hours");
+ * ```
+ */
 export declare const SIDEREAL_DAY_MS = 86164090.5;
-/** How far the Earth turns in one millisecond, in degrees. */
+/**
+ * How far the Earth turns in one millisecond, in degrees.
+ *
+ * @example
+ * ```ts
+ * import { DEGREES_PER_MS } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(DEGREES_PER_MS * 1000, "degrees a second");
+ * ```
+ */
 export declare const DEGREES_PER_MS: number;
-/** How far the Earth has turned after `ms` milliseconds, in degrees. */
+/**
+ * How far the Earth has turned after `ms` milliseconds, in degrees.
+ *
+ * @param ms - A time span in milliseconds.
+ * @returns The turn in degrees; a whole {@link SIDEREAL_DAY_MS} is 360.
+ *
+ * @example
+ * ```ts
+ * import { SIDEREAL_DAY_MS, spinAt } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(spinAt(SIDEREAL_DAY_MS / 4));
+ * ```
+ */
 export declare const spinAt: (ms: number) => number;
-/** The rotation that puts `centre` in the middle of the disc: d3-geo's rotate is the negative of the point. */
+/**
+ * The rotation that puts `centre` in the middle of the disc: d3-geo's rotate is the negative of the point.
+ *
+ * @param centre - The place to centre on.
+ * @returns The `[lambda, phi]` pair for `globe()`'s `rotation` option.
+ *
+ * @example
+ * ```ts
+ * import { centreRotation } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(centreRotation({ lon: 139.7, lat: 35.7 }));
+ * ```
+ */
 export declare const centreRotation: (centre: GeoPoint) => Rotation;
 /**
  * The rotation at `now` for a globe that was centred on `centre` at `start`. The tilt stays; the spin advances at the
  * Earth's own rate, so the disc turns as the real Earth does and the centred place drifts with it.
+ *
+ * @param centre - The place the globe was centred on at `start`.
+ * @param now - The time to draw for, in milliseconds.
+ * @param start - The time the globe was centred, in the same milliseconds as `now`.
+ * @returns The `[lambda, phi]` rotation at `now`.
+ *
+ * @example
+ * ```ts
+ * import { rotationAt, SIDEREAL_DAY_MS } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const tokyo = { lon: 139.7, lat: 35.7 };
+ * console.log(rotationAt(tokyo, SIDEREAL_DAY_MS / 2, 0));
+ * ```
  */
 export declare function rotationAt(centre: GeoPoint, now: number, start: number): Rotation;

package/dist/rotate.js

@@ -1,14 +1,69 @@
-/** One sidereal day — the Earth's turn against the stars, 23 h 56 min 4.0905 s — in milliseconds. */
+/**
+ * One sidereal day — the Earth's turn against the stars, 23 h 56 min 4.0905 s — in milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { SIDEREAL_DAY_MS } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(SIDEREAL_DAY_MS / 3_600_000, "hours");
+ * ```
+ */
 export const SIDEREAL_DAY_MS = 86_164_090.5;
-/** How far the Earth turns in one millisecond, in degrees. */
+/**
+ * How far the Earth turns in one millisecond, in degrees.
+ *
+ * @example
+ * ```ts
+ * import { DEGREES_PER_MS } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(DEGREES_PER_MS * 1000, "degrees a second");
+ * ```
+ */
 export const DEGREES_PER_MS = 360 / SIDEREAL_DAY_MS;
-/** How far the Earth has turned after `ms` milliseconds, in degrees. */
+/**
+ * How far the Earth has turned after `ms` milliseconds, in degrees.
+ *
+ * @param ms - A time span in milliseconds.
+ * @returns The turn in degrees; a whole {@link SIDEREAL_DAY_MS} is 360.
+ *
+ * @example
+ * ```ts
+ * import { SIDEREAL_DAY_MS, spinAt } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(spinAt(SIDEREAL_DAY_MS / 4));
+ * ```
+ */
 export const spinAt = (ms) => ms * DEGREES_PER_MS;
-/** The rotation that puts `centre` in the middle of the disc: d3-geo's rotate is the negative of the point. */
+/**
+ * The rotation that puts `centre` in the middle of the disc: d3-geo's rotate is the negative of the point.
+ *
+ * @param centre - The place to centre on.
+ * @returns The `[lambda, phi]` pair for `globe()`'s `rotation` option.
+ *
+ * @example
+ * ```ts
+ * import { centreRotation } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(centreRotation({ lon: 139.7, lat: 35.7 }));
+ * ```
+ */
 export const centreRotation = (centre) => [-centre.lon, -centre.lat];
 /**
  * The rotation at `now` for a globe that was centred on `centre` at `start`. The tilt stays; the spin advances at the
  * Earth's own rate, so the disc turns as the real Earth does and the centred place drifts with it.
+ *
+ * @param centre - The place the globe was centred on at `start`.
+ * @param now - The time to draw for, in milliseconds.
+ * @param start - The time the globe was centred, in the same milliseconds as `now`.
+ * @returns The `[lambda, phi]` rotation at `now`.
+ *
+ * @example
+ * ```ts
+ * import { rotationAt, SIDEREAL_DAY_MS } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const tokyo = { lon: 139.7, lat: 35.7 };
+ * console.log(rotationAt(tokyo, SIDEREAL_DAY_MS / 2, 0));
+ * ```
  */
 export function rotationAt(centre, now, start) {
     const [lambda, phi] = centreRotation(centre);

package/dist/satellites/index.d.ts

@@ -0,0 +1,3 @@
+export { createSatellites, type SatellitesOptions } from "./track.ts";
+export { DEFAULT_MAX_AGE_DAYS, MAX_SATELLITE_SPEED } from "./limits.ts";
+export type { ElementSet, RefusedElementSet, SatelliteInfo, SatelliteRef, Satellites } from "./types.ts";

package/dist/satellites/index.js

@@ -0,0 +1,3 @@
+// The satellites' pure parts: orbital elements in, positions out (SGP4 by satellite.js, an optional peer). They import on a server. The space view takes a group with `setSatellites`.
+export { createSatellites } from "./track.js";
+export { DEFAULT_MAX_AGE_DAYS, MAX_SATELLITE_SPEED } from "./limits.js";

package/dist/satellites/limits.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How old, in days, an element set may be at the moment shown before the satellite is left out: SGP4's error grows by a few kilometres a day, so a fortnight is as far as a picture should trust.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_MAX_AGE_DAYS } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(DEFAULT_MAX_AGE_DAYS);
+ * ```
+ */
+export declare const DEFAULT_MAX_AGE_DAYS = 14;
+/**
+ * The fastest clock, in game seconds a second, at which the space view still places a group of satellites: above it the two moments SGP4 is run at would be too far apart to interpolate, so the group is hidden rather than drawn wrongly. A satellite that was chosen with `selectSatellite` or ridden along is still placed exactly, one SGP4 call a frame.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SATELLITE_SPEED } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(MAX_SATELLITE_SPEED);
+ * ```
+ */
+export declare const MAX_SATELLITE_SPEED = 60;

package/dist/satellites/limits.js

@@ -0,0 +1,23 @@
+// The satellites' two limits, apart from the SGP4 code so the space view can read them without needing satellite.js.
+/**
+ * How old, in days, an element set may be at the moment shown before the satellite is left out: SGP4's error grows by a few kilometres a day, so a fortnight is as far as a picture should trust.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_MAX_AGE_DAYS } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(DEFAULT_MAX_AGE_DAYS);
+ * ```
+ */
+export const DEFAULT_MAX_AGE_DAYS = 14;
+/**
+ * The fastest clock, in game seconds a second, at which the space view still places a group of satellites: above it the two moments SGP4 is run at would be too far apart to interpolate, so the group is hidden rather than drawn wrongly. A satellite that was chosen with `selectSatellite` or ridden along is still placed exactly, one SGP4 call a frame.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SATELLITE_SPEED } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(MAX_SATELLITE_SPEED);
+ * ```
+ */
+export const MAX_SATELLITE_SPEED = 60;

package/dist/satellites/track.d.ts

@@ -0,0 +1,50 @@
+import type { ElementSet, Satellites } from "./types.ts";
+/**
+ * What `createSatellites` can be told.
+ *
+ * @example
+ * ```ts
+ * import type { SatellitesOptions } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const options: SatellitesOptions = { maxAgeDays: 7 };
+ * console.log(options.maxAgeDays);
+ * ```
+ */
+export interface SatellitesOptions {
+    /** The oldest an element set may be at the moment shown, in days (14 by default). */
+    maxAgeDays?: number;
+}
+/**
+ * Make a group of satellites from their element sets. Each starts SGP4 once here; one that does not (bad numbers, decayed at its own epoch) is listed in `refused` and left out.
+ * It needs satellite.js (MIT, an optional peer dependency) and imports in a browser or on a server.
+ *
+ * @param sets - Element sets in CelesTrak's JSON format (`ElementSet`), fetched by your page.
+ * @param options - `maxAgeDays`: the oldest an element set may be at the moment shown.
+ * @returns The group: `at(ms, out)` for positions, `exact`, `orbit`, `info`, and counters.
+ *
+ * @example
+ * ```ts
+ * import { createSatellites } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const group = createSatellites([
+ *   {
+ *     OBJECT_NAME: "ISS (ZARYA)",
+ *     OBJECT_ID: "1998-067A",
+ *     EPOCH: "2026-11-02T10:25:21.580320",
+ *     MEAN_MOTION: 15.49150046,
+ *     ECCENTRICITY: 0.0007139,
+ *     INCLINATION: 51.6332,
+ *     RA_OF_ASC_NODE: 335.9757,
+ *     ARG_OF_PERICENTER: 339.3739,
+ *     MEAN_ANOMALY: 20.6961,
+ *     NORAD_CAT_ID: 25544,
+ *     BSTAR: 0.00012,
+ *     MEAN_MOTION_DOT: 0.0001,
+ *     MEAN_MOTION_DDOT: 0,
+ *   },
+ * ]);
+ * const noon = Date.UTC(2026, 10, 2, 12);
+ * console.log(group.count, group.info(0, noon)?.altitudeKm.toFixed(0));
+ * ```
+ */
+export declare function createSatellites(sets: readonly ElementSet[], options?: SatellitesOptions): Satellites;

package/dist/satellites/track.js

@@ -0,0 +1,227 @@
+// SGP4 for a group of satellites, kept cheap: the whole group is run at two moments a step apart and every position in between is an interpolation, so the cost is one batch a step
+// (about once a second), never one a frame. satellite.js (MIT) does the SGP4 itself; this file never touches the screen and imports on a server.
+import { json2satrec, sgp4 } from "satellite.js";
+import { DEFAULT_MAX_AGE_DAYS } from "./limits.js";
+/** The Earth's mean radius in kilometres: the unit of every position here (the same as the space view's). */
+const EARTH_RADIUS_KM = 6371;
+const DAY_MS = 86_400_000;
+const MIN_STEP_MS = 1000;
+const MAX_STEP_MS = 60_000;
+const epochOf = (text) => Date.parse(/[zZ]|[+-]\d\d:?\d\d$/.test(text) ? text : `${text}Z`);
+/**
+ * Make a group of satellites from their element sets. Each starts SGP4 once here; one that does not (bad numbers, decayed at its own epoch) is listed in `refused` and left out.
+ * It needs satellite.js (MIT, an optional peer dependency) and imports in a browser or on a server.
+ *
+ * @param sets - Element sets in CelesTrak's JSON format (`ElementSet`), fetched by your page.
+ * @param options - `maxAgeDays`: the oldest an element set may be at the moment shown.
+ * @returns The group: `at(ms, out)` for positions, `exact`, `orbit`, `info`, and counters.
+ *
+ * @example
+ * ```ts
+ * import { createSatellites } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const group = createSatellites([
+ *   {
+ *     OBJECT_NAME: "ISS (ZARYA)",
+ *     OBJECT_ID: "1998-067A",
+ *     EPOCH: "2026-11-02T10:25:21.580320",
+ *     MEAN_MOTION: 15.49150046,
+ *     ECCENTRICITY: 0.0007139,
+ *     INCLINATION: 51.6332,
+ *     RA_OF_ASC_NODE: 335.9757,
+ *     ARG_OF_PERICENTER: 339.3739,
+ *     MEAN_ANOMALY: 20.6961,
+ *     NORAD_CAT_ID: 25544,
+ *     BSTAR: 0.00012,
+ *     MEAN_MOTION_DOT: 0.0001,
+ *     MEAN_MOTION_DDOT: 0,
+ *   },
+ * ]);
+ * const noon = Date.UTC(2026, 10, 2, 12);
+ * console.log(group.count, group.info(0, noon)?.altitudeKm.toFixed(0));
+ * ```
+ */
+export function createSatellites(sets, options = {}) {
+    const maxAgeDays = options.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS;
+    const maxAgeMs = maxAgeDays * DAY_MS;
+    const recs = [];
+    const usable = [];
+    const epochs = [];
+    const refused = [];
+    for (const set of sets) {
+        const epoch = epochOf(set.EPOCH);
+        const refuse = (reason) => void refused.push({ name: set.OBJECT_NAME, noradId: set.NORAD_CAT_ID, reason });
+        if (!Number.isFinite(epoch)) {
+            refuse("the epoch is not a date");
+            continue;
+        }
+        try {
+            const rec = json2satrec(set);
+            const start = sgp4(rec, 0);
+            if (!start || !start.position || !start.velocity || rec.error !== 0) {
+                refuse("SGP4 could not start from these elements");
+                continue;
+            }
+            recs.push(rec);
+            usable.push(set);
+            epochs.push(epoch);
+        }
+        catch (error) {
+            refuse(error instanceof Error ? error.message : "SGP4 could not start from these elements");
+        }
+    }
+    const n = recs.length;
+    let a = new Float32Array(n * 3);
+    let b = new Float32Array(n * 3);
+    let okA = new Uint8Array(n);
+    let okB = new Uint8Array(n);
+    const shown = new Uint8Array(n);
+    let aMs = 0;
+    let bMs = 0;
+    let ready = false;
+    let stepMs = MIN_STEP_MS;
+    let propagations = 0;
+    let placed = 0;
+    const timing = { lastBatchMs: 0, maxBatchMs: 0 };
+    /** SGP4 for the whole group at one moment, into `buffer` in the space view's axes (TEME x, z, -y: x to the vernal equinox, y north). */
+    const sample = (buffer, ok, ms) => {
+        const started = performance.now();
+        for (let i = 0; i < n; i += 1) {
+            const epoch = epochs[i];
+            if (Math.abs(ms - epoch) > maxAgeMs) {
+                ok[i] = 0;
+                continue;
+            }
+            propagations += 1;
+            const result = sgp4(recs[i], (ms - epoch) / 60_000);
+            const p = result && result.position;
+            if (!p || !Number.isFinite(p.x)) {
+                ok[i] = 0;
+                continue;
+            }
+            ok[i] = 1;
+            buffer[i * 3] = p.x / EARTH_RADIUS_KM;
+            buffer[i * 3 + 1] = p.z / EARTH_RADIUS_KM;
+            buffer[i * 3 + 2] = -p.y / EARTH_RADIUS_KM;
+        }
+        timing.lastBatchMs = performance.now() - started;
+        if (timing.lastBatchMs > timing.maxBatchMs)
+            timing.maxBatchMs = timing.lastBatchMs;
+    };
+    const exactAt = (index, ms, out) => {
+        const epoch = epochs[index];
+        if (epoch === undefined || Math.abs(ms - epoch) > maxAgeMs)
+            return false;
+        propagations += 1;
+        const result = sgp4(recs[index], (ms - epoch) / 60_000);
+        if (!result || !result.position || !result.velocity || !Number.isFinite(result.position.x))
+            return false;
+        out[0] = result.position.x / EARTH_RADIUS_KM;
+        out[1] = result.position.z / EARTH_RADIUS_KM;
+        out[2] = -result.position.y / EARTH_RADIUS_KM;
+        out[3] = result.velocity.x;
+        out[4] = result.velocity.z;
+        out[5] = -result.velocity.y;
+        return true;
+    };
+    return {
+        count: n,
+        sets: usable,
+        refused,
+        maxAgeDays,
+        get propagations() {
+            return propagations;
+        },
+        timing,
+        get placed() {
+            return placed;
+        },
+        setStep(ms) {
+            const next = Math.min(MAX_STEP_MS, Math.max(MIN_STEP_MS, Math.round(ms)));
+            if (next !== stepMs) {
+                stepMs = next;
+                ready = false;
+            }
+        },
+        at(ms, out) {
+            if (n === 0)
+                return;
+            if (!ready || ms < aMs || ms > bMs) {
+                if (ready && ms > bMs && ms - bMs < stepMs) {
+                    [a, b] = [b, a];
+                    [okA, okB] = [okB, okA];
+                    aMs = bMs;
+                    bMs = aMs + stepMs;
+                    sample(b, okB, bMs);
+                }
+                else if (ready && ms < aMs && aMs - ms < stepMs) {
+                    [a, b] = [b, a];
+                    [okA, okB] = [okB, okA];
+                    bMs = aMs;
+                    aMs = bMs - stepMs;
+                    sample(a, okA, aMs);
+                }
+                else {
+                    aMs = ms;
+                    bMs = ms + stepMs;
+                    sample(a, okA, aMs);
+                    sample(b, okB, bMs);
+                    ready = true;
+                }
+            }
+            const t = (ms - aMs) / (bMs - aMs);
+            let count = 0;
+            for (let i = 0; i < n; i += 1) {
+                const k = i * 3;
+                if (okA[i] === 1 && okB[i] === 1) {
+                    out[k] = a[k] + (b[k] - a[k]) * t;
+                    out[k + 1] = a[k + 1] + (b[k + 1] - a[k + 1]) * t;
+                    out[k + 2] = a[k + 2] + (b[k + 2] - a[k + 2]) * t;
+                    shown[i] = 1;
+                    count += 1;
+                }
+                else {
+                    out[k] = 0;
+                    out[k + 1] = 0;
+                    out[k + 2] = 0;
+                    shown[i] = 0;
+                }
+            }
+            placed = count;
+        },
+        visible: (index) => shown[index] === 1,
+        exact: exactAt,
+        orbit(index, ms, points) {
+            const path = new Float32Array((points + 1) * 3);
+            const period = 1440 / (usable[index]?.MEAN_MOTION || 15);
+            const one = new Float64Array(6);
+            for (let k = 0; k < points; k += 1) {
+                if (exactAt(index, ms + (k / points) * period * 60_000, one))
+                    path.set(one.subarray(0, 3), k * 3);
+                else if (k > 0)
+                    path.copyWithin(k * 3, (k - 1) * 3, k * 3);
+            }
+            path.copyWithin(points * 3, 0, 3);
+            return path;
+        },
+        info(index, ms) {
+            const set = usable[index];
+            const one = new Float64Array(6);
+            if (!set || !exactAt(index, ms, one))
+                return undefined;
+            const info = {
+                index,
+                name: set.OBJECT_NAME,
+                noradId: set.NORAD_CAT_ID,
+                objectId: set.OBJECT_ID,
+                epochMs: epochs[index],
+                ageDays: (ms - epochs[index]) / DAY_MS,
+                altitudeKm: Math.hypot(one[0], one[1], one[2]) * EARTH_RADIUS_KM - EARTH_RADIUS_KM,
+                speedKmS: Math.hypot(one[3], one[4], one[5]),
+                periodMinutes: 1440 / set.MEAN_MOTION,
+                inclinationDeg: set.INCLINATION,
+            };
+            return info;
+        },
+    };
+}

package/dist/satellites/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * One satellite's orbital elements in the "GP" format that CelesTrak and Space-Track both serve as JSON (CCSDS OMM, one object per satellite). Only these fields are read.
+ * The package fetches nothing: your page gets the elements (see the satellites guide for the rules of the sources) and passes them in.
+ *
+ * @example
+ * ```ts
+ * import type { ElementSet } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const iss: ElementSet = {
+ *   OBJECT_NAME: "ISS (ZARYA)",
+ *   OBJECT_ID: "1998-067A",
+ *   EPOCH: "2026-11-02T10:25:21.580320",
+ *   MEAN_MOTION: 15.49150046,
+ *   ECCENTRICITY: 0.0007139,
+ *   INCLINATION: 51.6332,
+ *   RA_OF_ASC_NODE: 335.9757,
+ *   ARG_OF_PERICENTER: 339.3739,
+ *   MEAN_ANOMALY: 20.6961,
+ *   NORAD_CAT_ID: 25544,
+ *   BSTAR: 0.00012,
+ *   MEAN_MOTION_DOT: 0.0001,
+ *   MEAN_MOTION_DDOT: 0,
+ * };
+ * console.log(iss.OBJECT_NAME);
+ * ```
+ */
+export interface ElementSet {
+    OBJECT_NAME: string;
+    OBJECT_ID?: string;
+    /** The moment the elements describe, ISO 8601 in UTC (a trailing `Z` is optional). */
+    EPOCH: string;
+    /** Revolutions a day. */
+    MEAN_MOTION: number;
+    ECCENTRICITY: number;
+    /** Degrees. */
+    INCLINATION: number;
+    /** Degrees. */
+    RA_OF_ASC_NODE: number;
+    /** Degrees. */
+    ARG_OF_PERICENTER: number;
+    /** Degrees. */
+    MEAN_ANOMALY: number;
+    NORAD_CAT_ID: number;
+    BSTAR: number;
+    MEAN_MOTION_DOT: number;
+    MEAN_MOTION_DDOT: number;
+    EPHEMERIS_TYPE?: number;
+    CLASSIFICATION_TYPE?: string;
+    ELEMENT_SET_NO?: number;
+    REV_AT_EPOCH?: number;
+}
+/**
+ * What a page can tell a reader about one satellite at a moment: its name, its number, how old its elements are, how high and how fast it is.
+ *
+ * @example
+ * ```ts
+ * import type { SatelliteInfo } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const describe = (info: SatelliteInfo): string => `${info.name}: ${info.altitudeKm.toFixed(0)} km up, ${info.speedKmS.toFixed(2)} km/s`;
+ * console.log(typeof describe);
+ * ```
+ */
+export interface SatelliteInfo {
+    /** Where it is in its group. */
+    index: number;
+    name: string;
+    /** The NORAD catalogue number. */
+    noradId: number;
+    /** The international designator (for example `1998-067A`), when the elements carry one. */
+    objectId: string | undefined;
+    /** The moment of its elements, in milliseconds since the Unix epoch. */
+    epochMs: number;
+    /** Days between the elements' moment and the moment asked about (negative before it). */
+    ageDays: number;
+    /** Height above the mean Earth radius (6371 km) at that moment. */
+    altitudeKm: number;
+    /** Speed against the stars, kilometres a second. */
+    speedKmS: number;
+    /** One revolution, minutes. */
+    periodMinutes: number;
+    /** Degrees. */
+    inclinationDeg: number;
+}
+/**
+ * A satellite chosen from a group: which group and which place in it.
+ *
+ * @example
+ * ```ts
+ * import type { SatelliteRef } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const first: SatelliteRef = { group: "stations", index: 0 };
+ * console.log(first.group);
+ * ```
+ */
+export interface SatelliteRef {
+    group: string;
+    index: number;
+}
+/**
+ * A satellite the group could not use, and why: its elements did not start SGP4 (bad numbers), or it had decayed at its own epoch.
+ *
+ * @example
+ * ```ts
+ * import type { RefusedElementSet } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const show = (one: RefusedElementSet): string => `${one.name}: ${one.reason}`;
+ * console.log(typeof show);
+ * ```
+ */
+export interface RefusedElementSet {
+    name: string;
+    noradId: number;
+    reason: string;
+}
+/**
+ * A group of satellites, ready to give positions for any moment: what `createSatellites` returns, and what `<chikyu-space>` takes in `setSatellites`.
+ * Positions are in Earth radii (6371 km) from the Earth's centre, in the space view's axes (x to the vernal equinox, y north); a satellite whose elements
+ * are older than `maxAgeDays` at the moment asked about is not placed (its place stays at the centre and `visible(index)` is false).
+ *
+ * @example
+ * ```ts
+ * import type { Satellites } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const first = (group: Satellites): string => group.sets[0]?.OBJECT_NAME ?? "none";
+ * console.log(typeof first);
+ * ```
+ */
+export interface Satellites {
+    /** Satellites that started SGP4. */
+    readonly count: number;
+    /** Their elements, in the order of their places. */
+    readonly sets: readonly ElementSet[];
+    /** The ones left out, with the reason. */
+    readonly refused: readonly RefusedElementSet[];
+    /** The oldest an element set may be at the moment shown, in days. */
+    readonly maxAgeDays: number;
+    /** SGP4 calls made so far, for a page or a test to count. */
+    readonly propagations: number;
+    /** Milliseconds the last batch of SGP4 took, and the longest so far. */
+    readonly timing: {
+        lastBatchMs: number;
+        maxBatchMs: number;
+    };
+    /**
+     * Fill `out` (3 numbers a satellite) with the positions at `ms`: SGP4 is run for the whole group at two moments `step` apart and the positions between are interpolated, so a
+     * steady clock costs one batch a step and every call in between is arithmetic.
+     */
+    at(ms: number, out: Float32Array): void;
+    /** True if satellite `index` was placed by the last `at` (its elements are not too old at that moment). */
+    visible(index: number): boolean;
+    /** How many of them the last `at` placed. */
+    readonly placed: number;
+    /** The game time between the two moments SGP4 is run at (1000 to 60000 ms); the space view sets it from the clock's speed. */
+    setStep(ms: number): void;
+    /** One satellite at exactly `ms` (no interpolation): position in Earth radii and velocity in km/s into `out` (6 numbers). False if its elements are too old or SGP4 gave up. */
+    exact(index: number, ms: number, out: Float64Array): boolean;
+    /** The path of satellite `index` for one revolution from `ms`, `points` + 1 points in order along it (the last on the first), into a new array of Earth radii. */
+    orbit(index: number, ms: number, points: number): Float32Array;
+    /** Facts about one satellite at `ms`; undefined if it cannot be placed then. */
+    info(index: number, ms: number): SatelliteInfo | undefined;
+}

package/dist/satellites/types.js

@@ -0,0 +1,3 @@
+// What the satellites are made of and what the space view asks of them. Types only: nothing here imports satellite.js, so the space element can use them
+// without needing it.
+export {};