@tangram.gl/basemap-layers 0.0.0-stage → 0.0.1

package/src/glyph-store.ts

@@ -0,0 +1,326 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {GLYPH_RANGE_SIZE, parseGlyphRange} from './glyph-pbf';
+import type {Glyph} from './glyph-pbf';
+
+/** Options for a {@link GlyphStore}. */
+export type GlyphStoreOptions = {
+  /** The style's `glyphs` URL, with `{fontstack}` and `{range}`. */
+  url: string;
+  /** Base URL that a relative `glyphs` URL resolves against, normally the style URL. */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  fetchOptions?: RequestInit;
+};
+
+/** The highest code point of a glyph range, as in MapLibre GL JS. */
+const MAX_CODE_POINT = 0xffff;
+
+/**
+ * Bound on the font stacks a store keeps glyphs for: stacks come from untrusted style and tile
+ * data. When full, the stack used least recently is dropped, and loaded again if asked for,
+ * unless a consumer retains it (see {@link GlyphStore.retain}).
+ */
+export const MAX_GLYPH_STACKS = 64;
+
+/** Bound on the font stacks one consumer, such as a label layer, can retain. */
+export const MAX_RETAINED_GLYPH_STACKS = 2 * MAX_GLYPH_STACKS;
+
+/**
+ * Bound on the font stacks all the consumers of a store can retain together: the store never
+ * holds more than these, or {@link MAX_GLYPH_STACKS} when more.
+ */
+export const MAX_STORE_RETAINED_GLYPH_STACKS = 4 * MAX_GLYPH_STACKS;
+
+/**
+ * Whether MapLibre GL JS draws a character with the browser's fonts rather than the style's
+ * glyphs: CJK ideographs, hangul, hiragana and katakana, by default (`localIdeographFontFamily`).
+ */
+export function isLocalGlyph(codePoint: number): boolean {
+  return /\p{Ideo}|\p{sc=Hang}|\p{sc=Hira}|\p{sc=Kana}/u.test(String.fromCodePoint(codePoint));
+}
+
+/** The glyphs of one font stack: each loaded range, by its index, as a map from code point. */
+type StackEntry = {
+  ranges: Map<number, Map<number, Glyph>>;
+  requests: Map<number, Promise<void>>;
+};
+
+/**
+ * The glyph ranges of a style's `glyphs` URL, loaded per font stack and range as labels need
+ * them, as MapLibre GL JS loads them. A range that fails to load holds no glyphs, so its
+ * characters are not drawn, as in MapLibre.
+ */
+let lastStoreId = 0;
+
+export class GlyphStore {
+  /**
+   * Names this store among others, as of a style loaded again: a new store for the same URL holds
+   * none of the glyphs this one loaded.
+   */
+  readonly id = ++lastStoreId;
+  readonly url: string;
+  private readonly fetch: typeof fetch;
+  private readonly fetchOptions?: RequestInit;
+  private readonly stacks = new Map<string, StackEntry>();
+  /** The font stacks each consumer retains (see `retain`). */
+  private readonly retained = new Map<object, Set<string>>();
+  /** The number of consumers that retain each font stack retained. */
+  private readonly retainCounts = new Map<string, number>();
+  /** Called once when a consumer next gives back a font stack (see `onRetainedFreed`). */
+  private readonly freedListeners = new Map<object, () => void>();
+
+  constructor({url, baseUrl, fetch: fetchFn, fetchOptions}: GlyphStoreOptions) {
+    this.url = resolveGlyphsUrl(url, baseUrl);
+    this.fetch = fetchFn || ((...args: Parameters<typeof fetch>) => fetch(...args));
+    this.fetchOptions = fetchOptions;
+  }
+
+  /**
+   * The glyph of a code point: `undefined` while its range is not loaded, `null` when the range
+   * has no glyph for it.
+   */
+  getGlyph(fontStack: string, codePoint: number): Glyph | null | undefined {
+    const range = this.getStack(fontStack, false)?.ranges.get(getGlyphRange(codePoint));
+    return range ? (range.get(codePoint) ?? null) : undefined;
+  }
+
+  /** Whether the ranges of every code point of `text` are loaded, except local glyphs. */
+  hasGlyphs(fontStack: string, text: string): boolean {
+    const stack = this.getStack(fontStack, false);
+    for (const character of text) {
+      const codePoint = character.codePointAt(0)!;
+      if (codePoint <= MAX_CODE_POINT && !isLocalGlyph(codePoint)) {
+        if (!stack?.ranges.has(getGlyphRange(codePoint))) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Loads the ranges of the code points of `texts` that are not loaded yet. Resolves when they
+   * are, or have failed; returns null when there is nothing to load.
+   */
+  load(fontStack: string, texts: Iterable<string>): Promise<void> | null {
+    const stack = this.getStack(fontStack, true)!;
+    const pending = new Set<Promise<void>>();
+    for (const text of texts) {
+      for (const character of text) {
+        const codePoint = character.codePointAt(0)!;
+        if (codePoint > MAX_CODE_POINT || isLocalGlyph(codePoint)) {
+          continue;
+        }
+        const range = getGlyphRange(codePoint);
+        if (stack.ranges.has(range)) {
+          continue;
+        }
+        let request = stack.requests.get(range);
+        if (!request) {
+          request = this.loadRange(fontStack, range).then(glyphs => {
+            stack.ranges.set(range, glyphs);
+            stack.requests.delete(range);
+          });
+          stack.requests.set(range, request);
+        }
+        pending.add(request);
+      }
+    }
+    return pending.size ? Promise.all(pending).then(() => {}) : null;
+  }
+
+  /**
+   * Keeps the glyphs of `fontStack` for `owner` until it gives the stack back (see `retainOnly`
+   * and `release`). A label layer retains the font stack of each label it draws or waits for
+   * before it loads any, so that loading some of them does not drop the others: a batch of
+   * labels in more than {@link MAX_GLYPH_STACKS} font stacks could otherwise never load.
+   *
+   * Returns false when the stack cannot be retained: `owner` retains
+   * {@link MAX_RETAINED_GLYPH_STACKS} stacks already, or the store's consumers
+   * {@link MAX_STORE_RETAINED_GLYPH_STACKS}. Font stacks come from untrusted tile data, so
+   * those bounds hold whatever a tile names; a label layer leaves the labels of a font stack it
+   * cannot retain undrawn, as those of a glyph range that fails to load.
+   */
+  retain(owner: object, fontStack: string): boolean {
+    let owned = this.retained.get(owner);
+    if (owned?.has(fontStack)) {
+      return true;
+    }
+    const count = this.retainCounts.get(fontStack) || 0;
+    if (
+      (owned?.size ?? 0) >= MAX_RETAINED_GLYPH_STACKS ||
+      (!count && this.retainCounts.size >= MAX_STORE_RETAINED_GLYPH_STACKS)
+    ) {
+      return false;
+    }
+    if (!owned) {
+      owned = new Set();
+      this.retained.set(owner, owned);
+    }
+    owned.add(fontStack);
+    this.retainCounts.set(fontStack, count + 1);
+    return true;
+  }
+
+  /** Gives back the font stacks `owner` retains other than `fontStacks` (see `retain`). */
+  retainOnly(owner: object, fontStacks: ReadonlySet<string>): void {
+    const owned = this.retained.get(owner);
+    if (!owned) {
+      return;
+    }
+    let freed = false;
+    for (const fontStack of owned) {
+      if (!fontStacks.has(fontStack)) {
+        owned.delete(fontStack);
+        this.unretain(fontStack);
+        freed = true;
+      }
+    }
+    if (!owned.size) {
+      this.retained.delete(owner);
+    }
+    this.evict();
+    if (freed) {
+      this.generation++;
+      const listeners = [...this.freedListeners.values()];
+      this.freedListeners.clear();
+      for (const listener of listeners) {
+        listener();
+      }
+    }
+  }
+
+  /** Gives back the font stacks `owner` retains (see `retain`). */
+  release(owner: object): void {
+    this.freedListeners.delete(owner);
+    this.retainOnly(owner, new Set());
+  }
+
+  /**
+   * Counts the times a consumer gave back font stacks: a `retain` refused before may succeed
+   * once it has changed.
+   */
+  generation = 0;
+
+  /**
+   * Calls `listener` once, the next time a consumer gives back font stacks, in place of the
+   * listener `owner` set before; null removes it. A label layer whose font stacks were refused
+   * updates again then, to retain and load them.
+   */
+  onRetainedFreed(owner: object, listener: (() => void) | null): void {
+    if (listener) {
+      this.freedListeners.set(owner, listener);
+    } else {
+      this.freedListeners.delete(owner);
+    }
+  }
+
+  /**
+   * The URL of a range: the font names of the stack, each URL-encoded, joined by commas. Font
+   * stacks can come from tile data (a data-driven `text-font`), so a name cannot add path
+   * segments, a query or a fragment to the URL.
+   */
+  getRangeUrl(fontStack: string, range: number): string {
+    const begin = range * GLYPH_RANGE_SIZE;
+    // `encodeURIComponent` keeps dots: a name of only dots would be a `.` or `..` path segment.
+    const encoded = fontStack
+      .split(',')
+      .map(name => (/^\.+$/.test(name) ? name.replace(/\./g, '%2E') : encodeURIComponent(name)))
+      .join(',');
+    return this.url.replace(/\{(fontstack|range)\}/g, (_, name) =>
+      name === 'range' ? `${begin}-${begin + GLYPH_RANGE_SIZE - 1}` : encoded
+    );
+  }
+
+  private async loadRange(fontStack: string, range: number): Promise<Map<number, Glyph>> {
+    const glyphs = new Map<number, Glyph>();
+    try {
+      const response = await this.fetch(this.getRangeUrl(fontStack, range), this.fetchOptions);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      for (const glyph of parseGlyphRange(await response.arrayBuffer())) {
+        if (getGlyphRange(glyph.id) === range) {
+          glyphs.set(glyph.id, glyph);
+        }
+      }
+    } catch (error) {
+      // biome-ignore lint/suspicious/noConsole: a missing range leaves its characters undrawn.
+      console.warn(`Failed to load glyphs ${this.getRangeUrl(fontStack, range)}`, error);
+    }
+    return glyphs;
+  }
+
+  private getStack(fontStack: string, create: boolean): StackEntry | undefined {
+    let stack = this.stacks.get(fontStack);
+    if (stack) {
+      // Most recently used last.
+      this.stacks.delete(fontStack);
+      this.stacks.set(fontStack, stack);
+    } else if (create) {
+      stack = {ranges: new Map(), requests: new Map()};
+      this.stacks.set(fontStack, stack);
+      this.evict(fontStack);
+    }
+    return stack;
+  }
+
+  /**
+   * Drops the font stacks used least recently, beyond the bound, except those retained and
+   * `keep`, which is being loaded.
+   */
+  private evict(keep?: string): void {
+    for (const fontStack of this.stacks.keys()) {
+      if (this.stacks.size <= MAX_GLYPH_STACKS) {
+        return;
+      }
+      if (fontStack !== keep && !this.isRetained(fontStack)) {
+        this.stacks.delete(fontStack);
+      }
+    }
+  }
+
+  private isRetained(fontStack: string): boolean {
+    return this.retainCounts.has(fontStack);
+  }
+
+  private unretain(fontStack: string): void {
+    const count = this.retainCounts.get(fontStack)! - 1;
+    if (count) {
+      this.retainCounts.set(fontStack, count);
+    } else {
+      this.retainCounts.delete(fontStack);
+    }
+  }
+}
+
+/** The index of the range that holds a code point. */
+export function getGlyphRange(codePoint: number): number {
+  return Math.floor(codePoint / GLYPH_RANGE_SIZE);
+}
+
+/**
+ * Resolves a relative `glyphs` URL against the style URL. The template's braces are kept, which
+ * `URL` would encode.
+ */
+function resolveGlyphsUrl(url: string, baseUrl?: string): string {
+  if (!baseUrl || /^[a-z][a-z\d+.-]*:/i.test(url)) {
+    return url;
+  }
+  try {
+    const resolved = new URL(
+      url.replace(/[{}]/g, brace => (brace === '{' ? '%7B' : '%7D')),
+      baseUrl
+    );
+    return resolved.href.replace(/%7B/gi, '{').replace(/%7D/gi, '}');
+  } catch {
+    return url;
+  }
+}

package/src/grid-index.ts

@@ -0,0 +1,177 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * How a placed part lets others overlap it, as MapLibre GL JS's `text-overlap` / `icon-overlap`:
+ * `never` overlaps nothing and is overlapped by nothing; `always` overlaps anything; `cooperative`
+ * overlaps `always` and `cooperative` parts, but not `never` ones.
+ */
+export type OverlapMode = 'never' | 'always' | 'cooperative';
+
+/** Whether a part placed with `mode` may overlap one placed with `placedMode`. */
+export function allowsOverlap(mode: OverlapMode, placedMode: OverlapMode): boolean {
+  return mode === 'always' || (mode !== 'never' && placedMode !== 'never');
+}
+
+/**
+ * A grid of screen-space boxes and circles for label placement, as MapLibre GL JS's `GridIndex`:
+ * the plane is cut into square cells, each holding the shapes that reach into it, so that a test
+ * compares a shape only with the shapes of the cells it covers. Coordinates are pixels; a shape
+ * that reaches outside the grid is clamped to its edge cells.
+ */
+export class GridIndex {
+  readonly width: number;
+  readonly height: number;
+  private readonly cellSize: number;
+  private readonly columns: number;
+  private readonly rows: number;
+  /** Per cell, the indices of the shapes in it. */
+  private readonly cells: number[][];
+  /** Per shape: `x1, y1, x2, y2` for a box, `x, y, radius, NaN` for a circle. */
+  private readonly shapes: number[] = [];
+  private readonly modes: OverlapMode[] = [];
+  /** The query count at which each shape was last compared, so a query compares it once. */
+  private readonly seen: number[] = [];
+  private query = 0;
+
+  constructor(width: number, height: number, cellSize: number) {
+    this.width = width;
+    this.height = height;
+    this.cellSize = cellSize;
+    this.columns = Math.max(1, Math.ceil(width / cellSize));
+    this.rows = Math.max(1, Math.ceil(height / cellSize));
+    this.cells = Array.from({length: this.columns * this.rows}, () => []);
+  }
+
+  /** The number of shapes inserted. */
+  get size(): number {
+    return this.modes.length;
+  }
+
+  /** Adds a box from `x1, y1` to `x2, y2`. */
+  insert(x1: number, y1: number, x2: number, y2: number, mode: OverlapMode = 'never'): void {
+    this.add([x1, y1, x2, y2], mode, x1, y1, x2, y2);
+  }
+
+  /** Adds a circle. */
+  insertCircle(x: number, y: number, radius: number, mode: OverlapMode = 'never'): void {
+    this.add([x, y, radius, Number.NaN], mode, x - radius, y - radius, x + radius, y + radius);
+  }
+
+  /** Whether a box placed with `mode` would overlap a shape that it may not overlap. */
+  hitTest(x1: number, y1: number, x2: number, y2: number, mode: OverlapMode = 'never'): boolean {
+    return this.test(x1, y1, x2, y2, mode, (sx1, sy1, sx2, sy2) =>
+      Number.isNaN(sy2)
+        ? circleIntersectsBox(sx1, sy1, sx2, x1, y1, x2, y2)
+        : x1 <= sx2 && y1 <= sy2 && x2 >= sx1 && y2 >= sy1
+    );
+  }
+
+  /** Whether a circle placed with `mode` would overlap a shape that it may not overlap. */
+  hitTestCircle(x: number, y: number, radius: number, mode: OverlapMode = 'never'): boolean {
+    return this.test(x - radius, y - radius, x + radius, y + radius, mode, (sx1, sy1, sx2, sy2) =>
+      Number.isNaN(sy2)
+        ? (sx1 - x) ** 2 + (sy1 - y) ** 2 <= (sx2 + radius) ** 2
+        : circleIntersectsBox(x, y, radius, sx1, sy1, sx2, sy2)
+    );
+  }
+
+  /** Whether a box lies at least partly within the grid. */
+  isInside(x1: number, y1: number, x2: number, y2: number): boolean {
+    return x2 >= 0 && y2 >= 0 && x1 < this.width && y1 < this.height;
+  }
+
+  private add(
+    shape: number[],
+    mode: OverlapMode,
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number
+  ): void {
+    const index = this.modes.length;
+    this.shapes.push(...shape);
+    this.modes.push(mode);
+    this.seen.push(-1);
+    this.forEachCell(x1, y1, x2, y2, cell => {
+      this.cells[cell].push(index);
+      return false;
+    });
+  }
+
+  private test(
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number,
+    mode: OverlapMode,
+    intersects: (sx1: number, sy1: number, sx2: number, sy2: number) => boolean
+  ): boolean {
+    if (!this.isInside(x1, y1, x2, y2)) {
+      return false;
+    }
+    const query = ++this.query;
+    const {shapes, modes, seen} = this;
+    return this.forEachCell(x1, y1, x2, y2, cell => {
+      for (const index of this.cells[cell]) {
+        if (seen[index] === query) {
+          continue;
+        }
+        seen[index] = query;
+        const offset = index * 4;
+        if (
+          !allowsOverlap(mode, modes[index]) &&
+          intersects(shapes[offset], shapes[offset + 1], shapes[offset + 2], shapes[offset + 3])
+        ) {
+          return true;
+        }
+      }
+      return false;
+    });
+  }
+
+  /** Calls `visit` for each cell the box reaches, until it returns `true`. */
+  private forEachCell(
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number,
+    visit: (cell: number) => boolean
+  ): boolean {
+    const column1 = this.toCell(x1, this.columns);
+    const row1 = this.toCell(y1, this.rows);
+    const column2 = this.toCell(x2, this.columns);
+    const row2 = this.toCell(y2, this.rows);
+    for (let column = column1; column <= column2; column++) {
+      for (let row = row1; row <= row2; row++) {
+        if (visit(row * this.columns + column)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  private toCell(value: number, count: number): number {
+    return Math.max(0, Math.min(count - 1, Math.floor(value / this.cellSize)));
+  }
+}
+
+function circleIntersectsBox(
+  x: number,
+  y: number,
+  radius: number,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number
+): boolean {
+  const dx = x - Math.max(x1, Math.min(x, x2));
+  const dy = y - Math.max(y1, Math.min(y, y2));
+  return dx * dx + dy * dy <= radius * radius;
+}