@math.gl/geometry 5.0.0-alpha.17 → 5.0.0-alpha.19

package/src/curves/curve.ts

@@ -0,0 +1,96 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumericArray} from '@math.gl/core/types';
+
+export type CurvePoint = Readonly<ArrayLike<number>>;
+
+/** Parameterized Euclidean curve, with t in [0, 1]. */
+export abstract class Curve {
+  readonly dimension: number;
+
+  protected constructor(dimension: number) {
+    if (dimension !== 2 && dimension !== 3) {
+      throw new RangeError('Curve points must have two or three coordinates');
+    }
+    this.dimension = dimension;
+  }
+
+  getPoint(t: number): number[];
+  getPoint<T extends NumericArray>(t: number, result: T): T;
+  getPoint(t: number, result: NumericArray = new Array(this.dimension)): NumericArray {
+    validateParameter(t);
+    validateResult(result, this.dimension);
+    this.evaluate(t, result, false);
+    return result;
+  }
+
+  /** Derivative with respect to the normalized curve parameter t. */
+  getDerivative(t: number): number[];
+  getDerivative<T extends NumericArray>(t: number, result: T): T;
+  getDerivative(t: number, result: NumericArray = new Array(this.dimension)): NumericArray {
+    validateParameter(t);
+    validateResult(result, this.dimension);
+    this.evaluate(t, result, true);
+    return result;
+  }
+
+  /** Unit tangent; returns a zero vector at stationary points. */
+  getTangent(t: number): number[];
+  getTangent<T extends NumericArray>(t: number, result: T): T;
+  getTangent(t: number, result: NumericArray = new Array(this.dimension)): NumericArray {
+    this.getDerivative(t, result);
+    const length = Math.hypot(result[0], result[1], this.dimension === 3 ? result[2] : 0);
+    if (length > 0) {
+      for (let i = 0; i < this.dimension; i++) result[i] /= length;
+    }
+    return result;
+  }
+
+  /** Flat coordinates for divisions + 1 evenly spaced parameter samples. */
+  getPoints(divisions = 64): Float64Array {
+    validateDivisions(divisions);
+    const points = new Float64Array((divisions + 1) * this.dimension);
+    const point = new Array<number>(this.dimension);
+    for (let i = 0; i <= divisions; i++) {
+      this.getPoint(i / divisions, point);
+      points.set(point, i * this.dimension);
+    }
+    return points;
+  }
+
+  protected abstract evaluate(t: number, result: NumericArray, derivative: boolean): void;
+}
+
+/** Copy caller-owned control data so curves and their length tables stay stable. */
+export function copyPoints(points: readonly CurvePoint[]): number[][] {
+  if (!points.length) throw new RangeError('Invalid number of curve control points');
+  const dimension = points[0].length;
+  if (dimension !== 2 && dimension !== 3) {
+    throw new RangeError('Curve points must have two or three coordinates');
+  }
+  return points.map(point => {
+    if (point.length !== dimension) throw new RangeError('Control point dimensions must match');
+    return Array.from(point, value => {
+      if (!Number.isFinite(value)) throw new RangeError('Control coordinates must be finite');
+      return value;
+    });
+  });
+}
+
+export function validateParameter(t: number): void {
+  if (!Number.isFinite(t) || t < 0 || t > 1) {
+    throw new RangeError('Curve parameter must be finite and in [0, 1]');
+  }
+}
+
+export function validateDivisions(divisions: number): void {
+  if (!Number.isSafeInteger(divisions) || divisions < 1) {
+    throw new RangeError('divisions must be a positive safe integer');
+  }
+}
+
+function validateResult(result: NumericArray, dimension: number): void {
+  if (result.length < dimension) throw new RangeError('Result buffer is too short');
+}

package/src/curves/hermite-curve.ts

