@math.gl/geometry 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/polygon/index.ts

@@ -0,0 +1,35 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {Polygon} from './polygon';
+
+export {
+  getPolygonSignedArea,
+  getPolygonWindingDirection,
+  forEachSegmentInPolygon,
+  modifyPolygonWindingDirection
+} from './polygon-utils';
+export type {PolygonWinding, WindingDirection} from './polygon-utils';
+
+export {earcut} from './earcut';
+
+export {clipPolygon, clipPolyline} from './lineclip';
+
+export {cutPolygonByGrid, cutPolylineByGrid} from './cut-by-grid';
+
+export {cutPolylineByMercatorBounds, cutPolygonByMercatorBounds} from './cut-by-mercator-bounds';
+
+export {subdividePolyline} from './subdivide-polyline';
+export type {
+  SubdividePolylineOptions,
+  SubdividedPolyline,
+  PolylineEdgeSampler
+} from './subdivide-polyline';
+
+export {subdivideTriangleMesh} from './subdivide-triangle-mesh';
+export type {
+  TriangleMesh,
+  SubdivideTriangleMeshOptions,
+  SubdividedTriangleMesh
+} from './subdivide-triangle-mesh';

package/src/polygon/lineclip.ts

@@ -0,0 +1,218 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND ISC
+// SPDX-FileCopyrightText: Copyright (c) 2015, Mapbox
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Adapted from Mapbox lineclip for flat arrays and 3D positions. Original ISC notice retained below.
+
+/*
+  Adapted from https://github.com/mapbox/lineclip to work with flat arrays
+  and 3d positions
+
+  ISC License
+
+  Copyright (c) 2015, Mapbox
+
+  Permission to use, copy, modify, and/or distribute this software for any purpose
+  with or without fee is hereby granted, provided that the above copyright notice
+  and this permission notice appear in all copies.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+  TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+  THIS SOFTWARE.
+
+ */
+
+/* eslint-disable max-statements, max-depth, complexity */
+
+import {push, copy, getPointAtIndex} from './utils';
+import type {NumericArray} from '@math.gl/core';
+
+export type BoundingBox = [number, number, number, number];
+
+/**
+ * Cohen-Sutherland line clipping algorithm, adapted to efficiently
+ * handle polylines rather than just segments
+ */
+export function clipPolyline(
+  positions: Readonly<NumericArray>,
+  bbox: BoundingBox,
+  options?: {
+    size?: number;
+    startIndex?: number;
+    endIndex?: number;
+  }
+): number[][] {
+  const {size = 2, startIndex = 0, endIndex = positions.length} = options || {};
+  const numPoints = (endIndex - startIndex) / size;
+  const result: number[][] = [];
+  let part: number[] = [];
+  let a: number[];
+  let b: number[];
+  let codeA: number = -1;
+  let codeB: number;
+  let lastCode: number;
+
+  for (let i = 1; i < numPoints; i++) {
+    a = getPointAtIndex(positions, i - 1, size, startIndex, a);
+    b = getPointAtIndex(positions, i, size, startIndex, b);
+    if (codeA < 0) {
+      codeA = bitCode(a, bbox);
+    }
+    codeB = lastCode = bitCode(b, bbox);
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      if (!(codeA | codeB)) {
+        // accept
+        push(part, a);
+
+        if (codeB !== lastCode) {
+          // segment went outside
+          push(part, b);
+
+          if (i < numPoints - 1) {
+            // start a new line
+            result.push(part);
+            part = [];
+          }
+        } else if (i === numPoints - 1) {
+          push(part, b);
+        }
+        break;
+      } else if (codeA & codeB) {
+        // trivial reject
+        break;
+      } else if (codeA) {
+        // a outside, intersect with clip edge
+        intersect(a, b, codeA, bbox, a);
+        codeA = bitCode(a, bbox);
+      } else {
+        // b outside
+        intersect(a, b, codeB, bbox, b);
+        codeB = bitCode(b, bbox);
+      }
+    }
+
+    codeA = lastCode;
+  }
+
+  if (part.length) result.push(part);
+
+  return result;
+}
+
+/**
+ * Sutherland-Hodgeman polygon clipping algorithm
+ * polygon must be closed (first vertex == last vertex)
+ */
+export function clipPolygon(
+  positions: Readonly<NumericArray>,
+  bbox: BoundingBox,
+  options?: {
+    size?: number;
+    startIndex?: number;
+    endIndex?: number;
+  }
+): number[] {
+  const {size = 2, endIndex = positions.length} = options || {};
+  let {startIndex = 0} = options || {};
+  let numPoints = (endIndex - startIndex) / size;
+  let result: number[];
+  let p: number[];
+  let prev: number[];
+  let inside: boolean;
+  let prevInside: boolean;
+
+  // clip against each side of the clip rectangle
+  for (let edge = 1; edge <= 8; edge *= 2) {
+    result = [];
+    prev = getPointAtIndex(positions, numPoints - 1, size, startIndex, prev);
+    prevInside = !(bitCode(prev, bbox) & edge);
+
+    for (let i = 0; i < numPoints; i++) {
+      p = getPointAtIndex(positions, i, size, startIndex, p);
+      inside = !(bitCode(p, bbox) & edge);
+
+      // if segment goes through the clip window, add an intersection
+      if (inside !== prevInside) push(result, intersect(prev, p, edge, bbox));
+
+      if (inside) push(result, p); // add a point if it's inside
+
+      copy(prev, p);
+      prevInside = inside;
+    }
+
+    // close loop
+    positions = result;
+    startIndex = 0;
+    numPoints = result.length / size;
+
+    if (!numPoints) break;
+  }
+
+  return result;
+}
+
+/** intersect a segment against one of the 4 lines that make up the bbox */
+
+export function intersect(
+  a: number[],
+  b: number[],
+  edge: number,
+  bbox: BoundingBox,
+  out: number[] = []
+): number[] {
+  let t;
+  // Forces out[snapI] to be on the bbox edge
+  // Interpolation introduces precision issue which may cause lineclip to be
+  // stuck in an infinite loop
+  let snap: number;
+  if (edge & 8) {
+    // top
+    t = (bbox[3] - a[1]) / (b[1] - a[1]);
+    snap = 3;
+  } else if (edge & 4) {
+    // bottom
+    t = (bbox[1] - a[1]) / (b[1] - a[1]);
+    snap = 1;
+  } else if (edge & 2) {
+    // right
+    t = (bbox[2] - a[0]) / (b[0] - a[0]);
+    snap = 2;
+  } else if (edge & 1) {
+    // left
+    t = (bbox[0] - a[0]) / (b[0] - a[0]);
+    snap = 0;
+  } else {
+    return null;
+  }
+  for (let i = 0; i < a.length; i++) {
+    out[i] = (snap & 1) === i ? bbox[snap] : t * (b[i] - a[i]) + a[i];
+  }
+  return out;
+}
+
+/**
+ * bit code reflects the point position relative to the bbox:
+ *         left  mid  right
+ *    top  1001  1000  1010
+ *    mid  0001  0000  0010
+ * bottom  0101  0100  0110
+ */
+export function bitCode(p: number[], bbox: BoundingBox): number {
+  let code = 0;
+
+  if (p[0] < bbox[0]) code |= 1;
+  // left
+  else if (p[0] > bbox[2]) code |= 2; // right
+
+  if (p[1] < bbox[1]) code |= 4;
+  // bottom
+  else if (p[1] > bbox[3]) code |= 8; // top
+
+  return code;
+}

