@math.gl/polygon 3.5.7 → 3.6.0-alpha.3

package/src/polygon-utils.ts

@@ -0,0 +1,228 @@
+/* eslint-disable max-statements, max-depth, complexity, no-unused-expressions */
+
+import {equals} from '@math.gl/core';
+import type {NumericArray} from '@math.gl/core';
+
+export enum WINDING {
+  CLOCKWISE = 1,
+  COUNTER_CLOCKWISE = -1
+}
+
+/** 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;
+
+/** Parameters of a polygon. */
+type PolygonParams = {
+  start?: number; // Start index of the polygon in the array of positions. Defaults to 0.
+  end?: number; // End index of the polygon in the array of positions. Defaults to number of positions.
+  size?: number; // Size of a point, 2 (XZ) or 3 (XYZ). Defaults to 2. Affects only polygons stored in flat arrays.
+  isClosed?: boolean; // Indicates that the first point of the polygon is equal to the last point, and additional checks should be ommited.
+};
+
+/**
+ * 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. 1 is for clockwise, -1 for counterclockwise winding direction.
+ * @param options Parameters of the polygon.
+ * @return Returns true if the winding direction was changed.
+ */
+export function modifyPolygonWindingDirection(
+  points: NumericArray,
+  direction: number,
+  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 = {}
+): number {
+  return Math.sign(getPolygonSignedArea(points, options));
+}
+
+/**
+ * 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} = options;
+  const dim = options.size || 2;
+  let area = 0;
+  for (let i = start, j = end - dim; i < end; i += dim) {
+    area += (points[i] - points[j]) * (points[i + 1] + points[j + 1]);
+    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. 1 is for clockwise, -1 for counterclockwise winding direction.
+ * @param options Parameters of the polygon.
+ * @return Returns true if the winding direction was changed.
+ */
+export function modifyPolygonWindingDirectionPoints(
+  points: PointsArray,
+  direction: number,
+  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 = {}
+): number {
+  return Math.sign(getPolygonSignedAreaPoints(points, options));
+}
+
+/**
+ * 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} = options;
+  let area = 0;
+  for (let i = start, j = end - 1; i < end; ++i) {
+    area += (points[i][0] - points[j][0]) * (points[i][1] + points[j][1]);
+    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.ts

@@ -0,0 +1,98 @@
+/* eslint-disable no-undef, no-console */
+import {isArray} from '@math.gl/core';
+import type {SegmentVisitorPoints} 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 default 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 Winding direction of the polygon. 1 is for clockwise, -1 for counterclockwise winding direction.
+   */
+  getWindingDirection(): number {
+    return Math.sign(this.getSignedArea());
+  }
+
+  /**
+   * 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. 1 is for clockwise, -1 for counterclockwise winding direction.
+   * @return Returns true if the winding direction was changed.
+   */
+  modifyWindingDirection(direction: number): boolean {
+    if (this.isFlatArray) {
+      return modifyPolygonWindingDirection(this.points as NumericArray, direction, this.options);
+    }
+    return modifyPolygonWindingDirectionPoints(this.points as number[][], direction, this.options);
+  }
+}

package/src/{utils.js → utils.ts}

