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

package/src/polylabel.ts

@@ -0,0 +1,312 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Point labels on polygons sit at the polygon's pole of inaccessibility: the interior point
+// farthest from the outline. MapLibre places them there too. This file finds that point with the
+// grid refinement of Garcia-Castellanos and Lombardo, "Poles of inaccessibility: a calculation
+// algorithm for the remotest places on Earth" (Scottish Geographical Journal 123(3), 2007),
+// in its best-first form: candidate squares wait in a priority queue, ordered by the largest
+// distance any point in them could have, and a square is split into four only while it could
+// still beat the best point found by more than the precision.
+//
+// Tile geometry is untrusted input, so the search is bounded by the work it does. Scoring one
+// candidate costs one point-to-segment distance test per polygon vertex. The search counts those
+// tests against a budget, and returns the best point found when the budget runs out. A caller
+// can share one budget across all polygons of a tile, so a tile with many large polygons cannot
+// hold the main thread either. The first grid also has at most MAX_GRID_CELLS_PER_AXIS squares
+// along the longer side, and the precision has a floor relative to the polygon's size.
+
+const MAX_GRID_CELLS_PER_AXIS = 64;
+const MIN_RELATIVE_PRECISION = 1e-6;
+/** Default budget for one search: point-to-segment distance tests. */
+export const DEFAULT_POLE_SEARCH_SEGMENT_TESTS = 5e6;
+
+/** Remaining work, in point-to-segment distance tests, shared by the searches that use it. */
+export type PoleSearchBudget = {
+  segmentTests: number;
+};
+
+/**
+ * Returns the point inside a polygon farthest from its outline, to within `precision` in the
+ * polygon's units. `polygon` is GeoJSON-style: an outer ring followed by hole rings. Coordinates
+ * must be planar.
+ *
+ * The search spends at most `budget.segmentTests` point-to-segment distance tests and deducts
+ * what it spends, so one budget can bound several searches. When the budget runs out the best
+ * point found so far is returned. Returns null for a polygon without vertices, with a non-finite
+ * coordinate, or when the budget cannot pay for the first scored point.
+ */
+export function getPoleOfInaccessibility(
+  polygon: number[][][],
+  precision: number,
+  budget: PoleSearchBudget = {segmentTests: DEFAULT_POLE_SEARCH_SEGMENT_TESTS}
+): [number, number] | null {
+  const outline = polygon[0];
+  if (!outline || outline.length === 0) {
+    return null;
+  }
+  const vertexCount = countFiniteVertices(polygon);
+  if (vertexCount < 0) {
+    return null;
+  }
+
+  const box = getRingBox(outline);
+  const width = box.right - box.left;
+  const height = box.top - box.bottom;
+  if (width === 0 || height === 0) {
+    return [box.left, box.bottom];
+  }
+  const longSide = Math.max(width, height);
+  const tolerance = Math.max(
+    Number.isFinite(precision) && precision > 0 ? precision : 0,
+    longSide * MIN_RELATIVE_PRECISION
+  );
+
+  const search = new PoleSearch(polygon, vertexCount, budget);
+
+  // Two cheap first guesses: the area centroid, which is inside most convex-ish shapes, and the
+  // middle of the bounding box.
+  const [centroidX, centroidY] = getAreaCentroid(polygon[0]);
+  if (!search.score(centroidX, centroidY, 0)) {
+    return null;
+  }
+  if (!search.score(box.left + width / 2, box.bottom + height / 2, 0)) {
+    return search.bestPoint();
+  }
+
+  // The first grid uses squares as wide as the polygon's short side, so a long, thin polygon is
+  // covered by squares that fit it. The cap keeps a sliver from starting with millions of them.
+  const side = Math.max(Math.min(width, height), longSide / MAX_GRID_CELLS_PER_AXIS);
+  const columns = Math.ceil(width / side);
+  const rows = Math.ceil(height / side);
+  for (let column = 0; column < columns; column++) {
+    for (let row = 0; row < rows; row++) {
+      const x = box.left + (column + 0.5) * side;
+      const y = box.bottom + (row + 0.5) * side;
+      if (!search.score(x, y, side / 2)) {
+        return search.bestPoint();
+      }
+    }
+  }
+
+  search.refine(tolerance);
+  return search.bestPoint();
+}
+
+/** Returns the number of vertices in all rings, or -1 if any coordinate is not finite. */
+function countFiniteVertices(polygon: number[][][]): number {
+  let count = 0;
+  for (const ring of polygon) {
+    for (const point of ring) {
+      if (!Number.isFinite(point[0]) || !Number.isFinite(point[1])) {
+        return -1;
+      }
+    }
+    count += ring.length;
+  }
+  return count;
+}
+
+function getRingBox(ring: number[][]): {left: number; bottom: number; right: number; top: number} {
+  let left = Infinity;
+  let bottom = Infinity;
+  let right = -Infinity;
+  let top = -Infinity;
+  for (const point of ring) {
+    left = Math.min(left, point[0]);
+    right = Math.max(right, point[0]);
+    bottom = Math.min(bottom, point[1]);
+    top = Math.max(top, point[1]);
+  }
+  return {left, bottom, right, top};
+}
+
+/** The centroid of the area a ring encloses, or its first vertex when that area is zero. */
+function getAreaCentroid(ring: number[][]): [number, number] {
+  let twiceArea = 0;
+  let sumX = 0;
+  let sumY = 0;
+  let previous = ring[ring.length - 1];
+  for (const current of ring) {
+    const cross = previous[0] * current[1] - current[0] * previous[1];
+    twiceArea += cross;
+    sumX += (previous[0] + current[0]) * cross;
+    sumY += (previous[1] + current[1]) * cross;
+    previous = current;
+  }
+  if (twiceArea === 0) {
+    return [ring[0][0], ring[0][1]];
+  }
+  return [sumX / (3 * twiceArea), sumY / (3 * twiceArea)];
+}
+
+/**
+ * The state of one search: the best point so far and a max-heap of candidate squares. The
+ * squares are kept in parallel arrays, and the heap holds their indices, ordered by `reach`.
+ */
+class PoleSearch {
+  private readonly polygon: number[][][];
+  private readonly vertexCount: number;
+  private readonly budget: PoleSearchBudget;
+
+  private readonly centerX: number[] = [];
+  private readonly centerY: number[] = [];
+  private readonly halfSide: number[] = [];
+  /** The largest distance to the outline that any point of the square can have. */
+  private readonly reach: number[] = [];
+  private readonly heap: number[] = [];
+
+  private bestX = NaN;
+  private bestY = NaN;
+  private bestDistance = -Infinity;
+
+  constructor(polygon: number[][][], vertexCount: number, budget: PoleSearchBudget) {
+    this.polygon = polygon;
+    this.vertexCount = vertexCount;
+    this.budget = budget;
+  }
+
+  bestPoint(): [number, number] {
+    return [this.bestX, this.bestY];
+  }
+
+  /**
+   * Scores the square centered at (x, y), keeps its center if it is the best so far, and queues
+   * the square if it has area. Returns false, without scoring, when the budget cannot pay.
+   */
+  score(x: number, y: number, half: number): boolean {
+    if (this.budget.segmentTests < this.vertexCount) {
+      return false;
+    }
+    this.budget.segmentTests -= this.vertexCount;
+    const distance = getSignedOutlineDistance(this.polygon, x, y);
+    if (distance > this.bestDistance) {
+      this.bestX = x;
+      this.bestY = y;
+      this.bestDistance = distance;
+    }
+    if (half > 0) {
+      // No point in the square is farther from the center than half its diagonal.
+      this.enqueue(x, y, half, distance + half * Math.SQRT2);
+    }
+    return true;
+  }
+
+  /** Splits the most promising squares until none can beat the best point by `tolerance`. */
+  refine(tolerance: number): void {
+    while (this.heap.length > 0) {
+      const index = this.dequeue();
+      if (this.reach[index] - this.bestDistance <= tolerance) {
+        // The heap is ordered by reach, so no remaining square can do better either.
+        return;
+      }
+      const quarter = this.halfSide[index] / 2;
+      const x = this.centerX[index];
+      const y = this.centerY[index];
+      if (
+        !this.score(x - quarter, y - quarter, quarter) ||
+        !this.score(x + quarter, y - quarter, quarter) ||
+        !this.score(x - quarter, y + quarter, quarter) ||
+        !this.score(x + quarter, y + quarter, quarter)
+      ) {
+        return;
+      }
+    }
+  }
+
+  private enqueue(x: number, y: number, half: number, reach: number): void {
+    const index = this.reach.length;
+    this.centerX.push(x);
+    this.centerY.push(y);
+    this.halfSide.push(half);
+    this.reach.push(reach);
+
+    const {heap} = this;
+    let slot = heap.length;
+    heap.push(index);
+    while (slot > 0) {
+      const parentSlot = (slot - 1) >> 1;
+      if (this.reach[heap[parentSlot]] >= reach) {
+        break;
+      }
+      heap[slot] = heap[parentSlot];
+      slot = parentSlot;
+    }
+    heap[slot] = index;
+  }
+
+  private dequeue(): number {
+    const {heap, reach} = this;
+    const top = heap[0];
+    const moved = heap.pop() as number;
+    const size = heap.length;
+    if (size === 0) {
+      return top;
+    }
+    let slot = 0;
+    for (;;) {
+      let next = slot * 2 + 1;
+      if (next >= size) {
+        break;
+      }
+      if (next + 1 < size && reach[heap[next + 1]] > reach[heap[next]]) {
+        next += 1;
+      }
+      if (reach[heap[next]] <= reach[moved]) {
+        break;
+      }
+      heap[slot] = heap[next];
+      slot = next;
+    }
+    heap[slot] = moved;
+    return top;
+  }
+}
+
+/**
+ * Distance from (x, y) to the nearest edge of any ring: positive inside the polygon, negative
+ * outside, and 0 on an edge. Inside is decided by the even-odd rule, so holes count as outside.
+ */
+function getSignedOutlineDistance(polygon: number[][][], x: number, y: number): number {
+  let nearestSquared = Infinity;
+  let crossings = 0;
+  for (const ring of polygon) {
+    let start = ring[ring.length - 1];
+    for (const end of ring) {
+      // Count edges that cross the horizontal ray from (x, y) toward +x.
+      if (start[1] <= y !== end[1] <= y) {
+        const t = (y - start[1]) / (end[1] - start[1]);
+        if (start[0] + t * (end[0] - start[0]) > x) {
+          crossings++;
+        }
+      }
+      nearestSquared = Math.min(nearestSquared, getSquaredSegmentDistance(x, y, start, end));
+      start = end;
+    }
+  }
+  if (nearestSquared === 0) {
+    return 0;
+  }
+  const distance = Math.sqrt(nearestSquared);
+  return crossings % 2 === 1 ? distance : -distance;
+}
+
+/** Squared distance from (x, y) to the segment from `start` to `end`. */
+function getSquaredSegmentDistance(x: number, y: number, start: number[], end: number[]): number {
+  const edgeX = end[0] - start[0];
+  const edgeY = end[1] - start[1];
+  const lengthSquared = edgeX * edgeX + edgeY * edgeY;
+  // Where the perpendicular from (x, y) meets the edge's line, as a fraction of the edge.
+  const along =
+    lengthSquared === 0
+      ? 0
+      : Math.max(0, Math.min(1, ((x - start[0]) * edgeX + (y - start[1]) * edgeY) / lengthSquared));
+  const offsetX = start[0] + along * edgeX - x;
+  const offsetY = start[1] + along * edgeY - y;
+  return offsetX * offsetX + offsetY * offsetY;
+}

