@math.gl/geospatial 5.0.0-beta.1 → 5.0.0-beta.2

package/package.json

@@ -6,7 +6,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "keywords": [
     "webgl",
     "javascript",
@@ -1046,9 +1046,9 @@
   ],
   "dependencies": {
     "@mapbox/martini": "0.2.0",
-    "@math.gl/core": "5.0.0-beta.1",
-    "@math.gl/geometry": "5.0.0-beta.1",
-    "@math.gl/web-mercator": "5.0.0-beta.1",
+    "@math.gl/core": "5.0.0-beta.2",
+    "@math.gl/geometry": "5.0.0-beta.2",
+    "@math.gl/web-mercator": "5.0.0-beta.2",
     "polygon-clipping": "0.15.7"
   },
   "devDependencies": {
@@ -1060,5 +1060,5 @@
     "proj4": "2.22.0"
   },
   "sideEffects": false,
-  "gitHead": "13b9fae96e2df2010f5528a199316f47c044200b"
+  "gitHead": "f5c7bfdb4d9232e793237f08a86b513aedccc0a0"
 }

package/src/crs/crs-identifier.ts

@@ -0,0 +1,86 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSIdentifier} from './crs';
+
+/** WMS 1.3 `CRS:` codes and the OGC register entries they abbreviate. */
+const WMS_CRS_CODES = new Map<string, string>([
+  ['84', 'CRS84'],
+  ['83', 'CRS83'],
+  ['27', 'CRS27']
+]);
+/** Explicit input conveniences, not a case-insensitivity rule for all registry names. */
+const KNOWN_AUTHORITIES = new Set(['EPSG', 'OGC', 'ESRI', 'IAU']);
+const OGC_CRS_CODES = new Map<string, string>([
+  ['CRS84', 'CRS84'],
+  ['CRS83', 'CRS83'],
+  ['CRS27', 'CRS27'],
+  ['CRS84H', 'CRS84h']
+]);
+
+const AUTHORITY_CODE = /^([A-Z][A-Z0-9_-]*):([A-Z0-9_.-]+)$/i;
+const OGC_URN = /^urn:ogc:def:crs:([A-Z][A-Z0-9_-]*):([^:]*):([A-Z0-9_.-]+)$/i;
+const OGC_URI =
+  /^https?:\/\/www\.opengis\.net\/def\/crs\/([A-Z][A-Z0-9_-]*)\/([^/]+)\/([A-Z0-9_.-]+)\/?$/i;
+
+/**
+ * Normalizes recognized spellings of an authority CRS identifier to `AUTHORITY:CODE`.
+ *
+ * Recognized forms are `AUTHORITY:CODE`, the WMS 1.3 codes `CRS:84`, `CRS:83` and `CRS:27`,
+ * OGC URNs (`urn:ogc:def:crs:EPSG::32619`) and OGC URIs
+ * (`http://www.opengis.net/def/crs/EPSG/0/32619`). Known authority prefixes (EPSG, OGC, ESRI and IAU) and explicitly known OGC CRS codes
+ * accept case-insensitive input aliases. Other authority and code spellings are preserved.
+ *
+ * A version is removed only when it is empty or `0`, or when it is `1.3` on an OGC `CRS84`,
+ * `CRS83` or `CRS27` code, which the OGC register publishes only at that version. Any other
+ * versioned identifier is returned unchanged, so it does not compare equal to an unversioned one.
+ * Unrecognized strings are also returned unchanged.
+ *
+ * The result identifies a registry entry only. Different codes are never equated: `EPSG:4326` and
+ * `OGC:CRS84` stay distinct, as do Web Mercator aliases. No datum equivalence, axis-order
+ * convention or registry lookup is applied.
+ *
+ * @param identifier - CRS identifier as written by a source or service.
+ * @returns The canonical `AUTHORITY:CODE` identifier, or `identifier` unchanged.
+ */
+export function normalizeCRSIdentifier(identifier: CRSIdentifier): CRSIdentifier {
+  const text = identifier.trim();
+
+  const authorityCode = AUTHORITY_CODE.exec(text);
+  if (authorityCode) {
+    const [, authority, code] = authorityCode;
+    if (authority.toUpperCase() === 'CRS') {
+      const ogcCode = WMS_CRS_CODES.get(code);
+      return ogcCode ? `OGC:${ogcCode}` : identifier;
+    }
+    return formatIdentifier(authority, code);
+  }
+
+  const versioned = OGC_URN.exec(text) || OGC_URI.exec(text);
+  if (versioned) {
+    const [, authority, version, code] = versioned;
+    return isUnversioned(authority, version, code) ? formatIdentifier(authority, code) : identifier;
+  }
+
+  return identifier;
+}
+
+/** Whether a URN or URI version names no particular revision of the registry entry. */
+function isUnversioned(authority: string, version: string, code: string): boolean {
+  if (version === '' || version === '0') return true;
+  const ogcCode = code.toUpperCase();
+  return (
+    authority.toUpperCase() === 'OGC' &&
+    version === '1.3' &&
+    Array.from(WMS_CRS_CODES.values()).includes(ogcCode)
+  );
+}
+
+function formatIdentifier(authority: string, code: string): CRSIdentifier {
+  const upperAuthority = authority.toUpperCase();
+  const canonicalAuthority = KNOWN_AUTHORITIES.has(upperAuthority) ? upperAuthority : authority;
+  const canonicalCode =
+    canonicalAuthority === 'OGC' ? OGC_CRS_CODES.get(code.toUpperCase()) || code : code;
+  return `${canonicalAuthority}:${canonicalCode}`;
+}

