@johnmorrisdotca/wakusei-planets 0.0.0-stage → 0.3.0

package/dist/line.js

@@ -0,0 +1,280 @@
+// The line drawing: a body as thin outlines on a dark disc, in the same style as the family's other line drawings. One SVG string, no canvas, no DOM.
+import { apparent, nearMoons, orbitPath, system } from "./ephemeris.js";
+import { BODIES, ringReach } from "./facts.js";
+import { facing, portrait, silhouette, surfacePoint } from "./pose.js";
+import { cross, RAD, scale, unit } from "./vec.js";
+const NAVY = "#0b1424";
+const hex = (c) => [parseInt(c.slice(1, 3), 16), parseInt(c.slice(3, 5), 16), parseInt(c.slice(5, 7), 16)];
+/**
+ * Mix two `#rrggbb` colours: `t` is how much of `b` (0 to 1).
+ * @param a - The first colour.
+ * @param b - The second colour.
+ * @param t - How much of `b`, 0 to 1.
+ * @returns The mixed colour as `#rrggbb`.
+ *
+ * @example
+ * ```ts
+ * import { mix } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(mix("#000000", "#ffffff", 0.5));
+ * ```
+ */
+export function mix(a, b, t) {
+    const x = hex(a);
+    const y = hex(b);
+    return `#${[0, 1, 2].map((i) => Math.round(x[i] + (y[i] - x[i]) * t).toString(16).padStart(2, "0")).join("")}`;
+}
+const n = (v) => (Math.round(v * 100) / 100).toString();
+/** Points (screen units, y up) to an SVG path d-string around `frame`, optionally closed. */
+const path = (frame, points, close = false) => `M${points.map((p) => `${n(frame.cx + p[0] * frame.r)} ${n(frame.cy - p[1] * frame.r)}`).join("L")}${close ? "Z" : ""}`;
+/** Break a run of samples into runs where `visible` holds. */
+function runs(samples, visible) {
+    const out = [];
+    let current = [];
+    samples.forEach((p, i) => {
+        if (visible(p, i))
+            current.push(p);
+        else if (current.length > 0) {
+            out.push(current);
+            current = [];
+        }
+    });
+    if (current.length > 0)
+        out.push(current);
+    return out;
+}
+/** A small circle of angular radii (rx east-west, ry north-south, degrees) about a point of the body, as body-frame directions. */
+function around(lon, lat, rx, ry, steps = 28) {
+    const out = [];
+    for (let k = 0; k < steps; k += 1) {
+        const t = (k / steps) * 2 * Math.PI;
+        const dlat = ry * Math.sin(t);
+        const dlon = rx * Math.cos(t) / Math.max(0.15, Math.cos((lat + dlat) * RAD));
+        out.push({ lon: lon + dlon, lat: Math.max(-89.9, Math.min(89.9, lat + dlat)) });
+    }
+    return out;
+}
+function featurePaths(facts, pose, frame, stroke, hair) {
+    const f = facts.flattening;
+    const visible = (lon, lat) => facing(pose, lon, lat, f) > 0.02;
+    const out = [];
+    const draw = (pts, close, fill) => {
+        const parts = runs(pts.map((p) => surfacePoint(pose, p.lon, p.lat, f)), (_, i) => visible(pts[i].lon, pts[i].lat));
+        for (const part of parts) {
+            const whole = close && part.length === pts.length;
+            if (part.length < 2)
+                continue;
+            out.push(`<path d="${path(frame, part, whole || (fill && part.length > 3))}" fill="${fill ? stroke : "none"}" fill-opacity="${fill ? 0.16 : 0}" stroke="${stroke}" stroke-width="${n(hair)}" stroke-opacity="${fill ? 0.55 : 0.9}" stroke-linejoin="round" stroke-linecap="round"/>`);
+        }
+    };
+    const apply = (feature) => {
+        if (feature.kind === "circle")
+            draw(around(feature.lon, feature.lat, feature.radius, feature.radius), true, feature.fill === true);
+        else if (feature.kind === "oval")
+            draw(around(feature.lon, feature.lat, feature.rx, feature.ry), true, feature.fill === true);
+        else if (feature.kind === "band") {
+            const pts = [];
+            for (let lon = 0; lon <= 360; lon += 4)
+                pts.push({ lon, lat: feature.lat });
+            draw(pts, false, false);
+        }
+        else {
+            const pts = [];
+            for (let k = 0; k < feature.points.length - (feature.close === true ? 0 : 1); k += 1) {
+                const a = feature.points[k];
+                const b = feature.points[(k + 1) % feature.points.length];
+                for (let s = 0; s < 6; s += 1)
+                    pts.push({ lon: a[0] + ((b[0] - a[0]) * s) / 6, lat: a[1] + ((b[1] - a[1]) * s) / 6 });
+            }
+            const last = feature.points[feature.close === true ? 0 : feature.points.length - 1];
+            pts.push({ lon: last[0], lat: last[1] });
+            draw(pts, feature.close === true, false);
+        }
+    };
+    for (const feature of facts.features ?? [])
+        apply(feature);
+    return out.join("");
+}
+/** The rings of a planet as ellipse strokes, split into the part behind the planet and the part in front of it. */
+function ringPaths(facts, pose, frame, stroke, hair, scaleBy) {
+    const back = [];
+    const front = [];
+    if (facts.rings === undefined)
+        return { back: "", front: "" };
+    const e1 = pose.meridian;
+    const e2 = cross(pose.pole, pose.meridian);
+    const ring = (r, theta) => [r * (Math.cos(theta) * e1[0] + Math.sin(theta) * e2[0]), r * (Math.cos(theta) * e1[1] + Math.sin(theta) * e2[1]), r * (Math.cos(theta) * e1[2] + Math.sin(theta) * e2[2])];
+    const edge = (km, opacity, width) => {
+        const r = (km / facts.radiusKm) * scaleBy;
+        const pts = [];
+        for (let k = 0; k <= 120; k += 1)
+            pts.push(ring(r, (k / 120) * 2 * Math.PI));
+        for (const part of runs(pts, (p) => p[2] < 0))
+            back.push(`<path d="${path(frame, part)}" fill="none" stroke="${stroke}" stroke-opacity="${n(opacity)}" stroke-width="${n(width)}"/>`);
+        for (const part of runs(pts, (p) => p[2] >= 0))
+            front.push(`<path d="${path(frame, part)}" fill="none" stroke="${stroke}" stroke-opacity="${n(opacity)}" stroke-width="${n(width)}"/>`);
+    };
+    for (const band of facts.rings) {
+        const wide = (band.to - band.from) / facts.radiusKm > 0.02;
+        if (wide) {
+            edge(band.from, 0.35 + band.alpha * 0.4, hair);
+            edge(band.to, 0.35 + band.alpha * 0.4, hair);
+        }
+        else {
+            edge((band.from + band.to) / 2, 0.25 + band.alpha * 0.5, hair);
+        }
+    }
+    return { back: back.join(""), front: front.join("") };
+}
+/** The dark side of the disc as a filled shape, from the Sun's direction. Empty for a full disc. */
+function nightPath(pose, frame) {
+    const L = pose.light;
+    const xy = Math.hypot(L[0], L[1]);
+    if (xy < 1e-6 && L[2] > 0)
+        return "";
+    const c = Math.atan2(-L[1], -L[0]);
+    const u = [Math.cos(c - Math.PI / 2), Math.sin(c - Math.PI / 2), 0];
+    let v = cross(unit(L), u);
+    v = unit(v);
+    if (v[2] < 0)
+        v = scale(v, -1);
+    const pts = [];
+    for (let k = 0; k <= 48; k += 1) {
+        const t = (k / 48) * Math.PI;
+        pts.push([u[0] * Math.cos(t) + v[0] * Math.sin(t), u[1] * Math.cos(t) + v[1] * Math.sin(t), 0]);
+    }
+    for (let k = 1; k <= 48; k += 1) {
+        const a = c + Math.PI / 2 - (k / 48) * Math.PI;
+        pts.push([Math.cos(a), Math.sin(a), 0]);
+    }
+    return path(frame, pts, true);
+}
+function rays(frame, stroke, hair) {
+    const out = [];
+    for (let k = 0; k < 32; k += 1) {
+        const a = (k / 32) * 2 * Math.PI;
+        const long = k % 2 === 0;
+        const r0 = 1.07;
+        const r1 = long ? 1.24 : 1.15;
+        out.push(`M${n(frame.cx + Math.cos(a) * r0 * frame.r)} ${n(frame.cy + Math.sin(a) * r0 * frame.r)}L${n(frame.cx + Math.cos(a) * r1 * frame.r)} ${n(frame.cy + Math.sin(a) * r1 * frame.r)}`);
+    }
+    return `<path d="${out.join("")}" fill="none" stroke="${stroke}" stroke-width="${n(hair * 1.2)}" stroke-linecap="round" stroke-opacity="0.8"/>`;
+}
+const describe = (facts, lang, tail) => (lang === "ja" ? `${facts.name.ja}の線画${tail}` : `Line drawing of ${facts.name.en}${tail}`);
+const orbitMemo = new Map();
+/** A moon's orbit path as it is in the hour of `time`, kept so a moving picture does not work it out again. */
+function cachedOrbit(id, time) {
+    const key = `${id}:${Math.floor(time / 3_600_000)}`;
+    let path = orbitMemo.get(key);
+    if (path === undefined) {
+        if (orbitMemo.size > 64)
+            orbitMemo.clear();
+        path = orbitPath(id, time, 96);
+        orbitMemo.set(key, path);
+    }
+    return path;
+}
+function bodyGroup(id, pose, frame, o, hair, ringScale) {
+    const facts = BODIES[id];
+    const sil = silhouette(pose, facts.flattening);
+    const disc = `<ellipse cx="${n(frame.cx)}" cy="${n(frame.cy)}" rx="${n(frame.r * sil.a)}" ry="${n(frame.r * sil.b)}" transform="rotate(${n(sil.angle)} ${n(frame.cx)} ${n(frame.cy)})"`;
+    const rings = ringPaths(facts, pose, frame, o.stroke, hair, ringScale);
+    const dark = id === "sun" || facts.kind === "star" ? "" : nightPath(pose, frame);
+    const clipId = `wk-${id}-clip`;
+    return [
+        rings.back,
+        `${disc} fill="${o.paper}" stroke="${o.stroke}" stroke-width="${n(hair * 1.6)}"/>`,
+        `<clipPath id="${clipId}">${disc}/></clipPath>`,
+        `<g clip-path="url(#${clipId})">`,
+        featurePaths(facts, pose, frame, o.stroke, hair),
+        dark === "" ? "" : `<path d="${dark}" fill="${NAVY}" fill-opacity="0.62" stroke="${o.stroke}" stroke-opacity="0.35" stroke-width="${n(hair * 0.8)}" stroke-dasharray="${n(hair * 3)} ${n(hair * 3)}"/>`,
+        `</g>`,
+        id === "sun" ? rays(frame, o.stroke, hair) : "",
+        rings.front,
+    ].join("");
+}
+function poseFor(id, options) {
+    if (options.pose !== undefined)
+        return options.pose;
+    return options.time === undefined ? portrait(id, options) : apparent(id, options.time);
+}
+/**
+ * A body as a line drawing, as an SVG string: the outline (squeezed by its flattening and leaning at its axial tilt), bands and features, rings with their gaps, and the dark side
+ * dashed off. Give it a `time` to draw the body as the Earth sees it then; leave it out for a portrait. `moons: true` draws a planet with its moons on their orbits.
+ *
+ * @param id - The body's name: `sun`, a planet or a moon.
+ * @param options - The size, the pose (`tilt`, `pitch`, `phase`, `spin` or a `time`), `moons`, `fill`, the language and the colours.
+ * @returns The SVG markup, `<svg ...>` to `</svg>`.
+ *
+ * @example
+ * ```ts
+ * import { lineSvg } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const svg = lineSvg("saturn", { size: 320 });
+ * console.log(svg.startsWith("<svg"), svg.includes("Saturn"));
+ * ```
+ */
+export function lineSvg(id, options = {}) {
+    const facts = BODIES[id];
+    if (facts === undefined)
+        throw new Error(`wakusei-planets: no body called "${String(id)}"`);
+    const size = options.size ?? 320;
+    const lang = options.lang ?? "en";
+    const stroke = options.stroke ?? mix(facts.colour, "#ffffff", 0.42);
+    const paper = options.paper ?? mix(facts.colour, NAVY, id === "sun" ? 0.62 : 0.84);
+    const hair = Math.max(0.6, size / 320);
+    const head = (label) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${n(size)} ${n(size)}" width="${n(size)}" height="${n(size)}" role="img" aria-label="${label}"><title>${label}</title>`;
+    if (options.moons === true && facts.parent === undefined && id !== "sun")
+        return systemSvg(id, options, size, stroke, paper, hair, head);
+    const pose = poseFor(id, options);
+    const reach = Math.max(ringReach(facts), id === "sun" ? 1.26 : 1);
+    const fit = options.fill === undefined ? 0.94 / reach : options.fill;
+    const zoom = options.zoom ?? 1;
+    const frame = { cx: (size / 2) * (1 - (options.panX ?? 0)), cy: (size / 2) * (1 + (options.panY ?? 0)), r: (size / 2) * fit * zoom };
+    const label = describe(facts, lang, options.time === undefined ? "" : `, ${new Date(options.time).toISOString().slice(0, 16).replace("T", " ")} UTC`);
+    return `${head(label)}${bodyGroup(id, pose, frame, { stroke, paper }, hair, 1)}</svg>`;
+}
+/** A planet with its moons on their orbits, as the Earth sees it at a time. */
+function systemSvg(planet, options, size, stroke, paper, hair, head) {
+    const facts = BODIES[planet];
+    const time = options.time ?? Date.now();
+    const sys = options.moonsAt === undefined || options.pose === undefined ? system(planet, time) : undefined;
+    const pose = options.pose ?? sys.planet;
+    const lang = options.lang ?? "en";
+    const near = nearMoons(planet);
+    const reach = options.range ?? Math.max(ringReach(facts) * 1.1, ...near.map((m) => m.reach * 1.1), 1.8);
+    const all = options.moonsAt ?? sys.moons;
+    const moons = all.filter((m) => m.distance <= reach * 1.05);
+    const half = size / 2;
+    const unitPx = (half * 0.94) / reach;
+    const frame = { cx: half * (1 - (options.panX ?? 0)), cy: half * (1 + (options.panY ?? 0)), r: unitPx * (options.zoom ?? 1) };
+    const parts = [];
+    const names = [];
+    const moonPx = (id) => Math.max((BODIES[id].radiusKm / facts.radiusKm) * unitPx, size / 110);
+    // the orbits: the path each moon follows over one trip, as it is at that time
+    for (const m of moons) {
+        const flat = options.orbits?.get(m.id) ?? cachedOrbit(m.id, time);
+        const orbitPts = [];
+        for (let k = 0; k <= flat.length / 3; k += 1) {
+            const i = (k % (flat.length / 3)) * 3;
+            orbitPts.push([flat[i], flat[i + 1], flat[i + 2]]);
+        }
+        if (orbitPts.length > 2)
+            parts.push(`<path d="${path(frame, orbitPts)}" fill="none" stroke="${stroke}" stroke-opacity="0.28" stroke-width="${n(hair * 0.7)}"/>`);
+    }
+    const placed = moons.map((m) => ({ m, px: frame.cx + m.x * unitPx, py: frame.cy - m.y * unitPx }));
+    const draw = (items) => items
+        .map(({ m, px, py }) => {
+        const mf = BODIES[m.id];
+        const r = moonPx(m.id);
+        const label = options.labels === false ? "" : `<text x="${n(px + r + hair * 3)}" y="${n(py + size / 90)}" font-size="${n(size / 34)}" fill="${stroke}" fill-opacity="0.85" font-family="system-ui,sans-serif">${lang === "ja" ? mf.name.ja : mf.name.en}</text>`;
+        names.push(mf.name[lang]);
+        return `<circle cx="${n(px)}" cy="${n(py)}" r="${n(r)}" fill="${mix(mf.colour, NAVY, 0.25)}" stroke="${stroke}" stroke-width="${n(hair)}"/>${label}`;
+    })
+        .join("");
+    const behind = placed.filter(({ m }) => m.z < 0);
+    const inFront = placed.filter(({ m }) => m.z >= 0);
+    parts.push(draw(behind), bodyGroup(planet, pose, frame, { stroke, paper }, hair, 1), draw(inFront));
+    const label = lang === "ja" ? `${facts.name.ja}と衛星の線画 (${names.length})` : `Line drawing of ${facts.name.en} and its moons`;
+    return `${head(label)}${parts.join("")}</svg>`;
+}