package/src/raster-color-extension.ts

@@ -0,0 +1,245 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT AND BSD-3-Clause
+// Copyright (c) vis.gl contributors
+// Copyright (c) 2023, MapLibre contributors
+// Copyright (c) 2020, Mapbox
+
+/**
+ * @license
+ * Portions of this file are adapted from MapLibre GL JS v6.13.0,
+ * src/shaders/glsl/raster.fragment.glsl,
+ * under these licenses (see also THIRD-PARTY-NOTICES.md):
+ *
+ * Copyright (c) 2023, MapLibre contributors
+ *
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *
+ *     * Redistributions of source code must retain the above copyright notice,
+ *       this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright notice,
+ *       this list of conditions and the following disclaimer in the documentation
+ *       and/or other materials provided with the distribution.
+ *     * Neither the name of MapLibre GL JS nor the names of its contributors
+ *       may be used to endorse or promote products derived from this software
+ *       without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * MapLibre GL JS contains code from mapbox-gl-js v1.13 and earlier, licensed under a
+ * BSD-3-Clause license:
+ *
+ * Copyright (c) 2020, Mapbox
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ * * Neither the name of Mapbox GL JS nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+import {LayerExtension} from '@deck.gl/core';
+import type {CompositeLayer, Layer} from '@deck.gl/core';
+
+/** The style values of a raster layer's color adjustments, as evaluated from its paint. */
+export type RasterColorAdjustments = {
+  /** `raster-brightness-min`, 0 to 1. */
+  brightnessMin: number;
+  /** `raster-brightness-max`, 0 to 1. */
+  brightnessMax: number;
+  /** `raster-saturation`, -1 to 1. */
+  saturation: number;
+  /** `raster-contrast`, -1 to 1. */
+  contrast: number;
+  /** `raster-hue-rotate`, in degrees. */
+  hueRotate: number;
+};
+
+/** The style specification's defaults, which leave colors unchanged. */
+export const DEFAULT_RASTER_COLOR_ADJUSTMENTS: RasterColorAdjustments = {
+  brightnessMin: 0,
+  brightnessMax: 1,
+  saturation: 0,
+  contrast: 0,
+  hueRotate: 0
+};
+
+/** The shader uniforms of a set of color adjustments, computed as MapLibre GL JS does. */
+export type RasterColorUniforms = {
+  brightnessLow: number;
+  brightnessHigh: number;
+  saturationFactor: number;
+  contrastFactor: number;
+  spinWeights: [number, number, number];
+};
+
+/** Weights that rotate an RGB color about the gray axis by `angle` degrees. */
+function getSpinWeights(angle: number): [number, number, number] {
+  const radians = (angle * Math.PI) / 180;
+  const s = Math.sin(radians);
+  const c = Math.cos(radians);
+  return [(2 * c + 1) / 3, (-Math.sqrt(3) * s - c + 1) / 3, (Math.sqrt(3) * s - c + 1) / 3];
+}
+
+function getContrastFactor(contrast: number): number {
+  return contrast > 0 ? 1 / (1 - contrast) : 1 + contrast;
+}
+
+function getSaturationFactor(saturation: number): number {
+  return saturation > 0 ? 1 - 1 / (1.001 - saturation) : -saturation;
+}
+
+/** Converts color adjustments to shader uniforms, with MapLibre GL JS's `raster` program math. */
+export function getRasterColorUniforms(adjustments: RasterColorAdjustments): RasterColorUniforms {
+  return {
+    brightnessLow: adjustments.brightnessMin,
+    brightnessHigh: adjustments.brightnessMax,
+    saturationFactor: getSaturationFactor(adjustments.saturation),
+    contrastFactor: getContrastFactor(adjustments.contrast),
+    spinWeights: getSpinWeights(adjustments.hueRotate)
+  };
+}
+
+/** Whether a set of color adjustments changes any color. */
+export function hasRasterColorAdjustments(adjustments: RasterColorAdjustments): boolean {
+  return (Object.keys(DEFAULT_RASTER_COLOR_ADJUSTMENTS) as (keyof RasterColorAdjustments)[]).some(
+    key => adjustments[key] !== DEFAULT_RASTER_COLOR_ADJUSTMENTS[key]
+  );
+}
+
+const rasterColorModule = {
+  name: 'rasterColor',
+  fs: /* glsl */ `\
+layout(std140) uniform rasterColorUniforms {
+  float brightnessLow;
+  float brightnessHigh;
+  float saturationFactor;
+  float contrastFactor;
+  vec3 spinWeights;
+} rasterColor;
+
+// MapLibre GL JS's raster fragment shader, applied to an unpremultiplied color.
+vec3 rasterColor_adjust(vec3 color) {
+  vec3 rgb = vec3(
+    dot(color, rasterColor.spinWeights.xyz),
+    dot(color, rasterColor.spinWeights.zxy),
+    dot(color, rasterColor.spinWeights.yzx)
+  );
+  float average = (color.r + color.g + color.b) / 3.0;
+  rgb += (average - rgb) * rasterColor.saturationFactor;
+  rgb = (rgb - 0.5) * rasterColor.contrastFactor + 0.5;
+  return mix(vec3(rasterColor.brightnessLow), vec3(rasterColor.brightnessHigh), rgb);
+}
+`,
+  uniformTypes: {
+    brightnessLow: 'f32',
+    brightnessHigh: 'f32',
+    saturationFactor: 'f32',
+    contrastFactor: 'f32',
+    spinWeights: 'vec3<f32>'
+  }
+} as const;
+
+const injection = {
+  // MapLibre writes the adjusted color premultiplied, so a value pushed above 1 is clamped only
+  // after the multiplication by alpha. Layers using this extension blend premultiplied colors
+  // (`RASTER_COLOR_BLEND_PARAMETERS`) to draw the same.
+  'fs:DECKGL_FILTER_COLOR': /* glsl */ `
+  color.rgb = rasterColor_adjust(color.rgb) * color.a;
+`
+};
+
+/** The blending of layers using `RasterColorExtension`, whose shader outputs premultiplied colors. */
+export const RASTER_COLOR_BLEND_PARAMETERS = {
+  blendColorOperation: 'add',
+  blendColorSrcFactor: 'one',
+  blendColorDstFactor: 'one-minus-src-alpha',
+  // WebGL sets both factors together; these are deck.gl's alpha factors.
+  blendAlphaOperation: 'add',
+  blendAlphaSrcFactor: 'one',
+  blendAlphaDstFactor: 'one-minus-src-alpha'
+} as const;
+
+type RasterColorExtensionProps = {
+  /** The color adjustments of the raster style layer. */
+  rasterColorAdjustments?: RasterColorAdjustments;
+};
+
+/** Whether the extension's shader runs on a layer's device. It is written in GLSL only. */
+function isRasterColorSupported(layer: Layer): boolean {
+  return layer.context.device.type !== 'webgpu';
+}
+
+/**
+ * Applies a raster style layer's `raster-brightness-min`, `raster-brightness-max`,
+ * `raster-saturation`, `raster-contrast` and `raster-hue-rotate` to a `BitmapLayer`, with the
+ * formulas of MapLibre GL JS's raster shader. WebGL only.
+ *
+ * The adjusted colors are premultiplied, so the layer must blend with
+ * `RASTER_COLOR_BLEND_PARAMETERS` exactly where the shader runs. Added to a composite layer, the
+ * extension passes them to its sublayers as `rasterColorBlendParameters`, decided by the same
+ * device check as the shader; on WebGPU they are `null` and the sublayers keep their blending.
+ */
+export class RasterColorExtension extends LayerExtension {
+  static extensionName = 'RasterColorExtension';
+  static defaultProps = {
+    rasterColorAdjustments: {type: 'object', value: DEFAULT_RASTER_COLOR_ADJUSTMENTS, compare: 1}
+  };
+
+  getShaders(this: Layer<RasterColorExtensionProps>) {
+    if (!isRasterColorSupported(this)) {
+      return {};
+    }
+    return {modules: [rasterColorModule], inject: injection};
+  }
+
+  getSubLayerProps(this: CompositeLayer<RasterColorExtensionProps>, extension: this) {
+    return {
+      ...LayerExtension.prototype.getSubLayerProps.call(this, extension),
+      rasterColorBlendParameters: isRasterColorSupported(this)
+        ? RASTER_COLOR_BLEND_PARAMETERS
+        : null
+    };
+  }
+
+  draw(this: Layer<RasterColorExtensionProps>) {
+    if (!isRasterColorSupported(this)) {
+      return;
+    }
+    const adjustments = this.props.rasterColorAdjustments ?? DEFAULT_RASTER_COLOR_ADJUSTMENTS;
+    this.setShaderModuleProps({rasterColor: getRasterColorUniforms(adjustments)});
+  }
+}