package/src/crs/index.ts

@@ -32,6 +32,7 @@ export type {
   UnresolvedCRSReference
 } from './spatial-reference';
 export {createSpatialReference, inferCRSRepresentation} from './spatial-reference';
+export {normalizeCRSIdentifier} from './crs-identifier';
 export type {
   EncodeWKTCRSOptions,
   ParseWKTCRSOptions,

package/src/discontinuous/cap-map.ts

@@ -3,6 +3,8 @@
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import clipCircle from './spherical-clip/clip-circle.js';
+import {tracePolygonConstraints, composePolygonEdge} from './polygon-constraints';
+import {sourceArc} from './source-arc';
 import {circleStream} from './spherical-clip/circle.js';
 import {
   DiscontinuousMap,
@@ -91,11 +93,15 @@ export class CapMap extends DiscontinuousMap {
     rings: readonly (readonly GeographicPosition[])[],
     polygon: boolean,
     options?: MapSamplingOptions,
-    regionId?: string
+    regionId?: string,
+    segmentIndices?: number[][]
   ): Position[][] {
     const output: Position[][] = [];
     const originals = new Map<string, Position>();
-    let ring: Position[] = [];
+    let ring: Position[] = [],
+      indices: number[] = [],
+      activeSegment = 0;
+    let previousInput: GeographicPosition | undefined, currentInput: GeographicPosition | undefined;
     const precision =
       Math.min(
         options?.maxAngularStep ?? 2,
@@ -184,13 +190,60 @@ export class CapMap extends DiscontinuousMap {
       point: (x: number, y: number) => {
         if (++emitted > 1_000_000)
           throw new Error('Projection sampling limit exceeded; relax tolerance');
-        ring.push(originals.get(`${x},${y}`) ?? this.source([x / RAD, y / RAD]));
+        let source = originals.get(`${x},${y}`);
+        if (!source && !polygon && this.nonlinear && previousInput && currentInput) {
+          // The local nonlinear transform bends source arcs. A circle/chord
+          // intersection must be refined on its owning original source arc.
+          const a = geographic(previousInput),
+            b = geographic(currentInput),
+            length = angle(a, b);
+          const at = (t: number): Position =>
+            length < 1e-14
+              ? ([...currentInput!] as Position)
+              : coordinates(
+                  unit(
+                    a.map(
+                      (v, k) =>
+                        (Math.sin((1 - t) * length) * v + Math.sin(t * length) * b[k]) /
+                        Math.sin(length)
+                    ) as Vector
+                  )
+                );
+          const value = (t: number) => geographic(local(at(t)))[0] - Math.cos(this.cap);
+          const approximate = this.source([x / RAD, y / RAD]);
+          const reference = length ? Math.min(1, angle(a, geographic(approximate)) / length) : 0;
+          const roots: number[] = [];
+          for (let j = 0; j < 32; j++) {
+            let lo = j / 32,
+              hi = (j + 1) / 32,
+              f = value(lo),
+              g = value(hi);
+            if (Math.abs(f) < 1e-14) roots.push(lo);
+            if (f * g >= 0) continue;
+            for (let k = 0; k < 52; k++) {
+              const mid = (lo + hi) / 2;
+              if (value(mid) >= 0 === f >= 0) lo = mid;
+              else hi = mid;
+            }
+            roots.push((lo + hi) / 2);
+          }
+          if (Math.abs(value(1)) < 1e-14) roots.push(1);
+          if (!roots.length) throw new Error('Unresolved nonlinear cap source intersection');
+          roots.sort((a, b) => Math.abs(a - reference) - Math.abs(b - reference));
+          source = at(roots[0]);
+        }
+        ring.push(source ?? this.source([x / RAD, y / RAD]));
+        if (segmentIndices) indices.push(activeSegment);
       },
       lineStart: () => {
         ring = [];
+        indices = [];
       },
       lineEnd: () => {
-        if (ring.length > 1) output.push(ring);
+        if (ring.length > 1) {
+          output.push(ring);
+          segmentIndices?.push(indices);
+        }
       },
       polygonStart: () => {},
       polygonEnd: () => {}
@@ -207,7 +260,9 @@ export class CapMap extends DiscontinuousMap {
       const x = q[0] * RAD,
         y = q[1] * RAD;
       originals.set(`${x},${y}`, [...p]);
+      currentInput = p;
       stream.point(x, y);
+      previousInput = p;
     };
     const subdivide = (a: GeographicPosition, b: GeographicPosition, depth = 0) => {
       if (this.nonlinear && depth < 20) {
@@ -232,9 +287,13 @@ export class CapMap extends DiscontinuousMap {
       emit(b);
     };
     for (const points of rings) {
+      previousInput = undefined;
       stream.lineStart();
       if (points.length) emit(points[0]);
-      for (let i = 1; i < points.length; i++) subdivide(points[i - 1], points[i]);
+      for (let i = 1; i < points.length; i++) {
+        activeSegment = i - 1;
+        subdivide(points[i - 1], points[i]);
+      }
       if (polygon && points.length) subdivide(points[points.length - 1], points[0]);
       stream.lineEnd();
     }
@@ -246,15 +305,70 @@ export class CapMap extends DiscontinuousMap {
     options?: MapSamplingOptions
   ): MapLine[] {
     if (this.cap === Math.PI / 2 && !this.nonlinear) return super.projectLine(line, options);
-    // Super validates antipodal edges and sampling options even for invisible input.
-    return super
-      .projectLine(line, options)
-      .flatMap(part =>
-        this.clip([part.sourceCoordinates], false, options, part.regionId).flatMap(line =>
-          super.projectLine(line, options).filter(q => q.regionId === part.regionId)
-        )
+    // Attribute streaming intersections while the owning sampled edge is active.
+    // Rigid spherical rotations preserve the original great-circle semantics.
+    return super.projectLine(line, options).flatMap(part => {
+      const indices: number[][] | undefined = part.provenance ? [] : undefined;
+      const clipped = this.clip([part.sourceCoordinates], false, options, part.regionId, indices);
+      return clipped.flatMap((points, piece) =>
+        super
+          .projectLine(points, options)
+          .filter(q => q.regionId === part.regionId)
+          .map(q => {
+            const parent = part.provenance,
+              child = q.provenance;
+            if (!parent || !child) return q;
+            const provenance: NonNullable<MapLine['provenance']> = {
+              segments: [],
+              parameters: [],
+              vertices: [],
+              angularDistances: []
+            };
+            for (let j = 0; j < q.sourceCoordinates.length; j++) {
+              const k = child.segments[j];
+              // The incoming endpoint owns the clipped edge, including a newly
+              // generated entry point followed by its original end vertex.
+              const edge = indices![piece][k + 1];
+              const a = geographic(part.sourceCoordinates[edge]),
+                b = geographic(part.sourceCoordinates[edge + 1]),
+                p = geographic(q.sourceCoordinates[j]);
+              const length = angle(a, b),
+                t = length ? Math.min(1, angle(a, p) / length) : 0;
+              const endpoint = t < 1e-12 ? edge : t > 1 - 1e-12 ? edge + 1 : -1;
+              const segment = parent.segments[edge + 1];
+              const from = parent.segments[edge] === segment ? parent.parameters[edge] : 0;
+              provenance.segments.push(endpoint >= 0 ? parent.segments[endpoint] : segment);
+              provenance.parameters.push(
+                endpoint >= 0
+                  ? parent.parameters[endpoint]
+                  : from + t * (parent.parameters[edge + 1] - from)
+              );
+              provenance.vertices.push(endpoint >= 0 ? parent.vertices[endpoint] : 0xffffffff);
+              if (options?.pathDistances)
+                provenance.angularDistances.push(
+                  parent.angularDistances[edge] +
+                    t * (parent.angularDistances[edge + 1] - parent.angularDistances[edge])
+                );
+            }
+            if (options?.pathBoundaries) {
+              const same = (a: GeographicPosition, b: GeographicPosition) =>
+                angle(geographic(a), geographic(b)) < 1e-12;
+              provenance.startReason = same(q.sourceCoordinates[0], part.sourceCoordinates[0])
+                ? parent.startReason
+                : 'coverage-boundary';
+              provenance.endReason = same(
+                q.sourceCoordinates[q.sourceCoordinates.length - 1],
+                part.sourceCoordinates[part.sourceCoordinates.length - 1]
+              )
+                ? parent.endReason
+                : 'coverage-boundary';
+            }
+            return {...q, provenance};
+          })
       );
+    });
   }
+
   override projectPolygon(
     rings: readonly (readonly GeographicPosition[])[],
     options?: MapSamplingOptions
@@ -356,19 +470,134 @@ export class CapMap extends DiscontinuousMap {
       for (const ring of outer) {
         const plane = ring.map(planar),
           sources = [ring, ...holes.filter(h => contains(plane, planar(h[0])))];
+        const parentPlane = part.sourceCoordinates.map(r => r.map(planar));
+        const fromPlane = (p: Position): Position =>
+          coordinates(unit(center.map((v, k) => v + x[k] * p[0] + y[k] * p[1]) as Vector));
+        const traced = tracePolygonConstraints(
+          parentPlane,
+          sources.map(r => r.map(planar)),
+          this.nonlinear ? 2e-6 : 1e-10,
+          part.edgeProvenance,
+          p => this.visible(fromPlane(p))
+        );
+        const resolved = traced.rings.map(r => r.map(fromPlane));
+        traced.owners.forEach((owners, r) =>
+          owners.forEach((owner, i) => {
+            if (!owner) return;
+            const [pr, pe] = owner,
+              a = part.sourceCoordinates[pr][pe],
+              b = part.sourceCoordinates[pr][pe + 1],
+              at = sourceArc(a, b);
+            for (const j of [i, i + 1]) {
+              const point = resolved[r][j],
+                distance = angle(geographic(a), geographic(b)),
+                fraction = distance ? angle(geographic(a), geographic(point)) / distance : 0;
+              if (fraction < 1e-10) resolved[r][j] = [...a];
+              else if (fraction > 1 - 1e-10) resolved[r][j] = [...b];
+              else if (
+                Math.hypot(...cross(geographic(a), geographic(b))) > 1e-14 &&
+                Math.abs(dot(unit(cross(geographic(a), geographic(b))), geographic(point))) < 1e-12
+              ) {
+                resolved[r][j] = at(Math.min(1, Math.max(0, fraction)));
+              } else {
+                const value = (t: number) => geographic(this.local(at(t)))[0] - Math.cos(this.cap),
+                  roots: number[] = [];
+                for (let k = 0; k < 32; k++) {
+                  let lo = k / 32,
+                    hi = (k + 1) / 32,
+                    f = value(lo),
+                    g = value(hi);
+                  if (Math.abs(f) < 1e-13) roots.push(lo);
+                  if (f * g >= 0) continue;
+                  for (let n = 0; n < 52; n++) {
+                    const mid = (lo + hi) / 2;
+                    if (value(mid) >= 0 === f >= 0) lo = mid;
+                    else hi = mid;
+                  }
+                  roots.push((lo + hi) / 2);
+                }
+                if (Math.abs(value(1)) < 1e-13) roots.push(1);
+                if (!roots.length) throw new Error('Unresolved cap polygon source intersection');
+                roots.sort((a, b) => Math.abs(a - fraction) - Math.abs(b - fraction));
+                resolved[r][j] = at(roots[0]);
+              }
+            }
+          })
+        );
+        for (const ring of resolved) ring[ring.length - 1] = [...ring[0]];
         result.push({
           regionId: part.regionId,
-          sourceCoordinates: sources,
-          coordinates: sources.map(r =>
+          sourceCoordinates: resolved,
+          coordinates: resolved.map(r =>
             r.map(p => {
               const q = super.projectPoint(p, part.regionId);
-              if (!q)
-                throw new Error(
-                  `Cap point outside chart ${part.regionId}: ${p}, owner ${super.findRegions(p)}`
-                );
+              if (!q) throw new Error('Cap polygon source constraint left its owning chart');
               return q.position;
             })
-          )
+          ),
+          ...(options?.polygonEdgeProvenance
+            ? {
+                edgeProvenance: traced.owners.map((owners, r) =>
+                  owners.map((owner, i) => {
+                    const a = resolved[r][i],
+                      b = resolved[r][i + 1];
+                    if (owner) {
+                      const [pr, pe] = owner;
+                      return composePolygonEdge(
+                        part.edgeProvenance![pr][pe],
+                        part.sourceCoordinates[pr][pe],
+                        part.sourceCoordinates[pr][pe + 1],
+                        a,
+                        b
+                      );
+                    }
+                    if (angle(geographic(a), geographic(b)) < 64 * Number.EPSILON)
+                      return {
+                        kind: 'continuous-chart-join' as const,
+                        ring: 0xffffffff,
+                        segment: 0xffffffff,
+                        t0: 0,
+                        t1: 0
+                      };
+                    const kinds: string[] = [];
+                    region.boundary.forEach((p, j) => {
+                      const n = cross(
+                          geographic(p),
+                          geographic(region.boundary[(j + 1) % region.boundary.length])
+                        ),
+                        length = Math.hypot(...n);
+                      if (
+                        length &&
+                        [a, b].every(p => Math.abs(dot(n, geographic(p))) / length < 1e-9)
+                      ) {
+                        const seam = this.seams.find(s =>
+                          s.regions.some((id, k) => id === region.id && s.edges[k] === j)
+                        );
+                        if (seam) kinds.push(seam.kind);
+                      }
+                    });
+                    const horizon = [a, b].every(
+                      p => Math.abs(geographic(this.local(p))[0] - Math.cos(this.cap)) < 1e-7
+                    );
+                    if (!horizon && !kinds.length)
+                      throw new Error('Unknown cap polygon clipping constraint');
+                    return {
+                      kind: horizon
+                        ? ('coverage-boundary' as const)
+                        : kinds.includes('boundary')
+                          ? ('coverage-boundary' as const)
+                          : kinds.includes('cut')
+                            ? ('chart-cut' as const)
+                            : ('continuous-chart-join' as const),
+                      ring: 0xffffffff,
+                      segment: 0xffffffff,
+                      t0: 0,
+                      t1: 0
+                    };
+                  })
+                )
+              }
+            : {})
         });
       }
     }

package/src/discontinuous/elastic/geometry.ts

@@ -89,7 +89,8 @@ export function sample(
   line: Position[],
   project: (p: Position) => Position | null,
   options: MapSamplingOptions,
-  cellStep: number
+  cellStep: number,
+  interpolate?: (segment: number, t: number) => Position
 ) {
   const {step, tolerance} = sampling(options),
     source: Position[] = [],
@@ -101,11 +102,21 @@ export function sample(
   };
   const at = (p: Position) => {
     const q = project(p);
-    if (!q) throw new Error('Elastic grid is undefined inside its coverage');
+    if (!q) throw new Error(`Elastic grid is undefined inside its coverage at ${p}`);
     return q;
   };
-  const visit = (a: Position, b: Position, qa: Position, qb: Position, depth: number) => {
-    const mid = lerp(a, b, 0.5),
+  const visit = (
+    a: Position,
+    b: Position,
+    qa: Position,
+    qb: Position,
+    depth: number,
+    segment: number,
+    t0: number,
+    t1: number
+  ) => {
+    const tm = (t0 + t1) / 2,
+      mid = interpolate ? interpolate(segment, tm) : lerp(a, b, 0.5),
       qm = at(mid),
       chord = lerp(qa, qb, 0.5);
     if (
@@ -113,14 +124,14 @@ export function sample(
       Math.hypot(qm[0] - chord[0], qm[1] - chord[1]) > tolerance
     ) {
       if (depth >= 24) throw new Error('Elastic sampling limit exceeded');
-      visit(a, mid, qa, qm, depth + 1);
-      visit(mid, b, qm, qb, depth + 1);
+      visit(a, mid, qa, qm, depth + 1, segment, t0, tm);
+      visit(mid, b, qm, qb, depth + 1, segment, tm, t1);
     } else emit(b, qb);
   };
   if (line.length) {
     emit(line[0], at(line[0]));
     for (let i = 1; i < line.length; i++)
-      visit(line[i - 1], line[i], at(line[i - 1]), at(line[i]), 0);
+      visit(line[i - 1], line[i], at(line[i - 1]), at(line[i]), 0, i - 1, 0, 1);
   }
   return {source, xy};
 }