package/dist/live.d.ts

@@ -0,0 +1,42 @@
+import { type Pose } from "./ephemeris.ts";
+import { type BodyId } from "./facts.ts";
+import { type PortraitOptions } from "./pose.ts";
+/** What a live picture is asked for. */
+export interface LiveRequest {
+    id: BodyId;
+    /** The moment at the start of the clock, in milliseconds since 1970; `undefined` for a portrait with no date. */
+    start: number | undefined;
+    /** When the clock started, in the real milliseconds of `at()`'s `now`. */
+    startedAt: number;
+    /** Simulated seconds for each real second. */
+    rate: number;
+    /** Draw the planet's moons. Needs a date; the start is taken as the real time when none is given. */
+    moons: boolean;
+    portrait: PortraitOptions;
+    /** A portrait turns eastward by this many degrees a second. */
+    turn: number;
+}
+/** A moon in the system, carried forward. */
+export interface LiveMoon {
+    id: BodyId;
+    x: number;
+    y: number;
+    z: number;
+    distance: number;
+}
+/** The picture at one moment. */
+export interface LiveFrame {
+    pose: Pose;
+    moons: readonly LiveMoon[];
+    /** The simulated moment in milliseconds since 1970, or `undefined` in a portrait. */
+    time: number | undefined;
+    /** How many full workings-out have been made so far. */
+    anchors: number;
+}
+/** The degrees a second a body's own turn advances its prime meridian (a moon that keeps one face to its planet turns once a trip). */
+export declare function turnRate(id: BodyId): number;
+/** A live picture's maths: ask `at(request, now)` as often as you like; it works out the sky about once a second. */
+export declare function createLive(): {
+    at(request: LiveRequest, now: number): LiveFrame;
+    readonly anchors: number;
+};

