@react-x11/components 0.7.1 → 0.9.0

package/src/maps/labels.ts

@@ -9,6 +9,12 @@
 // is the one thing on a map nobody accepts blurred. And a tile's labels
 // would be **clipped at its edge**, which is where half of them sit.
 //
+// **Where a label can go is the GL renderer's answer too**: both renderers
+// take their anchors from `./anchors.ts` — a place name at its point, a
+// street's name on a straight stretch of the street, its pieces merged
+// first — so a map switched from one renderer to the other names the same
+// streets in the same places, at the same angles.
+//
 // The placement itself is done in **world pixels** rather than screen
 // pixels, and that is the load-bearing decision in this file. A placement
 // computed against the viewport changes whenever the viewport does, so a
@@ -17,12 +23,21 @@
 // scrolled away. Placed in world pixels, whether a label wins depends only
 // on the labels near it and the zoom, so a pan is a translation of a
 // placement that is already correct, and the blit stands.
+import {
+  LABEL_STRIDE,
+  LEVEL_SNAP,
+  LINE_MARGIN,
+  LabelField,
+  STRAIGHT_FRACTION,
+  buildTileLabels,
+  estimateWidth,
+} from './anchors.js';
+import type { GlLabelData } from './anchors.js';
 import type { MapCanvas } from './paint.js';
-import { GeomType, GeometryBuffer } from './mvt.js';
 import type { VectorTile } from './mvt.js';
 import type { PreparedStyle, PreparedLayer } from './paint.js';
 import { resolveZoomed } from './style.js';
-import type { SymbolLayer, Zoomed } from './style.js';
+import type { MapStyleLayer, SymbolLayer, Zoomed } from './style.js';
 import type { TileId, Transform } from './proj.js';
 import { tileCountAt, tileKey } from './proj.js';
 
