@johnmorrisdotca/chikyu-earth 0.4.0 → 0.7.0

package/dist/markers/layer.js

@@ -0,0 +1,455 @@
+// Markers over the globe, for either look: dots drawn in one pass on a 2D canvas, a few labels as real buttons, crowded places gathered into clusters.
+// It only draws when the view or the markers change (the element tells it), reads no layout to place a label, and shows no more labels than `maxLabels`.
+import { clusterPoints } from "./cluster.js";
+import { placeLabels } from "./labels.js";
+import { canvasRatio, projectAll } from "./project.js";
+const CSS = `
+.cm-canvas{position:absolute;inset:0;width:100%;height:100%;pointer-events:none}
+.cm-labels{position:absolute;inset:0;overflow:hidden;pointer-events:none}
+.cm-label{position:absolute;left:0;top:0;margin:0;padding:0 6px;height:20px;line-height:20px;font:12px/20px system-ui,-apple-system,"Segoe UI",sans-serif;color:#fff;background:rgba(7,11,18,.72);border:0;border-radius:10px;white-space:nowrap;pointer-events:none;will-change:transform}
+.cm-label:focus-visible{outline:2px solid #6cd0ff;outline-offset:1px}
+.cm-label[hidden]{display:none}
+.cm-list{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;margin:0;padding:0}
+`;
+const EDGE = 16;
+const LABEL_FONT = "12px system-ui, -apple-system, sans-serif";
+const TEXT_LIST_MAX = 200;
+/**
+ * Put markers on a globe, for either look: dots drawn in one pass on a canvas, a few labels as real buttons, crowded places gathered into clusters. It draws only when the view or the markers change, reads no layout to place a label, and shows no more labels than `maxLabels`. Hovering, clicking or focusing a marker fires `chikyu-marker-hover`, `chikyu-marker-click` and `chikyu-marker-focus` on the element, with your own `data` in the detail.
+ *
+ * @param element - `<chikyu-earth>` or `<chikyu-earth-realistic>`.
+ * @param options - The most labels, the cluster radius and the default colour; each has a default.
+ * @returns The markers: `add`, `addAll`, `update`, `remove`, `clear`, `groups`, `toggleGroup`, `stats` and `detach`.
+ *
+ * @example
+ * ```ts no-run
+ * import "@johnmorrisdotca/chikyu-earth/element";
+ * import { attachMarkers, type MarkerEventDetail } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const earth = document.querySelector("chikyu-earth")!;
+ * const markers = attachMarkers(earth);
+ * markers.add({ id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities" });
+ * earth.addEventListener("chikyu-marker-click", (event) => {
+ *   const { marker } = (event as CustomEvent<MarkerEventDetail>).detail;
+ *   console.log("chose", marker?.label);
+ * });
+ * ```
+ */
+export function attachMarkers(element, options = {}) {
+    const host = element.overlay;
+    const root = host.overlayRoot;
+    const doc = root.ownerDocument;
+    const maxLabels = options.maxLabels ?? 24;
+    const clusterRadius = options.clusterRadius ?? 28;
+    const defaultColor = options.color ?? "#6cd0ff";
+    const shadow = root.getRootNode();
+    const sheet = typeof CSSStyleSheet !== "undefined" && "adoptedStyleSheets" in doc && shadow instanceof ShadowRoot ? new CSSStyleSheet() : null;
+    let style = null;
+    if (sheet && shadow instanceof ShadowRoot) {
+        sheet.replaceSync(CSS);
+        shadow.adoptedStyleSheets = [...shadow.adoptedStyleSheets, sheet];
+    }
+    else {
+        style = doc.createElement("style");
+        style.textContent = CSS;
+        root.append(style);
+    }
+    const canvas = doc.createElement("canvas");
+    canvas.className = "cm-canvas";
+    canvas.setAttribute("aria-hidden", "true");
+    const labelBox = doc.createElement("div");
+    labelBox.className = "cm-labels";
+    const list = doc.createElement("ul");
+    list.className = "cm-list";
+    list.setAttribute("aria-label", "Places marked on the globe");
+    root.append(canvas, labelBox, list);
+    const ctx = canvas.getContext("2d");
+    const store = new Map();
+    const hidden = new Set();
+    let compiled = null;
+    let listDirty = true;
+    let renders = 0;
+    let last = host.pose;
+    let xs = new Float32Array(0);
+    let ys = new Float32Array(0);
+    let zs = new Float32Array(0);
+    const stats = { markers: 0, clusters: 0, labels: 0, renders: 0 };
+    // what the last render drew, for picking
+    let hitX = [];
+    let hitY = [];
+    let hitR = [];
+    let hitMembers = [];
+    let hitHover = null;
+    const pool = [];
+    let shown = 0;
+    const widths = new Map();
+    const compile = () => {
+        if (compiled)
+            return compiled;
+        const items = [...store.values()].filter((m) => !m.group || !hidden.has(m.group));
+        const lons = new Float64Array(items.length);
+        const lats = new Float64Array(items.length);
+        const sizes = new Float32Array(items.length);
+        items.forEach((m, i) => {
+            lons[i] = m.lon;
+            lats[i] = m.lat;
+            sizes[i] = Math.min(32, Math.max(4, m.size ?? 8));
+        });
+        compiled = { items, lons, lats, sizes };
+        if (xs.length < items.length) {
+            xs = new Float32Array(items.length);
+            ys = new Float32Array(items.length);
+            zs = new Float32Array(items.length);
+        }
+        return compiled;
+    };
+    const textWidth = (text) => {
+        let w = widths.get(text);
+        if (w === undefined) {
+            if (ctx) {
+                ctx.font = LABEL_FONT;
+                w = Math.ceil(ctx.measureText(text).width);
+            }
+            else
+                w = text.length * 7;
+            if (widths.size > 2000)
+                widths.clear();
+            widths.set(text, w);
+        }
+        return w;
+    };
+    const rebuildList = () => {
+        listDirty = false;
+        list.replaceChildren();
+        const entries = [...store.values()].filter((m) => !m.group || !hidden.has(m.group));
+        const summary = doc.createElement("li");
+        summary.textContent = `${entries.length} place${entries.length === 1 ? "" : "s"} marked on the globe`;
+        list.append(summary);
+        if (entries.length > TEXT_LIST_MAX)
+            return;
+        for (const m of entries) {
+            const li = doc.createElement("li");
+            li.textContent = m.description ?? m.label ?? `${m.lat.toFixed(1)}, ${m.lon.toFixed(1)}`;
+            list.append(li);
+        }
+    };
+    const drawIcon = (c, icon, x, y, r, color) => {
+        c.fillStyle = color;
+        c.strokeStyle = "rgba(0,0,0,.6)";
+        c.lineWidth = 1;
+        c.beginPath();
+        if (icon === "square")
+            c.rect(x - r, y - r, 2 * r, 2 * r);
+        else if (icon === "diamond") {
+            c.moveTo(x, y - r * 1.3);
+            c.lineTo(x + r * 1.3, y);
+            c.lineTo(x, y + r * 1.3);
+            c.lineTo(x - r * 1.3, y);
+            c.closePath();
+        }
+        else
+            c.arc(x, y, r, 0, Math.PI * 2);
+        if (icon === "ring") {
+            c.lineWidth = Math.max(1.5, r * 0.35);
+            c.strokeStyle = color;
+            c.stroke();
+        }
+        else {
+            c.fill();
+            c.stroke();
+        }
+    };
+    const render = (pose = last) => {
+        if (!pose || !ctx)
+            return;
+        last = pose;
+        renders += 1;
+        stats.renders = renders;
+        if (listDirty)
+            rebuildList();
+        root.style.transform = pose.transform;
+        const data = compile();
+        const ratio = canvasRatio(pose.width, pose.height, globalThis.devicePixelRatio || 1);
+        const pw = Math.max(1, Math.round(pose.width * ratio));
+        const ph = Math.max(1, Math.round(pose.height * ratio));
+        if (canvas.width !== pw || canvas.height !== ph) {
+            canvas.width = pw;
+            canvas.height = ph;
+        }
+        ctx.setTransform(pw / pose.width, 0, 0, ph / pose.height, 0, 0);
+        ctx.clearRect(0, 0, pose.width, pose.height);
+        const n = data.items.length;
+        projectAll(data.lons, data.lats, n, pose, xs, ys, zs);
+        const visible = [];
+        for (let i = 0; i < n; i += 1) {
+            if (zs[i] > 0.02 && xs[i] > -EDGE && xs[i] < pose.width + EDGE && ys[i] > -EDGE && ys[i] < pose.height + EDGE)
+                visible.push(i);
+        }
+        const groups = clusterRadius > 0 ? clusterPoints(visible, visible.length, xs, ys, clusterRadius) : visible.map((i) => ({ x: xs[i], y: ys[i], members: [i] }));
+        hitX = [];
+        hitY = [];
+        hitR = [];
+        hitMembers = [];
+        const items = [];
+        const labelled = [];
+        let clusters = 0;
+        for (const g of groups) {
+            if (g.members.length === 1) {
+                const i = g.members[0];
+                const m = data.items[i];
+                const r = data.sizes[i] / 2;
+                const edge = zs[i] < 0.15 ? 0.35 : zs[i] < 0.3 ? 0.7 : 1;
+                ctx.globalAlpha = edge;
+                drawIcon(ctx, m.icon ?? "dot", g.x, g.y, r, m.color ?? defaultColor);
+                ctx.globalAlpha = 1;
+                hitX.push(g.x);
+                hitY.push(g.y);
+                hitR.push(Math.max(10, r + 4));
+                hitMembers.push([i]);
+                if (m.label) {
+                    items.push({ x: g.x, y: g.y, r, w: textWidth(m.label) + 12, h: 20, priority: m.priority ?? 0 });
+                    labelled.push(i);
+                }
+            }
+            else {
+                clusters += 1;
+                const r = 10 + Math.min(10, Math.log2(g.members.length) * 3);
+                ctx.fillStyle = "rgba(108,208,255,.85)";
+                ctx.strokeStyle = "rgba(0,0,0,.6)";
+                ctx.lineWidth = 1;
+                ctx.beginPath();
+                ctx.arc(g.x, g.y, r, 0, Math.PI * 2);
+                ctx.fill();
+                ctx.stroke();
+                ctx.fillStyle = "#06101c";
+                ctx.font = "bold 11px system-ui, sans-serif";
+                ctx.textAlign = "center";
+                ctx.textBaseline = "middle";
+                ctx.fillText(String(g.members.length), g.x, g.y + 0.5);
+                hitX.push(g.x);
+                hitY.push(g.y);
+                hitR.push(r + 2);
+                hitMembers.push(g.members);
+            }
+        }
+        const placed = placeLabels(items, pose.width, pose.height, maxLabels);
+        for (let k = 0; k < placed.length; k += 1) {
+            const p = placed[k];
+            const m = data.items[labelled[p.item]];
+            let button = pool[k];
+            if (!button) {
+                button = doc.createElement("button");
+                button.type = "button";
+                button.className = "cm-label";
+                pool[k] = button;
+                labelBox.append(button);
+            }
+            if (button.dataset["id"] !== m.id) {
+                button.dataset["id"] = m.id;
+                button.textContent = m.label ?? "";
+                button.setAttribute("aria-label", m.description ?? m.label ?? m.id);
+            }
+            if (k >= shown)
+                button.hidden = false;
+            button.style.transform = `translate(${Math.round(p.left)}px,${Math.round(p.top)}px)`;
+        }
+        for (let k = placed.length; k < shown; k += 1) {
+            const button = pool[k];
+            if (button && !button.hidden) {
+                button.hidden = true;
+                delete button.dataset["id"];
+            }
+        }
+        shown = placed.length;
+        stats.markers = visible.length - groups.reduce((sum, g) => sum + (g.members.length > 1 ? g.members.length : 0), 0);
+        stats.clusters = clusters;
+        stats.labels = placed.length;
+    };
+    let scheduled = false;
+    const changed = () => {
+        compiled = null;
+        listDirty = true;
+        if (scheduled)
+            return;
+        scheduled = true;
+        queueMicrotask(() => {
+            scheduled = false;
+            render();
+        });
+    };
+    const unsubscribe = host.subscribe((pose) => render(pose));
+    // --- events ------------------------------------------------------------------------------------------------------------------------------------
+    const detail = (marker, x, y, cluster) => ({ marker, x, y, ...(cluster ? { cluster } : {}) });
+    const emit = (type, d) => {
+        element.dispatchEvent(new CustomEvent(type, { detail: d, bubbles: true, composed: true }));
+    };
+    const pick = (x, y) => {
+        let best = -1;
+        let bestD = Infinity;
+        for (let k = 0; k < hitX.length; k += 1) {
+            const dx = x - hitX[k];
+            const dy = y - hitY[k];
+            const d = dx * dx + dy * dy;
+            if (d <= hitR[k] * hitR[k] && d < bestD) {
+                best = k;
+                bestD = d;
+            }
+        }
+        return best;
+    };
+    const local = (event) => {
+        const rect = element.getBoundingClientRect();
+        const scale = last && rect.width > 0 ? last.width / rect.width : 1;
+        return { x: (event.clientX - rect.left) * scale, y: (event.clientY - rect.top) * scale };
+    };
+    let moveAt = 0;
+    const onMove = (event) => {
+        const now = performance.now();
+        if (now - moveAt < 33)
+            return;
+        moveAt = now;
+        const { x, y } = local(event);
+        const k = pick(x, y);
+        const id = k >= 0 && hitMembers[k].length === 1 ? (compile().items[hitMembers[k][0]]?.id ?? null) : null;
+        const key = k >= 0 ? (id ?? `cluster:${k}`) : null;
+        if (key === hitHover)
+            return;
+        hitHover = key;
+        element.toggleAttribute("data-marker-hover", key !== null);
+        emit("chikyu-marker-hover", detail(id ? (store.get(id) ?? null) : null, x, y, k >= 0 && !id ? hitMembers[k].map((i) => compile().items[i].id) : undefined));
+    };
+    const onLeave = () => {
+        if (hitHover === null)
+            return;
+        hitHover = null;
+        element.removeAttribute("data-marker-hover");
+        emit("chikyu-marker-hover", detail(null, -1, -1));
+    };
+    let downX = 0;
+    let downY = 0;
+    // The shared controls capture the pointer, so a click is told from where the press began and where the pointer is let go, seen on the window.
+    const onDown = (event) => {
+        if (event.button !== 0)
+            return;
+        downX = event.clientX;
+        downY = event.clientY;
+        window.addEventListener("pointerup", onUp, { capture: true, once: true });
+    };
+    const onUp = (event) => {
+        if (Math.hypot(event.clientX - downX, event.clientY - downY) > 6)
+            return;
+        const { x, y } = local(event);
+        const k = pick(x, y);
+        if (k < 0)
+            return;
+        const members = hitMembers[k];
+        const items = compile().items;
+        if (members.length === 1)
+            emit("chikyu-marker-click", detail(items[members[0]] ?? null, x, y));
+        else
+            emit("chikyu-marker-click", detail(null, x, y, members.map((i) => items[i].id)));
+    };
+    const onLabelClick = (event) => {
+        const id = event.target?.dataset?.["id"];
+        const m = id ? store.get(id) : undefined;
+        if (!m || !last)
+            return;
+        const p = projectAt(m);
+        emit("chikyu-marker-click", detail(m, p.x, p.y));
+    };
+    const onLabelFocus = (event) => {
+        const id = event.target?.dataset?.["id"];
+        const m = id ? store.get(id) : undefined;
+        if (!m || !last)
+            return;
+        const p = projectAt(m);
+        emit("chikyu-marker-focus", detail(m, p.x, p.y));
+    };
+    const projectAt = (m) => {
+        const k = compile().items.indexOf(m);
+        return k >= 0 ? { x: xs[k], y: ys[k] } : { x: 0, y: 0 };
+    };
+    element.addEventListener("pointermove", onMove);
+    element.addEventListener("pointerleave", onLeave);
+    element.addEventListener("pointerdown", onDown);
+    labelBox.addEventListener("click", onLabelClick);
+    labelBox.addEventListener("focusin", onLabelFocus);
+    const api = {
+        add(marker) {
+            store.set(marker.id, { ...marker });
+            changed();
+        },
+        addAll(markers) {
+            for (const marker of markers)
+                store.set(marker.id, { ...marker });
+            changed();
+        },
+        update(id, patch) {
+            const found = store.get(id);
+            if (!found)
+                return;
+            store.set(id, { ...found, ...patch, id });
+            changed();
+        },
+        remove(id) {
+            if (store.delete(id))
+                changed();
+        },
+        clear() {
+            store.clear();
+            changed();
+        },
+        get: (id) => store.get(id),
+        list: () => [...store.values()],
+        get size() {
+            return store.size;
+        },
+        groups() {
+            const counts = new Map();
+            for (const m of store.values())
+                if (m.group)
+                    counts.set(m.group, (counts.get(m.group) ?? 0) + 1);
+            for (const name of hidden)
+                if (!counts.has(name))
+                    counts.set(name, 0);
+            return [...counts].map(([name, count]) => ({ name, count, visible: !hidden.has(name) }));
+        },
+        showGroup(name) {
+            if (hidden.delete(name))
+                changed();
+        },
+        hideGroup(name) {
+            if (!hidden.has(name)) {
+                hidden.add(name);
+                changed();
+            }
+        },
+        toggleGroup(name, force) {
+            const show = force ?? hidden.has(name);
+            if (show)
+                api.showGroup(name);
+            else
+                api.hideGroup(name);
+            return show;
+        },
+        stats,
+        detach() {
+            unsubscribe();
+            element.removeEventListener("pointermove", onMove);
+            element.removeEventListener("pointerleave", onLeave);
+            element.removeEventListener("pointerdown", onDown);
+            window.removeEventListener("pointerup", onUp, true);
+            labelBox.removeEventListener("click", onLabelClick);
+            labelBox.removeEventListener("focusin", onLabelFocus);
+            canvas.remove();
+            labelBox.remove();
+            list.remove();
+            style?.remove();
+            if (sheet && shadow instanceof ShadowRoot)
+                shadow.adoptedStyleSheets = shadow.adoptedStyleSheets.filter((s) => s !== sheet);
+            root.style.transform = "";
+        },
+    };
+    render();
+    return api;
+}