package/dist/live.js

@@ -0,0 +1,62 @@
+// The moving picture's maths, at a low rate: the pose and the moons are worked out in full about once a second, and in between the body's turn and each moon's walk round its
+// planet are carried forward from there. A frame costs a few turns of vectors, never an ephemeris. Pure, no DOM.
+import { ORBITS } from "./data/orbits.js";
+import { apparent, system } from "./ephemeris.js";
+import { BODIES, MOONS_OF } from "./facts.js";
+import { portrait } from "./pose.js";
+import { turn, unit, cross } from "./vec.js";
+const ANCHOR_MS = 1000;
+/** The degrees a second a body's own turn advances its prime meridian (a moon that keeps one face to its planet turns once a trip). */
+export function turnRate(id) {
+    const f = BODIES[id];
+    return (f.synchronous === true && ORBITS[id] !== undefined ? ORBITS[id].sid : f.prime.rate) / 86400;
+}
+/** The pictured moon-planet's moons, or none. */
+const moonsOfPlanet = (id) => id in MOONS_OF;
+/** A live picture's maths: ask `at(request, now)` as often as you like; it works out the sky about once a second. */
+export function createLive() {
+    let anchor;
+    let count = 0;
+    return {
+        get anchors() {
+            return count;
+        },
+        at(r, now) {
+            const wantMoons = r.moons && moonsOfPlanet(r.id);
+            const timed = r.start !== undefined || wantMoons;
+            const sim = timed ? (r.start ?? r.startedAt) + (now - r.startedAt) * r.rate : undefined;
+            const signature = `${r.id}|${r.start}|${r.startedAt}|${r.rate}|${wantMoons}|${JSON.stringify(r.portrait)}`;
+            if (anchor === undefined || anchor.signature !== signature || now - anchor.real >= ANCHOR_MS || now < anchor.real) {
+                count += 1;
+                const pose = timed ? (wantMoons ? system(r.id, sim).planet : apparent(r.id, sim)) : portrait(r.id, r.portrait);
+                let place = [];
+                let axes = [];
+                if (wantMoons) {
+                    place = system(r.id, sim).moons;
+                    const later = system(r.id, sim + 3_600_000).moons;
+                    axes = place.map((m) => {
+                        const n = later.find((l) => l.id === m.id);
+                        return unit(cross([m.x, m.y, m.z], [n.x, n.y, n.z]));
+                    });
+                }
+                anchor = { real: now, sim, pose, place, axes, signature };
+            }
+            const a = anchor;
+            const seconds = a.sim === undefined || sim === undefined ? (now - r.startedAt) / 1000 : (sim - a.sim) / 1000;
+            let pose = a.pose;
+            if (a.sim === undefined) {
+                if (r.turn !== 0)
+                    pose = { ...pose, meridian: turn(pose.meridian, pose.pole, r.turn * seconds) };
+            }
+            else if (seconds !== 0) {
+                pose = { ...pose, meridian: turn(pose.meridian, pose.pole, turnRate(r.id) * seconds) };
+            }
+            const moons = a.place.map((m, i) => {
+                const rate = Math.abs(ORBITS[m.id]?.sid ?? 0) / 86400;
+                const p = turn([m.x, m.y, m.z], a.axes[i], rate * seconds);
+                return { id: m.id, x: p[0], y: p[1], z: p[2], distance: m.distance };
+            });
+            return { pose, moons, time: sim, anchors: count };
+        },
+    };
+}