@@ -53,7 +68,7 @@ export interface ShapedLabel {
  *
  * `mx`/`my` are normalized mercator, so a candidate outlives every camera
  * move — it is a property of the data, and collected once per tile per
- * zoom.
+ * zoom. So are the lengths a name along a street is fitted with.
  */
 export interface LabelCandidate {
   /** Stable for the life of the tile, which is what lets a placement be
@@ -66,8 +81,23 @@ export interface LabelCandidate {
   text: string;
   mx: number;
   my: number;
+  /** The baseline's direction, radians, y down: `0` for a point label, and
+   *  along its street — always upright — for a street name. */
+  angle: number;
+  /** A street name's room: the straight run either side of the anchor, the
+   *  distance to the nearest junction, the run's length and how far it
+   *  bends from straight — normalized mercator, so a placement at any zoom
+   *  reads them in its own pixels. `Infinity`, `Infinity`, `0`, `0` for a
+   *  point label, which fits anywhere. */
+  avail: number;
+  clear: number;
+  length: number;
+  dev: number;
   /** Layer-wide priority; higher wins a collision. */
   rank: number;
+  /** Importance within the layer — a road's class, a place's population —
+   *  which breaks a tie in rank. */
+  priority: number;
   /** Logical pixels. */
   size: number;
   color: string;
@@ -78,7 +108,7 @@ export interface LabelCandidate {
 }
 
 /** A candidate that won its place, with the box it occupies in world
- *  pixels at the zoom it was placed for. */
+ *  pixels at the zoom it was placed for — its turned text's bounding box. */
 export interface PlacedLabel extends LabelCandidate {
   /** World pixels: `mercator × worldSize`. */
   wx: number;
@@ -96,115 +126,120 @@ function num<T extends number>(
   return value === undefined ? fallback : resolveZoomed(value, zoom);
 }
 
+/** The tile units anchors are worked out in: the GL buckets', so the two
+ *  renderers' anchors are the same numbers. */
+const EXTENT = 4096;
+
 /**
- * The label candidates one tile contributes.
- *
- * Point geometry anchors at the point. Line and polygon geometry anchor at
- * the **midpoint of the longest part** — which is not a true label
- * placement (a street name should follow its street, and a country name
- * should sit at the pole of inaccessibility of its border) but is the
- * anchor those two would start from, and is right often enough to be worth
- * having while line placement is unwritten. See `docs/prd-maps.md`.
+ * Anchors, per tile and style. They depend on neither the zoom nor the
+ * camera, and merging a tile's street pieces is the one costly step, so a
+ * zoom that collects a tile's candidates again does not work them out
+ * again.
+ */
+const anchorCache = new WeakMap<
+  VectorTile,
+  { prepared: PreparedStyle; data: GlLabelData }
+>();
+
+function anchorsOf(tile: VectorTile, prepared: PreparedStyle): GlLabelData {
+  const hit = anchorCache.get(tile);
+  if (hit && hit.prepared === prepared) return hit.data;
+  const data = buildTileLabels(tile, prepared, EXTENT);
+  anchorCache.set(tile, { prepared, data });
+  return data;
+}
+
+/** A symbol layer's labelling at a zoom, or null where it does not label. */
+interface LayerPaint {
+  id: string;
+  size: number;
+  color: string;
+  halo: string | undefined;
+  haloWidth: number;
+  rank: number;
+  repeat: number;
+}
+
+function paintAt(
+  layer: MapStyleLayer | undefined,
+  zoom: number,
+): LayerPaint | null {
+  if (!layer || layer.type !== 'symbol' || layer.visible === false) {
+    return null;
+  }
+  if (layer.minZoom !== undefined && zoom < layer.minZoom) return null;
+  if (layer.maxZoom !== undefined && zoom >= layer.maxZoom) return null;
+  const symbol = layer as SymbolLayer;
+  return {
+    id: layer.id,
+    size: num(symbol.textSize, zoom, 12),
+    color: symbol.textColor ? resolveZoomed(symbol.textColor, zoom) : '#000000',
+    halo: symbol.textHaloColor
+      ? resolveZoomed(symbol.textHaloColor, zoom)
+      : undefined,
+    haloWidth: num(symbol.textHaloWidth, zoom, 1),
+    rank: symbol.rank ?? 0,
+    repeat: symbol.repeatDistance ?? 250,
+  };
+}
+
+/**
+ * The label candidates one tile contributes: its anchors (`./anchors.ts`),
+ * with this zoom's size and colours. A point label anchors at its point,
+ * an area's at the middle of its largest ring, and a street's name at the
+ * middle of a straight stretch of the street — or of a block of it —
+ * turned to lie along it.
  */
 export function collectLabels(
   tile: VectorTile,
   id: TileId,
   prepared: PreparedStyle,
   zoom: number,
-  buffer: GeometryBuffer,
 ): LabelCandidate[] {
   const out: LabelCandidate[] = [];
+  const data = anchorsOf(tile, prepared);
   const n = tileCountAt(id.z);
   const key = tileKey(id);
-  for (let i = 0; i < prepared.layers.length; i++) {
-    const { layer, filter } = prepared.layers[i];
-    if (layer.type !== 'symbol' || layer.visible === false) continue;
-    if (layer.minZoom !== undefined && zoom < layer.minZoom) continue;
-    if (layer.maxZoom !== undefined && zoom >= layer.maxZoom) continue;
-    const source = tile.layers.get(layer.sourceLayer);
-    if (!source || source.length === 0) continue;
-    const symbol = layer as SymbolLayer;
-    const size = num(symbol.textSize, zoom, 12);
-    const color = symbol.textColor
-      ? resolveZoomed(symbol.textColor, zoom)
-      : '#000000';
-    const halo = symbol.textHaloColor
-      ? resolveZoomed(symbol.textHaloColor, zoom)
-      : undefined;
-    const haloWidth = num(symbol.textHaloWidth, zoom, 1);
-    const rank = symbol.rank ?? 0;
-    const repeat = symbol.repeatDistance ?? 250;
-    const extent = source.extent;
-    const cursor = source.feature(0);
-    for (let f = 0; f < source.length; f++) {
-      source.seek(f, cursor);
-      if (!filter(cursor)) continue;
-      const raw = cursor.get(symbol.textField);
-      // The schema's fallback: a translated name field is absent for most
-      // features, and the local `name` is what a map without a translation
-      // shows rather than nothing.
-      const text =
-        typeof raw === 'string' && raw.length > 0
-          ? raw
-          : symbol.textField !== 'name'
-            ? typeof cursor.get('name') === 'string'
-              ? String(cursor.get('name'))
-              : ''
-            : '';
-      if (text.length === 0) continue;
-      cursor.readGeometry(buffer);
-      const anchor = anchorOf(buffer, cursor.type);
-      if (!anchor) continue;
-      out.push({
-        id: `${key}:${layer.id}:${f}`,
-        key: `${layer.id}|${text}`,
-        text,
-        // Tile-local to normalized mercator, the same arithmetic the
-        // rasterizer's transform does and for the same precision reason.
-        mx: (id.x + anchor.x / extent) / n,
-        my: (id.y + anchor.y / extent) / n,
-        rank,
-        size,
-        color,
-        halo,
-        haloWidth,
-        repeat,
-      });
+  // Tile units to normalized mercator.
+  const unit = 1 / (EXTENT * n);
+  const paints = new Map<number, LayerPaint | null>();
+  const a = data.anchors;
+  for (let r = 0; r < data.count; r++) {
+    const at = r * LABEL_STRIDE;
+    const index = a[at + LabelField.layer];
+    let paint = paints.get(index);
+    if (paint === undefined) {
+      paint = paintAt(prepared.layers[index]?.layer, zoom);
+      paints.set(index, paint);
     }
+    if (!paint) continue;
+    const text = data.texts[a[at + LabelField.text]];
+    const point = a[at + LabelField.avail] < 0;
+    out.push({
+      id: `${key}:${paint.id}:${r}`,
+      key: `${paint.id}|${text}`,
+      text,
+      // Tile-local to normalized mercator, the same arithmetic the
+      // rasterizer's transform does and for the same precision reason.
+      mx: (id.x + a[at + LabelField.x] / EXTENT) / n,
+      my: (id.y + a[at + LabelField.y] / EXTENT) / n,
+      angle: point ? 0 : a[at + LabelField.angle],
+      avail: point ? Infinity : a[at + LabelField.avail] * unit,
+      clear: point ? Infinity : a[at + LabelField.clear] * unit,
+      length: a[at + LabelField.length] * unit,
+      dev: a[at + LabelField.dev] * unit,
+      rank: paint.rank,
+      priority: a[at + LabelField.priority],
+      size: paint.size,
+      color: paint.color,
+      halo: paint.halo,
+      haloWidth: paint.haloWidth,
+      repeat: paint.repeat,
+    });
   }
   return out;
 }
 
-function anchorOf(
-  buffer: GeometryBuffer,
-  type: GeomType,
-): { x: number; y: number } | null {
-  if (buffer.points === 0) return null;
-  if (type === GeomType.Point) {
-    return { x: buffer.coords[0], y: buffer.coords[1] };
-  }
-  // The longest part, by its box — a cheap stand-in for arc length that
-  // does not need a second pass over the vertices.
-  let best = 0;
-  let bestSpan = -1;
-  for (let part = 0; part < buffer.parts; part++) {
-    const at = part * 4;
-    const span =
-      buffer.partBounds[at + 2] -
-      buffer.partBounds[at] +
-      (buffer.partBounds[at + 3] - buffer.partBounds[at + 1]);
-    if (span > bestSpan) {
-      bestSpan = span;
-      best = part;
-    }
-  }
-  const from = buffer.starts[best];
-  const to = buffer.starts[best + 1];
-  if (to <= from) return null;
-  const mid = from + ((to - from) >> 1);
-  return { x: buffer.coords[mid * 2], y: buffer.coords[mid * 2 + 1] };
-}
-
 /** Cache of shaped strings, owned by the element. */
 export class LabelShaper {
   private readonly _cache = new Map<string, ShapedLabel>();
@@ -267,13 +302,25 @@ export class LabelShaper {
   }
 }
 
+/** A street name is set level — on whole pixels, which is sharper — when
+ *  its street is this close to level. */
+function levelled(angle: number): number {
+  return Math.abs(angle) < LEVEL_SNAP ? 0 : angle;
+}
+
 /**
  * Place candidates against each other, in world pixels.
  *
- * Greedy by rank, which is what every map does: sort, and take a label if
- * nothing already taken overlaps it. The order has to be **total and
- * stable** — rank, then the candidate's id — because a tie broken by array
- * order would flicker as tiles arrived in a different order.
+ * Greedy, which is what every map does: sort, and take a label if it fits
+ * where it is and nothing already taken overlaps it. The order is the GL
+ * renderer's, less what depends on the view: rank, then importance within
+ * the layer, then a street name that clears its junctions over one that
+ * would cover a crossing street, then the longer straight run. It has to be
+ * **total and stable** — the candidate's id last — because a tie broken by
+ * array order would flicker as tiles arrived in a different order.
+ *
+ * A street name fits where the GL renderer says one does: on a stretch
+ * straight enough for its size, and long enough for all of it.
  */
 export function placeLabels(
   candidates: readonly LabelCandidate[],
@@ -282,9 +329,19 @@ export function placeLabels(
   options?: { padding?: number },
 ): PlacedLabel[] {
   const padding = options?.padding ?? 2;
-  const sorted = [...candidates].sort(
-    (a, b) => b.rank - a.rank || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
-  );
+  const clean = (c: LabelCandidate): number =>
+    c.clear * worldSize >= estimateWidth(c.text, c.size) / 2 ? 1 : 0;
+  const sorted = [...candidates]
+    .map((c) => ({ c, clean: clean(c) }))
+    .sort(
+      (a, b) =>
+        b.c.rank - a.c.rank ||
+        b.c.priority - a.c.priority ||
+        b.clean - a.clean ||
+        b.c.length - a.c.length ||
+        (a.c.id < b.c.id ? -1 : a.c.id > b.c.id ? 1 : 0),
+    )
+    .map((entry) => entry.c);
   const placed: PlacedLabel[] = [];
   // A sparse grid over world pixels. The cell is sized for the labels
   // themselves, so a box touches one or two cells and a collision test is a
@@ -297,18 +354,26 @@ export function placeLabels(
   const byText = new Map<string, { wx: number; wy: number }[]>();
 
   for (const candidate of sorted) {
+    // Bent under its size at this zoom: not a stretch to set a name on.
+    if (candidate.dev * worldSize > candidate.size * STRAIGHT_FRACTION) {
+      continue;
+    }
     const shaped = shaper.shape(
       candidate.text,
       candidate.size,
       candidate.color,
     );
     if (!shaped) return placed; // no font manager: nothing can be measured
+    // Longer than the straight stretch it would sit on, with a margin past
+    // each end: it would hang off the street, over whatever the street
+    // turns into.
+    const need = shaped.width / 2 + shaped.height * LINE_MARGIN;
+    if (candidate.avail * worldSize < need) continue;
     const wx = candidate.mx * worldSize;
     const wy = candidate.my * worldSize;
     // The repeat test before the overlap test, because it is the cheaper
-    // one and because it is what rejects most of a street layer: a street
-    // is one feature per segment, so the same name arrives a dozen times
-    // strung out along the road, none of them overlapping any other.
+    // one and because it is what rejects most of a street layer: a long
+    // street offers its name every block, none of them overlapping.
     if (candidate.repeat > 0) {
       const already = byText.get(candidate.key);
       if (already) {
@@ -325,8 +390,15 @@ export function placeLabels(
         if (tooClose) continue;
       }
     }
-    const width = shaped.width + padding * 2;
-    const height = shaped.height + padding * 2;
+    // The turned text's bounding box: what it covers, as far as another
+    // label can tell.
+    const angle = levelled(candidate.angle);
+    const w = shaped.width + padding * 2;
+    const h = shaped.height + padding * 2;
+    const cos = Math.abs(Math.cos(angle));
+    const sin = Math.abs(Math.sin(angle));
+    const width = w * cos + h * sin;
+    const height = w * sin + h * cos;
     const left = wx - width / 2;
     const top = wy - height / 2;
     const x0 = Math.floor(left / CELL);
@@ -354,6 +426,7 @@ export function placeLabels(
     if (!free) continue;
     const entry: PlacedLabel = {
       ...candidate,
+      angle,
       wx,
       wy,
       width,
@@ -387,6 +460,10 @@ export function placeLabels(
  * composites of two shaped runs. That is cheap for the few dozen labels a
  * pane holds and it is the difference between a place name that is
  * readable over a motorway and one that is not.
+ *
+ * A level label is drawn on whole device pixels. A street name along its
+ * street is drawn turned about its centre, where the context can turn —
+ * and level where it cannot, on a context with no transform.
  */
 export function drawLabels(
   ctx: MapCanvas,
@@ -401,28 +478,43 @@ export function drawLabels(
   const world = transform.world;
   const originX = pane.x + transform.paneX - transform.centerX * world;
   const originY = pane.y + transform.paneY - transform.centerY * world;
+  const turns = typeof ctx.rotate === 'function' && !!ctx.translate;
   for (const label of placed) {
-    const x = originX + label.wx - label.shaped.width / 2;
-    const y = originY + label.wy - label.shaped.height / 2;
+    const cx = originX + label.wx;
+    const cy = originY + label.wy;
+    const halfW = label.width / 2;
+    const halfH = label.height / 2;
     if (
-      x + label.shaped.width < pane.x ||
-      y + label.shaped.height < pane.y ||
-      x > pane.x + pane.width ||
-      y > pane.y + pane.height
+      cx + halfW < pane.x ||
+      cy + halfH < pane.y ||
+      cx - halfW > pane.x + pane.width ||
+      cy - halfH > pane.y + pane.height
     ) {
       continue;
     }
     if (
       clip &&
-      (x + label.shaped.width < clip.x ||
-        y + label.shaped.height < clip.y ||
-        x > clip.x + clip.width ||
-        y > clip.y + clip.height)
+      (cx + halfW < clip.x ||
+        cy + halfH < clip.y ||
+        cx - halfW > clip.x + clip.width ||
+        cy - halfH > clip.y + clip.height)
     ) {
       continue;
     }
-    const dx = Math.round(x * scale);
-    const dy = Math.round(y * scale);
+    const { width, height } = label.shaped;
+    const turned = label.angle !== 0 && turns;
+    let dx: number;
+    let dy: number;
+    if (turned) {
+      ctx.save();
+      ctx.translate!(cx * scale, cy * scale);
+      ctx.rotate!(label.angle);
+      dx = (-width * scale) / 2;
+      dy = (-height * scale) / 2;
+    } else {
+      dx = Math.round((cx - width / 2) * scale);
+      dy = Math.round((cy - height / 2) * scale);
+    }
     if (label.halo !== undefined && label.haloWidth > 0) {
       const halo = shaper.shape(label.text, label.size, label.halo);
       if (halo) {
@@ -434,6 +526,7 @@ export function drawLabels(
       }
     }
     label.shaped.layout.draw(ctx, dx, dy);
+    if (turned) ctx.restore();
     drawn++;
   }
   return drawn;