@johnmorrisdotca/chikyu-earth 0.4.0 → 0.7.0

package/dist/realistic/sun.d.ts

@@ -0,0 +1,44 @@
+import type { GeoPoint } from "../types.ts";
+/**
+ * Julian day number of a moment in milliseconds since the Unix epoch.
+ *
+ * @param ms - Milliseconds since 1970-01-01T00:00Z.
+ * @returns The Julian day number, with its fraction.
+ *
+ * @example
+ * ```ts
+ * import { julianDay } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(julianDay(Date.UTC(2000, 0, 1, 12)));
+ * ```
+ */
+export declare const julianDay: (ms: number) => number;
+/**
+ * The point where the Sun is at the zenith at `ms`: latitude is the Sun's declination, longitude runs west at 15 degrees an hour.
+ *
+ * @param ms - A moment, in milliseconds since the Unix epoch.
+ * @returns The longitude and latitude on the Earth that has the Sun straight overhead.
+ *
+ * @example
+ * ```ts
+ * import { subsolarPoint } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const sun = subsolarPoint(Date.UTC(2026, 5, 21, 12));
+ * console.log(sun.lat.toFixed(1), sun.lon.toFixed(1));
+ * ```
+ */
+export declare function subsolarPoint(ms: number): GeoPoint;
+/**
+ * A point on the globe as a unit vector: +z is longitude 0 on the equator, +x east, +y north.
+ *
+ * @param point - A longitude and latitude in degrees.
+ * @returns The `[x, y, z]` of the point on a sphere of radius 1.
+ *
+ * @example
+ * ```ts
+ * import { unitVector } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(unitVector({ lon: 90, lat: 0 }).map((n) => Math.round(n)));
+ * ```
+ */
+export declare function unitVector(point: GeoPoint): [number, number, number];

package/dist/realistic/sun.js

@@ -0,0 +1,65 @@
+const RAD = Math.PI / 180;
+const wrap360 = (degrees) => ((degrees % 360) + 360) % 360;
+/**
+ * Julian day number of a moment in milliseconds since the Unix epoch.
+ *
+ * @param ms - Milliseconds since 1970-01-01T00:00Z.
+ * @returns The Julian day number, with its fraction.
+ *
+ * @example
+ * ```ts
+ * import { julianDay } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(julianDay(Date.UTC(2000, 0, 1, 12)));
+ * ```
+ */
+export const julianDay = (ms) => ms / 86_400_000 + 2_440_587.5;
+/**
+ * The point where the Sun is at the zenith at `ms`: latitude is the Sun's declination, longitude runs west at 15 degrees an hour.
+ *
+ * @param ms - A moment, in milliseconds since the Unix epoch.
+ * @returns The longitude and latitude on the Earth that has the Sun straight overhead.
+ *
+ * @example
+ * ```ts
+ * import { subsolarPoint } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const sun = subsolarPoint(Date.UTC(2026, 5, 21, 12));
+ * console.log(sun.lat.toFixed(1), sun.lon.toFixed(1));
+ * ```
+ */
+export function subsolarPoint(ms) {
+    const jd = julianDay(ms);
+    const t = (jd - 2_451_545) / 36_525;
+    const meanLongitude = wrap360(280.46646 + t * (36_000.76983 + t * 0.0003032));
+    const meanAnomaly = wrap360(357.52911 + t * (35_999.05029 - t * 0.0001537)) * RAD;
+    const centre = (1.914602 - t * (0.004817 + 0.000014 * t)) * Math.sin(meanAnomaly) +
+        (0.019993 - 0.000101 * t) * Math.sin(2 * meanAnomaly) +
+        0.000289 * Math.sin(3 * meanAnomaly);
+    const node = (125.04 - 1934.136 * t) * RAD;
+    const apparentLongitude = (meanLongitude + centre - 0.00569 - 0.00478 * Math.sin(node)) * RAD;
+    const obliquity = (23 + (26 + (21.448 - t * (46.815 + t * (0.00059 - t * 0.001813))) / 60) / 60 + 0.00256 * Math.cos(node)) * RAD;
+    const declination = Math.asin(Math.sin(obliquity) * Math.sin(apparentLongitude));
+    const rightAscension = Math.atan2(Math.cos(obliquity) * Math.sin(apparentLongitude), Math.cos(apparentLongitude)) / RAD;
+    const siderealGreenwich = wrap360(280.46061837 + 360.98564736629 * (jd - 2_451_545) + 0.000387933 * t * t);
+    const lon = ((wrap360(rightAscension - siderealGreenwich) + 180) % 360) - 180;
+    return { lon, lat: declination / RAD };
+}
+/**
+ * A point on the globe as a unit vector: +z is longitude 0 on the equator, +x east, +y north.
+ *
+ * @param point - A longitude and latitude in degrees.
+ * @returns The `[x, y, z]` of the point on a sphere of radius 1.
+ *
+ * @example
+ * ```ts
+ * import { unitVector } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(unitVector({ lon: 90, lat: 0 }).map((n) => Math.round(n)));
+ * ```
+ */
+export function unitVector(point) {
+    const lon = point.lon * RAD;
+    const lat = point.lat * RAD;
+    return [Math.cos(lat) * Math.sin(lon), Math.sin(lat), Math.cos(lat) * Math.cos(lon)];
+}

