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

package/src/projection/experimental/rendering-profile/geographic-bounds.ts

@@ -0,0 +1,190 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {GeographicBounds, ProjectionRenderingProfile} from '../types';
+
+const RADIANS = Math.PI / 180;
+
+/** Kernel parameter ranges, in radians. These are not geographic coverage bounds. */
+export type AngularRanges = readonly [
+  min: readonly [lon: number, lat: number],
+  max: readonly [lon: number, lat: number]
+];
+
+/** Construct explicitly typed numerical parameter ranges, in radians. */
+export function createAngularRanges(
+  west: number,
+  south: number,
+  east: number,
+  north: number
+): AngularRanges {
+  return [
+    [west, south],
+    [east, north]
+  ];
+}
+
+/** Normalize a longitude in degrees; the dateline's canonical point is -180. */
+export function normalizeLongitude(longitude: number): number {
+  return longitude >= -180 && longitude < 180
+    ? longitude
+    : ((((longitude + 180) % 360) + 360) % 360) - 180;
+}
+
+/** Construct geographic coverage from an eastward degree interval, preserving a full world. */
+export function createGeographicBounds(
+  west: number,
+  south: number,
+  east: number,
+  north: number
+): GeographicBounds {
+  if (
+    ![west, south, east, north].every(Number.isFinite) ||
+    south < -90 ||
+    north > 90 ||
+    south > north ||
+    east - west < -360 ||
+    east - west > 360 + 1e-10
+  )
+    throw new Error('Invalid geographic coverage');
+  if (east - west >= 360 - 1e-10) return [-180, south, 180, north];
+  const wrappedEast = normalizeLongitude(east);
+  return [
+    normalizeLongitude(west),
+    south,
+    wrappedEast === -180 && east > west ? 180 : wrappedEast,
+    north
+  ];
+}
+
+/** Eastward longitude span in degrees, preserving full-world and single-meridian coverage. */
+export function getLongitudeSpan(bounds: GeographicBounds): number {
+  const span = bounds[2] - bounds[0];
+  // Modulo would collapse the explicitly represented full world to a meridian.
+  return span < 0 ? span + 360 : span;
+}
+
+/** Split periodic coverage into rectangles whose longitude endpoints are ordered. */
+export function splitGeographicBounds(bounds: GeographicBounds): GeographicBounds[] {
+  const [west, south, east, north] = bounds;
+  return west <= east
+    ? [bounds]
+    : [
+        [west, south, 180, north],
+        [-180, south, east, north]
+      ];
+}
+
+/** Inclusive coverage membership; +180 and -180 refer to the same meridian. */
+export function containsGeographicPoint(
+  bounds: GeographicBounds,
+  point: readonly [number, number]
+): boolean {
+  const [west, south, east, north] = bounds;
+  const longitude = normalizeLongitude(point[0]);
+  return (
+    point[1] >= south &&
+    point[1] <= north &&
+    (west <= east
+      ? (longitude >= west && longitude <= east) || (longitude === -180 && east === 180)
+      : longitude >= west || longitude <= east)
+  );
+}
+
+/** Intersect periodic coverage without replacing disconnected regions with an envelope. */
+export function intersectGeographicBounds(
+  a: GeographicBounds,
+  b: GeographicBounds
+): GeographicBounds[] {
+  const south = Math.max(a[1], b[1]),
+    north = Math.min(a[3], b[3]);
+  if (south > north) return [];
+  const intervals: [number, number][] = [];
+  for (const left of splitGeographicBounds(a))
+    for (const right of splitGeographicBounds(b)) {
+      const west = Math.max(left[0], right[0]),
+        east = Math.min(left[2], right[2]);
+      if (west <= east) intervals.push([west, east]);
+      else if ((left[2] === 180 && right[0] === -180) || (right[2] === 180 && left[0] === -180))
+        intervals.push([-180, -180]);
+    }
+  intervals.sort((left, right) => left[0] - right[0]);
+  const merged: [number, number][] = [];
+  for (const interval of intervals) {
+    const last = merged[merged.length - 1];
+    if (last && interval[0] <= last[1]) last[1] = Math.max(last[1], interval[1]);
+    else merged.push([...interval]);
+  }
+  if (merged.length > 1 && merged[0][0] === -180 && merged[merged.length - 1][1] === 180) {
+    const first = merged.shift()!,
+      last = merged.pop()!;
+    return [
+      [last[0], south, first[1], north],
+      ...merged.map(([west, east]) => [west, south, east, north] as GeographicBounds)
+    ];
+  }
+  return merged.map(([west, east]) => [west, south, east, north]);
+}
+
+/** Clamp a degree point to coverage using circular longitude distance. */
+export function clampGeographicPoint(
+  bounds: GeographicBounds,
+  point: readonly [number, number]
+): [number, number] {
+  let longitude = normalizeLongitude(point[0]);
+  const latitude = Math.max(bounds[1], Math.min(bounds[3], point[1]));
+  if (!containsGeographicPoint(bounds, [longitude, latitude])) {
+    const westDistance = Math.abs(normalizeLongitude(longitude - bounds[0]));
+    const eastDistance = Math.abs(normalizeLongitude(longitude - bounds[2]));
+    longitude = westDistance <= eastDistance ? bounds[0] : bounds[2];
+  }
+  return [longitude, latitude];
+}
+
+/** Express coverage in the kernel's angular parameters, choosing a continuous periodic interval. */
+export function getAngularRanges(
+  bounds: GeographicBounds,
+  primeMeridian = 0,
+  origin = 0
+): AngularRanges {
+  const width = getLongitudeSpan(bounds);
+  const west = bounds[0] * RADIANS - primeMeridian;
+  const middle = west + (width * RADIANS) / 2;
+  const shift = Math.round((origin - middle) / (2 * Math.PI)) * 2 * Math.PI;
+  return createAngularRanges(
+    width === 360 ? origin - Math.PI : west + shift,
+    bounds[1] * RADIANS,
+    width === 360 ? origin + Math.PI : west + shift + width * RADIANS,
+    bounds[3] * RADIANS
+  );
+}
+
+/** Convert numerical kernel ranges into Greenwich degree coverage at an explicit boundary. */
+export function getGeographicBounds(ranges: AngularRanges, primeMeridian = 0): GeographicBounds {
+  return createGeographicBounds(
+    (ranges[0][0] + primeMeridian) / RADIANS,
+    ranges[0][1] / RADIANS,
+    (ranges[1][0] + primeMeridian) / RADIANS,
+    ranges[1][1] / RADIANS
+  );
+}
+
+/** Combine projected envelopes for disconnected coverage regions. */
+export function unionRenderingBounds(
+  bounds: readonly ProjectionRenderingProfile['bounds'][]
+): ProjectionRenderingProfile['bounds'] {
+  if (!bounds.length) throw new Error('CRS coverage does not intersect the rendering target');
+  return [
+    [0, 1, 2].map(axis => Math.min(...bounds.map(pair => pair[0][axis]))) as [
+      number,
+      number,
+      number
+    ],
+    [0, 1, 2].map(axis => Math.max(...bounds.map(pair => pair[1][axis]))) as [
+      number,
+      number,
+      number
+    ]
+  ];
+}

