@johnmorrisdotca/chikyu-earth 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.5.0
+
+The Earth from space, and markers for any place on either globe, both under a hard performance budget.
+
+### Markers
+
+- **`attachMarkers(element)`** (`@johnmorrisdotca/chikyu-earth/markers`) puts your places on `<chikyu-earth>` or `<chikyu-earth-realistic>`: add, update and remove markers at `[lon, lat]` with a label, colour, icon and size; groups (cities, stadiums) shown or hidden together; markers that turn, zoom and pan with the globe and fade on the far side; crowded places gathered into clusters; labels that make room for each other; `chikyu-marker-hover`, `-click` and `-focus` events carrying your own `data`; a button for each shown label (Tab and Enter work) and a hidden list of every place for a screen reader. Chikyu ships no places; the demo shows 22 cities and 10 stadiums (Wikidata coordinates, CC0). [docs/markers.md](docs/markers.md).
+- **Budget**, each line tested: all dots in one 2D canvas pass, and a pool of 24 label buttons, never an element per place; 5,000 markers cost 0.36 ms a view change on the flat globe; a 5,000-marker drag on the Earth from space made 117 draws in 4 s (29 a second), the markers drawn with them one for one and not at all at rest or out of sight; the overlay canvas holds the same 4096-a-side, 6 MP limit.
+- The flat element's picture now sits in a holder beside the markers' overlay (a redraw replaces only the picture), and `lookAt` moves to `view.ts`.
+
+### The Earth from space
+
+An optional realistic look, drawn with three.js through kazoku-ui's shared renderer.
+
+- **`<chikyu-earth-realistic>`** (`@johnmorrisdotca/chikyu-earth/realistic/element`): day side from NASA's Blue Marble, the cities' lights on the night side, a cloud
+  layer that drifts with the date, a sun glint on the sea, an atmosphere at the rim, and the day and night line placed by the real Sun for a date and time (now by
+  default). The same shared controls (turn, tilt, zoom, pan) and the same `setView(view, final)` as the flat globe. `time`, `clouds`, `lights`, `center`,
+  `texture-base`, `max-texture` and `live-seconds` attributes; `chikyu-ready`, `chikyu-unavailable` and `chikyu-tier` events. [docs/realistic.md](docs/realistic.md).
+- **The flat look stays**: `<chikyu-earth>` is unchanged (and gains a `centre` getter); the demo's Line, Thick and Realistic buttons choose between them, keep the
+  camera, and keep the choice, the graticule, the clouds, the lights and the time in the address (kazoku-ui's address state). Without WebGL the demo says so and
+  shows the line globe.
+- **Optional, so the base install stays small**: `three` and `@johnmorrisdotca/kazoku-ui` are optional peer dependencies; the base entry and `<chikyu-earth>` need neither.
+  The realistic element, its Sun, its scene and its shaders, with kazoku-ui's renderer, are 22.6 KB minified (9.2 KB gzipped); three.js is the page's, and the demo's
+  subset of it (`demo/three-subset.ts`) is 188 KB gzipped. Sun position: `subsolarPoint(ms)` in `@johnmorrisdotca/chikyu-earth/realistic`, tested against the almanac
+  (declination within 0.05 degree, the equation of time in the longitude).
+- **Pictures** (1.55 MB in `dist/textures/`, WebP, all NASA public domain, credited in NOTICE.md): day at 1024, 2048 and 4096; night, clouds and a water mask at 1024 and 2048.
+  The 1024 ones load first; a larger one loads when the zoom needs it (about 3 texels per pixel of the disc's radius), replaces the smaller, and is freed 4 s after the
+  zoom drops. No texture is wider than 4096 (2048 on a device with 2 GB or less); `pnpm textures` rebuilds them.
+- **Performance, each proved by `e2e/realistic.gl.ts` (Chromium, software WebGL)**: 0 draw calls and 0 animation frames in 4 s at rest; a drag at 125 moves a second
+  draws 29.3 times a second, and 2,700 `setView` calls in 2 s make 59 draws; an Auto-turn at the Earth's rate draws 0 times in 6 s; one WebGL context; the canvas on a
+  5K screen at ratio 2 is 3264 x 1835 = 5.99 MP; the textures alive grow one a layer with the zoom and return to the start after it; 0 draws and 0 frames while out of
+  sight or in a hidden tab; after removal 0 buffers, 0 programs and none of our textures remain, and the element can come back; a lost context draws nothing and then
+  recovers, not black; no WebGL gives `chikyu-unavailable`. The soak (10 minutes, 976 moves, 2,000 markers on): JS heap 7.29 to 7.80 MB after garbage collection, GPU objects 20 to 20, textures, buffers and programs the same as at the start, the draw rate 5.4 a second on average, one WebGL context, no error.
+- `pnpm test:soak` (`SOAK_MINUTES`, 10 by default; CI runs 1) turns, zooms, re-times and toggles for that long and compares the heap, the GPU objects and the draw rate with the start.
+- `pnpm screenshots` also makes the realistic pictures; `scripts/make-textures.py` makes the textures from NASA's sources.
+
 ## 0.4.0
 
 The outlines now come from chizu, the controls from kazoku-ui 0.9, and the release from the family's shared workflow.

package/NOTICE.md

@@ -16,6 +16,33 @@ Each outline's English name, Japanese name and country code come from **chizu**'
 **kuni**'s (https://github.com/johnmorrisdotca/kuni, also by John Morris) and Unicode CLDR's
 (https://www.unicode.org/license.txt) and Wikidata's (CC0). chizu's own NOTICE.md has the terms.
 
+## The realistic Earth's pictures
+
+The pictures in `textures/` (and `dist/textures/`) are made by `scripts/make-textures.py` from four NASA Earth Observatory images, resized and
+re-encoded as WebP. NASA says its content "generally are not subject to copyright in the United States" and asks that "NASA should be acknowledged as the
+source of the material" (https://www.nasa.gov/nasa-brand-center/images-and-media/, read 2026-11-02). These are NASA's own images, not third-party
+material, so no other licence applies. This package is not endorsed by NASA and uses none of NASA's insignia or logotype.
+
+| Picture | Source | Credit |
+|---|---|---|
+| `day-*.webp` | Blue Marble: Next Generation with topography and bathymetry, September 2004, 5400 x 2700 (https://eoimages.gsfc.nasa.gov/images/imagerecords/73000/73801/world.topo.bathy.200409.3x5400x2700.jpg, Visible Earth 73801) | NASA Earth Observatory (Reto Stöckli, Blue Marble Next Generation) |
+| `water-*.webp` | made by `scripts/make-textures.py` from the day picture: where it is blue and dark | as above |
+| `night-*.webp` | Earth at Night, Black Marble 2016 color map at 0.1 degree, 3600 x 1800 (https://eoimages.gsfc.nasa.gov/images/imagerecords/144000/144898/BlackMarble_2016_01deg.jpg, Visible Earth 144898) | NASA Earth Observatory, Suomi NPP VIIRS data (Miguel Roman, NASA's Goddard Space Flight Center) |
+| `clouds-*.webp` | Blue Marble clouds, 2048 x 1024 (https://eoimages.gsfc.nasa.gov/images/imagerecords/57000/57747/cloud_combined_2048.jpg, Visible Earth 57747) | NASA Earth Observatory (Reto Stöckli) |
+
+The credit names are NASA's usual lines for these series; the Visible Earth pages (now at science.nasa.gov/earth/earth-observatory) did not show a credit line in the
+text read on 2026-11-02, so check them if you need the exact wording for print.
+
+## Sun position
+
+`src/realistic/sun.ts` uses the low-precision solar position formulas of NOAA's solar calculator (https://gml.noaa.gov/grad/solcalc/, after Jean Meeus,
+*Astronomical Algorithms*). Formulas are not copyrightable; the code is this package's own and MIT.
+
+## three.js
+
+The realistic look draws with three.js (https://threejs.org, MIT, copyright the three.js authors), the page's own optional peer dependency; this package
+does not bundle or ship it.
+
 ## Projection
 
 The orthographic projection, the spherical clipping and the SVG path generation are **d3-geo**
@@ -25,7 +52,7 @@ d3-geo is the package's projection dependency.
 ## Shared view controls
 
 The turn, tilt, zoom, pan and touch controls are **kazoku-ui** (https://github.com/johnmorrisdotca/kazoku-ui),
-also by John Morris, under the MIT licence. The package has no third-party dependencies of its own.
+also by John Morris, under the MIT licence. Its shared 3D renderer draws the realistic Earth.
 
 ## Marks
 

package/README.md

@@ -46,6 +46,36 @@ Centre it yourself instead:
 <chikyu-earth center="139.7,35.7" style="thick" graticule></chikyu-earth>
 ```
 
+## The Earth from space
+
+An optional second look, for a page with room for a real picture: day and night by the real Sun, cities' lights, a sun glint on the sea, a cloud layer and the
+atmosphere at the rim, drawn with three.js through kazoku-ui's shared renderer. It is its own entry point, so the line globe above costs nothing extra.
+
+<p align="center"><img alt="The Earth from space: Asia and the Pacific by day, with clouds and the sun glint" src="docs/images/realistic-desk.png" width="560"></p>
+
+```html
+<script type="module">
+  import "@johnmorrisdotca/chikyu-earth/realistic/element";
+</script>
+<chikyu-earth-realistic center="139.7,35.7" time="2026-06-21T03:00Z" texture-base="/textures/"></chikyu-earth-realistic>
+```
+
+Needs `three` and `@johnmorrisdotca/kazoku-ui` (both optional peers) and the pictures (1.6 MB, from NASA, in `dist/textures/`). It draws nothing while nothing changes,
+at most 30 times a second while it does, in one WebGL context, with textures that grow as you zoom and are freed after. All of it, the budget and the tests:
+[docs/realistic.md](docs/realistic.md).
+
+## Markers
+
+Mark any place at `[lon, lat]` with a label, colour or icon, in groups you can show or hide, on either look. Chikyu ships no places; yours move with the globe, fade on the far side, make room
+for their labels, gather into clusters when crowded, and fire hover, click and keyboard events with your own data. One canvas pass for thousands, a pool of 24 buttons for the labels. [docs/markers.md](docs/markers.md).
+
+```ts
+import { attachMarkers } from "@johnmorrisdotca/chikyu-earth/markers";
+
+const markers = attachMarkers(document.querySelector("chikyu-earth")!);
+markers.add({ id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities" });
+```
+
 ## Controls
 
 The shared [kazoku-ui view controls](https://github.com/johnmorrisdotca/kazoku-ui) supply every hand and button:

package/dist/element.d.ts

@@ -1,7 +1,12 @@
-import type { GlobeView } from "./types.ts";
+import type { OverlayHost } from "./markers/layer.ts";
+import type { GeoPoint, GlobeView } from "./types.ts";
 export declare class ChikyuEarth extends HTMLElement {
     #private;
     static observedAttributes: string[];
+    /** Where the view is centred now: the `center` attribute, else the reader's place once the browser has answered. */
+    get centre(): GeoPoint;
+    /** A box laid over the globe for markers (see `@johnmorrisdotca/chikyu-earth/markers`): where it is, the pose of the last drawing, and a way to hear the next. */
+    get overlay(): OverlayHost;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /**

package/dist/element.js

@@ -2,7 +2,7 @@
 // it opens centred on where you are (the `center` attribute wins over geolocation). Importing registers it once.
 import { globe } from "./globe.js";
 import { cleanStyle } from "./styles.js";
-import { HOME_VIEW } from "./view.js";
+import { globeBaseScale, HOME_VIEW, lookAt } from "./view.js";
 const readCentre = (value) => {
     if (!value)
         return null;
@@ -18,6 +18,25 @@ export class ChikyuEarth extends HTMLElement {
     #centre = { lon: 0, lat: 0 };
     #view = { ...HOME_VIEW };
     #drawn = { ...HOME_VIEW };
+    #listeners = new Set();
+    #overlay;
+    #pose = null;
+    /** Where the view is centred now: the `center` attribute, else the reader's place once the browser has answered. */
+    get centre() {
+        return { ...this.#centre };
+    }
+    /** A box laid over the globe for markers (see `@johnmorrisdotca/chikyu-earth/markers`): where it is, the pose of the last drawing, and a way to hear the next. */
+    get overlay() {
+        this.#ensureShell();
+        return {
+            overlayRoot: this.#overlay,
+            pose: this.#pose,
+            subscribe: (listener) => {
+                this.#listeners.add(listener);
+                return () => this.#listeners.delete(listener);
+            },
+        };
+    }
     connectedCallback() {
         this.#centre = readCentre(this.getAttribute("center")) ?? { lon: 0, lat: 0 };
         this.#render();
@@ -59,14 +78,47 @@ export class ChikyuEarth extends HTMLElement {
         const y = this.#view.panY - this.#drawn.panY;
         svg.style.transformOrigin = "50% 50%";
         svg.style.transform = zoom === 1 && x === 0 && y === 0 ? "" : `translate(${x}px, ${y}px) scale(${zoom})`;
+        this.#publish(svg.style.transform);
+    }
+    /** The shell: the picture's holder and the overlay for markers, made once; a redraw replaces only the picture. */
+    #ensureShell() {
+        const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+        if (!this.#overlay || !root.contains(this.#overlay)) {
+            root.innerHTML = `<style>:host{display:block;position:relative}.holder svg{display:block;width:100%;height:auto}.overlay{position:absolute;inset:0;pointer-events:none;transform-origin:50% 50%}</style><div class="holder"></div><div class="overlay"></div>`;
+            this.#overlay = root.querySelector(".overlay");
+        }
+        return root;
+    }
+    #publish(transform) {
+        if (this.#listeners.size === 0) {
+            this.#pose = null;
+            return;
+        }
+        const size = Number(this.getAttribute("size")) || 320;
+        const k = (this.clientWidth || size) / size;
+        const look = lookAt(this.#centre, this.#drawn);
+        const pose = {
+            lon: look.lon,
+            lat: look.lat,
+            radius: globeBaseScale(size) * this.#drawn.zoom * k,
+            cx: (size / 2 + this.#drawn.panX) * k,
+            cy: (size / 2 + this.#drawn.panY) * k,
+            width: size * k,
+            height: size * k,
+            transform,
+        };
+        this.#pose = pose;
+        for (const listener of this.#listeners)
+            listener(pose);
     }
     #render() {
         const size = Number(this.getAttribute("size")) || 320;
         const style = cleanStyle(this.getAttribute("style"));
         const svg = globe({ size, style, centre: this.#centre, view: this.#view, graticule: this.hasAttribute("graticule") });
-        const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
-        root.innerHTML = `<style>:host{display:block}svg{display:block;width:100%;height:auto}</style>${svg}`;
+        const root = this.#ensureShell();
+        root.querySelector(".holder").innerHTML = svg;
         this.#drawn = { ...this.#view };
+        this.#publish("");
     }
 }
 if (typeof customElements !== "undefined" && !customElements.get("chikyu-earth")) {

package/dist/markers/cluster.d.ts

@@ -0,0 +1,11 @@
+export interface Cluster {
+    x: number;
+    y: number;
+    /** Indices of the points in it. */
+    members: number[];
+}
+/**
+ * Group the points `indices` (into `xs` and `ys`) by the grid cell they fall in. A cell with one point is that point alone; with more it is one cluster at their
+ * average. Order is stable: clusters come in the order their first member was seen.
+ */
+export declare function clusterPoints(indices: ArrayLike<number>, count: number, xs: ArrayLike<number>, ys: ArrayLike<number>, cell: number): Cluster[];

package/dist/markers/cluster.js

@@ -0,0 +1,26 @@
+// Crowded markers become one: points closer than a cell on the screen share a cluster. A grid, so thousands of points cost one pass. Pure.
+/**
+ * Group the points `indices` (into `xs` and `ys`) by the grid cell they fall in. A cell with one point is that point alone; with more it is one cluster at their
+ * average. Order is stable: clusters come in the order their first member was seen.
+ */
+export function clusterPoints(indices, count, xs, ys, cell) {
+    const cells = new Map();
+    const out = [];
+    for (let k = 0; k < count; k += 1) {
+        const i = indices[k];
+        const key = Math.floor(xs[i] / cell) * 100_003 + Math.floor(ys[i] / cell);
+        const found = cells.get(key);
+        if (found) {
+            const n = found.members.length;
+            found.x = (found.x * n + xs[i]) / (n + 1);
+            found.y = (found.y * n + ys[i]) / (n + 1);
+            found.members.push(i);
+        }
+        else {
+            const made = { x: xs[i], y: ys[i], members: [i] };
+            cells.set(key, made);
+            out.push(made);
+        }
+    }
+    return out;
+}

package/dist/markers/index.d.ts

@@ -0,0 +1,5 @@
+export { attachMarkers, type Markers, type MarkerOptions, type OverlayElement, type OverlayHost, type OverlayPose } from "./layer.ts";
+export { project, projectAll, canvasRatio, type Pose } from "./project.ts";
+export { clusterPoints, type Cluster } from "./cluster.ts";
+export { placeLabels, type LabelItem, type Placement } from "./labels.ts";
+export type { GroupInfo, MarkerEventDetail, MarkerIcon, MarkerInput } from "./types.ts";

package/dist/markers/index.js

@@ -0,0 +1,6 @@
+// Markers on the globe: `attachMarkers(element)` for `<chikyu-earth>` or `<chikyu-earth-realistic>`. The pure parts (projection, clusters, label placement)
+// import on a server.
+export { attachMarkers } from "./layer.js";
+export { project, projectAll, canvasRatio } from "./project.js";
+export { clusterPoints } from "./cluster.js";
+export { placeLabels } from "./labels.js";

package/dist/markers/labels.d.ts

@@ -0,0 +1,24 @@
+export interface LabelItem {
+    /** The dot's centre and radius. */
+    x: number;
+    y: number;
+    r: number;
+    /** The label's box size. */
+    w: number;
+    h: number;
+    /** Higher is placed first. */
+    priority: number;
+}
+export interface Placement {
+    /** Index into the items given. */
+    item: number;
+    /** The label box's top-left corner. */
+    left: number;
+    top: number;
+}
+/**
+ * Place up to `max` labels inside `width` x `height`. Each label is tried to the right of its dot, then to the left, above and below; the first spot that is inside
+ * and free of the labels already placed wins. Items are taken highest priority first (a tie keeps the order given). The cost is the number of items times at most
+ * four tries against a grid of what is placed.
+ */
+export declare function placeLabels(items: readonly LabelItem[], width: number, height: number, max: number, cell?: number): Placement[];

package/dist/markers/labels.js

@@ -0,0 +1,52 @@
+// Which labels to show: the most important first, each beside its dot, none over another label or a dot's label slot already taken. Pure.
+const GAP = 3;
+/**
+ * Place up to `max` labels inside `width` x `height`. Each label is tried to the right of its dot, then to the left, above and below; the first spot that is inside
+ * and free of the labels already placed wins. Items are taken highest priority first (a tie keeps the order given). The cost is the number of items times at most
+ * four tries against a grid of what is placed.
+ */
+export function placeLabels(items, width, height, max, cell = 64) {
+    const order = items.map((_, i) => i).sort((a, b) => items[b].priority - items[a].priority || a - b);
+    const grid = new Map();
+    const placed = [];
+    const keys = (box) => {
+        const out = [];
+        for (let gx = Math.floor(box.l / cell); gx <= Math.floor(box.r / cell); gx += 1)
+            for (let gy = Math.floor(box.t / cell); gy <= Math.floor(box.b / cell); gy += 1)
+                out.push(gx * 100_003 + gy);
+        return out;
+    };
+    const free = (box) => {
+        for (const key of keys(box))
+            for (const other of grid.get(key) ?? [])
+                if (box.l < other.r && box.r > other.l && box.t < other.b && box.b > other.t)
+                    return false;
+        return true;
+    };
+    for (const index of order) {
+        if (placed.length >= max)
+            break;
+        const it = items[index];
+        const tries = [
+            [it.x + it.r + GAP, it.y - it.h / 2],
+            [it.x - it.r - GAP - it.w, it.y - it.h / 2],
+            [it.x - it.w / 2, it.y - it.r - GAP - it.h],
+            [it.x - it.w / 2, it.y + it.r + GAP],
+        ];
+        for (const [left, top] of tries) {
+            const box = { l: left, t: top, r: left + it.w, b: top + it.h };
+            if (box.l < 0 || box.t < 0 || box.r > width || box.b > height || !free(box))
+                continue;
+            for (const key of keys(box)) {
+                const list = grid.get(key);
+                if (list)
+                    list.push(box);
+                else
+                    grid.set(key, [box]);
+            }
+            placed.push({ item: index, left, top });
+            break;
+        }
+    }
+    return placed;
+}

package/dist/markers/layer.d.ts

@@ -0,0 +1,49 @@
+import { type Pose } from "./project.ts";
+import type { GroupInfo, MarkerInput } from "./types.ts";
+/** The view as an element tells it: the Pose, the size of the box it is drawn in, and the CSS transform its picture carries between redraws. */
+export interface OverlayPose extends Pose {
+    width: number;
+    height: number;
+    transform: string;
+}
+/** What an element gives the markers: a box laid over its view, the pose of its last draw, and a way to hear the next ones. */
+export interface OverlayHost {
+    readonly overlayRoot: HTMLElement;
+    readonly pose: OverlayPose | null;
+    subscribe(listener: (pose: OverlayPose) => void): () => void;
+}
+export interface MarkerOptions {
+    /** Most labels shown at once (24). */
+    maxLabels?: number;
+    /** Gather markers closer than this many pixels into a cluster (28); 0 turns clustering off. */
+    clusterRadius?: number;
+    /** The colour of a marker with none of its own. */
+    color?: string;
+}
+export interface Markers {
+    add(marker: MarkerInput): void;
+    addAll(markers: readonly MarkerInput[]): void;
+    update(id: string, patch: Partial<Omit<MarkerInput, "id">>): void;
+    remove(id: string): void;
+    clear(): void;
+    get(id: string): MarkerInput | undefined;
+    list(): MarkerInput[];
+    readonly size: number;
+    groups(): GroupInfo[];
+    showGroup(name: string): void;
+    hideGroup(name: string): void;
+    /** Show it if hidden and hide it if shown (or set it with `force`). Returns whether it is shown. */
+    toggleGroup(name: string, force?: boolean): boolean;
+    /** Markers and clusters drawn at the last render (for a page or a test). */
+    readonly stats: {
+        markers: number;
+        clusters: number;
+        labels: number;
+        renders: number;
+    };
+    detach(): void;
+}
+export type OverlayElement = HTMLElement & {
+    overlay: OverlayHost;
+};
+export declare function attachMarkers(element: OverlayElement, options?: MarkerOptions): Markers;