@@ -1,4 +1,6 @@
-export function push(target, source) {
+import type {NumericArray} from '@math.gl/core';
+
+export function push(target: number[], source: number[]): boolean {
   const size = source.length;
   const startIndex = target.length;
 
@@ -22,14 +24,20 @@ export function push(target, source) {
   return true;
 }
 
-export function copy(target, source) {
+export function copy(target: number[], source: Readonly<NumericArray>): void {
   const size = source.length;
   for (let i = 0; i < size; i++) {
     target[i] = source[i];
   }
 }
 
-export function getPointAtIndex(positions, index, size, offset, out = []) {
+export function getPointAtIndex(
+  positions: NumericArray,
+  index: number,
+  size: number,
+  offset: number,
+  out: number[] = []
+): number[] {
   const startI = offset + index * size;
   for (let i = 0; i < size; i++) {
     out[i] = positions[startI + i];

package/dist/es5/cut-by-grid.d.ts

@@ -1,24 +0,0 @@
-type Polygon = {positions: Array<number>, holeIndices?: Array<number>, vertexTypes?: Array<Number>};
-
-export function cutPolylineByGrid(
-  positions : Array<number>,
-  options? : {
-    size? : number,
-    broken? : boolean,
-    gridResolution? : number,
-    gridOffset? : [number, number],
-    startIndex? : number,
-    endIndex? : number
-  }
-) : Array<number> | Array<Array<number>>;
-
-export function cutPolygonByGrid(
-  positions : Array<number>,
-  holeIndices : Array<number> | null,
-  options? : {
-    size? : number,
-    gridResolution? : number,
-    gridOffset? : [number, number],
-    edgeTypes? : boolean
-  }
-) : Array<Polygon>;

package/dist/es5/cut-by-mercator-bounds.d.ts

@@ -1,23 +0,0 @@
-import {Polygon} from "./cut-by-grid";
-
-export function cutPolylineByMercatorBounds(
-  positions : Array<number>,
-  options? : {
-    size? : number,
-    startIndex? : number,
-    endIndex? : number,
-    normalize? : boolean
-  }
-) : Array<number>;
-
-export function cutPolygonByMercatorBounds(
-  positions : Array<number>,
-  holeIndices : Array<number> | null,
-  options? : {
-    size? : number,
-    normalize? : boolean,
-    maxLatitude?: number,
-    edgeTypes? : boolean
-  }
-) : Array<Polygon>;
-

package/dist/es5/earcut.d.ts

@@ -1,9 +0,0 @@
-/**
- * Computes a triangulation of a polygon
- * @param positions a flat array of the vertex positions that define the polygon.
- * @param holeIndices an array of hole indices if any (e.g. [5, 8] for a 12-vertex input would mean one hole with vertices 5–7 and another with 8–11).
- * @param size the number of elements in each vertex. Size `2` will interpret `positions` as `[x0, y0, x1, y1, ...]` and size `3` will interpret `positions` as `[x0, y0, z0, x1, y1, z1, ...]`. Default `2`.
- * @param areas areas of outer polygon and holes as computed by `getPolygonSignedArea()`. Can be optionally supplied to speed up triangulation
- * @returns array of indices into the `positions` array that describes the triangulation of the polygon
- */
-export function earcut(positions: number[], holeIndices?: number[], size?: number, areas?: number[]): number[];

package/dist/es5/lineclip.d.ts

@@ -1,25 +0,0 @@
-type BoundingBox = [number, number, number, number];
-
-export function clipPolyline(
-  positions : Array<number>,
-  bbox : BoundingBox,
-  options? : {
-    size? : number,
-    startIndex? : number,
-    endIndex? : number
-  }
-) : Array<Array<number>>;
-
-export function clipPolygon(
-  positions: Array<number>,
-  bbox: BoundingBox,
-  options? : {
-    size? : number,
-    startIndex? : number,
-    endIndex? : number
-  }
-) : Array<number>;
-
-export function intersect(a : Array<number>, b : Array<number>, edge : number, bbox : BoundingBox, out? : Array<number>);
-
-export function bitCode(p: Array<number>, bbox : BoundingBox) : number;

package/dist/es5/polygon.d.ts

@@ -1,36 +0,0 @@
-import {SegmentVisitorPoints} from './polygon-utils';
-
-export default class Polygon {
-  constructor(points: number[], options: {start?: number, end?: number,size?: number, isClosed?: boolean});
-
-  /**
-   * Returns signed area of the polygon.
-   * @returns Signed area of the polygon.
-   */
-  getSignedArea(): number; 
-
-  /**
-   * Returns absolute area of the polygon.
-   * @returns Absolute area of the polygon.
-   */
-  getArea(): number;
-
-  /**
-   * Returns winding direction of the polygon.
-   * @returns Winding direction of the polygon. 1 is for clockwise, -1 for counterclockwise winding direction.
-   */
-  getWindingDirection(): number;
-
-  /**
-   * Calls the visitor callback for each segment in the polygon.
-   * @param visitor A callback to call for each segment.
-   */
-  forEachSegment(SegmentVisitorPoints): void;
-
-  /**
-   * Checks winding direction of the polygon and reverses the polygon in case of opposite winding direction.
-   * @param direction Requested winding direction. 1 is for clockwise, -1 for counterclockwise winding direction.
-   * @return Returns true if the winding direction was changed.
-   */
-  modifyWindingDirection(direction: number): boolean;
-}

package/dist/esm/cut-by-grid.d.ts

@@ -1,24 +0,0 @@
-type Polygon = {positions: Array<number>, holeIndices?: Array<number>, vertexTypes?: Array<Number>};
-
-export function cutPolylineByGrid(
-  positions : Array<number>,
-  options? : {
-    size? : number,
-    broken? : boolean,
-    gridResolution? : number,
-    gridOffset? : [number, number],
-    startIndex? : number,
-    endIndex? : number
-  }
-) : Array<number> | Array<Array<number>>;
-
-export function cutPolygonByGrid(
-  positions : Array<number>,
-  holeIndices : Array<number> | null,
-  options? : {
-    size? : number,
-    gridResolution? : number,
-    gridOffset? : [number, number],
-    edgeTypes? : boolean
-  }
-) : Array<Polygon>;

package/dist/esm/cut-by-mercator-bounds.d.ts

@@ -1,23 +0,0 @@
-import {Polygon} from "./cut-by-grid";
-
-export function cutPolylineByMercatorBounds(
-  positions : Array<number>,
-  options? : {
-    size? : number,
-    startIndex? : number,
-    endIndex? : number,
-    normalize? : boolean
-  }
-) : Array<number>;
-
-export function cutPolygonByMercatorBounds(
-  positions : Array<number>,
-  holeIndices : Array<number> | null,
-  options? : {
-    size? : number,
-    normalize? : boolean,
-    maxLatitude?: number,
-    edgeTypes? : boolean
-  }
-) : Array<Polygon>;
-

package/dist/esm/lineclip.d.ts

@@ -1,25 +0,0 @@
-type BoundingBox = [number, number, number, number];
-
-export function clipPolyline(
-  positions : Array<number>,
-  bbox : BoundingBox,
-  options? : {
-    size? : number,
-    startIndex? : number,
-    endIndex? : number
-  }
-) : Array<Array<number>>;
-
-export function clipPolygon(
-  positions: Array<number>,
-  bbox: BoundingBox,
-  options? : {
-    size? : number,
-    startIndex? : number,
-    endIndex? : number
-  }
-) : Array<number>;
-
-export function intersect(a : Array<number>, b : Array<number>, edge : number, bbox : BoundingBox, out? : Array<number>);
-
-export function bitCode(p: Array<number>, bbox : BoundingBox) : number;

package/dist/esm/polygon-utils.d.ts

@@ -1,117 +0,0 @@
-import {NumberArray} from '@math.gl/core/';
-
-export const WINDING: {
-  CLOCKWISE: number;
-  COUNTER_CLOCKWISE: number;
-};
-
-// Polygon representation where each point is represented as a separate array of positions.
-type PointsArray = NumberArray[];
-
-// 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: NumberArray, p2: NumberArray, i1: number, i2: number) => void;
-
-// Parameters of a polygon.
-type PolygonParams = {
-  start?: number; // Start index of the polygon in the array of positions. Defaults to 0.
-  end?: number; // End index of the polygon in the array of positions. Defaults to number of positions.
-  size?: number; // Size of a point, 2 (XZ) or 3 (XYZ). Defaults to 2. Affects only polygons stored in flat arrays.
-  isClosed?: boolean; // Indicates that the first point of the polygon is equal to the last point, and additional checks should be ommited.
-};
-
-/**
- * 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. 1 is for clockwise, -1 for counterclockwise winding direction.
- * @param options Parameters of the polygon.
- * @return Returns true if the winding direction was changed.
- */
-export function modifyPolygonWindingDirection(
-  points: NumberArray,
-  direction: number,
-  options?: PolygonParams
-): boolean;
-
-/**
- * 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: NumberArray, options?: PolygonParams): number;
-
-/**
- * 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.
- */
-export function getPolygonSignedArea(points: NumberArray, options?: PolygonParams): number;
-
-/**
- * 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: NumberArray,
-  visitor: SegmentVisitorFlat,
-  options?: PolygonParams
-): void;
-
-/**
- * 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. 1 is for clockwise, -1 for counterclockwise winding direction.
- * @param options Parameters of the polygon.
- * @return Returns true if the winding direction was changed.
- */
-export function modifyPolygonWindingDirectionPoints(
-  points: PointsArray,
-  direction: number,
-  options?: PolygonParams
-): boolean;
-
-/**
- * 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
-): number;
-
-/**
- * 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;
-
-/**
- * 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;