package/src/projection/experimental/rendering-profile/geographic-rendering-profile.ts

@@ -0,0 +1,29 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ProjectionParameters, ProjectionImplementation} from '../types';
+import {DEGREES_TO_RADIANS, numberParameter} from '../parameters';
+import {createRectangleRenderingProfile} from './rectangular-rendering-profile';
+import {longitudeRange} from './rendering-bounds';
+
+/** Geographic rendering follows the same longitude branch as its output convention. */
+export function createGeographicProfile(
+  parameters: ProjectionParameters,
+  primeMeridian = 0
+): NonNullable<ProjectionImplementation['getRenderingProfile']> {
+  const center = numberParameter(parameters, 'lon_wrap', 0) * DEGREES_TO_RADIANS;
+  return coverage =>
+    createRectangleRenderingProfile(
+      ranges => {
+        const longitude = longitudeRange(ranges, center);
+        return [
+          [center + longitude[0], ranges[0][1], 0],
+          [center + longitude[1], ranges[1][1], 0]
+        ];
+      },
+      coverage ?? [-180, -90, 180, 90],
+      center,
+      primeMeridian
+    );
+}

package/src/projection/experimental/rendering-profile/geostationary-rendering-profile.ts

@@ -0,0 +1,128 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {KernelParameters} from '../kernel';
+import {
+  createAngularRanges,
+  getAngularRanges,
+  getGeographicBounds,
+  intersectGeographicBounds
+} from './geographic-bounds';
+import type {AngularRanges} from './geographic-bounds';
+import {combineRenderingProfiles, createAngularNormalization} from './rendering-profile';
+import {normalizeCoverage} from './rectangular-rendering-profile';
+import type {ProjectionImplementation, ProjectionRenderingProfile} from '../types';
+import {wrapLongitude} from '../parameters';
+import {sphericalRange} from './spherical-rendering-domain';
+import {multiply, envelope, add} from './rendering-bounds';
+
+/** The satellite limb is the ellipsoid/satellite tangency, Rg*X=1.
+ * Solve the limb's latitude and longitude intersections directly in geodetic coordinates.
+ */
+export function createGeostationaryProfile(
+  base: KernelParameters,
+  height: number,
+  sweepX = false
+): NonNullable<ProjectionImplementation['getRenderingProfile']> {
+  const radius = 1 + height / base.a;
+  const visibleRadius = radius / (1 + 1e-10);
+  const longitudeLimit = (latitude: number) =>
+    Math.acos(
+      Math.min(
+        1,
+        Math.sqrt(1 - base.es * Math.sin(latitude) ** 2) / (visibleRadius * Math.cos(latitude))
+      )
+    );
+  const latitudeLimit = (longitude: number) => {
+    const squared = (visibleRadius * Math.cos(longitude)) ** 2;
+    return Math.asin(Math.sqrt(Math.max(0, (squared - 1) / (squared - base.es))));
+  };
+  const fullX = height * Math.asin(1 / radius);
+  const fullY = height * Math.atan(Math.sqrt((1 - base.es) / (radius * radius - 1)));
+  const create = (
+    coverage: AngularRanges,
+    declared: boolean
+  ): ProjectionRenderingProfile | null => {
+    const closestLatitude = Math.max(coverage[0][1], Math.min(coverage[1][1], 0));
+    const maximumLongitude = longitudeLimit(closestLatitude);
+    const west = Math.max(coverage[0][0] - base.long0, -maximumLongitude);
+    const east = Math.min(coverage[1][0] - base.long0, maximumLongitude);
+    const maxLatitude = latitudeLimit(Math.max(west, Math.min(east, 0)));
+    const south = Math.max(coverage[0][1], -maxLatitude),
+      north = Math.min(coverage[1][1], maxLatitude);
+    if (east < west || north < south) return null;
+    const region = createAngularRanges(west, south, east, north);
+    const geographicCoverage = getGeographicBounds(
+      createAngularRanges(west + base.long0, south, east + base.long0, north),
+      base.primeMeridian
+    );
+    const center = ((base.long0 + base.primeMeridian) * 180) / Math.PI;
+    const normalizeLimb = createAngularNormalization(point => {
+      const longitude = Math.max(west, Math.min(east, wrapLongitude(point.x - base.long0)));
+      const limit = latitudeLimit(longitude);
+      const latitude = Math.max(Math.max(south, -limit), Math.min(Math.min(north, limit), point.y));
+      // Avoid reconstructing a native longitude when it is already within the limb.
+      if (longitude !== point.x - base.long0) point.x = longitude + base.long0;
+      point.y = latitude;
+    }, base.primeMeridian);
+    return {
+      get bounds() {
+        if (!declared)
+          return envelope([base.x0 - fullX, base.x0 + fullX], [base.y0 - fullY, base.y0 + fullY]);
+        // Geodetic surface coordinates: N*cos(phi)*sin(lambda), N*(1-e²)*sin(phi).
+        const sin = sphericalRange([0, 0, 1], region);
+        const n = [1, 1 / Math.sqrt(1 - base.es * Math.max(sin[0] ** 2, sin[1] ** 2))] as const;
+        const x = multiply(sphericalRange([1, 0, 0], region), n);
+        const y = multiply(sphericalRange([0, 1, 0], region), n);
+        const z = multiply(sin, [1 - base.es, (1 - base.es) * n[1]]);
+        const denominators = [radius - Math.min(1, x[1]), radius - Math.max(1 / radius, x[0])];
+        const angleRange = (
+          range: readonly [number, number],
+          other: readonly [number, number],
+          maximum: number,
+          orthogonal: boolean
+        ) => {
+          const minimumOther =
+            other[0] <= 0 && other[1] >= 0 ? 0 : Math.min(Math.abs(other[0]), Math.abs(other[1]));
+          const ds = orthogonal
+            ? [
+                Math.hypot(denominators[0], minimumOther),
+                Math.hypot(denominators[1], Math.max(Math.abs(other[0]), Math.abs(other[1])))
+              ]
+            : denominators;
+          const values = range.flatMap(value => ds.map(d => height * Math.atan(value / d)));
+          return [
+            Math.max(-maximum, Math.min(...values)),
+            Math.min(maximum, Math.max(...values))
+          ] as const;
+        };
+        return envelope(
+          add([base.x0, base.x0], angleRange(y, z, fullX, sweepX)),
+          add([base.y0, base.y0], angleRange(z, y, fullY, !sweepX))
+        );
+      },
+      normalize(point) {
+        normalizeCoverage(point, geographicCoverage, center);
+        normalizeLimb(point);
+      }
+    };
+  };
+  const extent = getGeographicBounds(
+    createAngularRanges(
+      base.long0 - longitudeLimit(0),
+      -latitudeLimit(0),
+      base.long0 + longitudeLimit(0),
+      latitudeLimit(0)
+    ),
+    base.primeMeridian
+  );
+  return coverage => {
+    const regions = coverage ? intersectGeographicBounds(coverage, extent) : [extent];
+    const profile = combineRenderingProfiles(regions, region =>
+      create(getAngularRanges(region, base.primeMeridian, base.long0), Boolean(coverage))
+    );
+    if (!profile) throw new Error('CRS coverage does not intersect the satellite limb');
+    return profile;
+  };
+}

