@math.gl/dggs 5.0.0-alpha.6 → 5.0.0-alpha.8

package/src/quadkey-decoder.ts

@@ -3,12 +3,17 @@
 // Copyright (c) vis.gl contributors
 
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 const TILE_SIZE = 512;
 
 /** Decoder for the quadkey DGGS */
-export const QuadkeyDecoder = {
+export const QuadkeyDecoder = withDGGSBoundaryOptions({
   name: 'quadkey',
   hasNumericRepresentation: false,
   cellColumnNames: ['quadkey', 'quadkeyId', 'quadkey_id'],
@@ -19,7 +24,7 @@ export const QuadkeyDecoder = {
   cellToBoundaryFlat: (cell: DGGSCell): number[] =>
     getQuadkeyBoundaryFlat(getDGGSCellToken(cell, 'Quadkey')),
   cellToBounds: (cell: DGGSCell): Bounds2D => getQuadkeyBounds(getDGGSCellToken(cell, 'Quadkey'))
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 function getQuadkeyLngLat(quadkey: string): [number, number] {
   const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);

package/src/s2-decoder.ts

@@ -3,14 +3,14 @@
 // Copyright (c) vis.gl contributors
 
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder} from './dggs-decoder';
+import {withDGGSBoundaryOptions, type DGGSCell, type DGGSDecoder} from './dggs-decoder';
 
 import {getS2IndexFromToken, getS2TokenFromIndex} from './s2-geometry/s2-token';
 import {getS2GeoBounds} from './s2-geometry/s2-to-boundary';
 import {getS2Cell, IJToST, STToUV, FaceUVToXYZ, XYZToLngLat} from './s2-geometry/s2-geometry';
 
 /** Decoder for the S2 DGGS */
-export const S2Decoder = {
+export const S2Decoder = withDGGSBoundaryOptions({
   name: 's2',
   hasNumericRepresentation: true,
   cellColumnNames: ['s2', 's2Token', 's2_token', 's2Cell', 's2_cell', 's2CellId', 's2_cell_id'],
@@ -20,7 +20,7 @@ export const S2Decoder = {
   cellToBoundary: (cell: DGGSCell): [number, number][] => getS2Boundary(cell),
   cellToBoundaryFlat: (cell: DGGSCell): number[] => getS2BoundaryFlat(cell),
   cellToBounds: (cell: DGGSCell): Bounds2D => getS2Bounds(cell)
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 /**
  * Retrieve S2 geometry center

package/src/unwrap-dggs-boundary.ts

@@ -0,0 +1,54 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Copy a cell boundary, unwrapping longitudes across the antimeridian.
+ * @param boundary Open or closed longitude/latitude pairs in degrees.
+ * @param referenceLongitude Optional longitude near which to place the first vertex.
+ * @returns Fresh pairs with each longitude nearest the preceding longitude. Exact
+ * 180-degree ties retain their direction. Latitudes and vertex order are preserved.
+ * @remarks Explicit boundaries spanning at least 360 degrees and closed rings with
+ * net longitude winding are copied unchanged. Polar cells need additional topology
+ * handling. This helper neither splits polygons nor calculates geodesic edges.
+ */
+export function unwrapDGGSBoundary(
+  boundary: ReadonlyArray<readonly [number, number]>,
+  referenceLongitude?: number
+): [number, number][] {
+  const result: [number, number][] = boundary.map(([longitude, latitude]) => [longitude, latitude]);
+  if (result.length === 0) {
+    return result;
+  }
+
+  let west = Infinity;
+  let east = -Infinity;
+  for (const [longitude] of boundary) {
+    west = Math.min(west, longitude);
+    east = Math.max(east, longitude);
+  }
+  if (east - west >= 360) {
+    return result;
+  }
+
+  let previous = referenceLongitude ?? result[0][0];
+  for (const point of result) {
+    const delta = point[0] - previous;
+    if (delta > 180) {
+      point[0] -= 360 * Math.ceil((delta - 180) / 360);
+    } else if (delta < -180) {
+      point[0] += 360 * Math.ceil((-delta - 180) / 360);
+    }
+    previous = point[0];
+  }
+
+  const first = boundary[0];
+  const last = boundary[boundary.length - 1];
+  if (first[0] === last[0] && first[1] === last[1]) {
+    if (Math.abs(result[result.length - 1][0] - result[0][0]) > 180) {
+      return boundary.map(([longitude, latitude]) => [longitude, latitude]);
+    }
+    result[result.length - 1] = [...result[0]];
+  }
+  return result;
+}