package/src/polygon/polygon-utils.ts

@@ -0,0 +1,273 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND ISC
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/* eslint-disable max-statements, max-depth, complexity, no-unused-expressions */
+
+import {equals} from '@math.gl/core';
+import type {NumericArray} from '@math.gl/core';
+
+/** Direction in which a polygon's vertices are ordered. */
+export type WindingDirection = 'clockwise' | 'counter-clockwise' | 'none';
+
+/** A non-degenerate polygon winding direction. */
+export type PolygonWinding = Exclude<WindingDirection, 'none'>;
+
+/** Polygon representation where each point is represented as a separate array of positions. */
+type PointsArray = NumericArray[];
+
+/** Segment visitor callback type for polygons defined with flat arrays, */
+type SegmentVisitorFlat = (
+  p1x: number,
+  p1y: number,
+  p2x: number,
+  p2y: number,
+  i1: number,
+  i2: number
+) => void;
+
+/** Segment visitor callback type for polygons defined with array of points. */
+export type SegmentVisitorPoints = (
+  p1: NumericArray,
+  p2: NumericArray,
+  i1: number,
+  i2: number
+) => void;
+
+export type Plane2D = 'xy' | 'yz' | 'xz';
+
+/** Parameters of a polygon. */
+type PolygonParams = {
+  /**
+   * Start index of the polygon in the array of positions.
+   * @default `0`
+   */
+  start?: number;
+  /**
+   * End index of the polygon in the array of positions.
+   * @default number of positions
+   */
+  end?: number;
+  /**
+   * Size of a point, 2 (XZ) or 3 (XYZ). Affects only polygons stored in flat arrays.
+   * @default `2`
+   */
+  size?: number;
+  /**
+   * Indicates that the first point of the polygon is equal to the last point, and additional checks should be ommited.
+   */
+  isClosed?: boolean;
+  /**
+   * The 2D projection plane on which to calculate the area of a 3D polygon.
+   * @default `'xy'`
+   */
+  plane?: Plane2D;
+};
+
+/**
+ * Checks winding direction of the polygon and reverses the polygon in case of opposite winding direction.
+ * Note: points are modified in-place.
+ * @param points An array that represents points of the polygon.
+ * @param direction Requested winding direction.
+ * @param options Parameters of the polygon.
+ * @return Returns true if the winding direction was changed.
+ */
+export function modifyPolygonWindingDirection(
+  points: NumericArray,
+  direction: PolygonWinding,
+  options: PolygonParams = {}
+): boolean {
+  const windingDirection = getPolygonWindingDirection(points, options);
+  if (windingDirection !== direction) {
+    reversePolygon(points, options);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Returns winding direction of the polygon.
+ * @param points An array that represents points of the polygon.
+ * @param options Parameters of the polygon.
+ * @returns Winding direction of the polygon.
+ */
+export function getPolygonWindingDirection(
+  points: NumericArray,
+  options: PolygonParams = {}
+): WindingDirection {
+  return getWindingDirection(getPolygonSignedArea(points, options));
+}
+
+export const DimIndex: Record<string, number> = {
+  x: 0,
+  y: 1,
+  z: 2
+} as const;
+
+/**
+ * Returns signed area of the polygon.
+ * @param points An array that represents points of the polygon.
+ * @param options Parameters of the polygon.
+ * @returns Signed area of the polygon.
+ * https://en.wikipedia.org/wiki/Shoelace_formula
+ */
+export function getPolygonSignedArea(points: NumericArray, options: PolygonParams = {}): number {
+  const {start = 0, end = points.length, plane = 'xy'} = options;
+  const dim = options.size || 2;
+  let area = 0;
+  const i0 = DimIndex[plane[0]];
+  const i1 = DimIndex[plane[1]];
+
+  for (let i = start, j = end - dim; i < end; i += dim) {
+    area += (points[i + i0] - points[j + i0]) * (points[i + i1] + points[j + i1]);
+    j = i;
+  }
+  return area / 2;
+}
+
+/**
+ * Calls the visitor callback for each segment in the polygon.
+ * @param points An array that represents points of the polygon
+ * @param visitor A callback to call for each segment.
+ * @param options Parameters of the polygon.
+ */
+export function forEachSegmentInPolygon(
+  points: NumericArray,
+  visitor: SegmentVisitorFlat,
+  options: PolygonParams = {}
+): void {
+  const {start = 0, end = points.length, size = 2, isClosed} = options;
+
+  const numPoints = (end - start) / size;
+  for (let i = 0; i < numPoints - 1; ++i) {
+    visitor(
+      points[start + i * size],
+      points[start + i * size + 1],
+      points[start + (i + 1) * size],
+      points[start + (i + 1) * size + 1],
+      i,
+      i + 1
+    );
+  }
+
+  const endPointIndex = start + (numPoints - 1) * size;
+  const isClosedEx =
+    isClosed ||
+    (equals(points[start], points[endPointIndex]) &&
+      equals(points[start + 1], points[endPointIndex + 1]));
+
+  if (!isClosedEx) {
+    visitor(
+      points[endPointIndex],
+      points[endPointIndex + 1],
+      points[start],
+      points[start + 1],
+      numPoints - 1,
+      0
+    );
+  }
+}
+
+function reversePolygon(
+  points: NumericArray,
+  options: {start?: number; end?: number; size?: number}
+): void {
+  const {start = 0, end = points.length, size = 2} = options;
+
+  const numPoints = (end - start) / size;
+  const numSwaps = Math.floor(numPoints / 2);
+  for (let i = 0; i < numSwaps; ++i) {
+    const b1 = start + i * size;
+    const b2 = start + (numPoints - 1 - i) * size;
+    for (let j = 0; j < size; ++j) {
+      const tmp = points[b1 + j];
+      points[b1 + j] = points[b2 + j];
+      points[b2 + j] = tmp;
+    }
+  }
+}
+
+/**
+ * Checks winding direction of the polygon and reverses the polygon in case of opposite winding direction.
+ * Note: points are modified in-place.
+ * @param points Array of points that represent the polygon.
+ * @param direction Requested winding direction.
+ * @param options Parameters of the polygon.
+ * @return Returns true if the winding direction was changed.
+ */
+export function modifyPolygonWindingDirectionPoints(
+  points: PointsArray,
+  direction: PolygonWinding,
+  options: PolygonParams = {}
+): boolean {
+  const currentDirection = getPolygonWindingDirectionPoints(points, options);
+  if (currentDirection !== direction) {
+    points.reverse();
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Returns winding direction of the polygon.
+ * @param points Array of points that represent the polygon.
+ * @param options Parameters of the polygon.
+ * @returns Winding direction of the polygon.
+ */
+export function getPolygonWindingDirectionPoints(
+  points: PointsArray,
+  options: PolygonParams = {}
+): WindingDirection {
+  return getWindingDirection(getPolygonSignedAreaPoints(points, options));
+}
+
+function getWindingDirection(signedArea: number): WindingDirection {
+  if (signedArea > 0) return 'clockwise';
+  if (signedArea < 0) return 'counter-clockwise';
+  return 'none';
+}
+
+/**
+ * Returns signed area of the polygon.
+ * @param points Array of points that represent the polygon.
+ * @param options Parameters of the polygon.
+ * @returns Signed area of the polygon.
+ */
+export function getPolygonSignedAreaPoints(
+  points: PointsArray,
+  options: PolygonParams = {}
+): number {
+  // https://en.wikipedia.org/wiki/Shoelace_formula
+  const {start = 0, end = points.length, plane = 'xy'} = options;
+  let area = 0;
+  const i0 = DimIndex[plane[0]];
+  const i1 = DimIndex[plane[1]];
+
+  for (let i = start, j = end - 1; i < end; ++i) {
+    area += (points[i][i0] - points[j][i0]) * (points[i][i1] + points[j][i1]);
+    j = i;
+  }
+  return area / 2;
+}
+
+/**
+ * Calls visitor callback for each segment in the polygon.
+ * @param points Array of points that represent the polygon.
+ * @param visitor A callback to call for each segment.
+ * @param options Parameters of the polygon.
+ */
+export function forEachSegmentInPolygonPoints(
+  points: PointsArray,
+  visitor: SegmentVisitorPoints,
+  options: PolygonParams = {}
+): void {
+  const {start = 0, end = points.length, isClosed} = options;
+  for (let i = start; i < end - 1; ++i) {
+    visitor(points[i], points[i + 1], i, i + 1);
+  }
+
+  const isClosedEx = isClosed || equals(points[end - 1], points[0]);
+  if (!isClosedEx) {
+    visitor(points[end - 1], points[0], end - 1, 0);
+  }
+}

package/src/polygon/polygon.ts

@@ -0,0 +1,105 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/* eslint-disable no-undef, no-console */
+import {isArray} from '@math.gl/core';
+import type {PolygonWinding, SegmentVisitorPoints, WindingDirection} from './polygon-utils';
+import type {NumericArray} from '@math.gl/core';
+
+import {
+  getPolygonSignedArea,
+  forEachSegmentInPolygon,
+  modifyPolygonWindingDirection,
+  getPolygonSignedAreaPoints,
+  forEachSegmentInPolygonPoints,
+  modifyPolygonWindingDirectionPoints
+} from './polygon-utils';
+
+export type PolygonOptions = {
+  start?: number;
+  end?: number;
+  size?: number;
+  isClosed?: boolean;
+};
+
+export class Polygon {
+  points: NumericArray | number[][];
+  isFlatArray: boolean;
+  options: PolygonOptions;
+
+  constructor(points: NumericArray | number[][], options: PolygonOptions = {}) {
+    this.points = points;
+    this.isFlatArray = !isArray(points[0]);
+
+    this.options = {
+      start: options.start || 0,
+      end: options.end || points.length,
+      size: options.size || 2,
+      isClosed: options.isClosed
+    };
+
+    Object.freeze(this);
+  }
+
+  /**
+   * Returns signed area of the polygon.
+   * @returns Signed area of the polygon.
+   */
+  getSignedArea(): number {
+    if (this.isFlatArray) return getPolygonSignedArea(this.points as NumericArray, this.options);
+
+    return getPolygonSignedAreaPoints(this.points as number[][], this.options);
+  }
+
+  /**
+   * Returns absolute area of the polygon.
+   * @returns Absolute area of the polygon.
+   */
+  getArea(): number {
+    return Math.abs(this.getSignedArea());
+  }
+
+  /**
+   * Returns winding direction of the polygon.
+   * @returns `'clockwise'`, `'counter-clockwise'`, or `'none'` for a degenerate polygon.
+   */
+  getWindingDirection(): WindingDirection {
+    const signedArea = this.getSignedArea();
+    if (signedArea > 0) return 'clockwise';
+    if (signedArea < 0) return 'counter-clockwise';
+    return 'none';
+  }
+
+  /**
+   * Calls the visitor callback for each segment in the polygon.
+   * @param visitor A callback to call for each segment.
+   */
+  forEachSegment(visitor: SegmentVisitorPoints): void {
+    if (this.isFlatArray) {
+      forEachSegmentInPolygon(
+        this.points as NumericArray,
+        // eslint-disable-next-line max-params
+        (x1, y1, x2, y2, i1, i2) => {
+          // TODO @igorDykhta original visitor uses arrays for each point, but with flat arrays performance degrades if we allocate points for each segment
+          visitor([x1, y1], [x2, y2], i1, i2);
+        },
+        this.options
+      );
+    } else {
+      forEachSegmentInPolygonPoints(this.points as number[][], visitor, this.options);
+    }
+  }
+
+  /**
+   * Checks winding direction of the polygon and reverses the polygon in case of opposite winding direction.
+   * @param direction Requested winding direction.
+   * @return Returns true if the winding direction was changed.
+   */
+  modifyWindingDirection(direction: PolygonWinding): boolean {
+    if (this.isFlatArray) {
+      return modifyPolygonWindingDirection(this.points as NumericArray, direction, this.options);
+    }
+    return modifyPolygonWindingDirectionPoints(this.points as number[][], direction, this.options);
+  }
+}