@johnmorrisdotca/chikyu-earth 0.4.0 → 0.7.0

package/dist/markers/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The shapes a marker can be drawn as: `dot`, `ring`, `square` or `diamond`.
+ *
+ * @example
+ * ```ts
+ * import type { MarkerIcon, MarkerInput } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const icon: MarkerIcon = "diamond";
+ * const stadium: MarkerInput = { id: "camp-nou", lon: 2.12, lat: 41.38, icon, group: "Stadiums" };
+ * console.log(stadium.icon);
+ * ```
+ */
+export type MarkerIcon = "dot" | "ring" | "square" | "diamond";
+/**
+ * A place on the Earth. Chikyu ships none: the page brings its own.
+ *
+ * @example
+ * ```ts
+ * import type { MarkerInput } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const tokyo: MarkerInput = { id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities", priority: 5, data: { population: 14_000_000 } };
+ * console.log(tokyo.label);
+ * ```
+ */
+export interface MarkerInput {
+    /** Your own unique name for it. */
+    id: string;
+    /** Degrees east and north. */
+    lon: number;
+    lat: number;
+    /** Shown beside the dot when there is room; also its name for a screen reader. */
+    label?: string;
+    /** What a screen reader says instead of the label (a sentence). */
+    description?: string;
+    /** Any CSS colour. Default the accent. */
+    color?: string;
+    icon?: MarkerIcon;
+    /** Diameter in CSS pixels, 4 to 32. Default 8. */
+    size?: number;
+    /** A name for a set of markers (cities, stadiums) that can be shown or hidden together. */
+    group?: string;
+    /** Higher keeps its label when labels crowd. Default 0. */
+    priority?: number;
+    /** Yours: given back in every event. */
+    data?: unknown;
+}
+/**
+ * What the `chikyu-marker-hover`, `chikyu-marker-click` and `chikyu-marker-focus` events carry in `event.detail`. A cluster click has `marker: null` and `cluster` listing the ids in it.
+ *
+ * @example
+ * ```ts
+ * import type { MarkerEventDetail } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const on = (event: Event): void => {
+ *   const detail = (event as CustomEvent<MarkerEventDetail>).detail;
+ *   console.log(detail.marker?.label ?? `${detail.cluster?.length} places`, detail.x, detail.y);
+ * };
+ * console.log(typeof on);
+ * ```
+ */
+export interface MarkerEventDetail {
+    marker: MarkerInput | null;
+    cluster?: string[];
+    /** Where the pointer or the marker is, in CSS pixels inside the globe's box. */
+    x: number;
+    y: number;
+}
+/**
+ * One group of markers: its name, how many it holds and whether it is shown.
+ *
+ * @example
+ * ```ts
+ * import type { GroupInfo } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const show = (groups: GroupInfo[]): string => groups.map((group) => `${group.name}: ${group.count}${group.visible ? "" : " (hidden)"}`).join(", ");
+ * console.log(show([{ name: "Cities", count: 3, visible: true }]));
+ * ```
+ */
+export interface GroupInfo {
+    name: string;
+    count: number;
+    visible: boolean;
+}

package/dist/markers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/realistic/earth.d.ts