@@ -0,0 +1,34 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumericArray} from '@math.gl/core/types';
+import {Curve, copyPoints, type CurvePoint} from './curve';
+
+/** Cubic curve with endpoint derivatives (not unit tangent directions). */
+export class HermiteCurve extends Curve {
+  private readonly data: number[][];
+
+  constructor(
+    start: CurvePoint,
+    end: CurvePoint,
+    startTangent: CurvePoint,
+    endTangent: CurvePoint
+  ) {
+    const data = copyPoints([start, end, startTangent, endTangent]);
+    super(data[0].length);
+    this.data = data;
+  }
+
+  protected evaluate(t: number, result: NumericArray, derivative: boolean): void {
+    const t2 = t * t;
+    const h0 = derivative ? 6 * t2 - 6 * t : (1 + 2 * t) * (1 - t) ** 2;
+    const h1 = derivative ? -6 * t2 + 6 * t : t2 * (3 - 2 * t);
+    const h2 = derivative ? 3 * t2 - 4 * t + 1 : t * (1 - t) ** 2;
+    const h3 = derivative ? 3 * t2 - 2 * t : t2 * (t - 1);
+    for (let i = 0; i < this.dimension; i++) {
+      result[i] =
+        h0 * this.data[0][i] + h1 * this.data[1][i] + h2 * this.data[2][i] + h3 * this.data[3][i];
+    }
+  }
+}

package/src/curves/index.ts

@@ -0,0 +1,15 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {Curve} from './curve';
+export type {CurvePoint} from './curve';
+export {
+  LineCurve,
+  QuadraticBezierCurve,
+  CubicBezierCurve
+} from './bezier-curves';
+export {HermiteCurve} from './hermite-curve';
+export {CatmullRomCurve} from './catmull-rom-curve';
+export type {CatmullRomCurveOptions} from './catmull-rom-curve';
+export {CurveArcLength} from './curve-arc-length';

