@johnmorrisdotca/wakusei-planets 0.6.0 → 0.7.0

package/dist/portrait/model.js

@@ -0,0 +1,578 @@
+// The portrait builder's scene as plain data, and everything that can be worked out from it without a screen: where each body goes when the layout is automatic, the camera that fits them,
+// which body is under a pointer, where a dragged body snaps, the order they are drawn in, the history for undo, and the short text that keeps a scene in the address. Pure: no DOM, no three.js.
+import { ORBITS } from "../data/orbits.js";
+import { BODIES, MOONS_OF, PLANET_IDS, ringReach } from "../facts.js";
+export const ASPECTS = [["16:9", 16 / 9], ["4:3", 4 / 3], ["1:1", 1], ["3:4", 3 / 4]];
+export const MAX_ITEMS = 40;
+/** The Sun, then each planet followed by its moons nearest first: the order a layout and a row of buttons use. */
+export const ORDER = ["sun", ...PLANET_IDS.flatMap((planet) => [planet, ...(planet in MOONS_OF ? [...MOONS_OF[planet]].sort(byDistance) : [])])];
+function byDistance(a, b) {
+    return (ORBITS[a]?.a ?? 0) - (ORBITS[b]?.a ?? 0);
+}
+export const rankOf = (id) => ORDER.indexOf(id);
+/**
+ * An empty scene with the usual settings: an automatic row, readable sizes, the stars behind, the Sun upper left.
+ *
+ * @returns A new scene with no bodies.
+ *
+ * @example
+ * ```ts
+ * import { defaultPortrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(defaultPortrait().bg);
+ * ```
+ */
+export function defaultPortrait() {
+    return {
+        items: [],
+        layout: "auto",
+        arrange: "row",
+        scale: "readable",
+        moons: "auto",
+        look: "painted",
+        bg: "stars",
+        aspect: 16 / 9,
+        light: { az: 300, el: 38 },
+        labels: true,
+        orbits: true,
+        shadows: true,
+        date: undefined,
+        camera: { x: 0, y: 0, h: 1 },
+    };
+}
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+const round = (v, places = 4) => Math.round(v * 10 ** places) / 10 ** places;
+// --- sizes ---------------------------------------------------------------------------------------------------------------------------------------------
+/** How far the picture of a body reaches past its disc, in its radii: Saturn's rings, the Sun's glow. */
+export const reachOf = (id) => (id === "sun" ? 1.7 : Math.max(1, ringReach(BODIES[id]) * 1.04));
+/** Raw sizes for the bodies, in any unit, in proportion: true to scale, or squeezed (a root of the radius) with the smallest lifted to a tenth of the largest so every body can be seen. */
+export function sizesFor(ids, mode) {
+    if (mode === "true")
+        return ids.map((id) => BODIES[id].radiusKm);
+    const raw = ids.map((id) => BODIES[id].radiusKm ** 0.3);
+    const floor = 0.11 * Math.max(...raw, 0);
+    return raw.map((r) => Math.max(r, floor));
+}
+/** Groups: a planet with its moons that are in the scene, or a body alone. */
+function groups(items, moons) {
+    const out = [];
+    const owner = new Map();
+    items.forEach((item, i) => {
+        const parent = BODIES[item.body].parent;
+        const home = moons === "auto" && parent !== undefined ? owner.get(parent) : undefined;
+        if (home !== undefined)
+            home.push(i);
+        else {
+            const group = [i];
+            out.push(group);
+            owner.set(item.body, group);
+        }
+    });
+    // moons nearest first inside their planet's group
+    for (const group of out)
+        if (group.length > 1)
+            group.splice(1, group.length - 1, ...group.slice(1).sort((a, b) => byDistance(items[a].body, items[b].body)));
+    return out;
+}
+/** A planet at the left of its group and its moons in a line to the right of it, in orbit order, each clear of the last. */
+function unitOf(members, radii, ids) {
+    const first = members[0];
+    const reachFirst = radii[first] * reachOf(ids[first]);
+    const at = [0];
+    let cursor = reachFirst;
+    let maxX = reachFirst;
+    let halfH = reachFirst;
+    for (const m of members.slice(1)) {
+        const r = radii[m];
+        const x = cursor + 0.22 * radii[first] + r;
+        at.push(x);
+        cursor = x + r;
+        maxX = Math.max(maxX, x + r);
+        halfH = Math.max(halfH, r);
+    }
+    return { members, at, minX: -reachFirst, maxX, halfH };
+}
+function arrangeUnits(units, how, aspect) {
+    const n = units.length;
+    const widths = units.map((u) => u.maxX - u.minX);
+    const tallest = Math.max(...units.map((u) => u.halfH * 2), 0);
+    const gap = 0.12 * Math.max(...widths, tallest, 1e-9);
+    if (how === "grid" && n > 1) {
+        const cols = Math.max(1, Math.ceil(Math.sqrt(n * aspect)));
+        const cellW = Math.max(...widths) + gap;
+        const cellH = tallest + gap;
+        return units.map((u, i) => {
+            const col = i % cols;
+            const row = Math.floor(i / cols);
+            const rows = Math.ceil(n / cols);
+            return { ox: (col - (cols - 1) / 2) * cellW - (u.minX + u.maxX) / 2, oy: ((rows - 1) / 2 - row) * cellH };
+        });
+    }
+    const total = widths.reduce((a, b) => a + b, 0) + gap * Math.max(0, n - 1);
+    let cursor = -total / 2;
+    const out = units.map((u, i) => {
+        const left = cursor;
+        cursor += widths[i] + gap;
+        return { ox: left - u.minX, oy: 0 };
+    });
+    if (how === "arc" && n > 1) {
+        const R = total * 0.85;
+        for (const o of out)
+            o.oy = (o.ox * o.ox) / (2 * R);
+    }
+    return out;
+}
+/** The camera that holds every body with a margin: its centre and half-height. */
+export function fitCamera(placed, aspect, margin = 1.1, labels = false) {
+    if (placed.length === 0)
+        return { x: 0, y: 0, h: 1 };
+    let x0 = Infinity;
+    let x1 = -Infinity;
+    let y0 = Infinity;
+    let y1 = -Infinity;
+    for (const p of placed) {
+        x0 = Math.min(x0, p.x - p.reach);
+        x1 = Math.max(x1, p.x + p.reach);
+        y0 = Math.min(y0, p.y - p.reach);
+        y1 = Math.max(y1, p.y + p.reach);
+    }
+    if (labels)
+        y0 -= (y1 - y0) * 0.08;
+    const h = Math.max((x1 - x0) / 2 / aspect, (y1 - y0) / 2, 1e-9) * margin;
+    return { x: (x0 + x1) / 2, y: (y0 + y1) / 2, h };
+}
+/**
+ * Where every body is and how big, and the camera that holds them. A manual scene gives what it stores. An automatic one works it out (a row, an arc or a grid, a planet's moons round it in orbit
+ * order) and fits the camera, so its units are the camera's half-height.
+ *
+ * @param scene - The scene.
+ * @returns Every body placed, back to front, and the camera.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, layoutPortrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const { placed } = layoutPortrait(addBody(addBody(defaultPortrait(), "earth"), "moon"));
+ * console.log(placed.map((item) => `${item.body} ${item.x.toFixed(2)}`).join(", "));
+ * ```
+ */
+export function resolve(scene) {
+    const p = scene;
+    if (p.layout === "manual" || p.items.length === 0) {
+        return { placed: p.items.map((item, index) => ({ ...item, index, reach: item.r * reachOf(item.body) })), camera: p.camera };
+    }
+    const ids = p.items.map((item) => item.body);
+    const sizes = sizesFor(ids, p.scale);
+    const grouped = groups(p.items, p.moons);
+    const units = grouped.map((members) => unitOf(members, sizes, ids));
+    const spots = arrangeUnits(units, p.arrange, p.aspect);
+    const raw = p.items.map((item, index) => ({ ...item, index, x: 0, y: 0, r: sizes[index], reach: sizes[index] * reachOf(item.body) }));
+    units.forEach((u, k) => {
+        u.members.forEach((m, j) => {
+            raw[m].x = spots[k].ox + u.at[j];
+            raw[m].y = spots[k].oy;
+        });
+    });
+    const cam = fitCamera(raw, p.aspect, 1.1, p.labels);
+    const k = 1 / cam.h;
+    return { placed: raw.map((it) => ({ ...it, x: (it.x - cam.x) * k, y: (it.y - cam.y) * k, r: it.r * k, reach: it.reach * k })), camera: { x: 0, y: 0, h: 1 } };
+}
+// --- changing a scene ----------------------------------------------------------------------------------------------------------------------------------
+const copy = (p) => ({ ...p, items: p.items.map((i) => ({ ...i })), light: { ...p.light }, camera: { ...p.camera } });
+/** A manual layout with every body where the automatic one has it now. */
+export function freeze(p) {
+    if (p.layout === "manual")
+        return p;
+    const { placed, camera } = resolve(p);
+    const out = copy(p);
+    out.layout = "manual";
+    out.items = placed.map((q) => ({ body: q.body, x: q.x, y: q.y, r: q.r, spin: q.spin, turn: q.turn, ...(q.tilt !== undefined ? { tilt: q.tilt } : {}), ...(q.pitch !== undefined ? { pitch: q.pitch } : {}) }));
+    out.camera = camera;
+    return out;
+}
+/** The automatic layout again. */
+export function auto(p) {
+    return { ...copy(p), layout: "auto" };
+}
+const fresh = (body) => ({ body, x: 0, y: 0, r: 0.3, spin: BODIES[body].showLon ?? 0, turn: 0 });
+/** The factor between a stored radius and the size a body should be by the scene's scale, from the bodies already there (0.3 of the half-height for the largest, for an empty scene). */
+function unitSize(p, adding) {
+    const have = p.items.filter((i) => i.r > 0);
+    if (have.length === 0)
+        return 0.34 / sizesFor([adding], p.scale)[0];
+    const sizes = sizesFor(have.map((i) => i.body), p.scale);
+    const k = have.map((i, n) => i.r / sizes[n]).sort((a, b) => a - b);
+    return k[Math.floor(k.length / 2)];
+}
+/**
+ * Add a body to a scene (once), in its place in the order of the sky for an automatic layout, or at the front and to the right of the others for a manual one.
+ *
+ * @param scene - The scene to add to; it is not changed.
+ * @param body - The body's name.
+ * @returns A new scene with the body, or the same one when it is already there.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const scene = addBody(addBody(defaultPortrait(), "saturn"), "earth");
+ * console.log(scene.items.map((item) => item.body).join(", "));
+ * ```
+ */
+export function addBody(scene, body) {
+    const p = scene;
+    if (p.items.some((i) => i.body === body) || p.items.length >= MAX_ITEMS)
+        return p;
+    const out = copy(p);
+    const item = fresh(body);
+    if (p.layout === "auto") {
+        item.r = 0.3;
+        const at = out.items.findIndex((i) => rankOf(i.body) > rankOf(body));
+        out.items.splice(at < 0 ? out.items.length : at, 0, item);
+        return out;
+    }
+    const sized = sizesFor([body], p.scale)[0] * unitSize(p, body);
+    item.r = Math.max(0.006, sized);
+    const right = out.items.reduce((m, i) => Math.max(m, i.x + i.r), -Infinity);
+    item.x = out.items.length === 0 ? out.camera.x : right + item.r * 1.4 + 0.04;
+    item.y = out.items.length === 0 ? out.camera.y : out.items[out.items.length - 1].y;
+    out.items.push(item);
+    const visible = Math.abs(item.x - out.camera.x) + item.r < out.camera.h * out.aspect && Math.abs(item.y - out.camera.y) + item.r < out.camera.h;
+    if (!visible)
+        out.camera = fitCamera(resolve(out).placed, out.aspect, 1.1, out.labels);
+    return out;
+}
+export function removeBody(p, body) {
+    if (!p.items.some((i) => i.body === body))
+        return p;
+    const out = copy(p);
+    out.items = out.items.filter((i) => i.body !== body);
+    return out;
+}
+/** Add the moons of a planet that are not in the scene yet, in orbit order. */
+export function addMoons(p, planet) {
+    const moons = planet in MOONS_OF ? [...MOONS_OF[planet]].sort(byDistance) : [];
+    let out = p;
+    for (const moon of moons)
+        out = addBody(out, moon);
+    if (out === p || p.layout === "auto")
+        return out;
+    // manual: lay the new moons out round their planet the way the automatic layout does
+    const host = out.items.find((i) => i.body === planet);
+    if (host === undefined)
+        return out;
+    const copyOut = copy(out);
+    let cursor = host.x + host.r * reachOf(host.body);
+    for (const moon of moons) {
+        const item = copyOut.items.find((i) => i.body === moon);
+        if (item === undefined || p.items.some((i) => i.body === moon))
+            continue;
+        item.x = cursor + 0.22 * host.r + item.r;
+        item.y = host.y;
+        cursor = item.x + item.r;
+    }
+    return copyOut;
+}
+/** Move one body to a new place in the list: the front is the end. */
+export function moveInOrder(p, from, to) {
+    const target = clamp(to, 0, p.items.length - 1);
+    if (from === target || from < 0 || from >= p.items.length)
+        return p;
+    const out = copy(p);
+    const [item] = out.items.splice(from, 1);
+    out.items.splice(target, 0, item);
+    return out;
+}
+/** Change one body's fields. */
+export function setItem(p, index, change) {
+    if (index < 0 || index >= p.items.length)
+        return p;
+    const out = copy(p);
+    out.items[index] = { ...out.items[index], ...change };
+    if (out.items[index].tilt === undefined)
+        delete out.items[index].tilt;
+    if (out.items[index].pitch === undefined)
+        delete out.items[index].pitch;
+    return out;
+}
+/** Change the portrait's own settings. A change to manual layout keeps every body where it is on the page. */
+export function setPortrait(p, change) {
+    let out = copy(p);
+    if (change.layout === "manual")
+        out = freeze(out);
+    out = { ...out, ...change, light: { ...(change.light ?? out.light) }, camera: { ...(change.camera ?? out.camera) } };
+    out.aspect = clamp(out.aspect, 0.25, 4);
+    return out;
+}
+/** Every body sized by a scale, keeping the largest as it is (a manual layout's way to go back to true or readable sizes). */
+export function rescale(p, mode) {
+    const out = copy(p);
+    out.scale = mode;
+    if (p.items.length === 0 || p.layout === "auto")
+        return out;
+    const largest = p.items.reduce((m, i) => (i.r > m.r ? i : m), p.items[0]);
+    const base = sizesFor([largest.body], mode)[0];
+    const sizes = sizesFor(p.items.map((i) => i.body), mode);
+    out.items.forEach((item, i) => {
+        item.r = Math.max(0.004, (sizes[i] / base) * largest.r);
+    });
+    return out;
+}
+/** Move the camera to the middle of the bodies, keeping its zoom. */
+export function centreCamera(p) {
+    if (p.layout === "auto")
+        return p;
+    const fit = fitCamera(resolve(p).placed, p.aspect, 1.1, p.labels);
+    return { ...copy(p), camera: { ...p.camera, x: fit.x, y: fit.y } };
+}
+/** Zoom out or in so every body is in the picture. */
+export function fitAll(p) {
+    if (p.layout === "auto")
+        return p;
+    return { ...copy(p), camera: fitCamera(resolve(p).placed, p.aspect, 1.1, p.labels) };
+}
+// --- looking at the picture -----------------------------------------------------------------------------------------------------------------------------
+/** The scene's units to pixels: a body at the camera's centre is in the middle of a picture `width` by `height`. */
+export function toScreen(camera, width, height) {
+    const scale = height / (2 * camera.h);
+    return { px: (x) => width / 2 + (x - camera.x) * scale, py: (y) => height / 2 - (y - camera.y) * scale, scale };
+}
+/** The inverse: a pixel to the scene's units. */
+export function fromScreen(camera, width, height, x, y) {
+    const scale = height / (2 * camera.h);
+    return { x: (x - width / 2) / scale + camera.x, y: -(y - height / 2) / scale + camera.y };
+}
+/** The index of the body under a point (scene units), front first; a body smaller than `slop` is still hit within it. */
+export function hitTest(placed, x, y, slop = 0) {
+    for (let i = placed.length - 1; i >= 0; i -= 1) {
+        const p = placed[i];
+        if (Math.hypot(x - p.x, y - p.y) <= Math.max(p.r, slop))
+            return i;
+    }
+    return -1;
+}
+/** Where a body being dragged snaps: its middle and edges to the middle and edges of the others and to the middle of the picture, within `tolerance` (scene units). */
+export function snap(moving, others, centre, tolerance) {
+    const best = (own, targets) => {
+        let found;
+        for (const t of targets)
+            for (const o of own)
+                if (Math.abs(t - o) <= tolerance && (found === undefined || Math.abs(t - o) < Math.abs(found.delta)))
+                    found = { delta: t - o, at: t };
+        return found;
+    };
+    const xs = [centre.x, ...others.flatMap((o) => [o.x - o.r, o.x, o.x + o.r])];
+    const ys = [centre.y, ...others.flatMap((o) => [o.y - o.r, o.y, o.y + o.r])];
+    const sx = best([moving.x - moving.r, moving.x, moving.x + moving.r], xs);
+    const sy = best([moving.y - moving.r, moving.y, moving.y + moving.r], ys);
+    const guides = [];
+    if (sx !== undefined)
+        guides.push({ axis: "x", at: sx.at });
+    if (sy !== undefined)
+        guides.push({ axis: "y", at: sy.at });
+    return { x: moving.x + (sx?.delta ?? 0), y: moving.y + (sy?.delta ?? 0), guides };
+}
+/** The Sun's direction as a unit vector in the picture's frame (x right, y up, z toward the viewer). */
+export function lightVector(light) {
+    const az = (light.az * Math.PI) / 180;
+    const el = (light.el * Math.PI) / 180;
+    return [Math.sin(az) * Math.cos(el), Math.cos(az) * Math.cos(el), Math.sin(el)];
+}
+/** The states a scene has been through, to step back and forward over. A state is never changed, so each is kept as it is. */
+export function createHistory(initial, limit = 100) {
+    const past = [];
+    let future = [];
+    let now = initial;
+    return {
+        get current() {
+            return now;
+        },
+        get canUndo() {
+            return past.length > 0;
+        },
+        get canRedo() {
+            return future.length > 0;
+        },
+        push(next) {
+            if (next === now)
+                return;
+            past.push(now);
+            if (past.length > limit)
+                past.shift();
+            future = [];
+            now = next;
+        },
+        replace(next) {
+            now = next;
+            future = [];
+        },
+        undo() {
+            const back = past.pop();
+            if (back !== undefined) {
+                future.push(now);
+                now = back;
+            }
+            return now;
+        },
+        redo() {
+            const forward = future.pop();
+            if (forward !== undefined) {
+                past.push(now);
+                now = forward;
+            }
+            return now;
+        },
+    };
+}
+// --- the address --------------------------------------------------------------------------------------------------------------------------------------
+const LOOKS = ["line", "realistic", "painted"];
+const BACKGROUNDS = ["black", "stars", "gradient", "transparent"];
+const ARRANGES = ["row", "arc", "grid", "orbit"];
+const num = (value, fallback) => {
+    if (value === undefined || value === "")
+        return fallback;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : fallback;
+};
+const optional = (value) => {
+    if (value === undefined || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * The scene as one short piece of text that is safe in an address: fields joined by `~`, each `name:value`, then one `body_x_y_r_spin_tilt_pitch_turn` for each body, back to front. An empty scene is an empty string.
+ *
+ * @param scene - The scene.
+ * @returns The text.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, encodeScene } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(encodeScene(addBody(defaultPortrait(), "mars")));
+ * ```
+ */
+export function encodeScene(scene) {
+    const p = scene;
+    const d = defaultPortrait();
+    const fields = [];
+    if (p.layout !== d.layout)
+        fields.push(`layout:${p.layout}`);
+    if (p.arrange !== d.arrange)
+        fields.push(`arrange:${p.arrange}`);
+    if (p.scale !== d.scale)
+        fields.push(`scale:${p.scale}`);
+    if (p.moons !== d.moons)
+        fields.push(`moons:${p.moons}`);
+    if (p.look !== d.look)
+        fields.push(`look:${p.look}`);
+    if (p.bg !== d.bg)
+        fields.push(`bg:${p.bg}`);
+    if (round(p.aspect, 3) !== round(d.aspect, 3))
+        fields.push(`ratio:${round(p.aspect, 3)}`);
+    if (p.light.az !== d.light.az || p.light.el !== d.light.el)
+        fields.push(`light:${round(p.light.az, 1)},${round(p.light.el, 1)}`);
+    if (!p.labels)
+        fields.push("labels:0");
+    if (!p.orbits)
+        fields.push("orbits:0");
+    if (!p.shadows)
+        fields.push("shadows:0");
+    if (p.date !== undefined)
+        fields.push(`date:${p.date}`);
+    if (p.layout === "manual")
+        fields.push(`cam:${round(p.camera.x)},${round(p.camera.y)},${round(p.camera.h)}`);
+    for (const i of p.items) {
+        const manual = p.layout === "manual";
+        fields.push([i.body, manual ? round(i.x) : "", manual ? round(i.y) : "", manual ? round(i.r) : "", round(i.spin, 1), i.tilt === undefined ? "" : round(i.tilt, 1), i.pitch === undefined ? "" : round(i.pitch, 1), i.turn === 0 ? "" : round(i.turn, 2)].join("_"));
+    }
+    return fields.join("~");
+}
+/**
+ * The scene from its text. Anything it does not understand is left at its default and a body it does not know is dropped, so any text gives a scene.
+ *
+ * @param text - Text from `encodeScene`, or anything.
+ * @returns The scene.
+ *
+ * @example
+ * ```ts
+ * import { decodeScene } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(decodeScene("look:painted~jupiter_0_0_0.3_0").items[0]?.body);
+ * ```
+ */
+export function decodeScene(text) {
+    const p = defaultPortrait();
+    const items = [];
+    for (const field of text.split("~")) {
+        if (field === "")
+            continue;
+        const colon = field.indexOf(":");
+        if (colon > 0) {
+            const key = field.slice(0, colon);
+            const value = field.slice(colon + 1);
+            if (key === "layout")
+                p.layout = value === "manual" ? "manual" : "auto";
+            else if (key === "arrange" && ARRANGES.includes(value))
+                p.arrange = value;
+            else if (key === "scale")
+                p.scale = value === "true" ? "true" : "readable";
+            else if (key === "moons")
+                p.moons = value === "manual" ? "manual" : "auto";
+            else if (key === "look" && LOOKS.includes(value))
+                p.look = value;
+            else if (key === "bg" && BACKGROUNDS.includes(value))
+                p.bg = value;
+            else if (key === "ratio")
+                p.aspect = clamp(num(value, p.aspect), 0.25, 4);
+            else if (key === "light") {
+                const [az, el] = value.split(",");
+                p.light = { az: ((num(az, p.light.az) % 360) + 360) % 360, el: clamp(num(el, p.light.el), 0, 90) };
+            }
+            else if (key === "labels")
+                p.labels = value !== "0";
+            else if (key === "orbits")
+                p.orbits = value !== "0";
+            else if (key === "shadows")
+                p.shadows = value !== "0";
+            else if (key === "date")
+                p.date = Number.isFinite(Date.parse(value)) ? value : undefined;
+            else if (key === "cam") {
+                const [x, y, h] = value.split(",");
+                p.camera = { x: num(x, 0), y: num(y, 0), h: Math.max(1e-6, num(h, 1)) };
+            }
+            continue;
+        }
+        const [body, x, y, r, spin, tilt, pitch, turn] = field.split("_");
+        if (body === undefined || !(body in BODIES) || items.some((i) => i.body === body) || items.length >= MAX_ITEMS)
+            continue;
+        const item = { body: body, x: num(x, 0), y: num(y, 0), r: Math.max(0.0005, num(r, 0.3)), spin: num(spin, BODIES[body].showLon ?? 0), turn: clamp(num(turn, 0), -720, 720) };
+        const t = optional(tilt);
+        const pi = optional(pitch);
+        if (t !== undefined)
+            item.tilt = t;
+        if (pi !== undefined)
+            item.pitch = clamp(pi, -90, 90);
+        items.push(item);
+    }
+    p.items = items;
+    return p;
+}
+const fromList = (ids, change = {}) => ids.reduce((p, id) => addBody(p, id), { ...defaultPortrait(), ...change });
+/**
+ * Ready-made scenes to start from: a family photo of the Sun and the planets, the gas giants to scale, Jupiter and the Galileans, and the Earth and the Moon to scale.
+ *
+ * @example
+ * ```ts
+ * import { PORTRAIT_PRESETS } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(PORTRAIT_PRESETS.map((preset) => preset.id).join(", "));
+ * ```
+ */
+export const PRESETS = [
+    { id: "family", name: { en: "Family photo", ja: "家族写真" }, scene: fromList(["sun", ...PLANET_IDS], { arrange: "arc", scale: "readable", moons: "manual", orbits: false }) },
+    { id: "giants", name: { en: "Gas giants", ja: "巨大ガス惑星" }, scene: fromList(["jupiter", "saturn", "uranus", "neptune"], { arrange: "row", scale: "true", moons: "manual", bg: "gradient" }) },
+    { id: "galileans", name: { en: "Jupiter and the Galileans", ja: "木星とガリレオ衛星" }, scene: fromList(["jupiter", "io", "europa", "ganymede", "callisto"], { arrange: "row", scale: "readable", moons: "auto", orbits: true }) },
+    { id: "earthmoon", name: { en: "Earth and Moon to scale", ja: "地球と月 (大きさの比)" }, scene: fromList(["earth", "moon"], { arrange: "row", scale: "true", moons: "auto", orbits: true }) },
+];

package/dist/portrait/overlay.d.ts

@@ -0,0 +1,50 @@
+import { type Look } from "../facts.ts";
+import { type Background, type Guide, type Portrait, type Resolved } from "./model.ts";
+export interface Shapes {
+    circles: {
+        cx: number;
+        cy: number;
+        r: number;
+        kind: "orbit" | "select";
+    }[];
+    lines: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    }[];
+    texts: {
+        x: number;
+        y: number;
+        text: string;
+        size: number;
+    }[];
+}
+export interface Star {
+    x: number;
+    y: number;
+    /** Radius as a fraction of the picture's height. */
+    r: number;
+    a: number;
+}
+/** The sky's stars: the same ones every time, so a picture and its export agree. */
+export declare function starfield(count?: number): Star[];
+/** The CSS behind the picture for a background (the stars are separate gradients, so the page draws them without a script). */
+export declare function backgroundCss(bg: Background): string;
+/** Paint the background onto a 2D canvas the size of the picture. */
+export declare function paintBackground(ctx: CanvasRenderingContext2D, bg: Background, width: number, height: number): void;
+/** The orbit rings and the names for a picture of this size, and the selected body's outline and the guides when asked. */
+export declare function shapesOf(p: Portrait, resolved: Resolved, width: number, height: number, lang?: "en" | "ja", edit?: {
+    selected?: number;
+    guides?: readonly Guide[];
+}): Shapes;
+/** The shapes as SVG elements (no wrapper), in the picture's pixels. */
+export declare function shapesSvg(s: Shapes): string;
+/** The shapes on a 2D canvas. */
+export declare function drawShapes(ctx: CanvasRenderingContext2D, s: Shapes, ratio?: number): void;
+/**
+ * The portrait in the line look: one SVG, the bodies drawn one over another in the order of the list, each as a nested picture sized so its disc has the radius the layout gave it.
+ * Anything a body's rings or glow need past the disc is inside its own picture.
+ */
+export declare function lineScene(p: Portrait, resolved: Resolved, width: number, height: number, poses: readonly import("../ephemeris.ts").Pose[], lang?: "en" | "ja"): string;
+export type { Look };