package/dist/realistic/textures.d.ts

@@ -0,0 +1,40 @@
+import type * as THREE from "three";
+import type { AssetCache } from "@johnmorrisdotca/kazoku-ui/renderer";
+import { type Layer } from "./tiers.ts";
+/**
+ * The parts of three.js the Earth and the space view use. A page can hand over a module that re-exports just these (see `setThreeLoader`) instead of all of three.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ThreeParts } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const load = (): Promise<ThreeParts> => import("three");
+ * console.log(typeof load);
+ * ```
+ */
+export type ThreeParts = {
+    [Name in "Texture" | "BufferGeometry" | "BufferAttribute" | "ShaderMaterial" | "Group" | "Mesh" | "Scene" | "OrthographicCamera" | "PerspectiveCamera" | "Vector3" | "WebGLRenderer" | "RepeatWrapping" | "ClampToEdgeWrapping" | "LinearMipmapLinearFilter" | "LinearFilter" | "BackSide" | "DoubleSide" | "LineLoop" | "LineBasicMaterial" | "Color"]: (typeof THREE)[Name];
+};
+/** Milliseconds a lower texture size must be enough before the larger one is let go. */
+export declare const DOWNGRADE_AFTER_MS = 4000;
+export interface TextureDeps {
+    assets: AssetCache;
+    /** Ends with a slash. */
+    textureBase: () => string;
+    /** The widest texture, 4096 at most. */
+    cap: () => number;
+    invalidate: () => void;
+    onError?: (error: unknown) => void;
+    onTier?: (layer: Layer, width: number) => void;
+}
+export interface TextureSet {
+    /** The `{ value }` a shader uniform takes, one a layer; the value is the texture now in use. */
+    readonly uniforms: Record<string, {
+        value: THREE.Texture | null;
+    }>;
+    /** Hold the width each layer needs for a disc of this many device pixels across the radius (`radiusPx[layer]`, or one number for all). */
+    sync(radiusPx: number | Partial<Record<Layer, number>>): void;
+    dispose(): void;
+}
+/** Load the base picture of each layer, then hand back the set. Rejects (after freeing what it took) if one will not load. */
+export declare function createTextureSet(three: ThreeParts, layers: readonly Layer[], deps: TextureDeps): Promise<TextureSet>;

package/dist/realistic/textures.js

