@perspective-dev/viewer-charts 4.3.0

package/src/ts/layout/ticks.ts

@@ -0,0 +1,168 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+function niceNum(value: number, round: boolean): number {
+    const exp = Math.floor(Math.log10(value));
+    const frac = value / Math.pow(10, exp);
+    let nice: number;
+    if (round) {
+        if (frac < 1.5) {
+            nice = 1;
+        } else if (frac < 3) {
+            nice = 2;
+        } else if (frac < 7) {
+            nice = 5;
+        } else {
+            nice = 10;
+        }
+    } else {
+        if (frac <= 1) {
+            nice = 1;
+        } else if (frac <= 2) {
+            nice = 2;
+        } else if (frac <= 5) {
+            nice = 5;
+        } else {
+            nice = 10;
+        }
+    }
+
+    return nice * Math.pow(10, exp);
+}
+
+/**
+ * Generate an array of "nice" tick values spanning [min, max].
+ * @param min - Domain minimum
+ * @param max - Domain maximum
+ * @param targetCount - Desired number of ticks (approximate)
+ */
+export function computeNiceTicks(
+    min: number,
+    max: number,
+    targetCount: number,
+): number[] {
+    if (targetCount < 1) {
+        targetCount = 1;
+    }
+
+    const range = niceNum(max - min, false);
+    const step = niceNum(range / targetCount, true);
+    const tickMin = Math.ceil(min / step) * step;
+    const tickMax = Math.floor(max / step) * step;
+
+    const ticks: number[] = [];
+
+    // Use epsilon to avoid floating point overshoot
+    for (let t = tickMin; t <= tickMax + step * 0.001; t += step) {
+        ticks.push(t);
+    }
+
+    return ticks;
+}
+
+/**
+ * Format a numeric tick value for display.
+ * Uses K/M/B suffixes for large numbers, fixed decimals for small.
+ */
+export function formatTickValue(val: number): string {
+    const abs = Math.abs(val);
+    if (abs === 0) {
+        return "0";
+    }
+
+    if (abs >= 1e9) {
+        return (val / 1e9).toFixed(1) + "B";
+    }
+
+    if (abs >= 1e6) {
+        return (val / 1e6).toFixed(1) + "M";
+    }
+
+    if (abs >= 1e3) {
+        return (val / 1e3).toFixed(1) + "K";
+    }
+
+    if (Number.isInteger(val)) {
+        return val.toString();
+    }
+
+    if (abs >= 1) {
+        return val.toFixed(1);
+    }
+
+    return val.toFixed(2);
+}
+
+/**
+ * Format a timestamp (ms since epoch) as a human-readable date/time label.
+ * Adapts precision based on the tick spacing.
+ */
+export function formatDateTickValue(val: number, stepMs?: number): string {
+    const d = new Date(val);
+    if (isNaN(d.getTime())) {
+        return formatTickValue(val);
+    }
+
+    // If step is provided, choose precision based on tick interval
+    if (stepMs !== undefined && stepMs > 0) {
+        const DAY = 86_400_000;
+        const HOUR = 3_600_000;
+        const MINUTE = 60_000;
+
+        if (stepMs >= DAY * 28) {
+            // Monthly or longer — show year-month
+            return d.toLocaleDateString(undefined, {
+                year: "numeric",
+                month: "short",
+            });
+        }
+
+        if (stepMs >= DAY) {
+            // Daily — show month and day
+            return d.toLocaleDateString(undefined, {
+                month: "short",
+                day: "numeric",
+            });
+        }
+
+        if (stepMs >= HOUR) {
+            // Hourly
+            return d.toLocaleString(undefined, {
+                month: "short",
+                day: "numeric",
+                hour: "numeric",
+            });
+        }
+
+        if (stepMs >= MINUTE) {
+            // Minutes
+            return d.toLocaleTimeString(undefined, {
+                hour: "numeric",
+                minute: "2-digit",
+            });
+        }
+
+        // Sub-minute
+        return d.toLocaleTimeString(undefined, {
+            hour: "numeric",
+            minute: "2-digit",
+            second: "2-digit",
+        });
+    }
+
+    // Default: show date only
+    return d.toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    });
+}

package/src/ts/map/mercator.ts