package/dist/markers/project.d.ts

@@ -0,0 +1,82 @@
+/** The view: the point of the Earth at the middle of the disc, the disc's radius and its centre, in CSS pixels. */
+/**
+ * The view: the point of the Earth at the middle of the disc, the disc's radius and its centre, in CSS pixels.
+ *
+ * @example
+ * ```ts
+ * import { project, type Pose } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const pose: Pose = { lon: 10, lat: 20, radius: 100, cx: 150, cy: 150 };
+ * console.log(project(10, 20, pose));
+ * ```
+ */
+export interface Pose {
+    lon: number;
+    lat: number;
+    radius: number;
+    cx: number;
+    cy: number;
+}
+/**
+ * Project a longitude and latitude (degrees) to the screen. `z` is the cosine of the angle from the middle of the disc: above 0 the point faces
+ * the viewer, below it is on the far side. North is up.
+ *
+ * @param lon - Longitude in degrees east.
+ * @param lat - Latitude in degrees north.
+ * @param pose - The view.
+ * @returns The point's x and y in pixels and `z`, the cosine of its angle from the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { project } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const where = project(139.69, 35.69, { lon: 139.69, lat: 35.69, radius: 200, cx: 210, cy: 210 });
+ * console.log(where.x, where.y, where.z);
+ * ```
+ */
+export declare function project(lon: number, lat: number, pose: Pose): {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Project many points into flat arrays (reused between calls); `z` is the cosine used for a point's facing test.
+ *
+ * @param lons - Longitudes in degrees.
+ * @param lats - Latitudes in degrees.
+ * @param count - How many points to project.
+ * @param pose - The view.
+ * @param xs - Filled with each point's x in pixels.
+ * @param ys - Filled with each point's y in pixels.
+ * @param zs - Filled with each point's `z`: above 0 it faces the viewer.
+ *
+ * @example
+ * ```ts
+ * import { projectAll } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = new Float32Array(2);
+ * const ys = new Float32Array(2);
+ * const zs = new Float32Array(2);
+ * projectAll([0, 180], [0, 0], 2, { lon: 0, lat: 0, radius: 100, cx: 100, cy: 100 }, xs, ys, zs);
+ * console.log(zs[0], zs[1]);
+ * ```
+ */
+export declare function projectAll(lons: ArrayLike<number>, lats: ArrayLike<number>, count: number, pose: Pose, xs: Float32Array, ys: Float32Array, zs: Float32Array): void;
+/**
+ * The pixel ratio for an overlay canvas: the device's, to 2, held to 4096 a side and 6 million pixels (the same budget as the 3D canvas).
+ *
+ * @param width - The canvas's width in CSS pixels.
+ * @param height - The canvas's height in CSS pixels.
+ * @param deviceRatio - The device's pixel ratio.
+ * @param maxSide - The most pixels on a side.
+ * @param maxPixels - The most pixels in all.
+ * @returns The ratio to draw at, between 0.1 and 2.
+ *
+ * @example
+ * ```ts
+ * import { canvasRatio } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * console.log(canvasRatio(420, 420, 3), canvasRatio(5000, 3000, 2));
+ * ```
+ */
+export declare function canvasRatio(width: number, height: number, deviceRatio: number, maxSide?: number, maxPixels?: number): number;

package/dist/markers/project.js

@@ -0,0 +1,93 @@
+// Where a point on the Earth lands on a screen, for the orthographic view both looks share. Pure.
+const RAD = Math.PI / 180;
+/**
+ * Project a longitude and latitude (degrees) to the screen. `z` is the cosine of the angle from the middle of the disc: above 0 the point faces
+ * the viewer, below it is on the far side. North is up.
+ *
+ * @param lon - Longitude in degrees east.
+ * @param lat - Latitude in degrees north.
+ * @param pose - The view.
+ * @returns The point's x and y in pixels and `z`, the cosine of its angle from the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { project } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const where = project(139.69, 35.69, { lon: 139.69, lat: 35.69, radius: 200, cx: 210, cy: 210 });
+ * console.log(where.x, where.y, where.z);
+ * ```
+ */
+export function project(lon, lat, pose) {
+    const phi = lat * RAD;
+    const phi0 = pose.lat * RAD;
+    const delta = (lon - pose.lon) * RAD;
+    const cosPhi = Math.cos(phi);
+    const z = Math.sin(phi0) * Math.sin(phi) + Math.cos(phi0) * cosPhi * Math.cos(delta);
+    return {
+        x: pose.cx + pose.radius * cosPhi * Math.sin(delta),
+        y: pose.cy - pose.radius * (Math.cos(phi0) * Math.sin(phi) - Math.sin(phi0) * cosPhi * Math.cos(delta)),
+        z,
+    };
+}
+/**
+ * Project many points into flat arrays (reused between calls); `z` is the cosine used for a point's facing test.
+ *
+ * @param lons - Longitudes in degrees.
+ * @param lats - Latitudes in degrees.
+ * @param count - How many points to project.
+ * @param pose - The view.
+ * @param xs - Filled with each point's x in pixels.
+ * @param ys - Filled with each point's y in pixels.
+ * @param zs - Filled with each point's `z`: above 0 it faces the viewer.
+ *
+ * @example
+ * ```ts
+ * import { projectAll } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = new Float32Array(2);
+ * const ys = new Float32Array(2);
+ * const zs = new Float32Array(2);
+ * projectAll([0, 180], [0, 0], 2, { lon: 0, lat: 0, radius: 100, cx: 100, cy: 100 }, xs, ys, zs);
+ * console.log(zs[0], zs[1]);
+ * ```
+ */
+export function projectAll(lons, lats, count, pose, xs, ys, zs) {
+    const phi0 = pose.lat * RAD;
+    const sin0 = Math.sin(phi0);
+    const cos0 = Math.cos(phi0);
+    for (let i = 0; i < count; i += 1) {
+        const phi = lats[i] * RAD;
+        const delta = (lons[i] - pose.lon) * RAD;
+        const sinPhi = Math.sin(phi);
+        const cosPhi = Math.cos(phi);
+        const cosDelta = Math.cos(delta);
+        zs[i] = sin0 * sinPhi + cos0 * cosPhi * cosDelta;
+        xs[i] = pose.cx + pose.radius * cosPhi * Math.sin(delta);
+        ys[i] = pose.cy - pose.radius * (cos0 * sinPhi - sin0 * cosPhi * cosDelta);
+    }
+}
+/**
+ * The pixel ratio for an overlay canvas: the device's, to 2, held to 4096 a side and 6 million pixels (the same budget as the 3D canvas).
+ *
+ * @param width - The canvas's width in CSS pixels.
+ * @param height - The canvas's height in CSS pixels.
+ * @param deviceRatio - The device's pixel ratio.
+ * @param maxSide - The most pixels on a side.
+ * @param maxPixels - The most pixels in all.
+ * @returns The ratio to draw at, between 0.1 and 2.
+ *
+ * @example
+ * ```ts
+ * import { canvasRatio } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * console.log(canvasRatio(420, 420, 3), canvasRatio(5000, 3000, 2));
+ * ```
+ */
+export function canvasRatio(width, height, deviceRatio, maxSide = 4096, maxPixels = 6_000_000) {
+    let ratio = Math.min(Math.max(deviceRatio, 1), 2);
+    ratio = Math.min(ratio, maxSide / Math.max(width, 1), maxSide / Math.max(height, 1));
+    const pixels = width * height * ratio * ratio;
+    if (pixels > maxPixels)
+        ratio *= Math.sqrt(maxPixels / pixels);
+    return Math.max(0.1, ratio);
+}