@@ -0,0 +1,81 @@
+import type * as THREE from "three";
+import type { AssetCache, Item3D } from "@johnmorrisdotca/kazoku-ui/renderer";
+import type { GeoPoint, GlobeView } from "../types.ts";
+import { lookAt } from "../view.ts";
+import type { Layer } from "./tiers.ts";
+import { type ThreeParts } from "./textures.ts";
+export type { ThreeParts };
+type Three = ThreeParts;
+/**
+ * The glow reaches this many radii from the centre; the globe at 1x is drawn to fit inside it.
+ *
+ * @example
+ * ```ts
+ * import { ATMOSPHERE_OUTER } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(ATMOSPHERE_OUTER);
+ * ```
+ */
+export declare const ATMOSPHERE_OUTER = 1.08;
+/** What the scene reads at each draw; the element changes it and asks for a draw. */
+export interface EarthModel {
+    /** The home centre; the shared controls' yaw and tilt are added to it as in the flat globe. */
+    centre: GeoPoint;
+    view: GlobeView;
+    /** The moment shown, in milliseconds since the epoch: it fixes where the Sun is and how far the clouds have drifted. */
+    time: number;
+    clouds: boolean;
+    lights: boolean;
+    /** Where the camera looked at the last draw (the element decides from it whether a new draw is worth it). */
+    drawn: {
+        view: GlobeView;
+        time: number;
+        radius: number;
+        centre: GeoPoint;
+    } | null;
+    /** The pixel ratio the textures are chosen for. */
+    ratio(): number;
+}
+export interface EarthDeps {
+    assets: AssetCache;
+    /** Ends with a slash. */
+    textureBase: () => string;
+    /** The widest texture, 4096 at most. */
+    cap: () => number;
+    /** Clouds' eastward drift against the ground, degrees an hour. */
+    drift: number;
+    invalidate: () => void;
+    onError?: (error: unknown) => void;
+    onTier?: (layer: Layer, width: number) => void;
+    /** Told at every draw where the disc is, for what is laid over it (markers). */
+    onPose?: (pose: {
+        lon: number;
+        lat: number;
+        radius: number;
+        cx: number;
+        cy: number;
+        width: number;
+        height: number;
+    }) => void;
+}
+export declare const newModel: () => EarthModel;
+/**
+ * The disc's radius in CSS pixels in a box of `width` x `height` at `zoom`: it fits the glow in the box at 1x.
+ *
+ * @param width - The box's width in CSS pixels.
+ * @param height - The box's height in CSS pixels.
+ * @param zoom - The view's zoom, 1 at Fit.
+ * @returns The radius in CSS pixels, at least 1.
+ *
+ * @example
+ * ```ts
+ * import { discRadius } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(discRadius(400, 400, 1).toFixed(1));
+ * ```
+ */
+export declare const discRadius: (width: number, height: number, zoom: number) => number;
+export { lookAt };
+/** An equirectangular sphere: +z is longitude 0 on the equator, +x east, +y north; v is 0 at the north pole (the top row of the picture). */
+export declare function sphere(three: Three, columns: number, rows: number): THREE.BufferGeometry;
+export declare function createEarthItem(model: EarthModel, deps: EarthDeps): Item3D<Three>;

package/dist/realistic/earth.js