package/dist/pose.d.ts

@@ -0,0 +1,62 @@
+import { type BodyFacts, type BodyId } from "./facts.ts";
+import type { Pose } from "./ephemeris.ts";
+import { type Vec3 } from "./vec.ts";
+/**
+ * Options for a pose when no date is given. Angles are in degrees: `tilt` leans the pole on the page, `pitch` is how far the viewer looks over the pole, `phase` is the Sun–body–viewer angle and `spin` the longitude at the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { portrait, type PortraitOptions } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const options: PortraitOptions = { tilt: 20, pitch: 15, phase: 60 };
+ * console.log(portrait("jupiter", options).light.length);
+ * ```
+ */
+export interface PortraitOptions {
+    /** The axial tilt on the page: how far the north pole leans to the right of straight up. Default: the body's own tilt (turned to 120 or less). */
+    tilt?: number;
+    /** How far the viewer looks over the north pole: 0 sees the equator edge-on, 90 looks straight down at the pole. Default 12, or 22 for a body with rings. */
+    pitch?: number;
+    /** The Sun–body–viewer angle: 0 is full, 90 half, 180 new. Default 38. */
+    phase?: number;
+    /** The longitude at the middle of the disc, degrees east. Default: the longitude of the body's best-known side. */
+    spin?: number;
+}
+/**
+ * The tilt a drawing shows for a body: its obliquity, turned past 120 degrees to the other side (Venus is nearly upside down, so it is drawn nearly upright).
+ * @param facts - A body's facts.
+ * @returns The tilt in degrees to lean the drawing by.
+ *
+ * @example
+ * ```ts
+ * import { BODIES, drawnTilt } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(drawnTilt(BODIES.uranus), drawnTilt(BODIES.venus).toFixed(2));
+ * ```
+ */
+export declare const drawnTilt: (facts: BodyFacts) => number;
+/**
+ * A pose from a tilt, a pitch, a phase and a spin: the body as a portrait, with the Sun a little above the left. The same arguments always give the same pose.
+ * @param id - The body's name.
+ * @param options - The pose's tilt, pitch, phase and spin.
+ * @returns The pose, as unit vectors in the viewer's frame.
+ *
+ * @example
+ * ```ts
+ * import { portrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const pose = portrait("mars", { phase: 90 });
+ * console.log(pose.light[0] < -0.9);
+ * ```
+ */
+export declare function portrait(id: BodyId, options?: PortraitOptions): Pose;
+/** A longitude and latitude (degrees) as a point on the body, in the viewer's frame (unit radius): x right, y up, z toward the viewer. The flattening squeezes it along the pole. */
+export declare function surfacePoint(pose: Pose, lon: number, lat: number, flattening?: number): Vec3;
+/** The outward normal's z at a longitude and latitude: positive when that point faces the viewer. */
+export declare function facing(pose: Pose, lon: number, lat: number, flattening?: number): number;
+/** The silhouette of a body: its half-width, half-height along the pole's direction and the angle of the pole from straight up, clockwise, in degrees. */
+export declare function silhouette(pose: Pose, flattening: number): {
+    a: number;
+    b: number;
+    angle: number;
+};