@@ -0,0 +1,141 @@
+import { chooseTier, TIERS } from "./tiers.js";
+/** Milliseconds a lower texture size must be enough before the larger one is let go. */
+export const DOWNGRADE_AFTER_MS = 4000;
+/** Load the base picture of each layer, then hand back the set. Rejects (after freeing what it took) if one will not load. */
+export async function createTextureSet(three, layers, deps) {
+    let disposed = false;
+    const held = [];
+    const keyOf = (layer, texels) => `chikyu-earth:${layer}:${texels}`;
+    const take = (layer, texels) => {
+        const key = keyOf(layer, texels);
+        const entry = deps.assets.acquire(key, () => {
+            const texture = new three.Texture();
+            texture.wrapS = three.RepeatWrapping;
+            texture.wrapT = three.ClampToEdgeWrapping;
+            texture.minFilter = three.LinearMipmapLinearFilter;
+            texture.magFilter = three.LinearFilter;
+            texture.anisotropy = 8;
+            const controller = new AbortController();
+            const made = { width: texels, texture, closed: false, ready: Promise.resolve(), release: () => undefined };
+            made.ready = fetch(`${deps.textureBase()}${layer}-${texels}.webp`, { signal: controller.signal })
+                .then((response) => {
+                if (!response.ok)
+                    throw new Error(`${layer}-${texels}.webp: ${response.status}`);
+                return response.blob();
+            })
+                .then((blob) => createImageBitmap(blob, { premultiplyAlpha: "none", colorSpaceConversion: "none" }))
+                .then((bitmap) => {
+                if (made.closed)
+                    bitmap.close();
+                else {
+                    texture.image = bitmap;
+                    texture.needsUpdate = true;
+                }
+            });
+            made.ready.catch(() => undefined);
+            made.release = () => {
+                made.closed = true;
+                controller.abort();
+                texture.dispose();
+                texture.image?.close?.();
+            };
+            return made;
+        }, (value) => value.release());
+        held.push(key);
+        return entry;
+    };
+    const letGo = (layer, texels) => {
+        const key = keyOf(layer, texels);
+        const at = held.indexOf(key);
+        if (at >= 0)
+            held.splice(at, 1);
+        deps.assets.release(key);
+    };
+    const slots = new Map();
+    for (const layer of layers) {
+        const baseWidth = TIERS[layer][0];
+        const base = take(layer, baseWidth);
+        slots.set(layer, { layer, uniform: { value: null }, base, baseWidth, entry: base, width: baseWidth, loading: undefined, timer: undefined });
+    }
+    try {
+        await Promise.all([...slots.values()].map((slot) => slot.base.ready));
+    }
+    catch (error) {
+        for (const slot of slots.values())
+            letGo(slot.layer, slot.baseWidth);
+        deps.onError?.(error);
+        throw error;
+    }
+    for (const slot of slots.values())
+        slot.uniform.value = slot.base.texture;
+    const swap = (slot, entry, texels) => {
+        const previous = slot.entry;
+        slot.entry = entry;
+        slot.width = texels;
+        slot.uniform.value = entry.texture;
+        if (previous !== slot.base)
+            letGo(slot.layer, previous.width);
+        deps.onTier?.(slot.layer, texels);
+    };
+    const moveTo = (slot, texels) => {
+        if (disposed || texels === slot.width || slot.loading === texels)
+            return;
+        if (texels === slot.baseWidth) {
+            swap(slot, slot.base, texels);
+            deps.invalidate();
+            return;
+        }
+        slot.loading = texels;
+        const entry = take(slot.layer, texels);
+        entry.ready.then(() => {
+            if (disposed || slot.loading !== texels) {
+                letGo(slot.layer, texels);
+                return;
+            }
+            slot.loading = undefined;
+            swap(slot, entry, texels);
+            deps.invalidate();
+        }, (error) => {
+            letGo(slot.layer, texels);
+            if (slot.loading === texels)
+                slot.loading = undefined;
+            deps.onError?.(error);
+        });
+    };
+    let lastRadius = 0;
+    const wantedFor = (slot, radius) => {
+        const px = typeof radius === "number" ? radius : (radius[slot.layer] ?? 0);
+        return chooseTier(slot.layer, px, deps.cap());
+    };
+    return {
+        uniforms: Object.fromEntries([...slots].map(([layer, slot]) => [layer, slot.uniform])),
+        sync(radiusPx) {
+            lastRadius = radiusPx;
+            for (const slot of slots.values()) {
+                const wanted = wantedFor(slot, radiusPx);
+                if (slot.timer !== undefined && wanted >= slot.width) {
+                    clearTimeout(slot.timer);
+                    slot.timer = undefined;
+                }
+                if (wanted > slot.width)
+                    moveTo(slot, wanted);
+                else if (wanted < slot.width && slot.timer === undefined) {
+                    slot.timer = setTimeout(() => {
+                        slot.timer = undefined;
+                        const now = wantedFor(slot, lastRadius);
+                        if (now < slot.width)
+                            moveTo(slot, now);
+                    }, DOWNGRADE_AFTER_MS);
+                }
+            }
+        },
+        dispose() {
+            disposed = true;
+            for (const slot of slots.values())
+                if (slot.timer !== undefined)
+                    clearTimeout(slot.timer);
+            for (const key of held.splice(0))
+                deps.assets.release(key);
+        },
+    };
+}