@@ -0,0 +1,163 @@
+import { HOME_VIEW, lookAt } from "../view.js";
+import { ATMOSPHERE_FRAG, ATMOSPHERE_VERT, CLOUD_FRAG, SURFACE_FRAG, SURFACE_VERT } from "./shaders.js";
+import { subsolarPoint, unitVector } from "./sun.js";
+import { createTextureSet } from "./textures.js";
+const RAD = Math.PI / 180;
+/**
+ * The glow reaches this many radii from the centre; the globe at 1x is drawn to fit inside it.
+ *
+ * @example
+ * ```ts
+ * import { ATMOSPHERE_OUTER } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(ATMOSPHERE_OUTER);
+ * ```
+ */
+export const ATMOSPHERE_OUTER = 1.08;
+const CLOUD_RADIUS = 1.006;
+const LAYERS = ["day", "night", "clouds", "water"];
+export const newModel = () => ({
+    centre: { lon: 0, lat: 0 },
+    view: { ...HOME_VIEW },
+    time: Date.now(),
+    clouds: true,
+    lights: true,
+    drawn: null,
+    ratio: () => Math.min(globalThis.devicePixelRatio || 1, 2),
+});
+/**
+ * The disc's radius in CSS pixels in a box of `width` x `height` at `zoom`: it fits the glow in the box at 1x.
+ *
+ * @param width - The box's width in CSS pixels.
+ * @param height - The box's height in CSS pixels.
+ * @param zoom - The view's zoom, 1 at Fit.
+ * @returns The radius in CSS pixels, at least 1.
+ *
+ * @example
+ * ```ts
+ * import { discRadius } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(discRadius(400, 400, 1).toFixed(1));
+ * ```
+ */
+export const discRadius = (width, height, zoom) => Math.max(1, (Math.min(width, height) / 2 / ATMOSPHERE_OUTER - 1) * zoom);
+export { lookAt };
+/** An equirectangular sphere: +z is longitude 0 on the equator, +x east, +y north; v is 0 at the north pole (the top row of the picture). */
+export function sphere(three, columns, rows) {
+    const positions = new Float32Array((columns + 1) * (rows + 1) * 3);
+    const uvs = new Float32Array((columns + 1) * (rows + 1) * 2);
+    let p = 0;
+    let q = 0;
+    for (let j = 0; j <= rows; j += 1) {
+        const lat = (0.5 - j / rows) * Math.PI;
+        for (let i = 0; i <= columns; i += 1) {
+            const lon = (i / columns - 0.5) * 2 * Math.PI;
+            positions[p++] = Math.cos(lat) * Math.sin(lon);
+            positions[p++] = Math.sin(lat);
+            positions[p++] = Math.cos(lat) * Math.cos(lon);
+            uvs[q++] = i / columns;
+            uvs[q++] = j / rows;
+        }
+    }
+    const index = [];
+    for (let j = 0; j < rows; j += 1) {
+        for (let i = 0; i < columns; i += 1) {
+            const a = j * (columns + 1) + i;
+            const b = a + columns + 1;
+            index.push(a, b, a + 1, b, b + 1, a + 1);
+        }
+    }
+    const geometry = new three.BufferGeometry();
+    geometry.setAttribute("position", new three.BufferAttribute(positions, 3));
+    geometry.setAttribute("uv", new three.BufferAttribute(uvs, 2));
+    geometry.setIndex(index);
+    return geometry;
+}
+export function createEarthItem(model, deps) {
+    return {
+        key: "chikyu-earth:realistic",
+        async build({ three, width, height }) {
+            let size = { width, height };
+            const textures = await createTextureSet(three, LAYERS, {
+                assets: deps.assets,
+                textureBase: deps.textureBase,
+                cap: deps.cap,
+                invalidate: deps.invalidate,
+                ...(deps.onError ? { onError: deps.onError } : {}),
+                ...(deps.onTier ? { onTier: deps.onTier } : {}),
+            });
+            const uniform = textures.uniforms;
+            const sunDir = { value: new three.Vector3(1, 0, 0) };
+            const grid = sphere(three, 128, 64);
+            const surface = new three.ShaderMaterial({
+                vertexShader: SURFACE_VERT,
+                fragmentShader: SURFACE_FRAG,
+                uniforms: { dayMap: uniform.day, nightMap: uniform.night, waterMap: uniform.water, sunDir, lights: { value: 1 }, ortho: { value: 1 } },
+            });
+            const cloudShift = { value: 0 };
+            const cloudMaterial = new three.ShaderMaterial({
+                vertexShader: SURFACE_VERT,
+                fragmentShader: CLOUD_FRAG,
+                uniforms: { cloudMap: uniform.clouds, sunDir, shift: cloudShift, opacity: { value: 0.9 } },
+                transparent: true,
+                depthWrite: false,
+            });
+            const atmosphere = new three.ShaderMaterial({
+                vertexShader: ATMOSPHERE_VERT,
+                fragmentShader: ATMOSPHERE_FRAG,
+                uniforms: { sunView: sunDir, outer: { value: ATMOSPHERE_OUTER }, ortho: { value: 1 } },
+                transparent: true,
+                depthWrite: false,
+                side: three.BackSide,
+            });
+            const turned = new three.Group();
+            const earth = new three.Mesh(grid, surface);
+            const clouds = new three.Mesh(grid, cloudMaterial);
+            clouds.scale.setScalar(CLOUD_RADIUS);
+            clouds.renderOrder = 2;
+            turned.add(earth, clouds);
+            const glow = new three.Mesh(grid, atmosphere);
+            glow.scale.setScalar(ATMOSPHERE_OUTER);
+            glow.renderOrder = 1;
+            glow.frustumCulled = false;
+            const scene = new three.Scene();
+            scene.add(turned, glow);
+            const camera = new three.OrthographicCamera(-1, 1, 1, -1, 0.1, 20);
+            camera.position.set(0, 0, 5);
+            return {
+                scene,
+                camera,
+                update() {
+                    const view = model.view;
+                    const look = lookAt(model.centre, view);
+                    turned.rotation.set(look.lat * RAD, -look.lon * RAD, 0, "XYZ");
+                    const [sx, sy, sz] = unitVector(subsolarPoint(model.time));
+                    sunDir.value.set(sx, sy, sz).applyEuler(turned.rotation);
+                    cloudShift.value = -(((model.time / 3_600_000) * deps.drift) % 360) / 360;
+                    clouds.visible = model.clouds;
+                    surface.uniforms["lights"].value = model.lights ? 1 : 0;
+                    const radius = discRadius(size.width, size.height, view.zoom);
+                    camera.left = (-size.width / 2 - view.panX) / radius;
+                    camera.right = (size.width / 2 - view.panX) / radius;
+                    camera.top = (size.height / 2 + view.panY) / radius;
+                    camera.bottom = (-size.height / 2 + view.panY) / radius;
+                    camera.updateProjectionMatrix();
+                    model.drawn = { view: { ...view }, time: model.time, radius, centre: { ...model.centre } };
+                    textures.sync(radius * model.ratio());
+                    deps.onPose?.({ lon: look.lon, lat: look.lat, radius, cx: size.width / 2 + view.panX, cy: size.height / 2 + view.panY, width: size.width, height: size.height });
+                    return false;
+                },
+                resize(next, nextHeight) {
+                    size = { width: next, height: nextHeight };
+                },
+                dispose() {
+                    textures.dispose();
+                    grid.dispose();
+                    surface.dispose();
+                    cloudMaterial.dispose();
+                    atmosphere.dispose();
+                },
+            };
+        },
+    };
+}