package/dist/pose.js

@@ -0,0 +1,69 @@
+// A body's pose when no date is given: its axial tilt on the page, how far the viewer looks over its pole, and where the Sun is. Plus the turns that put a longitude
+// and latitude on the picture. Pure.
+import { BODIES } from "./facts.js";
+import { cross, dot, DEG, RAD, turn, unit } from "./vec.js";
+/**
+ * The tilt a drawing shows for a body: its obliquity, turned past 120 degrees to the other side (Venus is nearly upside down, so it is drawn nearly upright).
+ * @param facts - A body's facts.
+ * @returns The tilt in degrees to lean the drawing by.
+ *
+ * @example
+ * ```ts
+ * import { BODIES, drawnTilt } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(drawnTilt(BODIES.uranus), drawnTilt(BODIES.venus).toFixed(2));
+ * ```
+ */
+export const drawnTilt = (facts) => (facts.tiltDeg > 120 ? facts.tiltDeg - 180 : facts.tiltDeg);
+/**
+ * A pose from a tilt, a pitch, a phase and a spin: the body as a portrait, with the Sun a little above the left. The same arguments always give the same pose.
+ * @param id - The body's name.
+ * @param options - The pose's tilt, pitch, phase and spin.
+ * @returns The pose, as unit vectors in the viewer's frame.
+ *
+ * @example
+ * ```ts
+ * import { portrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const pose = portrait("mars", { phase: 90 });
+ * console.log(pose.light[0] < -0.9);
+ * ```
+ */
+export function portrait(id, options = {}) {
+    const facts = BODIES[id];
+    const roll = (options.tilt ?? drawnTilt(facts)) * RAD;
+    const pitchDeg = options.pitch ?? (facts.rings !== undefined ? 22 : 12);
+    const B = pitchDeg * RAD;
+    const pole = [Math.sin(roll) * Math.cos(B), Math.cos(roll) * Math.cos(B), Math.sin(B)];
+    const viewer = [0, 0, 1];
+    const eq = unit([viewer[0] - dot(viewer, pole) * pole[0], viewer[1] - dot(viewer, pole) * pole[1], viewer[2] - dot(viewer, pole) * pole[2]]);
+    const meridian = turn(eq, pole, -(options.spin ?? facts.showLon ?? 0));
+    const phase = (options.phase ?? 38) * RAD;
+    const lift = 14 * RAD;
+    const light = unit([-Math.sin(phase) * Math.cos(lift), Math.sin(lift), Math.cos(phase) * Math.cos(lift)]);
+    return { pole, meridian, light };
+}
+/** A longitude and latitude (degrees) as a point on the body, in the viewer's frame (unit radius): x right, y up, z toward the viewer. The flattening squeezes it along the pole. */
+export function surfacePoint(pose, lon, lat, flattening = 0) {
+    const cl = Math.cos(lat * RAD);
+    const east = cross(pose.pole, pose.meridian);
+    const x = cl * Math.cos(lon * RAD);
+    const y = cl * Math.sin(lon * RAD);
+    const z = Math.sin(lat * RAD) * (1 - flattening);
+    return [pose.meridian[0] * x + east[0] * y + pose.pole[0] * z, pose.meridian[1] * x + east[1] * y + pose.pole[1] * z, pose.meridian[2] * x + east[2] * y + pose.pole[2] * z];
+}
+/** The outward normal's z at a longitude and latitude: positive when that point faces the viewer. */
+export function facing(pose, lon, lat, flattening = 0) {
+    const cl = Math.cos(lat * RAD);
+    const east = cross(pose.pole, pose.meridian);
+    const x = cl * Math.cos(lon * RAD);
+    const y = cl * Math.sin(lon * RAD);
+    const z = Math.sin(lat * RAD) / (1 - flattening);
+    return pose.meridian[2] * x + east[2] * y + pose.pole[2] * z;
+}
+/** The silhouette of a body: its half-width, half-height along the pole's direction and the angle of the pole from straight up, clockwise, in degrees. */
+export function silhouette(pose, flattening) {
+    const c = 1 - flattening;
+    const s = pose.pole[2];
+    return { a: 1, b: Math.sqrt(c * c * (1 - s * s) + s * s), angle: Math.atan2(pose.pole[0], pose.pole[1]) * DEG };
+}