@@ -0,0 +1,204 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * Web Mercator projection helpers and XYZ tile-pyramid math. Pure
+ * functions, no side effects, safe to call from any thread (including
+ * the renderer worker).
+ *
+ * Mercator output is in *meters*, not the normalized [0, 1] form that
+ * some libraries use. We feed the meter values straight into the
+ * cartesian projection matrix in `plot-layout.ts`, so the upstream
+ * domain stays in physical units and per-pixel ground resolution is a
+ * straightforward division.
+ */
+
+/**
+ * WGS84 equatorial radius in meters. Matches what every standard tile
+ * provider (OSM, CartoDB, Mapbox, ...) uses for Web Mercator.
+ */
+export const EARTH_RADIUS_M = 6378137;
+
+/**
+ * Half the world extent in Mercator meters: π · R ≈ 20037508.34. The
+ * full Mercator square is `[-WORLD_HALF, +WORLD_HALF]` on both axes.
+ */
+export const WORLD_HALF = Math.PI * EARTH_RADIUS_M;
+
+/**
+ * Maximum absolute latitude representable in Web Mercator. Beyond this
+ * the projection diverges to ±∞; tile providers don't ship tiles
+ * outside [-MAX_LAT, +MAX_LAT]. Computed as
+ * `atan(sinh(π)) · 180 / π ≈ 85.0511287798°`.
+ */
+export const MAX_LAT = 85.0511287798066;
+
+/**
+ * Project (longitude, latitude) in degrees to Web Mercator meters.
+ *
+ * Latitudes outside ±MAX_LAT return `[NaN, NaN]` so callers in the
+ * cartesian build path (which already has a post-`projectPoint` NaN
+ * guard) discard those rows without special-casing.
+ */
+export function lonLatToMercator(lon: number, lat: number): [number, number] {
+    if (lat > MAX_LAT || lat < -MAX_LAT) {
+        return [NaN, NaN];
+    }
+
+    const x = (lon * Math.PI * EARTH_RADIUS_M) / 180;
+    const latRad = (lat * Math.PI) / 180;
+    const y = EARTH_RADIUS_M * Math.log(Math.tan(Math.PI / 4 + latRad / 2));
+    return [x, y];
+}
+
+/**
+ * Inverse: Mercator meters → (lon, lat) in degrees. Used by tooltip
+ * formatting and any UI that surfaces the cursor position to the user.
+ */
+export function mercatorToLonLat(x: number, y: number): [number, number] {
+    const lon = (x * 180) / (Math.PI * EARTH_RADIUS_M);
+    const lat = (Math.atan(Math.exp(y / EARTH_RADIUS_M)) * 360) / Math.PI - 90;
+    return [lon, lat];
+}
+
+/**
+ * A single XYZ tile address.
+ */
+export interface TileId {
+    z: number;
+    x: number;
+    y: number;
+}
+
+/**
+ * Mercator extent in meters of one XYZ tile. Y is in the Mercator
+ * convention (north positive), not the tile-pyramid convention (y=0
+ * at the top); the conversion is done inside the helper.
+ */
+export interface TileExtent {
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+}
+
+/**
+ * Return the Mercator-meter bounds of an XYZ tile. Tile (0, 0) at
+ * zoom 0 covers `[-WORLD_HALF, +WORLD_HALF]` on both axes — the whole
+ * world. Each zoom level subdivides into `2^z × 2^z` equal squares.
+ */
+export function tileExtent(z: number, x: number, y: number): TileExtent {
+    const n = 1 << z;
+    const tileSize = (2 * WORLD_HALF) / n;
+    const xMin = -WORLD_HALF + x * tileSize;
+    const xMax = xMin + tileSize;
+    // Tile y=0 sits at the *top* of the pyramid (north), so flip.
+    const yMax = WORLD_HALF - y * tileSize;
+    const yMin = yMax - tileSize;
+    return { xMin, yMin, xMax, yMax };
+}
+
+/**
+ * Pick the integer zoom level whose tile pixel resolution best matches
+ * the requested Mercator-meters-per-pixel. Snaps to the next coarser
+ * level so we never undersample (a finer level would fetch tiles only
+ * to scale them down).
+ *
+ * `targetResolutionMpp` is meters per *device pixel*; the caller
+ * computes it as `(domain.xMax - domain.xMin) / plotRect.width`.
+ */
+export function pickZoom(
+    targetResolutionMpp: number,
+    tileSizePx = 256,
+    maxZoom = 19,
+): number {
+    if (!isFinite(targetResolutionMpp) || targetResolutionMpp <= 0) {
+        return 0;
+    }
+
+    // Resolution at zoom z = (2·WORLD_HALF) / (tileSizePx · 2^z).
+    // Solve for z; floor so we stay at the next coarser level when in
+    // between two levels.
+    const z = Math.log2((2 * WORLD_HALF) / (tileSizePx * targetResolutionMpp));
+    return Math.max(0, Math.min(maxZoom, Math.floor(z)));
+}
+
+/**
+ * Enumerate every visible tile at a single zoom level that intersects
+ * the given Mercator extent. Returned in left-to-right, top-to-bottom
+ * order so the layer's render loop produces a deterministic draw
+ * sequence (helps with debugging tile-load races).
+ *
+ * Tiles outside the world's `[0, 2^z)` X range are *not* wrapped —
+ * antimeridian wraparound is a v2 feature. Callers see a gap when
+ * panning past ±180° lon; tiles inside the valid range still render.
+ */
+export function tilesForExtent(extent: TileExtent, z: number): TileId[] {
+    const n = 1 << z;
+    const tileSize = (2 * WORLD_HALF) / n;
+
+    // Tile X grows east; tile Y grows south. Convert the extent's
+    // bounds accordingly.
+    const xMinTile = Math.floor((extent.xMin + WORLD_HALF) / tileSize);
+    const xMaxTile = Math.floor((extent.xMax + WORLD_HALF) / tileSize);
+    const yMinTile = Math.floor((WORLD_HALF - extent.yMax) / tileSize);
+    const yMaxTile = Math.floor((WORLD_HALF - extent.yMin) / tileSize);
+
+    const result: TileId[] = [];
+    for (let ty = yMinTile; ty <= yMaxTile; ty++) {
+        if (ty < 0 || ty >= n) {
+            continue;
+        }
+
+        for (let tx = xMinTile; tx <= xMaxTile; tx++) {
+            if (tx < 0 || tx >= n) {
+                continue;
+            }
+
+            result.push({ z, x: tx, y: ty });
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Return the parent tile (one zoom level coarser) of the given tile,
+ * along with the [0, 1] UV sub-rect that this tile occupies inside
+ * its parent. Used by the layer's "draw what we have" fallback while
+ * a missing target tile is in-flight — the parent texture is sampled
+ * with the sub-rect so the visible region keeps tile-aligned content
+ * instead of flashing blank.
+ *
+ * Returns `null` for zoom-0 tiles (no parent).
+ */
+export function parentTile(tile: TileId): {
+    parent: TileId;
+    uvMin: [number, number];
+    uvMax: [number, number];
+} | null {
+    if (tile.z <= 0) {
+        return null;
+    }
+
+    const parent: TileId = {
+        z: tile.z - 1,
+        x: tile.x >> 1,
+        y: tile.y >> 1,
+    };
+
+    const u = tile.x & 1;
+    const v = tile.y & 1;
+    const uvMin: [number, number] = [u * 0.5, v * 0.5];
+    const uvMax: [number, number] = [uvMin[0] + 0.5, uvMin[1] + 0.5];
+    return { parent, uvMin, uvMax };
+}

package/src/ts/map/tile-cache.ts

@@ -0,0 +1,96 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * Bounded LRU of `WebGLTexture` keyed by tile cache key (see
+ * `tile-loader.tileKey`). Evicts least-recently-touched entries on
+ * insert past `capacity`, deleting their GPU textures.
+ *
+ * Default capacity of 256 is enough to cover a full screen worth of
+ * tiles at zoom-1 jumps either side of the current viewport plus the
+ * parent fallbacks — at 256×256 RGBA that's ~64 MB of texture memory,
+ * which sits comfortably under the 256 MB headroom most browsers
+ * grant to a tab.
+ */
+export class TileCache {
+    private _entries = new Map<string, WebGLTexture>();
+    private readonly _capacity: number;
+
+    constructor(capacity = 256) {
+        this._capacity = capacity;
+    }
+
+    /**
+     * Fetch a texture by key. Touching an existing entry moves it to
+     * the LRU tail so it survives the next eviction sweep.
+     */
+    get(key: string): WebGLTexture | undefined {
+        const tex = this._entries.get(key);
+        if (tex !== undefined) {
+            // Re-insert to push the entry to the tail.
+            this._entries.delete(key);
+            this._entries.set(key, tex);
+        }
+
+        return tex;
+    }
+
+    /**
+     * Insert a texture under `key`. If the cache is at capacity, evict
+     * the oldest entry first (calling `gl.deleteTexture` on its GPU
+     * resource).
+     */
+    set(
+        gl: WebGL2RenderingContext | WebGLRenderingContext,
+        key: string,
+        texture: WebGLTexture,
+    ): void {
+        if (this._entries.has(key)) {
+            const old = this._entries.get(key)!;
+            gl.deleteTexture(old);
+            this._entries.delete(key);
+        }
+
+        this._entries.set(key, texture);
+        while (this._entries.size > this._capacity) {
+            const oldestKey = this._entries.keys().next().value;
+            if (oldestKey === undefined) {
+                break;
+            }
+
+            const tex = this._entries.get(oldestKey)!;
+            gl.deleteTexture(tex);
+            this._entries.delete(oldestKey);
+        }
+    }
+
+    /**
+     * Whether a key is resident. Used to gate the "kick off a fetch"
+     * branch in the layer's render loop.
+     */
+    has(key: string): boolean {
+        return this._entries.has(key);
+    }
+
+    /**
+     * Release every texture. Called on chart destroy. Safe to call
+     * with a stale `gl` reference (no-op if `deleteTexture` rejects),
+     * but in practice the caller passes the still-live worker context.
+     */
+    dispose(gl: WebGL2RenderingContext | WebGLRenderingContext): void {
+        for (const tex of this._entries.values()) {
+            gl.deleteTexture(tex);
+        }
+
+        this._entries.clear();
+    }
+}