package/dist/realistic/element.d.ts

@@ -0,0 +1,93 @@
+import type { GeoPoint, GlobeView } from "../types.ts";
+import { setThreeLoader } from "./shared.ts";
+export { setThreeLoader };
+import type { OverlayHost } from "../markers/layer.ts";
+import { type Layer } from "./tiers.ts";
+type EarthLayer = Extract<Layer, "day" | "night" | "clouds" | "water">;
+/**
+ * What the realistic Earth is doing: `loading` its pictures, `live` and drawing, `unavailable` (no WebGL), `lost` (the GPU took the context; it comes back by itself) or `idle` (another view has the page's one WebGL context; press or focus it to take it).
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarthRealistic, EarthState } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * const describe = (earth: ChikyuEarthRealistic): EarthState => earth.stats.state;
+ * console.log(typeof describe);
+ * ```
+ */
+export type EarthState = "loading" | "live" | "unavailable" | "lost" | "idle";
+/**
+ * A `time` attribute: "now" (or none) follows the clock, else an ISO date such as 2026-06-21T12:00:00Z.
+ *
+ * @param value - The attribute's text, or `null` when it is not there.
+ * @returns The moment in milliseconds since the Unix epoch, or `"now"` when the value is empty, `"now"` or not a date.
+ *
+ * @example
+ * ```ts no-run
+ * import { readTime } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * console.log(readTime("2026-06-21T12:00:00Z"), readTime(null), readTime("tomorrow"));
+ * ```
+ */
+export declare const readTime: (value: string | null) => number | "now";
+/**
+ * The `<chikyu-earth-realistic>` custom element: the Earth from space, drawn with three.js through kazoku-ui's shared renderer (one WebGL context for the page). It takes `center` (`"lon,lat"`), `time` (`now` or an ISO date; the real Sun at that moment), `clouds="off"`, `lights="off"`, `live-seconds` and `texture-base` (where the pictures are served from), and a shared view controller's camera through `setView`. It draws only when something changes, at most 30 times a second, and nothing while it is out of sight or the tab is hidden.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarthRealistic } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * const earth = document.createElement("chikyu-earth-realistic") as ChikyuEarthRealistic;
+ * earth.setAttribute("center", "139.7,35.7");
+ * earth.setAttribute("time", "2026-06-21T03:00Z");
+ * earth.setAttribute("texture-base", "/textures/");
+ * document.body.append(earth);
+ * ```
+ */
+export declare class ChikyuEarthRealistic extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /** A box laid over the Earth for markers (see `@johnmorrisdotca/chikyu-earth/markers`): where it is, the pose of the last draw, and a way to hear the next. */
+    get overlay(): OverlayHost;
+    /** Where the view starts: longitude and latitude; the shared controls' yaw and tilt turn it from there. */
+    get centre(): GeoPoint;
+    set centre(value: GeoPoint);
+    /** The moment shown: milliseconds since the epoch, or "now" to follow the clock. */
+    get time(): number | "now";
+    set time(value: number | Date | "now");
+    get clouds(): boolean;
+    set clouds(value: boolean);
+    get lights(): boolean;
+    set lights(value: boolean);
+    /** What the element is doing, for a page or a test: its state, the texture widths held, the draws made. */
+    get stats(): {
+        state: EarthState;
+        tiers: Record<EarthLayer, number>;
+        draws: number;
+        contexts: number;
+        canvas: {
+            width: number;
+            height: number;
+            pixels: number;
+        };
+        assets: {
+            entries: number;
+            refs: number;
+        };
+    };
+    /**
+     * Apply a shared view controller's camera (yaw, tilt, zoom, pan). A change under half a pixel is not drawn, a settled change always is,
+     * and draws are at most 30 a second.
+     */
+    setView(view: GlobeView, final?: boolean): void;
+    /** The view as it is (for a page that wants to read it back). */
+    get view(): GlobeView;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "chikyu-earth-realistic": ChikyuEarthRealistic;
+    }
+}