package/src/lib/geometry-utils.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import type {TypedArray, TypedArrayConstructor} from '@math.gl/types';
+import type {TypedArray, TypedArrayConstructor} from '@math.gl/core/types';
 import type {GeometryAttribute} from './geometry';
 
 type GeometryLike = {

package/src/lib/geometry.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import type {TypedArray} from '@math.gl/types';
+import type {TypedArray} from '@math.gl/core/types';
 
 export type PrimitiveTopology =
   | 'point-list'

package/src/polygon/cut-by-grid.ts

@@ -0,0 +1,313 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/* eslint-disable max-statements, max-depth, complexity, no-unused-expressions */
+import {bitCode, intersect, BoundingBox} from './lineclip';
+import {getPointAtIndex, copy, push} from './utils';
+
+import type {NumericArray} from '@math.gl/core';
+
+export type Polygon = {
+  positions: Readonly<NumericArray>;
+  holeIndices?: Readonly<NumericArray>;
+  edgeTypes?: Readonly<NumericArray>;
+};
+
+export function cutPolylineByGrid(
+  positions: NumericArray,
+  options?: {
+    size?: number;
+    broken?: boolean;
+    gridResolution?: number;
+    gridOffset?: [number, number];
+    startIndex?: number;
+    endIndex?: number;
+  }
+): number[] | number[][] {
+  const {
+    size = 2,
+    broken = false,
+    gridResolution = 10,
+    gridOffset = [0, 0],
+    startIndex = 0,
+    endIndex = positions.length
+  } = options || {};
+  const numPoints = (endIndex - startIndex) / size;
+  let part: number[] = [];
+  const result: number[][] = [part];
+  const a: number[] = getPointAtIndex(positions, 0, size, startIndex);
+  let b: number[];
+  let codeB: number;
+  const cell: BoundingBox = getGridCell(a, gridResolution, gridOffset, []);
+  const scratchPoint: number[] = [];
+  push(part, a);
+
+  for (let i = 1; i < numPoints; i++) {
+    b = getPointAtIndex(positions, i, size, startIndex, b);
+    codeB = bitCode(b, cell);
+
+    while (codeB) {
+      // find the intersection with the current cell
+      intersect(a, b, codeB, cell, scratchPoint);
+      const codeAlt = bitCode(scratchPoint, cell);
+      if (codeAlt) {
+        intersect(a, scratchPoint, codeAlt, cell, scratchPoint);
+        codeB = codeAlt;
+      }
+      push(part, scratchPoint);
+      // move to the next cell
+      copy(a, scratchPoint);
+
+      moveToNeighborCell(cell, gridResolution, codeB);
+      if (broken && part.length > size) {
+        part = [];
+        result.push(part);
+        push(part, a);
+      }
+
+      codeB = bitCode(b, cell);
+    }
+
+    push(part, b);
+    copy(a, b);
+  }
+
+  return broken ? result : result[0];
+}
+
+const TYPE_INSIDE = 0;
+const TYPE_BORDER = 1;
+
+/** Internal helper type during cutting, name TBD */
+type PolygonCut = {
+  pos: Readonly<NumericArray>;
+  types: number[];
+  holes: Readonly<NumericArray>;
+};
+
+/** Internal helper type during cutting, name TBD */
+type MutablePolygonCut = {
+  pos: number[];
+  types: number[];
+  holes: number[];
+};
+
+/**
+ * Cuts a polygon by a pre-defined grid
+ */
+export function cutPolygonByGrid(
+  positions: Readonly<NumericArray>,
+  holeIndices: Readonly<NumericArray> | null = null,
+  options?: {
+    size?: number;
+    gridResolution?: number;
+    gridOffset?: [number, number];
+    edgeTypes?: boolean;
+  }
+): Polygon[] {
+  if (!positions.length) {
+    // input is empty
+    return [];
+  }
+  const {size = 2, gridResolution = 10, gridOffset = [0, 0], edgeTypes = false} = options || {};
+  const result: Polygon[] = [];
+  const queue: PolygonCut[] = [
+    {
+      pos: positions,
+      types: edgeTypes ? (new Array(positions.length / size).fill(TYPE_BORDER) as number[]) : null,
+      holes: holeIndices || []
+    }
+  ];
+  const bbox: number[][] = [[], []];
+  // @ts-ignore
+  let cell: BoundingBox = [];
+
+  // Recursively bisect polygon until every part fit in a single grid cell
+  while (queue.length) {
+    const {pos, types, holes} = queue.shift();
+
+    // Get the bounding box of the outer polygon
+    getBoundingBox(pos, size, holes[0] || pos.length, bbox);
+    cell = getGridCell(bbox[0], gridResolution, gridOffset, cell);
+    const code = bitCode(bbox[1], cell);
+
+    if (code) {
+      // Split the outer ring at the boundary
+      let parts = bisectPolygon(pos, types, size, 0, holes[0] || pos.length, cell, code);
+      const polygonLow: MutablePolygonCut = {pos: parts[0].pos, types: parts[0].types, holes: []};
+      const polygonHigh: MutablePolygonCut = {pos: parts[1].pos, types: parts[1].types, holes: []};
+      queue.push(polygonLow, polygonHigh);
+
+      // Split each hole at the boundary
+      for (let i = 0; i < holes.length; i++) {
+        parts = bisectPolygon(pos, types, size, holes[i], holes[i + 1] || pos.length, cell, code);
+
+        if (parts[0]) {
+          polygonLow.holes.push(polygonLow.pos.length);
+          polygonLow.pos = concatInPlace(polygonLow.pos, parts[0].pos);
+          if (edgeTypes) {
+            polygonLow.types = concatInPlace(polygonLow.types, parts[0].types);
+          }
+        }
+        if (parts[1]) {
+          polygonHigh.holes.push(polygonHigh.pos.length);
+          polygonHigh.pos = concatInPlace(polygonHigh.pos, parts[1].pos);
+          if (edgeTypes) {
+            polygonHigh.types = concatInPlace(polygonHigh.types, parts[1].types);
+          }
+        }
+      }
+    } else {
+      // Polygon fits in a single cell, no more processing required
+      const polygon: Polygon = {positions: pos};
+      if (edgeTypes) {
+        polygon.edgeTypes = types;
+      }
+      if (holes.length) {
+        polygon.holeIndices = holes;
+      }
+
+      result.push(polygon);
+    }
+  }
+  return result;
+}
+
+// edgeTypes:
+// TYPE_BORDER - edge from the original polygon
+// TYPE_INSIDE - inside the original polygon
+// eslint-disable-next-line max-params
+function bisectPolygon(
+  positions: Readonly<NumericArray>,
+  edgeTypes: number[] | undefined,
+  size: number,
+  startIndex: number,
+  endIndex: number,
+  bbox: BoundingBox,
+  edge: number
+): {
+  pos: number[];
+  types?: number[];
+}[] {
+  const numPoints = (endIndex - startIndex) / size;
+  const resultLow: number[] = [];
+  const resultHigh: number[] = [];
+  const typesLow: number[] = [];
+  const typesHigh: number[] = [];
+  const scratchPoint: number[] = [];
+
+  let p: number[];
+  let side: number;
+  let type: number;
+  const prev = getPointAtIndex(positions, numPoints - 1, size, startIndex);
+  let prevSide = Math.sign(edge & 8 ? prev[1] - bbox[3] : prev[0] - bbox[2]);
+  let prevType = edgeTypes && edgeTypes[numPoints - 1];
+  let lowPointCount = 0;
+  let highPointCount = 0;
+
+  for (let i = 0; i < numPoints; i++) {
+    p = getPointAtIndex(positions, i, size, startIndex, p);
+    side = Math.sign(edge & 8 ? p[1] - bbox[3] : p[0] - bbox[2]);
+    type = edgeTypes && edgeTypes[startIndex / size + i];
+
+    // if segment goes through the boundary, add an intersection
+    if (side && prevSide && prevSide !== side) {
+      intersect(prev, p, edge, bbox, scratchPoint);
+      push(resultLow, scratchPoint) && typesLow.push(prevType);
+      push(resultHigh, scratchPoint) && typesHigh.push(prevType);
+    }
+
+    if (side <= 0) {
+      push(resultLow, p) && typesLow.push(type);
+      lowPointCount -= side;
+    } else if (typesLow.length) {
+      typesLow[typesLow.length - 1] = TYPE_INSIDE;
+    }
+    if (side >= 0) {
+      push(resultHigh, p) && typesHigh.push(type);
+      highPointCount += side;
+    } else if (typesHigh.length) {
+      typesHigh[typesHigh.length - 1] = TYPE_INSIDE;
+    }
+
+    copy(prev, p);
+    prevSide = side;
+    prevType = type;
+  }
+
+  return [
+    lowPointCount ? {pos: resultLow, types: edgeTypes && typesLow} : null,
+    highPointCount ? {pos: resultHigh, types: edgeTypes && typesHigh} : null
+  ];
+}
+
+function getGridCell(
+  p: number[],
+  gridResolution: number,
+  gridOffset: [number, number],
+  out: number[]
+): BoundingBox {
+  const left = Math.floor((p[0] - gridOffset[0]) / gridResolution) * gridResolution + gridOffset[0];
+  const bottom =
+    Math.floor((p[1] - gridOffset[1]) / gridResolution) * gridResolution + gridOffset[1];
+  out[0] = left;
+  out[1] = bottom;
+  out[2] = left + gridResolution;
+  out[3] = bottom + gridResolution;
+  return out as BoundingBox;
+}
+
+function moveToNeighborCell(cell: number[], gridResolution: number, edge: number): void {
+  if (edge & 8) {
+    // top
+    cell[1] += gridResolution;
+    cell[3] += gridResolution;
+  } else if (edge & 4) {
+    // bottom
+    cell[1] -= gridResolution;
+    cell[3] -= gridResolution;
+  } else if (edge & 2) {
+    // right
+    cell[0] += gridResolution;
+    cell[2] += gridResolution;
+  } else if (edge & 1) {
+    // left
+    cell[0] -= gridResolution;
+    cell[2] -= gridResolution;
+  }
+}
+
+function getBoundingBox(
+  positions: Readonly<NumericArray>,
+  size: number,
+  endIndex: number,
+  out: number[][]
+): number[][] {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+
+  for (let i = 0; i < endIndex; i += size) {
+    const x = positions[i];
+    const y = positions[i + 1];
+    minX = x < minX ? x : minX;
+    maxX = x > maxX ? x : maxX;
+    minY = y < minY ? y : minY;
+    maxY = y > maxY ? y : maxY;
+  }
+
+  out[0][0] = minX;
+  out[0][1] = minY;
+  out[1][0] = maxX;
+  out[1][1] = maxY;
+  return out;
+}
+
+function concatInPlace(arr1: number[], arr2: number[]): number[] {
+  for (let i = 0; i < arr2.length; i++) {
+    arr1.push(arr2[i]);
+  }
+  return arr1;
+}

package/src/polygon/cut-by-mercator-bounds.ts

@@ -0,0 +1,204 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {cutPolylineByGrid, cutPolygonByGrid} from './cut-by-grid';
+import {getPointAtIndex, push} from './utils';
+import type {Polygon} from './cut-by-grid';
+import type {NumericArray} from '@math.gl/core';
+
+// https://en.wikipedia.org/wiki/Web_Mercator_projection
+const DEFAULT_MAX_LATITUDE = 85.051129;
+
+/** https://user-images.githubusercontent.com/2059298/78465769-938b7a00-76ae-11ea-9b95-1f4c26425ab9.png */
+export function cutPolylineByMercatorBounds(
+  positions: Readonly<NumericArray>,
+  options?: {
+    size?: number;
+    startIndex?: number;
+    endIndex?: number;
+    normalize?: boolean;
+  }
+): number[][] {
+  const {size = 2, startIndex = 0, endIndex = positions.length, normalize = true} = options || {};
+
+  // Remap longitudes so that each segment takes the shorter path
+  const newPositions = positions.slice(startIndex, endIndex);
+  wrapLongitudesForShortestPath(newPositions, size, 0, endIndex - startIndex);
+
+  const parts = cutPolylineByGrid(newPositions, {
+    size,
+    broken: true,
+    gridResolution: 360,
+    gridOffset: [-180, -180]
+  }) as number[][];
+
+  if (normalize) {
+    // Each part is guaranteed to be in a single copy of the world
+    // Map longitudes back to [-180, 180]
+    for (const part of parts) {
+      shiftLongitudesIntoRange(part, size);
+    }
+  }
+  return parts;
+}
+
+/** https://user-images.githubusercontent.com/2059298/78465770-94241080-76ae-11ea-809a-6a8534dac1d9.png */
+export function cutPolygonByMercatorBounds(
+  positions: Readonly<NumericArray>,
+  holeIndices: Readonly<NumericArray> | null = null,
+  options?: {
+    size?: number;
+    normalize?: boolean;
+    maxLatitude?: number;
+    edgeTypes?: boolean;
+  }
+): Polygon[] {
+  const {size = 2, normalize = true, edgeTypes = false} = options || {};
+  holeIndices = holeIndices || [];
+  const newPositions: number[] = [];
+  const newHoleIndices: number[] = [];
+  let srcStartIndex = 0;
+  let targetIndex = 0;
+
+  for (let ringIndex = 0; ringIndex <= holeIndices.length; ringIndex++) {
+    // srcStartIndex/srcEndIndex define the ring in the original positions
+    const srcEndIndex = holeIndices[ringIndex] || positions.length;
+    // targetStartIndex/targetIndex define the ring in newPositions
+    const targetStartIndex = targetIndex;
+
+    // In case the ring contains a pole (e.g. Antarctica), we'll have to insert vertices
+    // The insertion point is defined by the vertex closest to the pole
+    // Split the the ring by the insertion point when copying to newPositions
+    const splitIndex = findSplitIndex(positions, size, srcStartIndex, srcEndIndex);
+    for (let i = splitIndex; i < srcEndIndex; i++) {
+      newPositions[targetIndex++] = positions[i];
+    }
+    for (let i = srcStartIndex; i < splitIndex; i++) {
+      newPositions[targetIndex++] = positions[i];
+    }
+
+    // Remap longitudes so that each segment takes the shorter path
+    wrapLongitudesForShortestPath(newPositions, size, targetStartIndex, targetIndex);
+
+    // Handle the case when the ring contains a pole
+    insertPoleVertices(newPositions, size, targetStartIndex, targetIndex, options?.maxLatitude);
+
+    srcStartIndex = srcEndIndex;
+    newHoleIndices[ringIndex] = targetIndex;
+  }
+  newHoleIndices.pop();
+
+  const parts = cutPolygonByGrid(newPositions, newHoleIndices, {
+    size,
+    gridResolution: 360,
+    gridOffset: [-180, -180],
+    edgeTypes
+  });
+
+  if (normalize) {
+    // Each part is guaranteed to be in a single copy of the world
+    // Map longitudes back to [-180, 180]
+    for (const part of parts) {
+      // May mutate newPositions, which is created by us.
+      shiftLongitudesIntoRange(part.positions as NumericArray, size);
+    }
+  }
+  return parts;
+}
+
+/* Helpers */
+
+// See comments for insertPoleVertices
+function findSplitIndex(
+  positions: Readonly<NumericArray>,
+  size: number,
+  startIndex: number,
+  endIndex: number
+): number {
+  let maxLat = -1;
+  let pointIndex = -1;
+  for (let i = startIndex + 1; i < endIndex; i += size) {
+    const lat = Math.abs(positions[i]);
+    if (lat > maxLat) {
+      maxLat = lat;
+      pointIndex = i - 1;
+    }
+  }
+  return pointIndex;
+}
+
+// https://user-images.githubusercontent.com/2059298/78857483-5987e400-79de-11ea-98fc-0631287a8431.png
+//
+// If the polygon contains a pole, to tesselate it correctly, we need to insert the edge
+// of map into the polygon. This requires adding two vertices that represent the pole, by
+// drawing a perpendicular line to the Mercator map edge from a selected vertex on the ring.
+//
+// We select the insertion position carefully so that the inserted line segments do not
+// intersect with the ring itself. This is ensured by findSplitIndex, which returns the
+// vertex closest to the pole.
+function insertPoleVertices(
+  positions: number[],
+  size: number,
+  startIndex: number,
+  endIndex: number,
+  maxLatitude: number = DEFAULT_MAX_LATITUDE
+): void {
+  // Check if the ring contains a pole
+  const firstLng = positions[startIndex];
+  const lastLng = positions[endIndex - size];
+  if (Math.abs(firstLng - lastLng) > 180) {
+    // The ring does not make a round trip
+    // Add the nearest pole to the vertices so that the polygon tesselates correctly
+    const p = getPointAtIndex(positions, 0, size, startIndex);
+    // Copy the first vertex to the world of the last vertex
+    p[0] += Math.round((lastLng - firstLng) / 360) * 360;
+    push(positions, p);
+    // Project the copied vertex to the edge of the map
+    p[1] = Math.sign(p[1]) * maxLatitude;
+    push(positions, p);
+    // Project the first vertex to the edge of the map
+    p[0] = firstLng;
+    push(positions, p);
+  }
+}
+
+function wrapLongitudesForShortestPath(
+  positions: NumericArray,
+  size: number,
+  startIndex: number,
+  endIndex: number
+): void {
+  let prevLng: number = positions[0];
+  let lng: number;
+  for (let i = startIndex; i < endIndex; i += size) {
+    lng = positions[i];
+    const delta = lng - prevLng;
+    if (delta > 180 || delta < -180) {
+      lng -= Math.round(delta / 360) * 360;
+    }
+    positions[i] = prevLng = lng;
+  }
+}
+
+function shiftLongitudesIntoRange(positions: NumericArray, size: number): void {
+  let refLng: number;
+  const pointCount = positions.length / size;
+
+  // Find a longitude that is not on the edge of a world
+  // Which we will use to determine which world copy it is
+  for (let i = 0; i < pointCount; i++) {
+    refLng = positions[i * size];
+    if ((refLng + 180) % 360 !== 0) {
+      break;
+    }
+  }
+
+  const delta = -Math.round(refLng / 360) * 360;
+  if (delta === 0) {
+    return;
+  }
+  for (let i = 0; i < pointCount; i++) {
+    positions[i * size] += delta;
+  }
+}