package/dist/realistic/tiers.d.ts

@@ -0,0 +1,94 @@
+/**
+ * One of the pictures the realistic Earth and the space view draw with: `day`, `night`, `clouds`, `water` and `moon`.
+ *
+ * @example
+ * ```ts
+ * import { TIERS, type Layer } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const layer: Layer = "clouds";
+ * console.log(TIERS[layer]);
+ * ```
+ */
+export type Layer = "day" | "night" | "clouds" | "water" | "moon";
+/**
+ * The widths each layer is shipped in (every picture is 2:1, so the height is half).
+ *
+ * @example
+ * ```ts
+ * import { TIERS } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TIERS.day);
+ * ```
+ */
+export declare const TIERS: Record<Layer, readonly number[]>;
+/**
+ * The most pixels across a texture the package ever asks the GPU for.
+ *
+ * @example
+ * ```ts
+ * import { MAX_TEXTURE } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(MAX_TEXTURE);
+ * ```
+ */
+export declare const MAX_TEXTURE = 4096;
+/**
+ * Texels across the whole circumference wanted per device pixel of the globe's radius: 3 is a little under 2 pi, so a texel is a little larger than a pixel.
+ *
+ * @example
+ * ```ts
+ * import { TEXELS_PER_RADIUS_PIXEL } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TEXELS_PER_RADIUS_PIXEL);
+ * ```
+ */
+export declare const TEXELS_PER_RADIUS_PIXEL = 3;
+/**
+ * The width to hold for a layer when the globe's disc has radius `radiusPx` device pixels: the smallest shipped width that gives
+ * `TEXELS_PER_RADIUS_PIXEL` texels per pixel, else the largest, never more than `cap`, never less than the smallest.
+ *
+ * @param layer - Which picture.
+ * @param radiusPx - The disc's radius in device pixels.
+ * @param cap - The most pixels across to ask for; {@link MAX_TEXTURE} by default.
+ * @returns One of the widths in {@link TIERS} for that layer.
+ *
+ * @example
+ * ```ts
+ * import { chooseTier } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(chooseTier("day", 200), chooseTier("day", 900), chooseTier("day", 900, 2048));
+ * ```
+ */
+export declare function chooseTier(layer: Layer, radiusPx: number, cap?: number): number;
+/**
+ * The cap for this device: low-memory phones stop at 2048, and the GPU's own limit and the option are never passed.
+ *
+ * @param options - `max` (the page's own limit), `gpuMax` (the GPU's `MAX_TEXTURE_SIZE`) and `deviceMemory` (gigabytes, from `navigator.deviceMemory`); each may be left out.
+ * @returns The most pixels across any picture may have on this device.
+ *
+ * @example
+ * ```ts
+ * import { textureCap } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureCap(), textureCap({ deviceMemory: 2 }), textureCap({ gpuMax: 1024 }));
+ * ```
+ */
+export declare function textureCap(options?: {
+    max?: number;
+    gpuMax?: number;
+    deviceMemory?: number;
+}): number;
+/**
+ * Bytes of GPU memory a texture of this width costs, with its mipmaps, at 4 bytes a pixel (the most it can be).
+ *
+ * @param width - Pixels across; the picture is 2:1.
+ * @returns The bytes the GPU holds for it.
+ *
+ * @example
+ * ```ts
+ * import { textureBytes } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureBytes(4096));
+ * ```
+ */
+export declare const textureBytes: (width: number) => number;