package/src/projection/experimental/rendering-profile/identity-rendering-profile.ts

@@ -0,0 +1,15 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ProjectionRenderingProfile} from '../types';
+
+/** Identity coordinates use a unit square as their default rendering target. */
+export function getIdentityRenderingProfile(): ProjectionRenderingProfile {
+  return {
+    bounds: [
+      [-1, -1, 0],
+      [1, 1, 0]
+    ]
+  };
+}

package/src/projection/experimental/rendering-profile/rectangular-rendering-profile.ts

@@ -0,0 +1,133 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {
+  GeographicBounds,
+  ProjectionImplementation,
+  ProjectionRenderingProfile
+} from '../types';
+import type {AngularRanges} from './geographic-bounds';
+import {
+  clampGeographicPoint,
+  getAngularRanges,
+  getLongitudeSpan,
+  getGeographicBounds,
+  intersectGeographicBounds,
+  normalizeLongitude
+} from './geographic-bounds';
+import {combineRenderingProfiles} from './rendering-profile';
+
+export type ResolveRenderingBounds = (
+  parameters: AngularRanges
+) => ProjectionRenderingProfile['bounds'];
+
+/** Clamp Greenwich longitude/latitude in degrees to one rendering rectangle. */
+export function normalizeCoverage(
+  point: {x: number; y: number},
+  coverage: GeographicBounds,
+  center = 0,
+  over = false
+): void {
+  const span = getLongitudeSpan(coverage);
+  const west =
+    span === 360
+      ? center - 180
+      : coverage[0] + Math.round((center - coverage[0] - span / 2) / 360) * 360;
+  const east = west + span;
+  // Keep geographic values in degrees: a covered seam endpoint must not be
+  // perturbed by a radians round trip onto the opposite projection branch.
+  if (over) {
+    point.x = Math.max(west, Math.min(east, point.x));
+    point.y = Math.max(coverage[1], Math.min(coverage[3], point.y));
+    return;
+  }
+  const best = clampGeographicPoint(coverage, [point.x, point.y]);
+  let longitude = best[0];
+  if (best[0] === normalizeLongitude(point.x) && point.x >= west && point.x <= east)
+    longitude = point.x;
+  else if (longitude < west || longitude > east)
+    longitude += Math.round(((west + east) / 2 - longitude) / 360) * 360;
+  const offset = longitude - center;
+  point.x = Math.abs(offset) <= 180 ? longitude : center + normalizeLongitude(offset);
+  point.y = best[1];
+}
+
+/** Geographic coverage with a projection-owned analytical envelope. */
+export function createRectangleRenderingProfile(
+  resolveBounds: ResolveRenderingBounds,
+  coverage: GeographicBounds,
+  origin = 0,
+  primeMeridian = 0,
+  over = false
+): ProjectionRenderingProfile {
+  const center = ((origin + primeMeridian) * 180) / Math.PI;
+  return {
+    get bounds() {
+      return resolveBounds(getAngularRanges(coverage, primeMeridian, origin));
+    },
+    normalize(point) {
+      normalizeCoverage(point, coverage, center, over);
+    }
+  };
+}
+
+function createRegionsRenderingProfile(
+  resolveBounds: ResolveRenderingBounds,
+  regions: readonly GeographicBounds[],
+  origin: number,
+  primeMeridian: number,
+  over: boolean
+): ProjectionRenderingProfile {
+  const profile = combineRenderingProfiles(regions, region =>
+    createRectangleRenderingProfile(resolveBounds, region, origin, primeMeridian, over)
+  );
+  if (!profile) throw new Error('CRS coverage does not intersect the rendering target');
+  return profile;
+}
+
+/** Algorithms opt into rectangular coverage and clipping to their own default target. */
+export function withRectangleRenderingProfile(
+  implementation: ProjectionImplementation,
+  parameters: AngularRanges,
+  resolveBounds: ResolveRenderingBounds,
+  primeMeridian = 0,
+  over = false
+): ProjectionImplementation {
+  const origin = (parameters[0][0] + parameters[1][0]) / 2;
+  const defaults = getGeographicBounds(parameters, primeMeridian);
+  const center = ((origin + primeMeridian) * 180) / Math.PI;
+  return {
+    ...implementation,
+    longitudeOrigin: origin,
+    getRenderingProfile(coverage) {
+      if (!coverage)
+        return {
+          bounds: resolveBounds(parameters),
+          normalize(point) {
+            normalizeCoverage(point, defaults, center, over);
+          }
+        };
+      try {
+        const profile = createRectangleRenderingProfile(
+          resolveBounds,
+          coverage,
+          origin,
+          primeMeridian,
+          over
+        );
+        const bounds = profile.bounds;
+        return {bounds, normalize: profile.normalize};
+      } catch {
+        // Singular coverage is clipped to this algorithm's chosen finite target.
+        return createRegionsRenderingProfile(
+          resolveBounds,
+          intersectGeographicBounds(coverage, defaults),
+          origin,
+          primeMeridian,
+          over
+        );
+      }
+    }
+  };
+}