package/dist/scene/body.d.ts

@@ -0,0 +1,68 @@
+import type { Item3D, Scene3D } from "@johnmorrisdotca/kazoku-ui/renderer";
+import type * as THREE from "three";
+import type { Pose } from "../ephemeris.ts";
+import { type BodyFacts, type BodyId } from "../facts.ts";
+import { type BodyLook } from "./look.ts";
+/** The parts of three.js the bodies use: a page may hand over a module with only these (see `setThreeLoader`). */
+export type ThreeParts = Pick<typeof THREE, "AdditiveBlending" | "BufferAttribute" | "BufferGeometry" | "ClampToEdgeWrapping" | "DataTexture" | "DoubleSide" | "Line" | "LineBasicMaterial" | "LinearFilter" | "Mesh" | "NoColorSpace" | "OrthographicCamera" | "PlaneGeometry" | "RepeatWrapping" | "RGBAFormat" | "RingGeometry" | "Scene" | "ShaderMaterial" | "SphereGeometry" | "TextureLoader" | "Vector2" | "Vector3" | "WebGLRenderer">;
+/** One moon in a system view: its place in planet radii (viewer's frame) and the points of its orbit, if they changed. */
+export interface MoonDraw {
+    id: BodyId;
+    x: number;
+    y: number;
+    z: number;
+    /** The orbit as x, y, z triples in planet radii. A new array replaces the old line. */
+    orbit?: Float32Array;
+}
+/** Everything that changes how the scene looks. The element fills one in and hands it over; the scene holds no clock of its own. */
+export interface SceneState {
+    pose: Pose;
+    /** Body radii from the middle to the edge of the picture, at zoom 1. */
+    extent: number;
+    zoom: number;
+    panX: number;
+    panY: number;
+    moons?: readonly MoonDraw[];
+    /** The smallest a moon is drawn, in CSS pixels across its radius. Default 2.5. */
+    minMoonPx?: number;
+    /** The colour of the orbit lines, `#rrggbb`. */
+    orbitColour?: string;
+}
+/** The scene the shared renderer draws, with the one call that moves it. */
+export interface BodyScene extends Scene3D {
+    apply(state: SceneState): void;
+    /** What the scene is drawing now: the texture width in use, or 0 for the shader. */
+    readonly textureWidth: number;
+    readonly painted: boolean;
+}
+export interface BodyItemOptions {
+    id: BodyId;
+    look: "realistic" | "painted";
+    /** A key that changes whenever the picture would: the renderer keeps one still for each key. */
+    key: string;
+    state(): SceneState;
+    /** Where the pictures are: a folder address that ends in a slash. */
+    textureBase(): string;
+    /** Where the widths from `painted.far` up are: a folder address that ends in a slash. */
+    farBase(): string;
+    /** The widest texture worth fetching for a disc this many CSS pixels across (the element's call). */
+    wantedWidth(discPx: number): number;
+    /** The scene asks for a redraw when a sharper picture arrives. */
+    redraw(): void;
+    /** The scene tells the element which way it drew (the look can fall back to the shader). */
+    report?(note: {
+        painted: boolean;
+        width: number;
+        failed?: boolean;
+    }): void;
+}
+/** A body that has no registered look is still drawn: a lit ball in its mean colour. */
+export declare function fallbackLook(facts: BodyFacts): BodyLook;
+/**
+ * The shared-renderer item for a body: what `renderer.view(host, item)` shows. `state()` is read when the scene is built and `apply` moves it afterwards.
+ *
+ * @param T - The three.js module (the element passes the page's own).
+ * @param options - The body, the look, the key and the callbacks.
+ * @returns The item for kazoku-ui's shared renderer.
+ */
+export declare function createBodyItem(options: BodyItemOptions): Item3D<ThreeParts>;