package/dist/realistic/tiers.js

@@ -0,0 +1,94 @@
+// Which size of each picture to hold on the GPU. Small first, sharper on zoom, and never past a cap. Pure.
+/**
+ * The widths each layer is shipped in (every picture is 2:1, so the height is half).
+ *
+ * @example
+ * ```ts
+ * import { TIERS } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TIERS.day);
+ * ```
+ */
+export const TIERS = {
+    day: [1024, 2048, 4096],
+    night: [1024, 2048],
+    clouds: [1024, 2048],
+    water: [1024, 2048],
+    moon: [1024, 2048],
+};
+/**
+ * The most pixels across a texture the package ever asks the GPU for.
+ *
+ * @example
+ * ```ts
+ * import { MAX_TEXTURE } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(MAX_TEXTURE);
+ * ```
+ */
+export const MAX_TEXTURE = 4096;
+/**
+ * Texels across the whole circumference wanted per device pixel of the globe's radius: 3 is a little under 2 pi, so a texel is a little larger than a pixel.
+ *
+ * @example
+ * ```ts
+ * import { TEXELS_PER_RADIUS_PIXEL } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TEXELS_PER_RADIUS_PIXEL);
+ * ```
+ */
+export const TEXELS_PER_RADIUS_PIXEL = 3;
+/**
+ * The width to hold for a layer when the globe's disc has radius `radiusPx` device pixels: the smallest shipped width that gives
+ * `TEXELS_PER_RADIUS_PIXEL` texels per pixel, else the largest, never more than `cap`, never less than the smallest.
+ *
+ * @param layer - Which picture.
+ * @param radiusPx - The disc's radius in device pixels.
+ * @param cap - The most pixels across to ask for; {@link MAX_TEXTURE} by default.
+ * @returns One of the widths in {@link TIERS} for that layer.
+ *
+ * @example
+ * ```ts
+ * import { chooseTier } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(chooseTier("day", 200), chooseTier("day", 900), chooseTier("day", 900, 2048));
+ * ```
+ */
+export function chooseTier(layer, radiusPx, cap = MAX_TEXTURE) {
+    const widths = TIERS[layer].filter((width) => width <= Math.max(cap, TIERS[layer][0]));
+    const wanted = radiusPx * TEXELS_PER_RADIUS_PIXEL;
+    return widths.find((width) => width >= wanted) ?? widths[widths.length - 1];
+}
+/**
+ * The cap for this device: low-memory phones stop at 2048, and the GPU's own limit and the option are never passed.
+ *
+ * @param options - `max` (the page's own limit), `gpuMax` (the GPU's `MAX_TEXTURE_SIZE`) and `deviceMemory` (gigabytes, from `navigator.deviceMemory`); each may be left out.
+ * @returns The most pixels across any picture may have on this device.
+ *
+ * @example
+ * ```ts
+ * import { textureCap } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureCap(), textureCap({ deviceMemory: 2 }), textureCap({ gpuMax: 1024 }));
+ * ```
+ */
+export function textureCap(options = {}) {
+    let cap = Math.min(MAX_TEXTURE, options.max ?? MAX_TEXTURE, options.gpuMax ?? MAX_TEXTURE);
+    if (options.deviceMemory !== undefined && options.deviceMemory <= 2)
+        cap = Math.min(cap, 2048);
+    return cap;
+}
+/**
+ * Bytes of GPU memory a texture of this width costs, with its mipmaps, at 4 bytes a pixel (the most it can be).
+ *
+ * @param width - Pixels across; the picture is 2:1.
+ * @returns The bytes the GPU holds for it.
+ *
+ * @example
+ * ```ts
+ * import { textureBytes } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureBytes(4096));
+ * ```
+ */
+export const textureBytes = (width) => Math.round(width * (width / 2) * 4 * (4 / 3));

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);